Page info
title title

Revision History

Content changes to this document from the previous to the current level are indicated by revision bars (|) unless a complete rewrite is indicated.

...

For more Documentation, Build/Deployment instructions and examples, visit refer to the project documentation home on the GForge archive page.

Scope

The LexEVS Grid service will provide programmatic access to the LexBIG domain objects that are available via the LexBIG information model.

...

The LexEVS Grid Service is implemented to expose the API and Model of LexBIG 2.3. For more information on LexBIG, see http://informatics.mayo.edu^{Image Removed}. the Mayo Clinic website

LexEVS Grid Service is deployed in a JBoss

...

the GForge archive.

EVSAPI itself depends on an installation of LexBIG

The diagram below shows the various components of the LexEVS Grid Service System and how they interact.

...

Below is the LexEVS Grid Service Architecture, viewed from inside of the Web Service Container. For more information on how Service Contexts and Resources are used, see the section, Service Contexts and State below.

Image Modified

LexEVS Grid Service Class Diagram

The LexEVS Grid Service is built on the LexGrid/LexBIG model and implementation. For more information about this model, visit:

Historical link
https://gforge.nci.nih.gov/plugins/scmsvn/viewcvs.php/LexBIG_Core_Services/LexBIG-2.3/lexbig/lbModel/?root=lexevs

and

Historical link
https://gforge.nci.nih.gov/plugins/scmsvn/viewcvs.php/LexBIG_Core_Services/LexBIG-2.3/lgModel/?root=lexevs

Also, visit http://informatics.mayo.edu^{Image Removed} the Mayo website

For information specific to the LexEVS Grid Service, visit:

Historical link
https://gforge.nci.nih.gov/plugins/scmsvn/viewcvs.php/LexBIG_Core_Services/LexBIG-2.3/lexbig/lbModel.cagrid/?root=lexevs

...

The main Service API exposed by the LexEVS Grid service will be the http://informatics.mayo.edu/LexGrid/downloads/javadocGrid/org/LexGrid/LexBIG/cagrid/interfaces/LexBIGServiceGrid.html^{Image Removed}

...

1. Client invokes caGrid service .
2. caGrid Service uses Distributed LexBIG to implement call.
3. Distributed LexBIG returns requested info to caGrid service.
4. caGrid service sends response to client.

Main Service API

http://informatics.mayo.edu/LexGrid/downloads/javadocGrid/org/LexGrid/LexBIG/cagrid/interfaces/LexBIGServiceGrid.html^{Image Removed}

Using the API

To use the LexEVS Grid Services, either org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter or org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter objects may be instantiated. These are two different Interfaces for accessing the Grid Services.

• org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter- An Interface for interacting with the LexEVS Grid Services. This Interface is intended to mirror the existing LexBIG API as much as possible. There is no object wrapping for semantic purposes on this interface. This allows existing applications using the LexBIG API to used Grid Services without code changes. This Interface may be acquired by instantiating LexBIGServiceAdapter with the Grid Service URL as a parameter.

  Code Block
  LexBIGService lbs = new LexBIGServiceAdapter("http://...");

• org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter- An Interface for interacting with the LexEVS Grid Services. This Interfaces is the Semantically defined interface. All method parameters and return values are defined and annotated as CDEs to be loaded into CADSR. This Interface is intended to be caGrid Silver Level Compliant. This Interface may be acquired by instantiating LexBIGServiceGridAdapter with the Grid Service URL as a parameter.

  Code Block
  LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter("http://...");

...

...

...

...

...

...

getGenericExtension

getGenericExtensions(ExtensionIdentification)

getHistoryService

getHistoryService(CodingSchemeIdentification)

getSortAlgorithms

getSortAlgorithms(SortContext)

resolveCodingSchemeCopyright

resolveCodingSchemeCopyright(CodingSchemeIdentification)

setSecurityToken

setSecurityToken(CodingSchemeIdentification, SecurityToken)

...

