Page History

Versions Compared

Key

This line was added.
This line was removed.
Formatting was changed.

Wiki Markup
{scrollbar:icons=false} h1. {page-info:title} {section} {column} {panel:title=Contents of this Page} {toc:minLevel=2} {panel} {column} {column} {align:right}{include:Menu LexEVS 6.0 Programmers to Include}{align}{column} {section} h2. 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]. h2. ISO 21090 Model The LexEVS 6.0 Analytical Grid Services use a version of the LexGRID/LexBIG model, extended to support ISO 21090 Datatypes. Click the [adapted model link\|https://ncisvn.nci.nih.gov/svn/lexevs/base/v6/trunk/lexevs_service_cagrid_model/LexEVS-iso21090-model/master/iso21090]. h2. Using the API There are two (2) different interfaces for accessing the LexEVS Grid Services: # {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}}, or # {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}} * Option 1, org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter provides an interface for interacting with the LexEVS Grid Services. This Interface is intended to mirror the existing LexEVS API as much as possible. There is no object wrapping for semantic purposes on this interface. This allows existing applications of the LexEVS API to use Grid Services without code changes. This Interface may be acquired by instantiating LexBIGServiceAdapter with the Grid Service URL as a parameter. {code}LexBIGService lbs = new LexBIGServiceAdapter ("http://lexevsapi-analytical60.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService");{code} * Option 2, org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter also provides an interface for interacting with the LexEVS Grid Services. However, 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}LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter ("http://lexevsapi-analytical60.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService");{code} h2. Method Descriptions h3. getCodingSchemeConcepts {{getCodingSchemeConcepts(CodingSchemeIdentification, CodingSchemeVersionOrTag)}} \| 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: \| {_}Implementation{_}: * _Step 1_: Create a Resource on the server and populate it with the requested {{org.LexGrid.LexBIG.LexBIGService.CodedNodeSet}}. * _Step 2_: Return the Client Reference to the user. This Reference has the above {{org.LexGrid.LexBIG.LexBIGService.CodedNodeSet}} as a Resource. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.CodedNodeSetClient}} object is built from the above Reference. \| \| -\- \| {_}Sample Call{_}: * _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2_: Build a org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag containing the Version information for the desired Coding Scheme. {code} CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag(); csvt.setVersion("testVersion"); {code} * _Step 3_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name. {code} CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setCode(code); {code} * _Step 4_: Invoke the LexBIG caGrid service as follows: {code} CodedNodeSetGrid cns = lbs.getCodingSchemeConcepts(codingScheme, csvt); {code} \| h3. getFilter {{getFilter(ExtensionIdentification)}} \| 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: \| {_}Implementation{_}: * _Step 1_: Create a Resource on the server and populate it with the requested {{org.LexGrid.LexBIG.Extensions.Query.Filter}}. * _Step 2_: Return the Client Reference to the user. This Reference has the above {{org.LexGrid.LexBIG.Extensions.Query.Filter}} as a Resource. This client is a Service Context that allows the user to call regular {{org.LexGrid.LexBIG.Extensions.Query.Filter}} API calls through the grid service. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Filter.client.FilterClient}} object is built from the above Reference. This FilterClient implements the Interface {{org.LexGrid.LexBIG.Extensions.Query.Filter}}. This makes calling Grid Service Calls through {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Filter.client.FilterClient}} transparent to the end user. \| \| -\- \| {_}Sample Call{_}: * _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.ExtensionIdentification to hold the Extension name. {code} ExtensionIdentification extension = new ExtensionIdentification(); extension.setLexBIGExtensionName(name); {code} * _Step 3_: Invoke the LexEVS caGrid service as follows: {code} Filter filter = lbs.getFilter(extension); {code} \| h3. getSortAlgorithm {{getSortAlgorithm(ExtensionIdentification)}} \| 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.stubs.types.SortReference_ \| \| Exception: \| _RemoteException_ \| \| Implementation Details: \| {_}Implementation{_}: * _Step 1_: Create a Resource on the server and populate it with the requested org.LexGrid.LexBIG.Extensions.Query.Sort * _Step 2_: Return the Client Reference to the user. This Reference has the above {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Sort.client.SortClient}} as a Resource. This client is a Service Context that allows the user to call regular {{org.LexGrid.LexBIG.Extensions.Query.Sort}} API calls through the grid service. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Sort.client.SortClient}} object is built from the above Reference. This SortClient implements the Interface {{org.LexGrid.LexBIG.Extensions.Query.Sort}}. This makes calling Grid Service Calls through {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Sort.client.SortClient}} transparent to the end user. \| \| -\- \| {_}Sample Call{_}: * _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.ExtensionIdentification}} to hold the Extension name. {code} ExtensionIdentification extension = new ExtensionIdentification(); extension.setLexBIGExtensionName(name); {code} * _Step 3_: Invoke the LexEVS caGrid service as follows: {CODE} Filter filter = lbs.getSortAlgorithm(extension); {CODE} \| h3. getFilterExtensions {{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: \| {_}Implementation:_\\ _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call:_ * _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2:_ Invoke the LexEVS caGrid service as follows: {code} ExtensionDescriptionList extDescList = lbs.getFilterExtensions(); {code} \| h3. getServiceMetadata {{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._\\ _stubs.types.LexBIGServiceMetadataReference_ \| \| Exception: \| _RemoteException_ \| \| Implementation Details: \| {_}Implementation:_ * _Step 1:_ Create a Resource on the server and populate it with the requested {{org.LexGrid.LexBIG.LexBIGService.LexBIGServiceMetadata}}. * _Step 2:_ Return the LexBIGServiceMetadataClient to the user. This LexBIGServiceMetadataClient has the above {{org.LexGrid.LexBIG.LexBIGService.LexBIGServiceMetadata}} as a Resource. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.LexBIGServiceMetadataClient}} object is built from the above Reference. \| \| -\- \| {_}Sample Call:_' * _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2:_ Invoke the LexEVS caGrid service as follows: {code} LexBIGServiceMetadataGrid metadata = lbs.getServiceMetadata(); {code} \| h3. getSupportedCodingSchemes {{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: \| {_}Implementation:_\\ _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call:_ * _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2:_ Invoke the LexEVS caGrid service as follows: {code} CodingSchemeRenderingList csrl = lbs.getSupportedCodingSchemes(); {code} \| h3. getLastUpdateTime {{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: \| {_}Implementation:_\\ _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call:_ * _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2:_ Invoke the LexEVS caGrid service as follows: {code} Date date = lbs.getLastUpdateTime(); {code} \| h3. resolveCodingScheme {{resolveCodingScheme(CodingSchemeIdentification, CodingSchemeVersionOrTag)}} \| 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: \| {_}Implementation{_}:\\ _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call{_}: * _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name. {code} CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setCode(code); {code} * _Step 3_: Build a {{org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag}} containing the Version information for the desired Coding Scheme. {code} CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag(); csvt.setVersion("testVersion"); {code} * _Step 4_: Invoke the LexEVS caGrid service as follows: {code} CodedNodeSetGrid cns = lbs.resolveCodingScheme(codingScheme, csvt); {code} \| h3. getNodeGraph {{getNodeGraph(CodingSchemeIdentification, CodingSchemeVersionOrTag, RelationContainerIdentification)}} \| 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._ CodedNodeGraph.stubs.types.CodedNodeGraphReference \| \| Exception: \| _RemoteException_ \| \| Implementation Details: \| {_}Implementation{_}: * _Step 1_: Create a Resource on the server and populate it with the requested {{org.LexGrid.LexBIG.LexBIGService.CodedNodeGraph}}. * _Step 2_: Return the Client Reference to the user. This Reference has the above {{org.LexGrid.LexBIG.LexBIGService.CodedNodeGraph}} as a Resource. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.CodedNodeGraphClient}} object is built from the above Reference. \| \| -- \| {_}Sample Call{_}: * _Step 1_: Connect to the LexBIG caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name. {code} CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setCode(code); {code} * _Step 3_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag}} containing the Version information for the desired Coding Scheme. {code} CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag(); csvt.setVersion("testVersion"); {code} * _Step 4_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.RelationContainerIdentification}} containing the Relation Container information. {code} RelationContainerIdentification container = new RelationContainerIdentification(); container.setDc(name); {code} * _Step 5_: Invoke the LexEVS caGrid service as follows, providing String parameters for the desired Coding Scheme and Relationship Name: {code} CodedNodeGraphGrid cng = client.getNodeGraph(codingScheme, csvt, container); {code} \| h3. getMatchAlgorithms {{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: \| {_}Implementation:_\\ _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call:_ * _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2:_ Invoke the LexEVS caGrid service as follows: {code} ModuleDescriptionList mdl = lbs.getMatchAlgorithms(); {code} \| h3. getGenericExtensions {{getGenericExtensions()}} \| Description: \| Returns a description of all registered extensions used to implement application-specific behavior that is centrally accessible from a LexBIGService. {info:title=Note}nly generic extensions (base class GenericExtension) will be listed here. All other classes are retrievable at the appropriate interface point (filter, sort, etc).{info} \| \| Input: \| _none_ \| \| Output: \| _org.LexGrid.LexBIG.iso21090.DataModel.Collections.ExtensionDescriptionList_ \| \| Exception: \| _RemoteException_ \| \| Implementation Details: \| {_}Implementation:_\\ _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call:_ * _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2:_ Invoke the LexEVS caGrid service as follows: {code} ExtensionDescriptionList edl = lbs.getGenericExtensions(); {code} \| h3. getGenericExtension {{getGenericExtensions(ExtensionIdentification)}} \| 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: \| {_}Implementation{_}:\\ _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call{_}: * _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} {info:title=Note}Currently this method will return a LexBIGServiceConvenienceMethods instance.{info} * _Step 2_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.ExtensionIdentification}} to hold the Extension name. {code} ExtensionIdentification extension = new ExtensionIdentification(); extension.setLexBIGExtensionName("LexBIGServiceConvenienceMethods"); {code} * _Step 3_: Invoke the LexEVS caGrid service as follows: {code} LexBIGServiceConvenienceMethodsGrid lbscm = lbs.getGenericExtensions(extension); {code} * _Step 4_: Return the {{LexBIGServiceConvenienceMethodsClient}} to the user. This LexBIGServiceConvenienceMethodsClient has the above {{org.LexGrid.LexBIG.Extensions.Generic.LexBIGServiceConvenienceMethods}} as a Resource. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.CodedNodeGraphClient}} object is built from the above Reference. \| h3. getHistoryService {{getHistoryService(CodingSchemeIdentification)}} \| 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._\\ _HistoryService.stubs.types.HistoryServiceReference_ \| \| Exception: \| _RemoteException_ \| \| Implementation Details: \| {_}Implementation{_}: * _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results. * _Step 2_: Return the HistoryServiceClient to the user. This HistoryServiceClient has the above {{org.LexGrid.LexBIG.History.HistoryService}} as a Resource. This Client is a Service Context that allows the user to call regular {{org.LexGrid.LexBIG.History.HistoryService}} API calls through the grid service. HistoryServiceClient implements the Interface {{org.LexGrid.LexBIG.History.HistoryServic}}e. This makes calling Grid Service Calls through {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.HistoryService.client.HistoryServiceClient}} transparent to the end user. \| \| -\- \| {_}Sample Call{_}: * _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification}} to hold the Coding Scheme name. {code} CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setCode(code); {code} * _Step 3_: Invoke the LexEVS caGrid service as follows: {code} HistoryServiceGrid history = lbs.getHistoryService(codingScheme); {code} \| h3. getSortAlgorithms {{getSortAlgorithms(SortContext)}} \| 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: \| {_}Implementation{_}:\\ _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call{_}: * _Step 1_: Connect to the LexEVS caGrid Service using the org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter or org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2_: Invoke the LexEVS caGrid service as follows: {code} SortDescriptionList sortDescList = lbs.getSortAlgorithms(sortContext); {code} \| h3. resolveCodingSchemeCopyright {{resolveCodingSchemeCopyright(CodingSchemeIdentification)}} \| 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: \| {_}Implementation{_}:\\ _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call{_}: * _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification}} to hold the Coding Scheme name. {code} CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setCode(code); {code} * _Step 3_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag}} containing the Version information for the desired Coding Scheme. {code} CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag(); csvt.setVersion("testVersion"); {code} * _Step 4_: Invoke the LexEVS caGrid service as follows: {code} CodingSchemeCopyRight copyright = lbs.resolveCodingSchemeCopyright(codingScheme, csvt); {code} \| h3. setSecurityToken {{setSecurityToken(CodingSchemeIdentification, SecurityToken)}} \| 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: \| {_}Implementation{_}:\\ _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\ {_}Sample Call{_}: * _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}. {code} LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url); {code} * _Step 2_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name. {code} CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setName("codingScheme"); {code} * _Step 3_: Build an gov.nih.nci.evs.security.SecurityToken containing the security information for the desired Coding Scheme. {code} SecurityToken metaToken = new SecurityToken(); metaToken.setAccessToken("token"); {code} * _Step 4_: Invoke the LexEVS 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. {code} LexBIGServiceGrid lbsg = lbs.setSecurityToken(codingScheme, metaToken); {code} \| h2. Usage Instructions h3. Service URL {highlight:red}This link doesn't work in original.[LexEVS Grid Service 4.2 URL\|http://lexevsapi.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService].{highlight} The service is also accessible via: [caGRID Portal\|http://cagrid-portal.nci.nih.gov/web/guest/home;jsessionid=AEEE79C27E8EDB4EC0117C2CE8857D49] h3. 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 the following table. \|\| Product \|\| Jars \|\| License \|\| Home Page \|\| \| Apache WS-Addressing \| addressing-1.0.jar \| [adressing 1.0.LICENSE\|http://www.ogsa-dai.ac.uk/documentation/ogsadai-wsi-2.2-thirdparty/addressing-1.0.LICENSE] \| From Globus 4.0.2 Java Web Services Core lib directory: {highlight:red}This is not found.[http://www.globus.org/toolkit/downloads/4.0.2]{highlight} \\ Source available at {highlight:red}This is not found.[http://ws.apache.org/addressing]{highlight}. \| \| Apache Axis \| * axis-ant.jar * axis.jar * commons-pool-1.3.jar * commons-logging-1.1.jar * commons-lang-2.2.jar * commons-collections-3.2.jar * commons-codec-1.3.jar * log4j-1.2.8.jar * jaxrpc.jar * saaj.jar * wsdl4j.jar \| [axis-jars.LICENSE\|http://www.ogsa-dai.ac.uk/documentation/ogsadai-wsi-2.2/thirdparty/axis-jars.LICENSE] \| [http://ws.apache.org/axis] \| \| Apache Xerces \| xercesImpl.jar \| [xerces.LICENSE\|http://www.ogsa-dai.ac.uk/documentation/ogsadai-wsi-2.2/thirdparty/xerces.LICENSE] \| [http://xerces.apache.org/xerces-j] \| \| Apache Lucene \| * lucene-core-2.3.2.jar * lucene-regex-2.3.2.jar * lucene-snowball-2.3.2.jar \| [Lucene LICENSE\|http://www.apache.org/licenses/LICENSE-2.0] \| [http://lucene.apache.org/] \| \| ASM - all purpose Java bytecode manipulation and analysis framework \| asm.jar \| [http://asm.objectweb.org/license.html] \| [http://asm.objectweb.org/] \| \| Castor \| castor-1.2.jar \| [http://www.castor.org/license.html] \| [http://www.castor.org/index.html] \| \| Globus Toolkit \| cog-axis.jar\\ cog-jglobus.jar \| [http://www.globus.org/toolkit/legal/4.0/] \| \| Bouncy Castle Crypto APIs \| jce-jdk13-125.jar \| [http://www.bouncycastle.org/licence.html] \| [http://www.bouncycastle.org/] \| \| Open Permis \| wsrf_core.jar\\ wsrf_core_stubs.jar \| [http://www.openpermis.org/BSDlicenceKent.txt] \| [http://www.openpermis.org/] \| \| Apache\\ WSS4J \| wss4j.jar \| [http://ws.apache.org/wss4j/license.html] \| [http://ws.apache.org/wss4j/] \| \| Spring \| spring.jar \| [Spring LICENSE\|http://www.apache.org/licenses/LICENSE-2.0] \| [http://www.springframework.org] \| The NCICB software captured under the caBIG® umbrella are listed in the following table. \|\| 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 \| h3. Downloads For your convenience, the required libraries are available for download here: [required libraries\|https://gforge.nci.nih.gov/docman/view.php/491/14401/lexevs42-gridsrvc-jars.jar] In order to programmatically access the LexEVS API Grid Service, these libraries need to be added to your local classpath. h2. Code Examples h3. Example Client and Service Calls, and SOAP Messages See [zip file\|http://gforge.nci.nih.gov/docman/view.php/491/14252/TestClient.zip]. h3. Example API usage Example 1: Searching for concepts in NCI Thesaurus containing the string "Gene." {include:SearchingForConcepts_Snippet} h2. Error Handling h3. 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. A MalformedURIException is thrown in the case if a poorly-formed URL string. In this case, the exception is thrown before an attempt to connect is even made. 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. {include:LexGridServiceConnection_Snippet} This example shows a typical connection to the LexEVS Grid Service, with the two potential Exceptions being caught and handled as necessary. h3. 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. h3. 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). h2. Security Issues h3. LexEVS Grid Service Security Certain vocabulary content accessible through the LexEVS Grid Service may require extra authorization to access. Each client is required to supply its own access credentials via Security Tokens. These Security Tokens are implemented by a SecurityToken object: <font color="000FFF">Name: SecurityToken Namespace: gme://caCORE.caCORE/3.2/gov.nih.nci.evs.security Package: gov.nih.nci.evs.security</font> h3. Accessing Secure Content A client establishes access to a secured vocabulary via the following Grid Service Calls: * _Step 1:_ Connect to the LexEVS caGrid Service LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(<font color="000FFF">url</font>); * _Step 2:_ Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name. {code} CodingSchemeIdentification <font color="000FFF">codingScheme</font> = <font color="990066">new</font> CodingSchemeIdentification(); codingScheme.setName(<font color="000FFF">"codingScheme"</font>); {code} * _Step 3:_ Build an gov.nih.nci.evs.security.SecurityToken containing the security information for the desired Coding Scheme. <span style="background-color: #CCCCCC">SecurityToken</span> token = <font color="990066">new</font> <span style="background-color: #CCCCCC">SecurityToken</span> (); token.setAccessToken(<font color="000FFF">"securityToken"</font>); * _Step 4:_ Invoke the LexEVS 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. {code} LexBIGServiceGrid lbsg = lbs.setSecurityToken(<font color="000FFF">codingScheme, token</font>); {code} It is important to note that the Grid Service "setSecurityToken" returns an {{org.LexGrid.LexBIG.cagrid.LexEVSGridService.stubs.types .LexEVSGridServiceReference.LexEVSGridServiceReference}} object. This reference must be used to access the secured vocabularies. h3. Implementation Each call to "setSecurityToken" sets up a secured connection to Distributed LexEVS with the access privileges included in the SecurityToken parameter. The LexEVSGridServiceReference that is returned to the client contains a unique key identifier to the secure connection that has been created on the server. All subsequent calls the client makes through this LexEVSGridServiceReference will be made securely. If additional SecurityTokens are passed in through the "setSecurityToken" Grid Service, the additional security will be added and maintained. The "setSecurityToken" Grid Service is a stateful service. This means that after the client sets a SecurityToken, any subsequent call will be applied to that SecurityToken. Secure connections are not maintained on the server indefinitely, but are based on load conditions. The server will allow 30 unique secure connections to be set up for clients without any time limitations. As additional requests for secure connections are received by the server, connections will be released by the server on an 'oldest first' basis. No connection, however, may be released prior to 5 minutes after its creation. If no SecurityTokens are passed in by the client, a non-secure Distributed LexEVS connection will be used. The server maintains one (and only one) un-secured Distributed LexEVS connection that is shared by any client not requesting security. {info:title=Note}All non-secured information accessed by the LexEVS Grid Service is publicly available from NCICB and users are expected to follow the licensing requirements currently in place for accessing and using NCI EVS information.{info} {scrollbar:icons=false}

Wiki Markup

{scrollbar:icons=false}

h1. {page-info:title}
{section}
{column}
{panel:title=Contents of this Page}
{toc:minLevel=2}
{panel}
{column}
{column}
{align:right}{include:Menu LexEVS 6.0 Programmers to Include}{align}{column}
{section}


h2. 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].

