 |
Page History
| Scrollbar | ||
|---|---|---|
|
| Page info | ||||
|---|---|---|---|---|
|
| Section | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Introduction
The Analytical Grid Service is an API used by programmers to pull data from the system (a target instance of LexEVS on the grid) using a set of method calls and appropriate parameters. The results differ from method to method but are all objects in the LexEVS model.
The following table summarizes the operations available through the LexEVS Analytical Grid Service. Each of the operations is also defined in detail below. The grid analytical service and related operations are viewable via the caGrid Portal (http://cagrid-portal.nci.nih.gov
).
ISO 21090 Model
The LexEVS 6.0 Analytical Grid Services use a version of the LexGRID/LexBIG model, extended to support ISO 21090 Datatypes.
The adapted model may be found here.
Using the API
There are two (2) different interfaces for accessing the LexEVS Grid Services:
...
| Code Block |
|---|
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter
("http://lexevsapi-analytical60.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService"); |
Method Descriptions
getCodingSchemeConcepts
Description: | Returns the set of all (or all active) concepts in the specified coding scheme. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification, org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag |
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.CodedNodeSet.stubs.types.CodedNodeSetReference |
Exception: | RemoteException |
Implementation Details: |
getFilter
Description: | Returns an instance of the filter extension registered with the given name. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.ExtensionIdentification |
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Filter.stubs.types.FilterReference |
Exception: | RemoteException |
Implementation Details: |
getSortAlgorithm
Description: | Returns an instance of the sort extension registered with the given name. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.ExtensionIdentification |
Output: | ''org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Sort. |
Exception: | RemoteException |
Implementation Details: |
getFilterExtensions
Description: | Returns a description of all registered extensions used to provide additional filtering of query results. |
Input: | none |
Output | org.LexGrid.LexBIG.iso21090.DataModel.Collections.ExtensionDescriptionList |
Exception: | RemoteException |
Implementation Details: |
...
ExtensionDescriptionList extDescList = lbs.getFilterExtensions(); |
getServiceMetadata
Description: | Return an interface to perform system-wide query over metadata for loaded code systems and providers. |
Input: | none |
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.LexBIGServiceMetadata. |
Exception: | RemoteException |
Implementation Details: |
...
LexBIGServiceMetadataGrid metadata = lbs.getServiceMetadata(); |
getSupportedCodingSchemes
Description: | Return a list of coding schemes and versions that are supported by this service, along with their status. |
Input: | none |
Output: | org.LexGrid.LexBIG.iso21090.DataModel.Collections.CodingSchemeRenderingList |
Exception: | RemoteException |
Implementation Details: |
...
CodingSchemeRenderingList csrl = lbs.getSupportedCodingSchemes(); |
getLastUpdateTime
Description: | Return the last time that the content of this service was changed; null if no changes have occurred. Tag assignments do not count as service changes for this purpose. |
Input: | none |
Output: | java.util.Date |
Exception: | RemoteException |
Implementation Details: |
...
Date date = lbs.getLastUpdateTime(); |
resolveCodingScheme
Description: | Return detailed coding scheme information given a specific tag or version identifier. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification, org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag |
Output: | org.LexGrid.codingSchemes.CodingScheme |
Exception: | RemoteException |
Implementation Details: |
getNodeGraph
Description: | Returns the node graph as represented in the particular relationship set in the coding scheme. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification, org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag, org.LexGrid.LexBIG.iso21090.DataModel.cagrid.RelationContainerIdentification |
Output: | ''org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices. |
Exception: | RemoteException |
Implementation Details: |
getMatchAlgorithms
Description: | Returns the node graph as represented in the particular relationship set in the coding scheme. |
Input: | none |
Output: | org.LexGrid.LexBIG.iso21090.DataModel.Collections.ModuleDescriptionList |
Exception: | RemoteException |
Implementation Details: |
...
Step 2: Invoke the LexEVS caGrid service as follows:
ModuleDescriptionList mdl = lbs.getMatchAlgorithms(); |
getGenericExtensions
Description: | Returns a description of all registered extensions used to implement application-specific behavior that is centrally accessible from a LexBIGService. |
...
Step 2: Invoke the LexEVS caGrid service as follows:
ExtensionDescriptionList edl = lbs.getGenericExtensions(); |
getGenericExtension
Description: | Returns an instance of the application-specific extension registered with the given name. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.ExtensionIdentification |
Output: | org.LexGrid.LexBIG.iso21090.DataModel.Collections.SortDescriptionList |
Exception: | RemoteException |
Implementation Details: |
getHistoryService
Description: | Resolve a reference to the history api servicing the given coding scheme. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification |
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices. |
Exception: | RemoteException |
Implementation Details: |
getSortAlgorithms
Description: | Returns a description of all registered extensions used to provide additional filtering of query results. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.InterfaceElements.types.SortContext |
Output: | org.LexGrid.LexBIG.iso21090.DataModel.Collections.SortDescriptionList |
Exception: | RemoteException |
Implementation Details: |
resolveCodingSchemeCopyright
Description: | Return coding scheme copyright given a specific tag or version identifier. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification |
Output: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeCopyRight |
Exception: | RemoteException |
Implementation Details: |
setSecurityToken
Description: | Sets the Security Token for the given Coding Scheme. |
Input: | org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification, gov.nih.nci.evs.security.SecurityToken |
Output: | org.LexGrid.LexBIG.cagrid.LexEVSGridService.stubs.types.LexEVSGridServiceReference.LexEVSGridServiceReference |
Exception: | RemoteException |
Implementation Details: |
Usage Instructions
Service URL
The LexEVS Grid Service 4.2 URL is: http://lexevsapi.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService.
The service is also accessible via the caGRID Portal.
Required Libraries
The libraries required for programmatic access to the LexEVS Grid Service are listed in the tables below. The 3rd Party Software Libraries required for use of the LexEVS API Grid Service are listed in Table 4.1 and the NCICB software captured under the caBIG® umbrella are listed in Table 4.2.
...
Library | Associated JARs |
|---|---|
caGrid Software Libraries | caGrid-ServiceSecurityProvider-client-1.2.jar |
caGrid-ServiceSecurityProvider-common-1.2.jar | |
caGrid-ServiceSecurityProvider-stubs-1.2.jar | |
caGrid-core-1.2.jar | |
caGrid-metadata-common-1.2.jar | |
caGrid-metadata-data-1.2.jar | |
caGrid-metadata-security-1.2.jar | |
caGrid-metadatautils-1.2.jar | |
EVS API Libaries | evsapi42-beans.jar |
evsapi42-framework.jar | |
LexEVS Grid Service Client Library | LexEVSGridService-client.jar |
LexEVS Grid Service Stubs | LexEVSGridService-stubs.jar |
LexEVS Grid Service Common | LexEVSGridService-common.jar |
LexEVS Grid Service Service | LexEVSGridService-service.jar |
LexEVS Grid Service Tests | LexEVSGridService-tests.jar |
caCORE SDK Library | sdk-client-framework.jar |
LexEVS API | lexbig.jar |
Custom Castor Serializer | castor-bean-serializer.jar |
Downloads
For your convenience, the required libraries are available for download here:
...
In order to programmatically access the LexEVS API Grid Service, these libraries need to be added to your local classpath.
Code Examples
Example client and service calls, and SOAP messages
See http://gforge.nci.nih.gov/docman/view.php/491/14252/TestClient.zip
Example API usage
Example 1: Searching for concepts in NCI Thesaurus containing the string "Gene"
:SearchingForConcepts_Snippet
Error Handling
Error Connecting to LexEVS Grid Service
When connecting through the Java Client, java.net.ConnectException and org.apache.axis.types.URI.MalformedURIException may be thrown upon an unsuccessful attempt to connect.
...
This example shows a typical connection to the LexEVS Grid Service, with the two potential Exceptions being caught and handled as necessary.
LexEVS Errors
LexEVS errors will be forwarded through the Distributed LexEVS layer and then on to the Grid layer. Input parameters, along with any other LexEVS (or Distributed LexEVS) errors will be detected on the server, not the client, and forwarded. All Generic LexEVS (or Distributed LexEVS) errors will be forwarded via a RemoteException, with the cause of the error and underlying LexEVS error message included.
Invalid Service Context Access
Service Context Services are not meant to be called directly. If the client attempts to do so, an org.LexGrid.LexBIG.cagrid.LexEVSGridService.CodedNodeSet.stubs.types.InvalidServiceContextAccess Exception will be thrown. This indicates a call was made to a Service Context without obtaining a Service Context Reference via the Main Service (see the above section Service Contexts and State for more information).
Security Issues
LexEVS Grid Service Security
...