CaGrid:Tutorials:1.2:DataService:caCORE SDK 4

From caGridWiki

NOTE: A number of bugs have been fixed since the 1.2 release that could cause issues with this tutorial. Please make sure you obtain the latest release of caGrid 1.2 by checking out caGrid. Here are instructions for checking out the release:

caGrid 1.2 Release Stream

export CVS_RSH=ssh
cvs –d:ext:anonymous@cbiocvs2.nci.nih.gov:/share/content/gforge/cagrid-1-0 co -r caGrid-1_2_release  cagrid-1-0/caGrid

When prompted for the password, respond with: anonymous

caGrid 1.1 Release Stream

export CVS_RSH=ssh
cvs –d:ext:anonymous@cbiocvs2.nci.nih.gov:/share/content/gforge/cagrid-1-0 co -r caGrid-1_1_release  cagrid-1-0/caGrid

When prompted for the password, respond with: anonymous

caGrid 1.0 Release Stream

export CVS_RSH=ssh
cvs –d:ext:anonymous@cbiocvs2.nci.nih.gov:/share/content/gforge/cagrid-1-0 co -r caGrid-1_0_release  cagrid-1-0/caGrid

When prompted for the password, respond with: anonymous

Development Stream

export CVS_RSH=ssh
cvs –d:ext:anonymous@cbiocvs2.nci.nih.gov:/share/content/gforge/cagrid-1-0 co cagrid-1-0/caGrid

When prompted for the password, respond with: anonymous.

caGrid Data Service creation is accomplished by the use of an extension to the Introduce toolkit. This extension can streamline the process of creating a data service backed by the caCORE SDK using a wizard like interface which prompts for values as required, or simply make use of a custom query processing back end.

Prerequisites

This tutorial assumes you have your system configured for both caGrid 1.2 as well as caCORE SDK 4.0. Before attempting this tutorial, please review the information on the tutorial prerequisites page.

Launch the Introduce Grid Service Authoring Toolkit

In a system terminal execute the following commands to launch Introduce

 

 %> cd %CAGRID_LOCATION%
 %> ant introduce

Create the Service Skeleton

1. Select Create caGrid Service Skeleton from the toolbar at the top of the Introduce portal, or select Tools -> Create caBIG Service from the menu. The Create caBIG Grid Service screen will appear.
2. Choose a directory in which to place the generated service. This tutorial uses "C:\caGrid\generatedServices\Sdk4Example".
3. Type in the Service Name. This tutorial will use "Sdk4Example".
4. Choose a Package Name. This tutorial will use "org.cagrid.sdk4.example".
5. Choose a Namespace. This tutorial will use "http://example.sdk4.cagrid.org/CaGridTutorialService".
   • NOTE: The service creation dialog will attempt to guess this for you from your package and service names.
6. Select the Data Service radio button from the Customize Service section.
   
7. Click the Create button located at the bottom of the creation screen.

Select the service style

The caGrid data services extension provides a pluggable framework for creating highly custom data services known as data service styles. Styles may be provided by a third party, or installed with caGrid. Styles are provided to create data services backed by various caCORE SDK.

1. When the Data Service Configuration window appears, use the drop down menu to select the "caCORE SDK v 4" option.
2. Leave the check boxes for WS-Enumeration and Bulk Data Transport unchecked for this tutorial
   • These options enable specialized results retrieval for the data service.
     
3. Click the OK button to continue with the selected service style.

The Data Service caCORE SDK 4 Wizard

The caCORE SDK v 4 data service style provides a wizard interface which is run prior to generation of the data service's source code. This wizard provided facilities to select the client interface to the caCORE SDK and configure it, as well as selection of a domain model and mapping that domain to XML schemas for use on the grid.

This panel is strictly informational. The wizard displays the current step in the lower left hand corner of the window, and provides simple 'Previous' and 'Next' buttons to navigate the steps. These buttons will become enabled and disabled as the content of each page is validated. If any fields on the current page are in an invalid state, the 'Next' button will be disabled, and the field will show a red highlight. Mouse-over tooltips are used to indicate the problem. When all steps are complete, the 'Next' button becomes 'Finish', and will complete the wizard and proceed to code generation. Click the Next: Configuration button to continue the wizard.

Configuring the Client

The next step of the wizard.

This panel allows the service developer to select various outputs from the caCORE SDK which are required by the caGrid data service to utilize it as a data resource. There are two modes of operation for this panel: 'simple' and 'advanced', selectable by way of radio buttons near the top-left of the panel. In 'simple' mode, the developer is prompted to select the output directory in a caCORE SDK installation, and the extension will attempt to locate the other components it requires in its subdirectories.

Selecting the output directory

