 |
Page History
| Scrollbar | ||
|---|---|---|
|
| Page info | ||||
|---|---|---|---|---|
|
| Panel | ||||
|---|---|---|---|---|
| ||||
|
| Code Block |
|---|
Some links are provided in this format for historical purposes. |
Introduction
This document is a section of the WIP LJJ LexEVS 5.x Programmer's Guide.
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.
Using the API
There are two (2) different interfaces for accessing the LexEVS Grid Services:
org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter, ororg.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 Block LexBIGService lbs = new LexBIGServiceAdapter ("http://lexevsapi-analytical50.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService");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 Block LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter ("http://lexevsapi-analytical50.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService);
Method Descriptions
getCodingSchemeConcepts
...
getCodingSchemeConcepts(CodingSchemeIdentification,
...
CodingSchemeVersionOrTag)
Description: | Returns the set of all (or all active) concepts in the specified coding scheme. | ||||||
|---|---|---|---|---|---|---|---|
Input: | org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification, org.LexGrid.LexBIG.DataModel.Core.CodingSchemeVersionOrTag | ||||||
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.CodedNodeSet.stubs.types.CodedNodeSetReference | ||||||
Exception: | RemoteException | ||||||
Implementation Details: | Implementation:
| ||||||
Sample Call; | Sample Call:
|
getFilter
...
getFilter(ExtensionIdentification)
Description: | Returns an instance of the filter extension registered with the given name. | ||||||
|---|---|---|---|---|---|---|---|
Input: | org.LexGrid.LexBIG.DataModel.cagrid.ExtensionIdentification | ||||||
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Filter.stubs.types.FilterReference | ||||||
Exception: | RemoteException | ||||||
Implementation Details: | Implementation :
| ||||||
Sample Call: | Sample Call:
|
getSortAlgorithm
...
getSortAlgorithm(ExtensionIdentification)
Description: | Returns an instance of the sort extension registered with the given name. | ||||||
|---|---|---|---|---|---|---|---|
Input: | org.LexGrid.LexBIG.DataModel.cagrid.ExtensionIdentification | ||||||
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.Sort. | ||||||
Exception: | RemoteException | ||||||
Implementation Details: | Implementation:
| ||||||
Sample Call: | Sample Call:
|
getFilterExtensions
...
getFilterExtensions()
Description: | Returns a description of all registered extensions used to provide additional filtering of query results. | ||||
|---|---|---|---|---|---|
Input: | none | ||||
Output | org.LexGrid.LexBIG.DataModel.Collections.ExtensionDescriptionList | ||||
Exception: | RemoteException | ||||
Implementation Details: | Implementation:
|
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. | ||||
Exception: | RemoteException | ||||
Implementation Details: | Implementation:
| ||||
Sample Call: | Sample Call: '
|
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.DataModel.Collections.CodingSchemeRenderingList | ||||
Exception: | RemoteException | ||||
Implementation Details: | Implementation:
|
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:
|
resolveCodingScheme
...
resolveCodingScheme(CodingSchemeIdentification,
...
CodingSchemeVersionOrTag)
Description: | Return detailed coding scheme information given a specific tag or version identifier. | ||||||
|---|---|---|---|---|---|---|---|
Input: | org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification, org.LexGrid.LexBIG.DataModel.Core.CodingSchemeVersionOrTag | ||||||
Output: | org.LexGrid.codingSchemes.CodingScheme | ||||||
Exception: | RemoteException | ||||||
Implementation Details: | Implementation:
|
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.DataModel.cagrid.CodingSchemeIdentification, org.LexGrid.LexBIG.DataModel.Core.CodingSchemeVersionOrTag, org.LexGrid.LexBIG.DataModel.cagrid.RelationContainerIdentification | |||||||||||
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices. | |||||||||||
Exception: | RemoteException | |||||||||||
Implementation Details: | Implementation:
| |||||||||||
 | Sample Call: | Sample Call :
|
getMatchAlgorithms
...
getMatchAlgorithms()
Description: | Returns the node graph as represented in the particular relationship set in the coding scheme. | ||||
|---|---|---|---|---|---|
Input: | none | ||||
Output: | org.LexGrid.LexBIG.DataModel.Collections.ModuleDescriptionList | ||||
Exception: | RemoteException | ||||
Implementation Details: | Implementation:
|
getGenericExtensions
...
getGenericExtensions()
Description: | Returns a description of all registered extensions used to implement application-specific behavior that is centrally accessible from a LexBIGService.
| |||||
|---|---|---|---|---|---|---|
Input: | none | |||||
Output: | org.LexGrid.LexBIG.DataModel.Collections.ExtensionDescriptionList | |||||
Exception: | RemoteException | |||||
Implementation Details: | Implementation:
|
getGenericExtension
...
getGenericExtensions(ExtensionIdentification)
Description: | Returns an instance of the application-specific extension registered with the given name. | |||||||
|---|---|---|---|---|---|---|---|---|
Input: | org.LexGrid.LexBIG.DataModel.cagrid.ExtensionIdentification | |||||||
Output: | org.LexGrid.LexBIG.DataModel.Collections.SortDescriptionList | |||||||
Exception: | RemoteException | |||||||
Implementation Details: | Implementation :
|
getHistoryService
...
getHistoryService(CodingSchemeIdentification)
Description: | Resolve a reference to the history api servicing the given coding scheme. | ||||
|---|---|---|---|---|---|
Input: | org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification | ||||
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices. | ||||
Exception: | RemoteException | ||||
Implementation Details: | Implementation :
| ||||
Sample Call: | Sample Call :
|
getSortAlgorithms
...
getSortAlgorithms(SortContext)
Description: | Returns a description of all registered extensions used to provide additional filtering of query results. | ||
|---|---|---|---|
Input: | org.LexGrid.LexBIG.DataModel.InterfaceElements.types.SortContext | ||
Output: | org.LexGrid.LexBIG.DataModel.Collections.SortDescriptionList | ||
Exception: | RemoteException | ||
Implementation Details: | Implementation :
|
resolveCodingSchemeCopyright
resolveCodingSchemeCopyright(CodingSchemeIdentification)
...
Description: |
|---|
...
Return |
...
coding |
...
scheme |
...
copyright |
...
given |
...
a |
...
specific |
...
tag |
...
or |
...
version |
...
identifier. |
...
Input: |
|---|
...
org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification |
...
Output: |
|---|
...
org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeCopyRight |
...
Exception: | RemoteException |
|---|---|
Implementation Details: | Implementation :
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
setSecurityToken
setSecurityToken(CodingSchemeIdentification, SecurityToken)
...
...
Description: |
|---|
...
Sets |
...
the |
...
Security |
...
Token |
...
for |
...
the |
...
given |
...
Coding |
...
Scheme. |
...
Input: |
|---|
...
org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification, |
...
gov.nih.nci.evs.security.SecurityToken |
...
Output: |
|---|
...
org.LexGrid.LexBIG.cagrid.LexEVSGridService.stubs.types.LexEVSGridServiceReference.LexEVSGridServiceReference |
...
Exception: |
|---|
...
RemoteException | |
Implementation Details: | Implementation :
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
| Code Block |
|---|
* _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.
|
...
|
...
Usage Instructions
Service URL
...
The LexEVS Grid Service 4.2 URL is:
http://lexevsapi.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService.
...
The
...
service
...
is
...
also
...
accessible
...
via
...
the
...
...
...
.
Required Libraries
The libraries required for programmatic access to the LexEVS Grid Service are listed in the tables below. The 3rd Party Software Libraries required for use of the LexEVS API Grid Service are listed in Table 4.1 and the NCICB software captured under the caBIG® umbrella are listed in the following table.
Product | Jars | License | Home Page |
|---|---|---|---|
Apache WS-Addressing | addressing-1.0.jar |
...
...
...
From Globus 4.0.2 Java Web Services Core lib directory: http://www. |
...
...
|
...
Apache Axis |
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
...
Apache Xerces | xercesImpl.jar |
...
...
...
...
...
Apache Lucene |
|
...
|
...
|
...
...
...
...
...
...
...
ASM - all purpose Java bytecode manipulation and analysis framework | asm.jar |
...
...
Castor | castor-1.2.jar |
...
|
...
|
...
Globus Toolkit |
|
...
|
...
...
Bouncy Castle Crypto APIs | jce-jdk13-125.jar |
...
...
...
Open Permis |
|
...
|
...
...
...
Apache WSS4J | wss4j.jar |
...
...
...
Spring | spring.jar |
...
...
...
...
...
...
The
...
following
...
table
...
lists
...
the
...
NCICB/caBIG
...
Libraries.
...
Library | Associated JARs |
|---|---|
caGrid Software Libraries | caGrid-ServiceSecurityProvider-client-1.2.jar |
...
 | caGrid-ServiceSecurityProvider-common-1.2.jar |
...
 | caGrid-ServiceSecurityProvider-stubs-1.2.jar |
...
 | caGrid-core-1.2.jar |
...
 | caGrid-metadata-common-1.2.jar |
...
 | caGrid-metadata-data-1.2.jar |
...
 | caGrid-metadata-security-1.2.jar |
...
 | caGrid-metadatautils-1.2.jar |
...
EVS |
...
API |
...
Libaries |
...
evsapi42-beans.jar |
...
 | evsapi42-framework.jar |
...
LexEVS |
...
Grid |
...
Service |
...
Client |
...
Library |
...
LexEVSGridService-client.jar |
...
LexEVS |
...
Grid |
...
Service |
...
Stubs |
...
LexEVSGridService-stubs.jar |
...
LexEVS |
...
Grid |
...
Service |
...
Common |
...
LexEVSGridService-common.jar |
...
LexEVS |
...
Grid |
...
Service |
...
Service |
...
LexEVSGridService-service.jar |
...
LexEVS |
...
Grid |
...
Service |
...
Tests |
...
LexEVSGridService-tests.jar |
...
caCORE |
...
SDK |
...
Library |
...
sdk-client-framework.jar |
...
LexEVS |
...
API |
...
lexbig.jar |
...
Custom |
...
Castor |
...
Serializer |
...
castor-bean-serializer.jar |
...
Downloads
For your convenience, the required libraries are available for download here:
...
...
In
...
order
...
to
...
programmatically
...
access
...
the
...
LexEVS
...
API
...
Grid
...
Service,
...
these
...
libraries
...
need
...
to
...
be
...
added
...
to
...
your
...
local
...
classpath.
...
Code Examples
Example Client and Service Calls and SOAP Messages
See TestClient.zip
Example API Usage
Example 1: Searching for concepts in NCI Thesaurus containing the string "Gene"
| Include Page | ||||
|---|---|---|---|---|
|
Error Handling
Error Connecting to LexEVS Grid Service
When connecting through the Java Client, java.net.ConnectException and org.apache.axis.types.URI.MalformedURIException
...
may
...
be
...
thrown
...
upon
...
an
...
unsuccessful
...
attempt
...
to
...
connect.
...
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 Page | ||||
|---|---|---|---|---|
|
This example shows a typical connection to the LexEVS Grid Service, with the two potential Exceptions being caught and handled as necessary.
LexEVS Errors
LexEVS errors will be forwarded through the Distributed LexEVS layer and then on to the Grid layer. Input parameters, along with any other LexEVS (or Distributed LexEVS) errors will be detected on the server, not the client, and forwarded. All Generic LexEVS (or Distributed LexEVS) errors will be forwarded via a RemoteException, with the cause of the error and underlying LexEVS error message included.
Invalid Service Context Access
Service Context Services are not meant to be called directly. If the client attempts to do so, an org.LexGrid.LexBIG.cagrid.LexEVSGridService.CodedNodeSet.stubs.types.InvalidServiceContextAccess
...
Exception
...
will
...
be
...
thrown.
...
This
...
indicates
...
a
...
call
...
was
...
made
...
to
...
a
...
Service
...
Context
...
without
...
obtaining
...
a
...
Service
...
Context
...
Reference
...
via
...
the
...
Main
...
Service
...
(see
...
the
...
above
...
section
...
Service
...
Contexts
...
and
...
State
...
for
...
more
...
information).
...
Security
...
Issues
...
LexEVS
...
Grid
...
Service
...
Security
...
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:
...
{Name:
...
SecurityToken
...
Namespace:
...
gme://caCORE.caCORE/3.2/gov.nih.nci.evs.security
...
Package:
...
gov.nih.nci.evs.security
...
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(url);
...
Step
...
2:
...
Build
...
an
...
org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification
...
to
...
hold
...
the
...
Coding
...
Scheme
...
name.
...
Code Block CodingSchemeIdentification codingScheme = new CodingSchemeIdentification();
...
codingScheme.setName("codingScheme");
...
Step
...
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");
...
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 Block LexBIGServiceGrid lbsg = lbs.setSecurityToken(codingScheme, token);
...
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.
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.
...