h2. ISO 21090 Model

The LexEVS 6.0 Analytical Grid Services use a version of the LexGRID/LexBIG model, extended to support ISO 21090 Datatypes.

Click the [adapted model link|https://ncisvn.nci.nih.gov/svn/lexevs/base/v6/trunk/lexevs_service_cagrid_model/LexEVS-iso21090-model/master/iso21090].

h2. Using the API

There are two (2) different interfaces for accessing the LexEVS Grid Services:

# {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}}, or
# {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}

* *Option 1, org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter* provides an interface for interacting with the LexEVS Grid Services. This Interface is intended to mirror the existing LexEVS API as much as possible. There is no object wrapping for semantic purposes on this interface. This allows existing applications of the LexEVS API to use Grid Services without code changes.
This Interface may be acquired by instantiating LexBIGServiceAdapter with the Grid Service URL as a parameter.
{code}LexBIGService lbs = new LexBIGServiceAdapter
("http://lexevsapi-analytical60.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService");{code}
* *Option 2, org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter* also provides an interface for interacting with the LexEVS Grid Services. However, 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}LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter
("http://lexevsapi-analytical60.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService");{code}

h2. Method Descriptions


h3. getCodingSchemeConcepts

{{getCodingSchemeConcepts(CodingSchemeIdentification, CodingSchemeVersionOrTag)}}