Alternatively, the service developer may select the required components manually by first selecting the 'Advanced' option, then using the provided 'Browse' buttons to populate each field. Once these file location fields have been populated, the service developer may then select to use the 'local' or 'remote' application service APIs. The remote API connects to a caCORE SDK application via HTTP transport, and requires a URL. The local API bypasses HTTP transport all together, and communicates directly with the Hibernate layer of the caCORE SDK. This option should improve performance by removing a level of network overhead, but will only function properly in cases where the grid data service will be deployed on the same machine that the caCORE SDK system is deployed to.

1. For this tutorial, use the Simple option for configuration, and select the output directory of your caCORE SDK 4.0 installation. This example uses "c:/caCore4Release/output". Note: make sure that the output directory contains only one project, the project that you are selecting.
   1. If you are wish to use the minimal caCore SDK output available in the prerequisites, the file DataServices_SDK_40_Tutorial.zip must first be extraced, then extract the resulting archive caCore4MinimalOutput.zip.
   2. In Simple mode, after choosing the directory, all of the fields in the dialog should be populated with the desired information except the hostname and the port number.
2. Select the Remote API radio button.
   • This enables fields specific to this API
3. Set the host name of the machine where the remote application service is running by filling in the text field next to Host Name. This text field requires the user to enter a URL (for example http://www.example.com).
4. Set the port on which the remote application service is configured to accept connections by filling in an integer in the text field labeled Port. Typically, this is port 8080.

1. Click the Next button on the wizard to continue.

Application Service Security

The caCORES SDK Application Service can be configured to require a user name and password for access. If the service is so configured, this panel allows the service developer to specify which user name and password should be used. Two options are available. One option allows a static, single user name and password to be used for all connections to the application service. The other option attempts to use the grid identity of the user making a query to the data service as the user name.

For this tutorial, simply leave all fields blank and unchecked on this page, and click Next.

Selecting a Domain Model

All caGrid data services are required to expose a domain model in their service metadata. This domain model describes the classes available in the data service, as well as their attributes, and relationships to one another. Using this model, a client can formulate queries, and discover data services which contain information they may be interested in. Additionally, the data service itself can use this information to validate queries for their correctness and map domain objects to their XML document representations. Models may be supplied from the caDSR, or from the local file system. For this tutorial, a domain model will be supplied which represents the caCORE SDK version 4 example model.

1. Select the Domain Model From File radio button.
   • This will disable components not relevant to this function, and enable the file selection fields.
2. Click the Browse button at the right hand side of the field labeled Domain Model File.
3. Navigate to the location of sdkExampleDomainModel.xml, and click 'Open' in the file browser.
   • This domain model file is available here
   • Once selected, the packages contained in domain model will be displayed in a list on the panel.
     

Note: to use another domain model file (for example, if you're creating a data service from another caCORE SDK 4 project), you have two options to convert the XMI model used by the SDK to a domain model usable in caGrid:
OPTION 1:
1. When you click the Browse button at the right hand side to select a domain model file, change the file type selection to select XML Model Interchange (*.xmi) files.
2. Browse to and select your XMI model from the SDK's models directory.
3. Proceed to step 4 in Option 2.

OPTION 2:
1. cd to $CAGRID_LOCATION/projects/dataExtensions
2. ant xmiToDomainModel
3. Point to the XMI file exported from EA per the caCORE SDK 4.0 programmer's guide instructions
4. Select "caCORE SDK 4.0 XMI from EA" as the XMI type
5. Type in a project short name
6. Type in a project version
7. Click OK
8. Choose where to save your domain model file and type in a name.

1. Click the Next button to continue to the last step in the wizard.

Mapping Domain Packages to XML Schema

Every class exposed by the domain model must be supplied with a corresponding XML schema representation so it may be utilized in the grid. The mapping panel of this wizard streamlines this process by simultaneously generating the mapping from model to schema and configuring serialization of the XML data types to correspond to the domain model's Java beans.

Packages from the domain model are listed, along with a suggested XML schema namespace, a mapping status, and a button to manually resolve the mapping for each package. This panel contains two buttons which serve as convenience methods for mapping a large batch of packages to their schemas. The 'Map From GME' button attempts to locate the suggested namespaces in the Global Model Exchange service and pull the corresponding schemas. The 'Map From Config' button makes use of the XML schemas provided by the caCORE SDK's output to map to each package of the domain model.

1. Click the Map From Config button, and this mapping will be performed automatically.
   • If this operation succeeds, the mapping status of each package will change from 'Unknown' to 'Found', and the 'Done' button will be enabled.
     
2. Click the Done button to complete the wizard.

Complete

Once the wizard has been completed, the Introduce toolkit and data services extension will generate the code, wsdl, and other files required to complete the grid service generation. This process can take a few minutes depending on the selection of your domain model and speed of your system. Once this code generation process is complete, Introduce will display the service modification user interface, including the specialized tab for managing data service components.

Main Article: Data Services Introduce Extension

Deploying

This tutorial continues to deploy the newly created grid service.