----

{cagridroundpanel}
{pre:class=cagridheaderfont}Table of Contents{pre}

This tutorial assumes you have your system configured for both caGrid 1.2 as well as caCORE SDK 4.0.

* A full caGrid 1.2 installation
** This installation is rooted at %CAGRID_LOCATION%, an environment variable set to reference the base directory
* Access to a caCORE SDK 4.0 installation on the local file system
** The SDK must be configured to use the example model supplied with the download of the SDK
** The SDK system has been built and installed
* Network access to the installed caCORE SDK 4.0 system
** The host name and port will be required to query the remote system
* The domain model XML document for the caCORE SDK's example data model
** This available singularly from [the caGrid SVN repository|downloads:Source Code]

A comprehensive discussion of installation and configuration of the caCORE SDK is beyond the scope of this tutorial, however the general process works as follows:

* Download caCORE SDK ([http://gforge.nci.nih.gov/frs/?group_id=148])
* Create UML model and Data model ([caCORE SDK 4.0 Developer's Guide|http://gforge.nci.nih.gov/docman/view.php/148/8650/caCORE%20SDK%204.0%20Developer's%20Guide_101007.pdf])
* Perform mapping between Object and Data model using UML tag values or preferably you can use caAdapter ([caAdapter|http://ncicb.nci.nih.gov/NCICB/infrastructure/cacore_overview/caadapter])
* Generate a system using SDK by supplying your UML model as input

_Note:_ The SDK has a sample model which you can use to generate a system and subsequently create a grid service with the same model.

A high-level description of the features and usage of the SDK can be found in the [caCORE SDK 4.0 Developer's Guide|http://gforge.nci.nih.gov/docman/view.php/148/8650/caCORE%20SDK%204.0%20Developer's%20Guide_101007.pdf]

If you do not wish to build the caCORE SDK system yourself, a minimal set artifacts required to complete the tutorial is provided in the [caGrid tutorial materials download page.|https://project.bmi.ohio-state.edu/gf/download/frsrelease/117/510/DataServices_SDK_40_Tutorial.zip]

Once downloaded, the zip file contains the following items:

* README.txt
** A document describing the contents of the zip
* caCore4MinimalOutput.zip:
** Contains the 'output' folder resulting from building the caCORE SDK 4.0 using the supplied example uml model, pared down to remove files not required by the data service wizard or runtime
** This may be unpacked and used in the tutorial's "Configuring the Client" step.
* sdkExampleDomainModel.xml:
** The domain model document which represents the caCORE SDK's example object model
* Sdk4Example.zip:
** The completed tutorial service in zip format
** See the enclosed README.FIRST.txt in the unpacked zip for usage instructions

h2. Launch the Introduce Grid Service Authoring Toolkit

# Type in the Service Name. This tutorial will use *_"Sdk4Example"_*.
# Choose a Package Name. This tutorial will use *_"org.cagrid.sdk4.example"_*.
# 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.
# Select the *{_}Data Service{_}* radio button from the Customize Service section.{attached-image:tablealign=center|attachmentname=DataService_1.2_SDK_4_Creation.png}
# Click the *{_}Create{_}* button located at the bottom of the creation screen.

h2. Select the Service Style

The caGrid data services extension provides a pluggable framework for creating highly custom data services known as [data service styles|dataservices:Documentation]. Styles may be provided by a third party, or installed with caGrid. Styles are provided to create data services backed by various caCORE SDK.
# When the *{_}Data Service Configuration{_}* window appears, use the drop down menu to select the *_"caCORE SDK v 4"_* option.
# 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.{attached-image:tablealign=center|attachmentname=DataService_1.2_SDK_4_Style_Selection.png}
# Click the *{_}OK{_}* button to continue with the selected service style.

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.

# 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"_*.
## 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._
## 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*.
# Select the *{_}Remote API{_}* radio button.
#* This enables fields specific to this API
# 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]).
# 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{_}*.{attached-image:tablealign=center|attachmentname=DataService_1.2_SDK_4_Wizard_Step_2_Full.png}
# Click the *{_}Next{_}* button on the wizard to continue.

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|http://gforge.nci.nih.gov/plugins/scmcvs/cvsweb.php/%7Echeckout%7E/cagrid-1-0/caGrid/projects/sdkQuery4/test/resources/sdkExampleDomainModel.xml?rev=1.2;content-type=text%2Fplain;cvsroot=cagrid-1-0]
* Once selected, the packages contained in domain model will be displayed in a list on the panel.

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

* If this operation succeeds, the mapping status of each package will change from 'Unknown' to 'Found', and the 'Done' button will be enabled.

h3. Creation Process 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.

h2. Deploying the Data Service

Once a caGrid data service has been created, it must be deployed to a service container so it can be invoked.

h3. Cleaning Up the Container

This tutorial will deploy the generated grid data service to the Tomcat container. If other caGrid services (especially other data services) have been deployed to the container, class path conflicts can arise in the running service. If this is the case, before deploying the service, make sure the Tomcat container is totally clean of all other caGrid services. You can do this by removing the _wsrf_ directory under the _webapps_ directory inside the Tomcat base directory:

Once the wsrf folder has been removed, deploy Globus to Tomcat:

Start the Tomcat container so that the service can be invoked using grid calls.

Once the tutorial caGrid data service has been created and deployed to a service container, it may be invoked by a grid service client. This tutorial covers importing the project into Eclipse, importing [CQL|dataservices:CQL] queries from XML, and making use of the generic data service client tooling to query the service and print results.

h3. Importing the Service into Eclipse

All Introduce generated caGrid services contain both a .project and a .classpath file, which Eclipse uses to determine properties for a Java project (source folders, code builders, libraries, etc). While it is not required to use Eclipse for this tutorial, doing so makes it easier to make changes to the source code, and simplifies testing the client.

h3. Creating a Test Class

To begin making use of the tutorial service, we'll need a place to put source code, as well as an implementation file to make use of the generic data service client and handle some query results. While the client class produced with the service itself can be used for basic testing, domain specific logic should never be placed in the client when used in a production level system. This is because the client may be regenerated, or have methods added and removed by the Introduce toolkit as changes are made to the service model.

h3. Create a New Source Package

To create a new package, expand the '''Sdk4Example''' project in Eclipse, followed by the folder named '''src'''. This directory houses the source code generated by Introduce which implements the grid service. Create a new package named _org.cagrid.sdk4.example.tutorial_ under the source directory. In Eclipse, this is as easy as right-clicking '''src''', and selecting '''New->Package.''' Fill in the name of the package, and click '''Finish.'''
{attached-image:tablealign=center|attachmentname=Data_Services_SDK_4_Tutorial_Add_Package.png} Alternatively, this new package may be created as a directory on the file system. From the command line, create the directory _src/org/cagrid/sdk4/example/tutorial_.

h3. Create a New Class

To create some code which can invoke the grid data service, begin by creating a new Java class. In Eclipse, right click the newly created package, and select '''New->Class'''. Name the class '''QueryRunner''', and check the box to create a main method, which will make the class executable. Click '''Finish''' to create this class and have Eclipse generate the shell of it.

public static void main(String[] args) {
// TODO Auto-generated method stub

}

public QueryRunner(String serviceUrl, String queryFilename) {
this.serviceUrl = serviceUrl;
this.queryFilename = queryFilename;

h3. Adding a Query Method

DataServiceClient client = new DataServiceClient(serviceUrl);
// deserialize the CQL query
CQLQuery query = (CQLQuery) Utils.deserializeDocument(queryFilename, CQLQuery.class);
// execute the query on the data service
System.out.println("Querying");
CQLQueryResults results = client.query(query);
// create a results iterator
System.out.println("Iterating");
Iterator iter = new CQLQueryResultsIterator(results, true);
// iterate and print XML
while (iter.hasNext()) {
String value = (String) iter.next();
System.out.println("-- RESULT --");
System.out.println(value);
}
System.out.println("Done");
} catch (Exception ex) {
ex.printStackTrace();
}

import gov.nih.nci.cagrid.cqlquery.CQLQuery;
import gov.nih.nci.cagrid.cqlresultset.CQLQueryResults;
import gov.nih.nci.cagrid.data.client.DataServiceClient;

h3. Implement the Main Method

}
QueryRunner runner = new QueryRunner(args[0], args[1]);

h2. An Example Query

<ns1:Group logicRelation="AND">
<ns1:Association name="gov.nih.nci.cacoresdk.domain.other.levelassociation.Suit" roleName="suit">
<ns1:Attribute name="name" predicate="EQUAL_TO" value="Spade"/>
</ns1:Association>
<ns1:Attribute name="Name" predicate="EQUAL_TO" value="Ace"/>
</ns1:Group>
</ns1:Association>
</ns1:Target>

h2. Executing the Test Class

After the QueryRunner class and example CQL query have been created, we can use them together to query the remote data service and retrieve results.

h3. Execution Within Eclipse

* [http://localhost:8080/wsrf/services/cagrid/Sdk4Example]
** This is the URL of the tutorial grid service, as deployed in the local Tomcat installation
** If the container's port is different than the default, change ''8080'' to match it
* exampleCqlQuery.xml
** This is the CQL query from earlier in the tutorial. It will be executed by the data service.

<ns2:Suit name="Spade" id="1" xmlns:ns2="gme://caCORE.caCORE/4.0/gov.nih.nci.cacoresdk.domain.other.levelassociation"/>

<!-- Define the environment variable -->
<property environment="env" />

<!-- globus dir -->
<property name="ext.globus.dir" value="${env.GLOBUS_LOCATION}" />

<!-- Important directories and files -->
<property name="lib.dir" value="${basedir}/lib"/>
<property name="build.lib.dir" location="${basedir}/build/lib"/>
<property name="globus.lib.dir" location="${ext.globus.dir}/lib"/>

<target name="run" description="Runs the QueryRunner class from the caGrid 1.2 Data Services with caCORE SDK 4.0 tutorial">
<java classname="org.cagrid.sdk4.example.tutorial.QueryRunner"
args="${service.url} ${cql.file}">
<classpath>
<fileset dir="${build.lib.dir}">
<include name="**/*.jar"/>
</fileset>
<fileset dir="${lib.dir}">
<include name="**/*.jar"/>
</fileset>
<fileset dir="${globus.lib.dir}">
<include name="**/*.jar"/>
</fileset>
</classpath>
</java>
</target>

[java] The args attribute is deprecated. Please use nested arg elements.
[java] Arg: http://localhost:8080/wsrf/services/cagrid/Sdk4Example
[java] Arg: exampleCqlQuery.xml
[java] Querying
[java] Iterating
[java] -- RESULT --
[java] <ns2:Suit name="Spade" id="1" xmlns:ns2="gme://caCORE.caCORE/4.0/gov.nih.nci.cacoresdk.domain.other.levelassociation"/>
[java] Done

BUILD SUCCESSFUL

These results indicate the data service retrieved a single Suit instance matching the query criteria. Changing the CQL query passed to the QueryRunner will change the output as the data service locates different objects.