| 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: | *{_}Implementation{_}*:
* _Step 1_: Create a Resource on the server and populate it with the requested {{org.LexGrid.LexBIG.LexBIGService.CodedNodeSet}}.
* _Step 2_: Return the Client Reference to the user. This Reference has the above {{org.LexGrid.LexBIG.LexBIGService.CodedNodeSet}} as a Resource. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.CodedNodeSetClient}} object is built from the above Reference. |
| -\- | *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2_: Build a org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag containing the Version information for the desired Coding Scheme.
{code}
CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag(); csvt.setVersion("testVersion");
{code}
* _Step 3_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name.
{code}
CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setCode(code);
{code}
* _Step 4_: Invoke the LexBIG caGrid service as follows:
{code}
CodedNodeSetGrid cns = lbs.getCodingSchemeConcepts(codingScheme, csvt);
{code} |


h3. getFilter

{{getFilter(ExtensionIdentification)}}

| 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: | *{_}Implementation{_}*:
* _Step 1_: Create a Resource on the server and populate it with the requested {{org.LexGrid.LexBIG.Extensions.Query.Filter}}.
* _Step 2_: Return the Client Reference to the user. This Reference has the above {{org.LexGrid.LexBIG.Extensions.Query.Filter}} as a Resource. This client is a Service Context that allows the user to call regular {{org.LexGrid.LexBIG.Extensions.Query.Filter}} API calls through the grid service. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Filter.client.FilterClient}} object is built from the above Reference. This FilterClient implements the Interface {{org.LexGrid.LexBIG.Extensions.Query.Filter}}. This makes calling Grid Service Calls through {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Filter.client.FilterClient}} transparent to the end user. |
| -\- | *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.ExtensionIdentification to hold the Extension name.
{code}
ExtensionIdentification extension = new ExtensionIdentification(); extension.setLexBIGExtensionName(name);
{code}
* _Step 3_: Invoke the LexEVS caGrid service as follows:
{code}
Filter filter = lbs.getFilter(extension);
{code} |