For an example clients, service calls, and SOAP messages, see the sample code on the LexEVS documentation on GForge archive page.

Example API usage:

Searching for concepts in NCI Thesaurus containing the string "Gene"

//Create a Connection to the Grid Service
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(gridServiceURL);
 
//Set up the CodingSchemeIdentification object to define the Coding Scheme
CodingSchemeIdentification csid = new CodingSchemeIdentification();
csid.setName("NCI Thesaurus");
 
//Get the CodedNodeSet for that CodingScheme (This returns a CodedNodeSet Service Context) 
CodedNodeSetGrid cnsg = lbs.getCodingSchemeConcepts(csid, null); 
//getCodingSchemeConcepts is a Grid Service Call
 
//Set the text to match
MatchCriteria matchText = new MatchCriteria();
matchText.setText("Gene");
 
//Define a SearchDesignationOption, if any
SearchDesignationOption searchOption = new SearchDesignationOption();
 
//Choose an algorithm to do the matching
ExtensionIdentification matchAlgorithm = new ExtensionIdentification();
matchAlgorithm.setLexBIGExtensionName("contains");
 
//Chose a language
LanguageIdentification language = new LanguageIdentification();
language.setIdentifier("en");
 
//Restrict the CodedNodeSet
cnsg.restrictToMatchingDesignations(matchText, searchOption, matchAlgorithm, language); 
//restrictToMatchingDesignations is a Grid Service Call
 
//Create a SetResolutionPolicy to handle the details of Resolving the CodedNodeSet
//Here, we will set the Maximum number of Concepts returned to 10.
SetResolutionPolicy resolvePolicy = new SetResolutionPolicy();
resolvePolicy.setMaximumToReturn(10);
 
//Do the resolve
ResolvedConceptReferenceList rcrlist = cnsg.resolveToList(resolvePolicy); 
//resolveToList is a Grid Service Call
 
//Use the returned ResolvedConceptReferenceList to print some details about the concepts found

ResolvedConceptReference[] rcref = rcrlist.getResolvedConceptReference();
for (int i = 0; i < rcref.length; i++) {
	System.out.println(rcref[i].getConceptCode());
	System.out.println(rcref[i].getReferencedEntry().
		getPresentation()[0].getText().getContent()); 
}

...

Along with the Main Service (described above), the Server will also host the Service Contexts shown in the following diagram and described in the subsequent sections. These Service Contexts are not meant to be called directly as Grid Services. The main function of these Service Contexts is to provide additional functionality to the Main Service.

Image Modified

Service Context Operations Example in Introduce

...

LexEVS Grid Services use the WS-Resource Framework (WSRF) to allow for stateful calls to the server. When a client requests a Service Context, the client is not only issued a Reference to the Service Context that was requested, but to a unique stateful Resource on the server as well. This Resource is used in the LexEVS Grid Services as a way of statefully holding objects for further use by the client. For more information about how caGrid uses the WS-Resource Framework (WSRF), see http://www.cagrid.org/wiki/Metadata:WSRF^{Image Removed}

Historical link
http://www.cagrid.org/wiki/Metadata:WSRF

For more information on how Resources are implemented in the LexEVS Grid Service, refer to this LexEVSGrid presentation.

Service Context Sequence

...

Supported Service Contexts.

CodedNodeSet

http://informatics.mayo.edu/LexGrid/downloads/javadocGrid/org/LexGrid/LexBIG/cagrid/interfaces/CodedNodeSetGrid.html^{Image Removed}.html

To construct a CodedNodeSet, the user calls getCodingSchemeConcepts as described above. When the user creates a CodedNodeSet through the API call getCodingSchemeConcepts, the server creates and stores the CodedNodeSet server-side as a Resource. This Resource is associated with the client and will be accessible only by the client that created it.

...

1. The user requests a CodedNodeSet using getCodingSchemeConcepts. :RequestCodedNodeSet_

   Include Page
   CodedNodeSet Snippet CodedNodeSet Snippet

