The caGrid Data Services Infrastructure supports varying and pluggable service styles. Service styles are intended to allow service developers to repeatedly create data services which require a specific set of functionality to be added or have a well defined configuration and setup process. Styles can add logical functionality to the data service creation and modification processes by implementing specific interfaces which are invoked by the data services extension as it runs. Styles may also add graphical functionality to the service development process by adding a set of wizard panels to the creation process, and optionally including a tab in the service modification UI to further manage configuration of the style. Examples of data service styles include the caCORE SDK backend data source support features. The pluggable nature of service styles allows the main data services infrastructure to remain decoupled from the implementation details of caGrid-provided (or third party) query processors, and ensures that future development and support for new data sources will not always necessitate changes to the core codebase.
|Layout of the Styles Directory Layout|
Data service styles may be added to the data service extension to provide additional functionality to the service creation and configuration processes, and are selected by the service developer when a service is first created. Styles may be installed at any time after the primary caGrid Data Services extension has been installed by adding to the styles directory found in the installed data service extension directory. Each style must provide its own directory in which files it uses will be placed, but no restriction is made on the naming of these directories. At the top level of each style directory, a style.xml file must exist, describing the style. This document describes the style's name, which caGrid and Data Service versions it is compatible with, and information on which classes are to be loaded for each component of the style. If the service developer selects no style at service creation time, the service is created with only the standard data services components and query method, and ready to have a domain model, query processor, and other data service requirements selected and configured.
Data Service styles may add functionality to any or all of the following areas of service development with the Introduce toolkit:
- Creation Wizard
- The service style may supply a list of wizard panels to be displayed and chained together in a wizard-like fashion to break the setup process for the service style into a series of steps. These panels will be shown in a wizard dialog when a service style is selected at service creation time.
- Post-creation processing
- Just as Introduce extensions may add functionality to the service creation process, data service styles may add processing capabilities to this step.
- Modification User Interface
- The style may supply a graphical panel which will be added to the data service tab in the Introduce service modification viewer. This tab can be used to configure any style-specific options in the service.
- Post-code generation processing
- The style may add functionality to the code generation process of service modification. This processing will be invoked each time the service is modified and saved in Introduce.
Creating a data service style is a straightforward process, similar to writing an extension to the Introduce toolkit. New styles may be created by building up a few components and placing them in the appropriate subdirectories of the Introduce toolkit (as described here).
The caGrid Data Service styles infrastructure requires style implementations to conform to a specific format, and requires that the classes which compose the style's implementation inherit from certain classes.
A single XML document describes the style to the data services infrastructure. This document must be named style.xml, and placed in a unique directory under the <introduce>/extensions/data/styles directory. This style description document must conform to the schema provided with the data services infrastructure with the namespace http://gov.nih.nci.cagrid.data/Style, which can be found at the end of this guide.
The following is an example of the style description document:
Each part of this document influences the behavior or appearance of the style as the data service infrastructure executes it.
The root element of the style document attributes which define the name of this style, along with the version of the style. The name is displayed to the service developer at service creation time, allowing selection of a style. The name and version uniquely identify a style to the data service extension framework at runtime.
The style document allows for defining which versions of the caGrid Introduce toolkit and data service extension the style is compatible with. The document may define multiple <Version> elements indicating compatibility with multiple versions.
The document allows for a brief description of the style to accompany the style itself. This information is displayed at data service creation time when the user is given a chance to select a style to use with their data service.
This optional element defines a sequence of panels which will be loaded as part of the pre code generation process of creating a new caGrid Data Service. The panels are displayed in the order in which they are defined here, and can be used to configure aspects of the service style, or customize the underlying data service extension.
Each wizard panel's Java class must extend from the base class gov.nih.nci.cagrid.data.ui.wizard.AbstractWizardPanel. This class is essentially a JPanel with accessor methods for the Introduce service model and the data service extension data. The class also provides access to wizard functionality, such as enabling and disabling navigation buttons, and indicating that the wizard has been completed. Additionally, the base class has three abstract methods which must be implemented:
- This method is called by the wizard when the panel is to be displayed. This provides a callback to update the UI and reflect changes to the model which may impact the appearance of the wizard panel.
- This method is new for caGrid 1.2
- This method is called by the wizard itself when the user clicks the 'next' or 'finish' button to move to the next wizard panel or finish the wizard. This method gives the panel a chance to synchronize its state with that of the service model (ie. copying schemas and libraries, storing service properties).
- getPanelTitle() -> String
- This method should return the title you wish to be displayed by the wizard when the panel is visible on the screen.
- getPanelShortName() -> String
- This method should return a very short name to be displayed in the navigation buttons of the wizard. It should generally be one or two words long.
The data service creation process can be extended by the service style. The post-creation process helper is defined by the CreationHelper element. This element has an attribute called postCreationClassname, which defines the class name of the post-creation processor class. This class must implement the interface gov.nih.nci.cagrid.data.style.StyleCreationPostProcessor.
The data service code generation process can be extended by the service style. The pre code generation process, defined by the preCodegenClassname attribute, is executed after the data service pre code generation options have been completed, but before any other extensions have run. The post code generation process, defined by the postCodegenClassname is executed similarly.
The pre-codegen class must implement the interface gov.nih.nci.cagrid.data.style.StyleCodegenPreProcessor, and the post-codegen class must implement the interface gov.nih.nci.cagrid.data.style.StyleCodegenPostProcessor.
The style can optionally include a panel to be loaded into the data service modification UI. This panel can provide information on configuration options specific to the style (as in the case of the caCORE SDK styles), manage configuration, or present any other information the style developer may choose.
This class must extend from the base class gov.nih.nci.cagrid.data.ui.DataServiceModificationSubPanel. This class is essentially a JPanel with additional methods for accessing the underlying Introduce service model and the data service specific extension data.
Each style must provide any jar files it depends on for Java classes and resources in a directory named lib within the style directory itself. At runtime, classes referenced from the style document are loaded from the jars provided here. The classes contained in these jars may safely depend on other caGrid and Globus libraries, as the runtime classpath of the Introduce toolkit is appended to the library directory's contents.
The style description document.