h3. getSortAlgorithm

{{getSortAlgorithm(ExtensionIdentification)}}

| 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.stubs.types.SortReference_ |
| Exception: | _RemoteException_ |
| Implementation Details: | *{_}Implementation{_}*:
* _Step 1_: Create a Resource on the server and populate it with the requested org.LexGrid.LexBIG.Extensions.Query.Sort
* _Step 2_: Return the Client Reference to the user. This Reference has the above {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Sort.client.SortClient}} as a Resource. This client is a Service Context that allows the user to call regular {{org.LexGrid.LexBIG.Extensions.Query.Sort}} API calls through the grid service. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Sort.client.SortClient}} object is built from the above Reference. This SortClient implements the Interface {{org.LexGrid.LexBIG.Extensions.Query.Sort}}. This makes calling Grid Service Calls through {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Sort.client.SortClient}} transparent to the end user. |
| -\- | *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.ExtensionIdentification}} to hold the Extension name.
{code}
ExtensionIdentification extension = new ExtensionIdentification(); extension.setLexBIGExtensionName(name);
{code}
* _Step 3_: Invoke the LexEVS caGrid service as follows:
{CODE}
Filter filter = lbs.getSortAlgorithm(extension);
{CODE} |

h3. getFilterExtensions

{{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: | *{_}Implementation:_*\\
 _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call:_*
* _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2:_ Invoke the LexEVS caGrid service as follows:
{code}
ExtensionDescriptionList extDescList = lbs.getFilterExtensions();
{code} |

h3. getServiceMetadata

{{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._\\
 _stubs.types.LexBIGServiceMetadataReference_ |
| Exception: | _RemoteException_ |
| Implementation Details: | *{_}Implementation:_*
* _Step 1:_ Create a Resource on the server and populate it with the requested {{org.LexGrid.LexBIG.LexBIGService.LexBIGServiceMetadata}}.
* _Step 2:_ Return the LexBIGServiceMetadataClient to the user. This LexBIGServiceMetadataClient has the above {{org.LexGrid.LexBIG.LexBIGService.LexBIGServiceMetadata}} as a Resource. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.LexBIGServiceMetadataClient}} object is built from the above Reference. |
| -\- | *{_}Sample Call:_*'
* _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2:_ Invoke the LexEVS caGrid service as follows:
{code}
LexBIGServiceMetadataGrid metadata = lbs.getServiceMetadata();
{code} |

h3. getSupportedCodingSchemes

{{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: | *{_}Implementation:_*\\
 _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call:_*
* _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2:_ Invoke the LexEVS caGrid service as follows:
{code}
CodingSchemeRenderingList csrl = lbs.getSupportedCodingSchemes();
{code} |

h3. getLastUpdateTime

{{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: | *{_}Implementation:_*\\
 _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call:_*
* _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2:_ Invoke the LexEVS caGrid service as follows:
{code}
Date date = lbs.getLastUpdateTime();
{code} |


h3. resolveCodingScheme

{{resolveCodingScheme(CodingSchemeIdentification, CodingSchemeVersionOrTag)}}

| 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: | *{_}Implementation{_}*:\\
 _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name.
{code}
CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setCode(code);
{code}
* _Step 3_: Build a {{org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag}} containing the Version information for the desired Coding Scheme.
{code}
CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag(); csvt.setVersion("testVersion");
{code}
* _Step 4_: Invoke the LexEVS caGrid service as follows:
{code}
CodedNodeSetGrid cns = lbs.resolveCodingScheme(codingScheme, csvt);
{code} |


h3. getNodeGraph

{{getNodeGraph(CodingSchemeIdentification, CodingSchemeVersionOrTag, RelationContainerIdentification)}}

| 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._
 CodedNodeGraph.stubs.types.CodedNodeGraphReference |
| Exception: | _RemoteException_ |
| Implementation Details: | *{_}Implementation{_}*:
* _Step 1_: Create a Resource on the server and populate it with the requested {{org.LexGrid.LexBIG.LexBIGService.CodedNodeGraph}}.
* _Step 2_: Return the Client Reference to the user. This Reference has the above {{org.LexGrid.LexBIG.LexBIGService.CodedNodeGraph}} as a Resource. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.CodedNodeGraphClient}} object is built from the above Reference. |
| -- | *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexBIG caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name.
{code}
CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setCode(code);
{code}
* _Step 3_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag}} containing the Version information for the desired Coding Scheme.
{code}
CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag(); csvt.setVersion("testVersion");
{code}
* _Step 4_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.RelationContainerIdentification}} containing the Relation Container information.
{code}
RelationContainerIdentification container = new RelationContainerIdentification(); container.setDc(name);
{code}
* _Step 5_: Invoke the LexEVS caGrid service as follows, providing String parameters for the desired Coding Scheme and Relationship Name:
{code}
CodedNodeGraphGrid cng = client.getNodeGraph(codingScheme, csvt, container);
{code} |