2. The server calls the Distributed LexBIG getCodingSchemeConcepts method, returning to the server an org.LexGrid.LexBIG.Impl.CodedNodeSetImpl (the implementation of org.LexGrid.LexBIG.LexBIGService.CodedNodeSet) object.
3. The server then creates an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.CodedNodeSet.service.globus.resource.CodedNodeSetResource. This Resource will be used to hold the instance of org.LexGrid.LexBIG.Impl.CodedNodeSetImpl, the implementation of org.LexGrid.LexBIG.LexBIGService.CodedNodeSet that was created above.
4. The server returns an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.CodedNodeSet.stubs.types.CodedNodeSetReference object to the client. This is the reference to the CodedNodeSet Service Context. This object has a direct reference to the Resource created above. The user now uses this client to make transparent Grid calls through the Service Context.
5. The client may continue to make statefull calls to the CodedNodeSetClient and the assigned Resource.
6. These restrictions are separate calls but statefully maintained on the server via the Resource.

CodedNodeGraph

http://informatics.mayo.edu/LexGrid/downloads/javadocGrid/org/LexGrid/LexBIG/cagrid/interfaces/CodedNodeGraphGrid.html^{Image Removed}

To construct a CodedNodeGraph, the user calls getNodeGraph as described above. When the user creates a CodedNodeGraph through the API call getNodeGraph, the server creates and stores the CodedNodeGraph server-side as a Resource. This Resource is associated with the client and will be accessible only by the client that created it.

...

1. The user requests a CodedNodeGraph using getCodingSchemeConcepts.
   :RequestCodedNodeGraph_

   Include Page
   CodedNodeGraph Snippet CodedNodeGraph Snippet

2. The server calls the Distributed LexBIG getNodeGraph method, returning to the server an org.LexGrid.LexBIG.Impl.CodedNodeGraphImpl (the implementation of org.LexGrid.LexBIG.LexBIGService.CodedNodeGraph) object.
3. The server then creates an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.CodedNodeGraph.service.globus.resource.CodedNodeGraphResource. This Resource will be used to hold the instance of org.LexGrid.LexBIG.Impl.CodedNodeGraphImpl, the implementation of org.LexGrid.LexBIG.LexBIGService.CodedNodeGraph that was created above.
4. The server returns an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.CodedNodeGraph.stubs.types.CodedNodeGraphReference object to the client. This is the reference to the CodedNodeGraph Service Context. This object has a direct reference to the Resource created above. The user now uses this client to make transparent Grid calls through the Service Context.
5. The client may continue to make statefull calls to the CodedNodeGraphClient and the assigned Resource. For example, the client may add Restrictions to the CodedNodeGraph before a Resolve: :

   Include Page
   CodedNodeGraphRestriction Snippet CodedNodeGraphRestriction

   _

   Snippet

6. These restrictions are separate calls but statefully maintained on the server via the Resource.

LexBIGServiceConvenienceMethods

http://informatics.mayo.edu/LexGrid/downloads/javadocGrid/org/LexGrid/LexBIG/cagrid/interfaces/LexBIGServiceConvenienceMethodsGrid.html^{Image Removed}

To construct a LexBIGServiceConvenienceMethods, the user calls getGenericExtensions as described above. When the user creates a LexBIGServiceConvenienceMethods through the API call getGenericExtensions, the server creates and stores the LexBIGServiceConvenienceMethods server-side as a Resource. This Resource is associated with the client and will be accessible only by the client that created it.

...

1. The user requests a LexBIGServiceConvenienceMethods using getGenericExtensions.

   Include Page

   :

   RequestLexBIGServiceConvenienceMethods Snippet RequestLexBIGServiceConvenienceMethods

   _

   Snippet

