Page History
...
The following table explains the syntax, indicates whether specific elements are required, and gives examples.
The following table explains the URL syntax used by the caCORE LexEVS XML-HTTP interface_
Element | Meaning | Required | Example |
---|---|---|---|
<tt>server</tt> | Name of the Web server on which the caCORE LexEVS 5.0 Web application is deployed. | Yes | <tt>lexevsapi.nci.nih.gov/lexevsapi50</tt> |
<tt>servlet</tt> | URI and name of the servlet that will accept the HTTP GET requests. | Yes |
...
NOTE: Must be used in conjunction with a 'codingSchemeName' |
Table 4.12 - URL syntax used by the caCORE LexEVS XML-HTTP interface
The caCORE LexEVS architecture currently provides two servlets that accept incoming requests:
- 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.
Wiki Markup |
---|
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. |
Criteria statements in XML-HTTP queries generally use the following syntax (although you can also build more complex statements):
Code Block |
---|
{ClassName}[@{attributeName}={value}] [@{attributeName}={value}]... ClassName}[@{attributeName}={value}]/ {ClassName}[@{attributeName}={value}]/... |
Table 4.13 The following table explains the syntax for criteria statements and gives examples.
Parameter | Meaning | Example | |
---|---|---|---|
<tt>ClassName</tt> | The name of a class. | <tt>Entity</tt> | |
| The name of an attribute of the return class or an associated class | <tt>_entityCode</tt> | |
| The value of an attribute. | <tt>C123 |
Table 4.13 - Criteria statements within XML-HTTP queries
Examples of Use
The examples in Table 4.14 demonstrate example in the table below demonstrates 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.
Info | ||
---|---|---|
|
...
The servlet name GetXML in each of the examples can be replaced with GetHTML to view with layout and markup in a browser. |
Query |
| ||
---|---|---|---|
Semantic Meaning | Find all objects of type Entity that contain an 'entityCode' matching the pattern 'C123*'. |
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.
...
To specify a specific start position in the result set, specify the & startIndex
parameter. This will scroll to the desired position within the set of results.
...
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.NOTE:
Info | ||
---|---|---|
| ||
|
...
|
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> LexEVSApplicationService class implements the <tt>LexBIGService</tt> LexBIGService interface, effectively exposing LexEVS via caCORE.
Since in many cases the objects returned from the <tt>LexBIGService</tt> are not merely beans, but full-fledged data access objects (DAOs), the caCORE LexEVS client is configured to proxy method calls into the LexEVS objects and forward them to the caCORE server so that they execute within the LexEVS environment.
The following diagram shows the DLB environment for the caCORE LexEVS Server.
Figure 4.5 - DLB Architecture
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> @lgClientSideSafe
. 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> LexBIGMethodInterceptor ("the interceptor").
The interceptor is responsible for intercepting all client calls on the methods in each object. If a method is marked with the <tt>@lgClientSideSafe</tt> @lgClientSideSafe
annotation, it proceeds normally. Otherwise, the object, method name, and parameters are sent to the caCORE LexEVS server for remote execution.
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® 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>lexevsapilexevsapi-client.jar</tt> jar file, available for download on the NCICB Web site. The <tt>lexevsapilexevsapi-client.jar</tt> jar 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
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 table summarizes 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:
- org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter, or
- org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter
Option 1, org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter provides an interface for interacting with the LexEVS Grid Services. This Interface is intended to mirror the existing LexEVS API as much as possible. There is no object wrapping for semantic purposes on this interface. This allows existing applications of the LexEVS API to use Grid Services without code changes.
This Interface may be acquired by instantiating LexBIGServiceAdapter with the Grid Service URL as a parameter.
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
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, |
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.CodedNodeSet.stubs.types.CodedNodeSetReference |
Exception: | RemoteException |
Implementation Details: |
getFilter
Implementation:
| |||
Description: | Returns an instance of the filter extension registered with the given name. | ||
Input: |
| Output: |
|
Exception: | RemoteException | ||
Implementation Details: |
getSortAlgorithm
| |||
Description: | Returns an instance of the sort extension registered with the given name. | ||
Input: |
| Output: | ''
stubs.types.SortReference'' |
Exception: | RemoteException | ||
Implementation Details: |
getFilterExtensions
| ||||
Description: | Returns a description of all registered extensions used to provide additional filtering of query results. | |||
Input: | none | |||
Output |
| |||
Exception: | RemoteException | |||
|
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: |
Step 1: Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results.
Sample Call:
Step 1: Connect to the LexEVS caGrid Service using the org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter or org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter(url);
Step 2: Invoke the LexEVS caGrid service as follows:
ExtensionDescriptionList extDescList = lbs.getFilterExtensions(); |
getServiceMetadata
|
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.stubs.types.SortReference | ||||||
Exception: | RemoteException | ||||||
Implementation Details: | Implementation:
|
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:
|
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 | ||||||||||
Output: | org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices. | ||||||||||
Exception: | RemoteException | ||||||||||
Implementation Details: | Implementation:
|
getMatchAlgorithms
getMatchAlgorithms()
Description: | Returns the node graph as represented in the particular relationship set in the coding scheme | Description: | Return an interface to perform system-wide query over metadata for loaded code systems and providers. |
---|---|---|---|
Input: | none | ||
Output: | org.LexGrid.LexBIG.cagridDataModel.LexBIGCaGridServices.LexBIGServiceMetadata. | ||
Exception: | RemoteException | ||
Implementation Details: | Implementation: |
...
Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server |
...
, and forward the results. |
...
...
|
...
|
...
|
...
|
...
getGenericExtensions
getGenericExtensions()
...
Description: | Return Returns a list of coding schemes and versions that are supported by this service, along with their statusdescription 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.CodingSchemeRenderingListExtensionDescriptionList | |||||
Exception: | RemoteException | |||||
Implementation Details: | Implementation: |
...
Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results. |
...
|
...
|
...
|
...
|
...
getGenericExtension
getGenericExtensions(ExtensionIdentification)
...
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 | ||
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 | Output: | java.util.Date |
Exception: | RemoteException | ||
Implementation Details: | Implementation: |
...
Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results. |
...
|
...
|
Step 2: Invoke the LexEVS caGrid service as follows:
Date date = lbs.getLastUpdateTime(); |
resolveCodingScheme
Description: | Return detailed coding scheme information given a specific tag or version identifier. |
Input: | |
Description: | Returns the node graph as represented in the particular relationship set in the coding scheme. |
Input: |
|
Output: | org.LexGrid.codingSchemes.CodingScheme |
Exception: | RemoteException |
Implementation Details: |
getNodeGraph
|
| Output: | ''
CodedNodeGraph.stubs.types.CodedNodeGraphReference'' | ||||
Exception: | RemoteException | ||||||
Implementation Details: |
getMatchAlgorithms
|
getHistoryService
getHistoryService(CodingSchemeIdentification)
Description: | Resolve a reference to the history api servicing the given coding scheme. |
---|---|
Input: | org.LexGrid.LexBIG.DataModel.cagrid.CodingSchemeIdentification |
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.cagrid.LexBIGCaGridServices.HistoryService.stubs.types.HistoryServiceReference |
Exception: | RemoteException |
Implementation Details: | Implementation: |
...
|
...
|
...
|
...
|
...
|
...
getSortAlgorithms
getSortAlgorithms(SortContext)
...
Description: | Returns a description of all registered extensions used to implement application-specific behavior that is centrally accessible from a LexBIGService. |
---|
Note that only generic extensions (base class GenericExtension) will be listed here. All other classes are retrievable at the appropriate interface point (filter, sort, etc). |
provide additional filtering of query results. | |||
Input: | org.LexGrid.LexBIG.DataModel.InterfaceElements.types.SortContext | Input: | none |
---|---|---|---|
Output: | org.LexGrid.LexBIG.DataModel.Collections.ExtensionDescriptionListSortDescriptionList | ||
Exception: | RemoteException | ||
Implementation Details: | Implementation: |
...
Call this method on the associated LexEVS Service instance (or Distributed LexEVS instance) on the server, and forward the results. |
...
|
...
|
...
|
...
|
...
...
resolveCodingSchemeCopyright
...
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:
resolveCodingSchemeCopyright
Description: | Return coding scheme copyright given a specific tag or version identifier |
---|
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.DataModel.cagrid.LexBIGCaGridServices. |
Exception: | RemoteException |
Implementation Details: |
getSortAlgorithms
Description: | Returns a description of all registered extensions used to provide additional filtering of query results. | ||
Input: | Implementation:
|
| Output: |
Description: | Return coding scheme copyright given a specific tag or version identifier. | ||
---|---|---|---|
Input: |
| ||
Exception: | RemoteException | ||
Implementation Details: |
resolveCodingSchemeCopyright
resolveCodingSchemeCopyright
|
| Output: |
| ||||
---|---|---|---|---|---|---|---|
Exception: | RemoteException | ||||||
| Implementation Details: | Â |
setSecurityToken
setSecurityToken(CodingSchemeIdentification, SecurityToken)
...