h3. getMatchAlgorithms

{{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: | *{_}Implementation:_*\\
 _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call:_*
* _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2:_ Invoke the LexEVS caGrid service as follows:
{code}
ModuleDescriptionList mdl = lbs.getMatchAlgorithms();
{code} |


h3. getGenericExtensions

{{getGenericExtensions()}}

| Description: | Returns a description of all registered extensions used to implement application-specific behavior that is centrally accessible from a LexBIGService.
{info:title=Note}nly generic extensions (base class GenericExtension) will be listed here. All other classes are retrievable at the appropriate interface point (filter, sort, etc).{info} |
| Input: | _none_ |
| Output: | _org.LexGrid.LexBIG.iso21090.DataModel.Collections.ExtensionDescriptionList_ |
| Exception: | _RemoteException_ |
| Implementation Details: | *{_}Implementation:_*\\
 _Step 1:_ Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call:_*
* _Step 1:_ Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2:_ Invoke the LexEVS caGrid service as follows:
{code}
ExtensionDescriptionList edl = lbs.getGenericExtensions();
{code} |


h3. getGenericExtension

{{getGenericExtensions(ExtensionIdentification)}}

| 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: | *{_}Implementation{_}*:\\
 _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
{info:title=Note}Currently this method will return a LexBIGServiceConvenienceMethods instance.{info}
* _Step 2_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.ExtensionIdentification}} to hold the Extension name.
{code}
ExtensionIdentification extension = new ExtensionIdentification(); extension.setLexBIGExtensionName("LexBIGServiceConvenienceMethods");
{code}
* _Step 3_: Invoke the LexEVS caGrid service as follows:
{code}
LexBIGServiceConvenienceMethodsGrid lbscm = lbs.getGenericExtensions(extension);
{code}
* _Step 4_: Return the {{LexBIGServiceConvenienceMethodsClient}} to the user. This LexBIGServiceConvenienceMethodsClient has the above {{org.LexGrid.LexBIG.Extensions.Generic.LexBIGServiceConvenienceMethods}} as a Resource. An {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.CodedNodeGraphClient}} object is built from the above Reference. |