2. The server calls the Distributed LexBIG getGenericExtensions method, returning to the server an org.LexGrid.LexBIG.Impl.Extensions.GenericExtensions.LexBIGServiceConvenienceMethodsImpl (the implementation of org.LexGrid.LexBIG.Extensions.Generic.LexBIGServiceConvenienceMethods) object.
3. The server then creates an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.LexBIGServiceConvenienceMethods.service.globus.resource.LexBIGServiceConvenienceMethodsResource. This Resource will be used to hold the instance of org.LexGrid.LexBIG.Impl.Extensions.GenericExtensions.LexBIGServiceConvenienceMethodsImpl, the implementation of org.LexGrid.LexBIG.Extensions.Generic.LexBIGServiceConvenienceMethods that was created above.
4. The server returns an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServicesLexBIGServiceConvenienceMethods.stubs.types.LexBIGServiceConvenienceMethodsReference object to the client. This is the reference to the LexBIGServiceConvenienceMethods Service Context. This object has a direct reference to the Resource created above. This LexBIGServiceConvenienceMethodsClient implements org.LexGrid.LexBIG.Extensions.Generic.LexBIGServiceConvenienceMethods. The user now uses this client to make transparent Grid calls through the Service Context. Because this LexBIGServiceConvenienceMethods implements org.LexGrid.LexBIG.Extensions.Generic.LexBIGServiceConvenienceMethods, API calls will look to the user as being identical to direct LexBIG API calls.
5. The client may continue to make statefull calls to the LexBIGServiceConvenienceMethods Client and the assigned Resource.
6. These API calls are separate calls but statefully maintained on the server via the Resource.

LexBIGServiceMetadata

http://informatics.mayo.edu/LexGrid/downloads/javadocGrid/org/LexGrid/LexBIG/cagrid/interfaces/LexBIGServiceMetadataGrid.html^{Image Removed}/LexBIGServiceMetadataGrid.html

To construct a LexBIGServiceMetadata, the user calls getServiceMetadata as described above. When the user creates a LexBIGServiceMetadata through the API call getServiceMetadata , the server creates and stores the LexBIGServiceMetadata server-side as a Resource. This Resource is associated with the client and will be accessible only by the client that created it.

...

1. The user requests a LexBIGServiceMetadata using getServiceMetadata.

   Include Page
   RequestLexBIGServiceMetadata Snippet

   :

   RequestLexBIGServiceMetadata

   _

   Snippet

2. The server calls the Distributed LexBIG getServiceMetadata method, returning to the server an implementation of org.LexGrid.LexBIG.LexBIGService.LexBIGServiceMetadata object.
3. The server then creates an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.LexBIGServiceMetadata.service.globus.resource.LexBIGServiceMetadataResource. This Resource will be used to hold the instance of an implementation of org.LexGrid.LexBIG.LexBIGService.LexBIGServiceMetadata.
4. org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.LexBIGServiceMetadata.stubs.types.LexBIGServiceMetadata object to the client. This is the reference to the LexBIGServiceMetadata Service Context. This object has a direct reference to the Resource created above. The user now uses this client to make transparent Grid calls through the Service Context.
5. The client may continue to make statefull calls to the LexBIGServiceMetadata and the assigned Resource.
6. These API calls are separate calls but statefully maintained on the server via the Resource.

HistoryService

http://informatics.mayo.edu/LexGrid/downloads/javadocGrid/org/LexGrid/LexBIG/cagrid/interfaces/HistoryServiceGrid.html^{Image Removed}

To construct a HistoryService, the user calls getHistoryService as described above. When the user creates a HistoryService through the API call getHistoryService, the server creates and stores the HistoryService server-side as a Resource. This Resource is associated with the client and will be accessible only by the client that created it.

...

1. The user requests a HistoryService using getHistoryService .

   Include Page
   RequestHistoryService Snippet

   :

   RequestHistoryService

   _

   Snippet

