 |
Page History
<?xml version="1.0" encoding="utf-8"?>
<html>
Overview
This document is intended for developers looking for more information regarding the LexEVS API.
Software Requirements
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.
LexEVS API
Programming interfaces for the system fall into three primary categories:
...
Utility classes, such as those implementing iterator support, are provided by the system to provide convenience and optimize the handling of resources accessed through the runtime.
Core Services
Provides central entry points for programmatic access to system features and data.
...
Interface to perform system-wide query over optionally loaded metadata for loaded code systems and providers.
Service Extensions
Provides registration and lookup for pluggable system features.
...
Marks a class as an extension to the LexEVS application programming interface. This allows for centralized registration, lookup, and access to defined functions.
Query Extensions
Query extensions provide the ability to further constrain or manage query results.
...
Allows for unique sorting of query results. This interface provides a comparator to evaluate order of any two given items from the result set.
Load Extensions
Load extensions are responsible for the validation and import of content to the LexEVS repository. Vocabularies may be imported from a variety of formats including LexGrid canonical XML, NCI Thesaurus (OWL), and NCI MetaThesaurus (UMLS RRF).
...
Load an OBO change history file.
Export Extensions
Export extensions are responsible for the export of content from the LexEVS repository to other representative vocabulary formats.
...
Exports content to OWL XML format.
Index Extensions
Index extensions are built to optimize the finding, sorting and matching of query results.
...
It is the responsibility of the loader to properly interpret each index it services by name, version, and provider.
Generic Extensions
Generic extensions provides a mechanism to register application-specific extensions for reference and reuse.
...
Convenience methods to be implemented as a generic extension of the LexEVS API.
Utilities
Defines helper classes externalized by the LexEVS API.
Iterators
Iterators are used to provide controlled resolution of query results.
...
An iterator for retrieving resolved coding scheme references.
Search Algorithms
Supported LexEVS Search Algorithms
...
| Panel |
|---|
Name: RegExp |
Additional Utility Classes
Note: It is highly recommended that all LexEVS programmers familiarize themselves with the classes contained in the <tt>org.LexGrid.LexBIG.Utility</tt> package. Many useful features are provided in an effort to increase approachability of the API and assist the programmer in common tasks. This package currently contains the following classes:
<u>Constructors</u> - Helper class to ease creating common objects.
<u>ConvenienceMethods</u> - One-stop shopping for convenience methods that have been implemented against the LexEVS API.
<u>LBConstants</u> - Provides constants for use in the LexEVS API.
<u>ObjectToString</u> - Provides centralized formatting of LexEVS Objects to String representations.
Code Examples
Concept Resolution
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 <tt>ConceptReference</tt> objects which in turn contain references to one or more Concept objects. The following example provides a simple query of concept codes:
:ConceptResolution_Snippet
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:
:ServiceMetadataRetrieval_Snippet
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:
...
Note: While this section provides one example of combining criteria, this same pattern can be applied to many of the <tt>CodedNodeSet</tt> and <tt>CodedNodeGraph</tt> operations. It is strongly recommended that programmers familiarize themselves with this programming model and its application.
Additional Resources
The examples and automated test programs provided by the LexEVS installation (see file breakdown in VKC:Overview of the Software) are available as additional reference materials.
LexEVS GUI
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 VKC:Overview of the Software). 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.
Note: The LexEVS GUI supports both administrative and test functions. Please refer to the LexEVS Administrator's Guide for instructions on using the GUI as an administration tool.
Launching the GUI
Depending on the operating systems that you selected at installation time, you should have one or more of the following programs in the <tt>/gui</tt> folder:
...
Launch the GUI by executing the appropriate script for your platform. You will be presented with an application that looks like this:
Overview
The upper section of the GUI shows all of the code systems currently loaded, along with corresponding metadata. The lower section of the GUI is used to combine, restrict and resolve Code Sets and Code Graphs.
...
Note: The menu options are used primarily for administrative functions, and are covered in detail by the LexEVS Administrator's Guide. In addition, all of the disabled buttons in the top half of the application are used for administrative functions, and are also described in the LexEVS Administrator's Guide.
Creating New Queries
There are four buttons on the top half that are of interest for creating queries.
*Refresh - This button causes the LexEVS GUI to reread the available terminologies and their respective metadata. This can be useful when using the GUI to view a LexEVS environment that is being modified by another process.
*Get History - If a terminology with available history data is selected, this button opens a history browser to view it via the NCI history API. This option is currently only applicable when working with the NCI Thesaurus terminology.
*Get Code Set -This button causes the selected terminology to be added to the lower left section of the GUI as a code set - which is noted by a 'CS' prefix.
*Get Code Graph -This button causes the selected terminology to be added to the lower left section of the GUI as a code graph - which is noted by a 'CG' prefix.
Customizing Queries
After selecting a code system and clicking on Get Code Set or Get Code Graph, a row will be added to the lower left section of the GUI for each click. There are seven buttons in the lower left section that allow combinatorial logic between the code sets in the lower left.
*Union - This button is enabled if two Code Sets or two Code Graphs are selected in the lower left. Clicking the button creates a new virtual Code Set or Code Graph which represents the Boolean union of the two selected items. All restrictions applied to the individual items still apply.
*Intersection - This button is enabled if two Code Sets or two Code Graphs are selected in the lower left. Clicking the button creates a new virtual Code Set or Code Graph which represents the Boolean intersection of the two selected items. All restrictions applied to the individual items still apply.
*Difference - This button is enabled if two Code Sets or two Code Graphs are selected in the lower left. Clicking the button creates a new virtual Code Set which represents the Boolean difference of the two selected Code Sets. All restrictions applied to the individual items still apply.
*Restrict to Codes - This button is enabled if a Code Set and a Code Graph are selected in the lower left. Clicking the button creates a new virtual Code Graph which will be restricted to concept codes occurring in the selected Code Set.
*Restrict to Source Codes - This button is enabled if a Code Set and a Code Graph are selected in the lower left. Clicking the button creates a new virtual Code Graph which will have its source codes restricted to codes occurring in the selected Code Set.
*Restrict to Target Codes - This button is enabled if a Code Set and a Code Graph are selected in the lower left. Clicking the button creates a new virtual Code Graph which will have its target codes restricted to codes occurring in the selected Code Set.
*Remove - This button is enabled if any Code Set or Code Graph (or virtual Code Set or Code Graph) is selected in the lower left. Clicking the button will remove the selected item from the list.
The lower right section of the GUI is used to apply restrictions to Code Sets or Code Graphs, and set the variables that need to be passed into the resolve method.
Working with Code Sets
If a Code Set is selected in the lower left, then the lower right section will look like this:
...
The top drop down list indicates the type of restriction to add. The rest of the dialog box will change depending on the type of restriction selected. All required parameters for the selected restriction type will be presented.
*Edit - This button is enabled when a restriction is selected. Clicking it allows revision of an existing restriction.
*Remove -This button is enabled when a restriction is selected. Clicking it removes the selected restriction.
*Only Include Active Codes - This check box indicates whether or not to include inactive codes when resolving the selected code set.
*Set Sort Options - This button will bring up a dialog box to choose the desired sort order of the results.
*Resolve Code Set - This button will bring up a result window where the Code Set will be resolved and displayed.
Working with Code Graphs
If you select a Coded Node Graph in the lower left section of the LexEVS GUI, the lower right section will look like this:
...
The lower half provides additional variables applicable when resolving a Coded Node Graph. For further explanation of these options, refer to the LexEVS API documentation.
*Relation Container (Optional) - Indicates the CodingScheme Relations container to query. The drop down list is populated with allowable selections.
*Focus Code (Optional) - Provides the code used as a starting point when resolving graph relations. This value is required for some queries, depending on the nature of requested associations.
*Focus Code System (Optional) - Indicates the code system containing the Focus Code. The drop down list is populated with allowable selections.
*Max Resolve Depth - How many levels deep should the graph be resolved? -1 is the default, which does not limit the depth.
*Resolve Forward - Populate codes downstream from the focus node (based on directionality defined by each association).
*Resolve Backward - Populate codes upstream from the focus node (based on directionality defined by each association).
*Set Sort Options - This button will bring up a dialog box to choose the desired sort order of the results.
*Resolve As Set - Resolves and displays the graph results as a coded node set.
*Resolve As Graph -Resolves and displays the graph results.
Viewing Query Results
Clicking on the Resolve buttons for either a Coded Node Set or a Coded Node Graph will bring up the Result Browser window:
...
- <span style="font-variant: small-caps;"> Left Click + Mouse Movement</span> - Drags the view.
- <span style="font-variant: small-caps;"> Right Click + Mouse Movement Up Or Down</span> - Zooms in or out.
- <span style="font-variant: small-caps;">Right Click (on white space)</span> - Zooms the view to fit.
- <span style="font-variant: small-caps;">Ctrl + '+'</span> - Expands the graph connection lines
- <span style="font-variant: small-caps;">Ctrl + '-'</span> - Contracts the graph connection lines
- <span style="font-variant: small-caps;">Ctrl + '1' (or '2' or '3' or '4')</span> - Changes the orientation of the graph.
LexEVS caCORE Data Services API
Interacting with caCORE LexEVS
This chapter describes the components of the caCORE LexEVS and the service interface layer provided by the EVS API architecture. It gives examples of how to use the EVS APIs. It also describes the Distributed LexEVS API and the Distributed LexEVS APIAdapter.
caCORE LexEVS Components
The caCORE LexEVS API is a public domain, open source wrapper that provides full access to the LexEVS Terminology Server. LexEVS hosts the NCI Thesaurus, the NCI Metathesaurus, and several other vocabularies. Java clients accessing the NCI Thesaurus and Metathesaurus vocabularies communicate their requests via the open source caCORE LexEVS APIs, as shown in Overview of the caCORE LexEVS 4.0 release components.
...
Note: | The DLB Adapter is not intended to represent a complete set of convenience methods. As part of the caCORE LexEVS 5.x release, the intention is that users will work with the DLB API and suggest useful methods of convenience to the EVS Development Team. |
|---|
LexEVS Data Sources
The LexEVS data source is the open source LexEVS terminology server. EVS clients interface with the LexEVS API to retrieve desired vocabulary data. The EVS provides the NCI with services and resources for controlled biomedical vocabularies, including the NCI Thesaurus and the NCI Metathesaurus.
NCI Thesaurus
The NCI Thesaurus is composed of over 27,000 concepts represented by about 78,000 terms. The Thesaurus is organized into 18 hierarchical trees covering areas such as Neoplasms, Drugs, Anatomy, Genes, Proteins, and Techniques. These terms are deployed by the NCI in its automated systems for uses such as key wording and database coding.
NCI Metathesaurus
The NCI Metathesaurus maps terms from one standard vocabulary to another, facilitating collaboration, data sharing, and data pooling for clinical trials and scientific databases. The Metathesaurus is based on the Unified Medical Language System (UMLS) developed by the National Library of Medicine (NLM). It is composed of over 70 biomedical vocabularies.
Interfaces
Main interfaces included in the LexEVSAPI package.
LexEVSDistributed
The Distributed LexEVS Portion of LexEVSAPI. This interface is a framework for calling LexEVS API methods remotely, along with enforcing security measures. JavaDoc
LexEVSDataService
The caCORE-SDK Data Service Portion of LexEVSAPI. This extends on the caCORE ApplicationService to provide additional Query Options. JavaDoc
LexEVSService
The Main LexEVSAPI Interface. This includes support for caCORE-SDK Data Service calls as well as remote LexBIG API calls. JavaDoc
Search Paradigm
The caCORE LexEVS architecture includes a service layer that provides a single, common access paradigm to clients that use any of the provided interfaces. As an object-oriented middleware layer designed for flexible data access, caCORE LexEVS relies heavily on strongly typed objects and an object-in/object-out mechanism.
...
Figure 4.4 - Sequence diagram - caCORE 4.0 LexEVS API search mechanism
Querying the System
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:
a. This may NOT be specified without also specifying the 'CodingScheme' attribute.
b. 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.
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
Examples of Use
Example 4.1: Query By Example with No Query Options
...
_Table 4.7 - Explanation of statements in : _
Web Services API
The caCORE LexEVS Web Services API enables access to caCORE LexEVS data and vocabulary data from development environments where the Java API cannot be used, or where use of XML Web services is more desirable. This includes non-Java platforms and languages such as Perl, C/C++, .NET framework (C#, VB.Net), and Python.
...
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.
Building a Java SOAP Client
LexEVSAPI provides a tool to create a Java SOAP client capable of connecting to a LexEVSAPI SOAP service.
...
To build the client, use the command 'ant all' from the ./webServiceSoapClient directory.
XML-HTTP API
The caCORE LexEVS XML-HTTP API, based on the REST (Representational State Transfer) architectural style, provides a simple interface using the HTTP protocol. In addition to its ability to be invoked from most Internet browsers, developers can use this interface to build applications that do not require any programming overhead other than an HTTP client. This is particularly useful for developing Web applications using AJAX (Asynchronous JavaScript and XML).
Service Location and Syntax
The CORE EVS XML-HTTP interface uses the following URL syntax:
...
Table 4.13 - Criteria statements within XML-HTTP queries
Examples of Use
The examples in Table 4.14 demonstrate the usage of the XML-HTTP interface. In actual usage, these queries would either be submitted by a block of code or entered in the address bar of a Web browser.
...
Table 4.14 - XML-HTTP interface examples
Working with Result Sets
Because HTTP is a stateless protocol, the caCORE LexEVS server cannot detect the context of any incoming request. Consequently, each invocation of GetXML or GetHTML must contain all of the information necessary to retrieve the request, regardless of previous requests. Developers should consider this when working with the XML-HTTP interface.
...
When specifying attribute values in the query string, note that use of the following characters generates an error:
[ ] / \ # & %
Distributed LexEVS API
Overview
In place of the existing EVS 3.2 object model, caCORE LexEVS is making a gradual transition toward a pure LexEVS back-end terminology server and exposure of the LexEVS Service object model. caCORE 3.2 and earlier required a custom API layer between external users of the system and the proprietary Apelon Terminology Server APIs. With the transition to LexEVS, caCORE LexEVS can publicly expose the open source terminology service API without requiring a custom API layer.
Architecture
The LexEVS API is exposed by the LexEVS caCORE System for remote, distributed access (Figure 4.5). The caCORE System's <tt>LexEVSApplicationService</tt> class implements the <tt>LexBIGService</tt> interface, effectively exposing LexEVS via caCORE.
...
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.
LexEVS Annotations
To address LexEVS DAOs, the LexEVS API integration incorporated the addition of (1) Java annotation marking methods that can be safely executed on the client side; and (2) classes that can be passed to the client without being wrapped by a proxy. The annotation is named <tt>@lgClientSideSafe</tt>. Every method in the LexEVS API that is accessible to the caCORE LexEVS user had to be considered and annotated if necessary.
Aspect Oriented Programming Proxies
LexEVS integration with caCORE LexEVS was accomplished using Spring Aspect Oriented Programming (AOP) to proxy the LexEVS classes and intercept calls to their methods. The caCORE LexEVS client wraps every object returned by the <tt>LexBIGService</tt> inside an AOP Proxy with advice from a <tt>LexBIGMethodInterceptor</tt> ("the interceptor").
...
Figure 4.6 - Sequence diagram showing method interception
LexEVS API Documentation
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=14.
LexEVS Installation and Configuration
The DLB API is strictly a Java interface and requires Internet access for remote connectivity to the caCORE LexEVS server. Access to the DLB API requires access to the <tt>lexevsapi-client.jar</tt> file, available for download on the NCICB Web site. The <tt>lexevsapi-client.jar</tt> file needs to be available in the classpath. For more information, see VKC:Installing and Configuring the LexEVS 5.0 Java API.
Example of Use
Example 4.6: Using the DLB API
...
:DistributedCodingSchemeListTest_Java
LexEVS Analytical Grid Service API
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).
Using the API
There are two (2) different interfaces for accessing the LexEVS Grid Services:
...
:LexBIGServiceGridAdapter_Snippet
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, org.LexGrid.LexBIG.DataModel.Core.CodingSchemeVersionOrTag |
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.CodedNodeSet.stubs.types.CodedNodeSetReference |
Exception: | RemoteException |
Implementation Details: |
getFilter
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: |
getSortAlgorithm
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: |
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: |
...
ExtensionDescriptionList extDescList = lbs.getFilterExtensions(); |
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: |
...
LexBIGServiceMetadataGrid metadata = lbs.getServiceMetadata(); |
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: |
...
CodingSchemeRenderingList csrl = lbs.getSupportedCodingSchemes(); |
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: |
...
Date date = lbs.getLastUpdateTime(); |
resolveCodingScheme
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: |
getNodeGraph
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: |
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: |
...
Step 2: Invoke the LexEVS caGrid service as follows:
ModuleDescriptionList mdl = lbs.getMatchAlgorithms(); |
getGenericExtensions
Description: | Returns a description of all registered extensions used to implement application-specific behavior that is centrally accessible from a LexBIGService. |
...
Step 2: Invoke the LexEVS caGrid service as follows:
ExtensionDescriptionList edl = lbs.getGenericExtensions(); |
getGenericExtension
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: |
getHistoryService
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: |
getSortAlgorithms
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: |
resolveCodingSchemeCopyright
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: |
setSecurityToken
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: |
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 caGRID Portal.
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 Table 4.2.
...
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 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"
:SearchingForConcepts_Snippet
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.
...
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
...
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.
LexEVS Data Grid Service API
The LexEVS Data 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.
Example LexEVS queries follow.
Query for a Concept with a specific Code
- Example: Concept: C12345
:DataGridQueryByCode_Snippet
Query for a Concept with a specific Presentation Text
- Example: A concept with a namespace 'SNOMED Clinical Terms' that contains a Presentation equal to 'Heart'
:DataGridQueryByPresentationText_Snippet
Restrict Results to Specific Attributes
- Example: Retrieve all of the 'localIds' of any 'SupportedAssociation' in the system.
...