h3. getHistoryService

{{getHistoryService(CodingSchemeIdentification)}}

| 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._\\
 _HistoryService.stubs.types.HistoryServiceReference_ |
| Exception: | _RemoteException_ |
| Implementation Details: | *{_}Implementation{_}*:
* _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.
* _Step 2_: Return the HistoryServiceClient to the user. This HistoryServiceClient has the above {{org.LexGrid.LexBIG.History.HistoryService}} as a Resource. This Client is a Service Context that allows the user to call regular {{org.LexGrid.LexBIG.History.HistoryService}} API calls through the grid service. HistoryServiceClient implements the Interface {{org.LexGrid.LexBIG.History.HistoryServic}}e. This makes calling Grid Service Calls through {{org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.HistoryService.client.HistoryServiceClient}} transparent to the end user. |
| -\- | *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification}} to hold the Coding Scheme name.
{code}
CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setCode(code);
{code}
* _Step 3_: Invoke the LexEVS caGrid service as follows:
{code}
HistoryServiceGrid history = lbs.getHistoryService(codingScheme);
{code} |


h3. getSortAlgorithms

{{getSortAlgorithms(SortContext)}}

| 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: | *{_}Implementation{_}*:\\
 _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexEVS caGrid Service using the org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter or org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2_: Invoke the LexEVS caGrid service as follows:
{code}
SortDescriptionList sortDescList = lbs.getSortAlgorithms(sortContext);
{code} |