2. The server calls the Distributed LexBIG getHistoryService method, returning to the server an implementation of org.LexGrid.LexBIG.History.HistoryService object.
3. The server then creates an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.HistoryService.service.globus.resource.HistoryServiceResource. This Resource will be used to hold the instance of an implementation of org.LexGrid.LexBIG.History.HistoryService.
4. The server returns an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.LexBIGServiceMetadata.stubs.types.LexBIGServiceMetadata object to the client. This is the reference to the HistoryService Service Context. This object has a direct reference to the Resource created above. The user now uses this client to make transparent Grid calls through the Service Context.
5. The client may continue to make statefull calls to the HistoryServiceClient and the assigned Resource. For example, the client may call any method in org.LexGrid.LexBIG.History.HistoryService
   . Example: history.getLatestBaseline();
6. These API calls are separate calls but statefully maintained on the server via the Resource.

Sort

http://informatics.mayo.edu/LexGrid/downloads/javadoc/org/LexGrid/LexBIG/Extensions/Query/Sort.html^{Image Removed}

To construct a Sort, the user calls getSortAlgorithm as described above. When the user creates a Sort through the API call getSortAlgorithm, the server creates and stores the Sort server-side as a Resource. This Resource is associated with the client and will be accessible only by the client that created it.

...

1. The user requests a Sort using getSortAlgorithm . :

   Include Page
   RequestSort Snippet RequestSort

   _

   Snippet

2. The server calls the Distributed LexBIG getSortAlgorithm method, returning to the server an implementation of org.LexGrid.LexBIG.Extensions.Query.Sort) object.
3. The server then creates an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Sort .service.globus.resource.Sort Resource. This Resource will be used to hold the instance of an implementation of org.LexGrid.LexBIG.Extensions.Query.Sort.
4. The server returns an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.SortClient object to the client. This is the client to the Sort Service Context. This object has a direct reference to the Resource created above. This SortClient implements org.LexGrid.LexBIG.Extensions.Query.Sort. The user now uses this client to make transparent Grid calls through the Service Context. Because this Sort implements org.LexGrid.LexBIG.Extensions.Query.Sort, API calls will look to the user as being identical to direct LexBIG API calls.

5. The client may continue to make statefull calls to the SortClient and the assigned Resource. For example, the client may call any method in org.LexGrid.LexBIG.Extensions.Query.Sort

   :

   Include Page
   RequestSortCompare Snippet RequestSortCompare

   _

   Snippet

6. These API calls are separate calls but statefully maintained on the server via the Resource.

Filter

http://informatics.mayo.edu/LexGrid/downloads/javadoc/org/LexGrid/LexBIG/Extensions/Query/Filter.htm^{Image Removed}LexBIG/Extensions/Query/Filter.htm

To construct a Filter, the user calls getFilter as described above. When the user creates a Filter through the API call getFilter, the server creates and stores the Sort server-side as a Resource. This Resource is associated with the client and will be accessible only by the client that created it.

...

1. The user requests a Filter using getFilter :

   Include Page
   RequestFilter Snippet RequestFilter

   _

   Snippet

2. The server calls the Distributed LexBIG getFilter method, returning to the server an implementation of org.LexGrid.LexBIG.Extensions.Query.Filter) object.
3. The server then creates an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Filter.service.globus.resource.FilterResource. This Resource will be used to hold the instance of an implementation of org.LexGrid.LexBIG.Extensions.Query.Filter.
4. The server returns an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.FilterClient object to the client. This is the client to the Filter Service Context. This object has a direct reference to the Resource created above. This FilterClient implements org.LexGrid.LexBIG.Extensions.Query.Filter. The user now uses this client to make transparent Grid calls through the Service Context. Because this Filter implements org.LexGrid.LexBIG.Extensions.Query.Filter, API calls will look to the user as being identical to direct LexBIG API calls.
5. The client may continue to make statefull calls to the FilterClient and the assigned Resource. For example, the client may call any method in org.LexGrid.LexBIG.Extensions.Query.Filter

   Include Page

   :

   RequestFilterMatch Snippet RequestFilterMatch

   _

   Snippet

6. These API calls are separate calls but statefully maintained on the server via the Resource.

ResolvedConceptReferencesIterator

