Page History
Scrollbar | ||
---|---|---|
|
...
Page info | ||||
---|---|---|---|---|
|
This document is intended for developers looking for more information regarding the LexEVS API.
...
Search Algorithm
Code Block |
---|
Name: LuceneQuery
Version: 1.0
Description: Search with the Lucene query syntax.
See http://lucene.apache.org/java/2_3_2/queryparsersyntax.html
|
Search Algorithm
Code Block |
---|
Name: DoubleMetaphoneLuceneQuery
Version: 1.0
Description: Search with the Lucene query syntax, using a 'sounds like' algorithm.
A search for 'atack' will get a hit on 'attack'
See http://lucene.apache.org/java/2_3_2/queryparsersyntax.html
|
Search Algorithm
Code Block |
---|
Name: StemmedLuceneQuery
Version: 1.0
Description: Search with the Lucene query syntax, using stemmed terms.
A search for 'trees' will get a hit on 'tree'
See http://lucene.apache.org/java/2_3_2/queryparsersyntax.html
|
Search Algorithm
Code Block |
---|
Name: startsWith
Version: 1.0
Description: Equivalent to 'term*' (case insensitive)
|
Search Algorithm
Code Block |
---|
Name: exactMatch
Version: 1.0
Description: Exact match (case insensitive)
|
Search Algorithm
Code Block |
---|
Name: contains
Version: 1.0
Description: Equivalent to '* term* *' - in other words - a trailing wildcard on a term
(but no leading wild card) and the term can appear at any position.
|
Search Algorithm
Code Block |
---|
Name: RegExp
Version: 1.0
Description: A Regular Expression query. Searches against the lowercased text, so a
regular expression that specifies an uppercase character will never return a match.
Additionally, this searches against the entire string as a single token, rather than
the tokenized string - so write your regular expression accordingly.
Supported syntax is documented here:
http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html
|
...
Programmers access coded concepts by acquiring first a node set or graph. After specifying optional restrictions, the nodes in this set or graph can be resolved as a list of ConceptReference objects which in turn contain references to one or more Concept objects. The following example provides a simple query of concept codes:
Include Page | ||||
---|---|---|---|---|
|
Service Metadata Retrieval
The LexEVS system maintains service metadata which can provide client programs with information about code system content and assigned copyright/licensing information. Below is an brief example showing how to access and print some of this metadata:
Include Page | ||||
---|---|---|---|---|
|
Combinatorial Queries
One of the most powerful features of the LexEVS architecture is the ability to define multiple search and sort criteria without intermediate retrieval of data from the LexEVS service. Consider the following code snippet:
Include Page | ||||
---|---|---|---|---|
|
This example shows a simple yet powerful query to search a code system based on a 'sounds like' match algorithm (the list of all available match algorithms can be listed using the 'ListExtensions -m' admin script).
...
LexEVS conforms to the caCORE SDK API - for more information see caCORE SDK 4.1 Programmer's Guide.
QueryOptions
QueryOptions are designed to give the user extra control over the query before it is sent to the system. QueryOptions may be used to modify a query in these ways:
- 'CodingScheme' - Restricts the query to the specified Coding Scheme, instead of querying every available Coding Scheme.
- CodingSchemeVersionOrTag' - Restricts the query to the specified Version of the Coding Scheme. Note that:
- This may NOT be specified without also specifying the 'CodingScheme' attribute.
- If left unset, it will default to the version of the Coding Scheme tagged as "PRODUCTION" in the system.
- 'SecurityTokens' - Security Tokens to use with the specified query. These Security Tokens are scoped to the current query ONLY. An subsequent queries will also need to specify the necessary Query Options.
'LazyLoad' - Some high use-case model Objects have bee 'lazy-load' enabled. This means that some attributes and associations of a model Object may not be fully populated when returned to the user. This allows for faster query times. This defaults to false, meaning that all attributes and associations will be eagerly fetched by the server and model Objects will always be fully populated. To enable this on applicable Objects, set to true.
Info title Note Lazy Loading may only be used in conjunction with specifying a Coding Scheme and Version with the 'CodingScheme' and 'CodingSchemeVersionOrTag' attributes above.
- 'ResultPageSize' - the page size of results to return. The higher the number, the more results the system will return to the user at once. The client will request the next group of query results transparenly. This parameter is useful for performance tuning. For example, if a query returns a result of10,000 Objects, a 'ResultPageSize' of '1000' would make 10 calls to the server returning a page of 1000 results each time. If left unset, this value will default to the default set Page Size
...
Example 4.1: Query By Example with No Query Options
Include Page | ||||
---|---|---|---|---|
|
The following table explains specific statements in the code by line number.
...
Example 4.2: Query By Example with Query Options
Include Page | ||||
---|---|---|---|---|
|
The following table explains specific statements in the code by line number.
...
The Mayo Clinic wrote the LexEVS 5.0 API. Documentation describing the LexEVS Service Model is available on the LexGRID Vocabulary Services for caBIG GForge site at https://gforge.nci.nih.gov/frs/?group_id=14archive.
LexEVS Installation and Configuration
...
The following code sample shows use of the DLB API to retrieve the list of available coding schemes in the LexEVS repository.
Include Page |
---|
...
|
...
LexEVS Analytical Grid Service API
...
This Interface may be acquired by instantiating LexBIGServiceAdapter with the Grid Service URL as a parameter.
Include Page | ||||
---|---|---|---|---|
|
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.
Include Page | ||||
---|---|---|---|---|
|
Method Descriptions
getCodingSchemeConcepts
...
Description: | Returns the set of all (or all active) concepts in the specified coding scheme. | ||||||||
---|---|---|---|---|---|---|---|---|---|
Input: | org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification | ||||||||
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.CodedNodeSet.stubs.types.CodedNodeSetReference | ||||||||
Exception: | RemoteException | ||||||||
Implementation Details: | Implementation:
|
...
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:
|
...
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.stubs.types.SortReference | ||||||
Exception: | RemoteException | ||||||
Implementation Details: | Implementation:
|
...
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:
|
...
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:
|
...
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:
|
...
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:
|
...
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:
|
...
Description: | Returns the node graph as represented in the particular relationship set in the coding scheme. | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Input: | org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification | ||||||||||
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices. | ||||||||||
Exception: | RemoteException | ||||||||||
Implementation Details: | Implementation:
|
...
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:
|
...
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:
|
...
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:
|
...
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.HistoryService.stubs.types.HistoryServiceReference | ||||||
Exception: | RemoteException | ||||||
Implementation Details: | Implementation:
|
...
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:
|
...
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:
|
...
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:
|
...
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.globus.org/toolkit/downloads/4.0.2
| ||
Apache Axis | axis-ant.jar | http://ws.apache.org/axis | ||
Apache Xerces | xercesImpl.jar | http://xerces.apache.org/xerces-j | ||
Apache Lucene | lucene-core-2.3.2.jar | http://lucene.apache.org/ | ||
ASM | 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 | 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 | 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 | http://www.springframework.org |
...
For your convenience, the required libraries are available for download here:
https://gforge.nci.nih.gov/docman/view.php/491/14401/lexevs42-gridsrvc-jarslibs.jar.
To programmatically access the LexEVS API Grid Service, these libraries need to be added to your local classpath.
...
Example Client and Service Calls and SOAP Messages
See http://gforge.nci.nih.gov/docman/view.php/491/14252/ TestClient.zip
Example API Usage
Example 1: Searching for concepts in NCI Thesaurus containing the string "Gene"
Include Page | ||||
---|---|---|---|---|
|
Error Handling
Error Connecting to LexEVS Grid Service
...
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.
...
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:
Code Block |
---|
Name: SecurityToken
Namespace: gme://caCORE.caCORE/3.2/gov.nih.nci.evs.security
Package: gov.nih.nci.evs.security |
...
A client establishes access to a secured vocabulary via the following Grid Service Calls:
Connect to the LexEVS caGrid Service
Code Block LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
Build an
org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification
to hold the Coding Scheme name.Code Block CodingSchemeIdentification codingScheme = new CodingSchemeIdentification(); codingScheme.setName "codingScheme";
Build a
gov.nih.nci.evs.security.SecurityToken
containing the security information for the desired Coding Scheme.Code Block SecurityToken token = new SecurityToken(); token.setAccessToken("securityToken");
Invoke the LexEVS caGrid service as follows:
Code Block LexBIGServiceGrid lbsg = lbs.setSecurityToken(codingScheme, token);
This will return a reference to a new "LexBIGServiceGrid" instance that is associated with the security properties that were passed in.
Info | ||
---|---|---|
| ||
It is important to note that the Grid Service |
...
Query for a Concept with a Specific Code
Example: Concept: C12345
Include Page | ||||
---|---|---|---|---|
|
Query for a Concept with Specific Presentation Text
Example: A concept with a namespace 'SNOMED Clinical Terms' that contains a Presentation equal to 'Heart'
Include Page | ||||
---|---|---|---|---|
|
Restrict Results to Specific Attributes
Example: Retrieve all of the 'localIds' of any 'SupportedAssociation' in the system.
Include Page | ||||
---|---|---|---|---|
|
...
|
...
|
Scrollbar | ||
---|---|---|
|
...