h3. resolveCodingSchemeCopyright

{{resolveCodingSchemeCopyright(CodingSchemeIdentification)}}

| 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: | *{_}Implementation{_}*:\\
 _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification}} to hold the Coding Scheme name.
{code}
CodingSchemeIdentification codingScheme = new

CodingSchemeIdentification();

codingScheme.setCode(code);
{code}
* _Step 3_: Build an {{org.LexGrid.LexBIG.iso21090.DataModel.Core.CodingSchemeVersionOrTag}} containing the Version information for the desired Coding Scheme.
{code}
CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag(); csvt.setVersion("testVersion");
{code}
* _Step 4_: Invoke the LexEVS caGrid service as follows:
{code}
CodingSchemeCopyRight copyright = lbs.resolveCodingSchemeCopyright(codingScheme, csvt);
{code} |


h3. setSecurityToken

{{setSecurityToken(CodingSchemeIdentification, SecurityToken)}}

| 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: | *{_}Implementation{_}*:\\
 _Step 1_: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.\\
 *{_}Sample Call{_}*:
* _Step 1_: Connect to the LexEVS caGrid Service using the {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter}} or {{org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter}}.
{code}
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
{code}
* _Step 2_: Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name.
{code}
CodingSchemeIdentification codingScheme = new

CodingSchemeIdentification(); codingScheme.setName("codingScheme");
{code}
* _Step 3_: Build an gov.nih.nci.evs.security.SecurityToken containing the security information for the desired Coding Scheme.
{code}
SecurityToken metaToken = new SecurityToken();

metaToken.setAccessToken("token");
{code}
* _Step 4_: Invoke the LexEVS 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.
{code}
LexBIGServiceGrid lbsg = lbs.setSecurityToken(codingScheme, metaToken);
{code} |


h2. Usage Instructions


h3. Service URL

{highlight:red}This link doesn't work in original.[LexEVS Grid Service 4.2 URL|http://lexevsapi.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService].{highlight}

The service is also accessible via:

