Page History
...
Information regarding the software requirements LexEVS can be found in the LexEVS 5.x Installation Guide.
Setting
...
up your Environment
Information regarding the installation and configuration of the LexEVS environment can be found in the LexEVS 5.x Installation Guide.
...
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).
...
Lucene Queries are well documented and can be very powerful. The uninitiated user may need some background on their use however. The user should start here with the official Lucene Query Parser documentation.
Code Block |
---|
Link provided for historical purposes http://lucene.apache.org/java/2_3_2/queryparsersyntax.html |
Keep in mind that some LexEVS queries such as "startsWith" and "contains" use wild card searches under the covers, so that use of wild cards in this context can cause errors in searches involving these search types.
...
The examples and automated test programs provided by the LexEVS installation (see the file breakdown in the section, Overview of the Software #Overview) are available as additional reference materials.
...
The LexEVS Graphical User Interface, or GUI, is an optional component of the LexEVS install which will be in the /gui folder of the base LexEVS installation (see file breakdown in the section, Overview of the Software #Overview). The GUI is meant to provide a simple tool to test LexEVS API methods and quickly view the results; almost all public methods defined by the LexEVS API are supported. This guide provides a brief overview of how the GUI can aid programmers in writing code to the LexEVS API.
...
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 Web services interface can be used in any language-specific application that provides a mechanism for consuming XML Web services based on the Simple Object Access Protocol (SOAP). In those environments, connecting to caCORE LexEVS can be as simple as providing the end-point URL. Some platforms and languages require additional client-side code to handle the implementation of the SOAP envelope and the resolution of SOAP types.To view a list of packages that cater to different programming languages, visit http://www.w3.org/TR/SOAP/ and http://www.soapware.org/.
To maximize standards-based interoperability, the caCORE Web service conforms to the Web Services Interoperability Organization (WS-I) basic profile. The WS-I basic profile provides a set of non-proprietary specifications and implementation guidelines that enable interoperability between diverse systems. For more information about WS-I compliance, visit http://www.ws-i.org.
On the server side, Apache Axis is used to provide SOAP-based, inter-application communication. Axis provides the appropriate serialization and deserialization methods for the JavaBeans to achieve an application-independent interface. For more information about Axis, visit http://ws.apache.org/axis/.
Configuration
The caCORE/LexEVS WSDL file is located at http://lexevsapi.nci.nih.gov/lexevsapi50/services/lexevsapi50Service?wsdl. In addition to describing the protocols, ports, and operations exposed by the caCORE LexEVS Web service, this file can be used by a number of IDEs and tools to generate stubs for caCORE LexEVS objects. This enables code on different platforms to instantiate native objects for use as parameters and return values for the Web service methods. For more information on how to use the WSDL file to generate class stubs, consult the specific documentation for your platform.
The caCORE LexEVS Web services interface has a single end point called <tt>lexevsapi50Service</tt>, which is located at http://lexevsapi.nci.nih.gov/lexevsapi50/services/lexevsapi50Service. Client applications should use this URL to invoke Web service methods.
...
- GetXML - returns results in an XML format that can be parsed and consumed by most programming languages and many document authoring and management tools.
- GetHTML - presents result using a simple HTML interface that can be viewed by most modern Internet browsers.
Within the request string of the URL, the criteria element specifies the search criteria using XQuery-like syntax. Within this syntax, square brackets (\[ and \]) represent attributes and associated roles of a class, the _at_ symbol (@) signals an attribute name/value pair, and a forward slash character (/) specifies nested criteria. Within the request string of the URL, the criteria element specifies the search criteria using XQuery-like syntax. Within this syntax, square brackets ([ and ]) represent attributes and associated roles of a class, the at symbol (@) signals an attribute name/value pair, and a forward slash character specifies nested criteria. Wiki Markup
Criteria statements in XML-HTTP queries generally use the following syntax (although you can also build more complex statements):
...
A number of parameters, such as resultCounter
, pageSize
, and page
, are used internally by the system and are not designed to be set by the user.
Info | ||||
---|---|---|---|---|
| unmigrated-wiki-markup||||
When specifying attribute values in the query string, note that use of the following characters generates an error:
\ |
Distributed LexEVS API
Overview
...
The DLB environment will be configured on the caCORE LexEVS Server (http://lexevsapi.nci.nic.gov/lexevsapi50). This will give the server access to the LexEVS database and other resources. The client must therefore go through the caCORE LexEVS server to access any LexEVS data.
...
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
The following tables summarize 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).
Using the API
There are two (2) different interfaces for accessing the LexEVS Grid Services:
...
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:
|
...
The LexEVS Grid Service 4.2 URL is:
Code Block |
---|
Link provided for historical purposes http://lexevsapi.nci.nih.gov/wsrf/services/cagrid/LexEVSGridService |
...
] |
The service is also accessible via the caGRID Portal.
...
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 |
The following table lists the required NCICB/caBIG Libraries.
...
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.
Code Examples
Example Client and Service Calls and SOAP MessagesClient and Service Calls and SOAP Messages
See 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.
...
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 . Refer to the Service Contexts and State section in the Design and Architecture Guide 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:
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 |
...
The LexEVS Data Grid Service is a standard caGrid Data service based on the LexEVS 2009 Model.
caGrid Data Service Documentation
For complete documentation on caGrid Data Services, see caGrid Data Service Documentation.
Querying the System
To query the LexEVS Data Grid Service, use the standard caGrid CQL query method to compose queries. See caGrid Data Service API Documentation for more information.
...
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 | ||
---|---|---|
|