http://informatics.mayo.edu/LexGrid/downloads/javadoc/org/LexGrid/LexBIG/Utility/Iterators/ResolvedConceptReferencesIterator.html^{Image Removed}

A ResolvedConceptReferencesIterator is created when a CodedNodeSet or CodedNodeGraph is resolved. It allows results to be returned from the server incrementally instead of all at once. When the user creates a ResolvedConceptReferencesIterator, the server creates and stores the ResolvedConceptReferencesIterator server-side as a Resource. This Resource is associated with the client and will be accessible only by the client that created it.

...

1. The user gets a ResolvedConceptReferencesIterator from a Resolve.
2. The server calls the Distributed LexBIG resolve method on the CodedNodeSet, returning to the server an implementation of org.LexGrid.LexBIG.Utility.Iterators.ResolvedConceptReferencesIterator object.
3. The server then creates an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.ResolvedConceptReferencesIterator.service.globus.resource.ResolvedConceptReferencesIteratorResource. This Resource will be used to hold the instance of an implementation of org.LexGrid.LexBIG.Utility.Iterators.ResolvedConceptReferencesIterator.
4. The server returns an org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.ResolvedConceptReferencesIteratorClient object to the client. This is the client to the ResolvedConceptReferencesIterator Service Context. This object has a direct reference to the Resource created above. This ResolvedConceptReferencesIteratorClient implements org.LexGrid.LexBIG.Utility.Iterators.ResolvedConceptReferencesIterator. The user now uses this client to make transparent Grid calls through the Service Context. Because this ResolvedConceptReferencesIterator implements org.LexGrid.LexBIG.Utility.Iterators.ResolvedConceptReferencesIterator, API calls will look to the user as being identical to direct LexBIG API calls.
5. The client may continue to make statefull calls to the ResolvedConceptReferencesIteratorClient and the assigned Resource. For example, the client may call any method in org.LexGrid.LexBIG.Utility.Iterators.ResolvedConceptReferencesIterator :

   Include Page
   ResolvedConceptReferencesIterator Snippet ResolvedConceptReferencesIterator

   _

   Snippet

6. These API calls are separate calls but statefully maintained on the server via the Resource.

...

If the URL is well-formed, proper connection is tested. If the connection attempt fails, a ConnectException is thrown containing the reason for the failure.

This example shows a typical connection to the LexEVS Grid Service, with the two potential Exceptions being caught and handled as necessary.

...

Security in the LexEVS Grid Service is implemented in the Distributed LexBIG layer. The information in this section explains how the LexEVS Grid Services utilize this security implementation. For more information about the Distributed LexBIG Security Implementation, see this documentation:

...

LexEVS Grid Services utilize this security implementation. For more information about the Distributed LexBIG Security Implementation, refer to LexBIG Access to Licensed Vocabulary Implementation, attached to the EVS API GForge documents archive.

LexEVS Grid Service Security

...

1. Connect to the LexBIG caGrid Service
   LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);

2. Build an org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name.

   Code Block
   CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setName("codingScheme");

3. Build an gov.nih.nci.evs.security.SecurityToken containing the security information for the desired Coding Scheme.

   Code Block
   SecurityToken token = new SecurityToken(); token.setAccessToken("securityToken");

4. Invoke the LexBIG caGrid service as follows: This will return a reference to a new "LexBIGServiceGrid" instance that is associated with the security properties that were passed in.
   LexBIGServiceGrid lbsg = lbs.setSecurityToken(codingScheme, token);

...

LexEVS Grid Services utilize the performance enhancements of the LexBIG API.
For more information about LexBIG performance (which LexEVS Grid Services are dependent on), see http://informatics.mayo.edu^{Image Removed} the Mayo Clinic website

Internationalization

Not Internationalized

...

Both the current version of LexEVS grid service and a previous version may be "in service" simultaneously if the corresponding underlying EVSAPI service is also "in service" to manage migration of clients.

System Testing

See LexEVS Grid Service Testing Documentation (LexEVS Grid Service System Testing in the Project Documents, Development Documents section)