[caGRID Portal|http://cagrid-portal.nci.nih.gov/web/guest/home;jsessionid=AEEE79C27E8EDB4EC0117C2CE8857D49]


h3. 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 the following table.

|| Product || Jars || License || Home Page ||
| Apache WS-Addressing | addressing-1.0.jar | [adressing 1.0.LICENSE|http://www.ogsa-dai.ac.uk/documentation/ogsadai-wsi-2.2-thirdparty/addressing-1.0.LICENSE] | From Globus 4.0.2 Java Web Services Core lib directory: {highlight:red}This is not found.[http://www.globus.org/toolkit/downloads/4.0.2]{highlight} \\
 Source available at {highlight:red}This is not found.[http://ws.apache.org/addressing]{highlight}. |
| Apache Axis | * axis-ant.jar
* axis.jar
* commons-pool-1.3.jar
* commons-logging-1.1.jar
* commons-lang-2.2.jar
* commons-collections-3.2.jar
* commons-codec-1.3.jar
* log4j-1.2.8.jar
* jaxrpc.jar
* saaj.jar
* wsdl4j.jar | [axis-jars.LICENSE|http://www.ogsa-dai.ac.uk/documentation/ogsadai-wsi-2.2/thirdparty/axis-jars.LICENSE] | [http://ws.apache.org/axis] |
| Apache Xerces | xercesImpl.jar | [xerces.LICENSE|http://www.ogsa-dai.ac.uk/documentation/ogsadai-wsi-2.2/thirdparty/xerces.LICENSE] | [http://xerces.apache.org/xerces-j] |
| Apache Lucene | * lucene-core-2.3.2.jar
* lucene-regex-2.3.2.jar
* lucene-snowball-2.3.2.jar | [Lucene LICENSE|http://www.apache.org/licenses/LICENSE-2.0] | [http://lucene.apache.org/] |
| ASM - all purpose Java bytecode manipulation and analysis framework | asm.jar | [http://asm.objectweb.org/license.html] | [http://asm.objectweb.org/] |
| Castor | castor-1.2.jar | [http://www.castor.org/license.html] | [http://www.castor.org/index.html] |
| Globus Toolkit | cog-axis.jar\\
 cog-jglobus.jar | [http://www.globus.org/toolkit/legal/4.0/] |
| Bouncy Castle Crypto APIs | jce-jdk13-125.jar | [http://www.bouncycastle.org/licence.html] | [http://www.bouncycastle.org/] |
| Open Permis | wsrf_core.jar\\
 wsrf_core_stubs.jar | [http://www.openpermis.org/BSDlicenceKent.txt] | [http://www.openpermis.org/] |
| Apache\\
 WSS4J | wss4j.jar | [http://ws.apache.org/wss4j/license.html] | [http://ws.apache.org/wss4j/] |
| Spring | spring.jar | [Spring LICENSE|http://www.apache.org/licenses/LICENSE-2.0] | [http://www.springframework.org] |

The NCICB software captured under the caBIG® umbrella are listed in the following table.

|| 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 |


h3. Downloads

For your convenience, the required libraries are available for download here:

[required libraries|https://gforge.nci.nih.gov/docman/view.php/491/14401/lexevs42-gridsrvc-jars.jar]

In order to programmatically access the LexEVS API Grid Service, these libraries need to be added to your local classpath.


h2. Code Examples

h3. Example Client and Service Calls, and SOAP Messages

See [zip file|http://gforge.nci.nih.gov/docman/view.php/491/14252/TestClient.zip].

h3. Example API usage

*Example 1:* Searching for concepts in NCI Thesaurus containing the string "Gene."

{include:SearchingForConcepts_Snippet}

h2. Error Handling

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

A MalformedURIException is thrown in the case if a poorly-formed URL string. In this case, the exception is thrown before an attempt to connect is even made.

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.

{include:LexGridServiceConnection_Snippet}

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

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


h3. 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).

h2. Security Issues

h3. LexEVS Grid Service Security

Certain vocabulary content accessible through the LexEVS Grid Service may require extra authorization to access.  Each client is required to supply its own access credentials via Security Tokens. These Security Tokens are implemented by a SecurityToken object:

<font color="000FFF">Name: SecurityToken
Namespace: gme://caCORE.caCORE/3.2/gov.nih.nci.evs.security
Package: gov.nih.nci.evs.security</font>


h3. Accessing Secure Content

A client establishes access to a secured vocabulary via the following Grid Service Calls:

* _Step 1:_ Connect to the LexEVS caGrid Service
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(<font color="000FFF">url</font>);
* _Step 2:_ Build an org.LexGrid.LexBIG.iso21090.DataModel.cagrid.CodingSchemeIdentification to hold the Coding Scheme name.
{code}
CodingSchemeIdentification <font color="000FFF">codingScheme</font> = <font color="990066">*new*</font> CodingSchemeIdentification();
codingScheme.setName(<font color="000FFF">"codingScheme"</font>);
{code}
* _Step 3:_ Build an gov.nih.nci.evs.security.SecurityToken containing the security information for the desired Coding Scheme.
<span style="background-color: #CCCCCC">SecurityToken</span> token = <font color="990066">*new*</font> <span style="background-color: #CCCCCC">SecurityToken</span> ();
token.setAccessToken(<font color="000FFF">"securityToken"</font>);
* _Step 4:_ Invoke the LexEVS 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.
{code}
LexBIGServiceGrid lbsg = lbs.setSecurityToken(<font color="000FFF">codingScheme, token</font>);
{code}
It is important to note that the Grid Service "setSecurityToken" returns an {{org.LexGrid.LexBIG.cagrid.LexEVSGridService.stubs.types
.LexEVSGridServiceReference.LexEVSGridServiceReference}}
object. This reference must be used to access the secured vocabularies.

h3. Implementation

Each call to "setSecurityToken" sets up a secured connection to Distributed LexEVS with the access privileges included in the SecurityToken parameter. The LexEVSGridServiceReference that is returned to the client contains a unique key identifier to the secure connection that has been created on the server. All subsequent calls the client makes through this LexEVSGridServiceReference will be made securely. If additional SecurityTokens are passed in through the "setSecurityToken" Grid Service, the additional security will be added and maintained.

The "setSecurityToken" Grid Service is a stateful service. This means that after the client sets a SecurityToken, any subsequent call will be applied to that SecurityToken.

Secure connections are not maintained on the server indefinitely, but are based on load conditions. The server will allow 30 unique secure connections to be set up for clients without any time limitations. As additional requests for secure connections are received by the server, connections will be released by the server on an 'oldest first' basis. No connection, however, may be released prior to 5 minutes after its creation.

If no SecurityTokens are passed in by the client, a non-secure Distributed LexEVS connection will be used. The server maintains one (and only one) un-secured Distributed LexEVS connection that is shared by any client not requesting security.

{info:title=Note}All non-secured information accessed by the LexEVS Grid Service is publicly available from NCICB and users are expected to follow the licensing requirements currently in place for accessing and using NCI EVS information.{info}

{scrollbar:icons=false}

Content

Space Tools

Versions Compared

Old Version 9

New Version 10

Key