NIH | National Cancer Institute | NCI Wiki  

Error rendering macro 'rw-search'

null

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
Wiki Markup
{scrollbar:icons=false}

Page info
title
title

Section
Column
Panel
titleContents of this Page
Table of Contents
minLevel2
Column
Align
alignright
Include Page
Menu LexEVS 6.0 Programmers to Include
Menu LexEVS 6.0 Programmers to Include

Introduction

This document 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 the overview of the caCORE LexEVS 4.0 release components in the following figure.

A graphic showing the overview of the caCORE LexEVS release components.

The open source interfaces provided as part of caCORE LexEVS 6.0 include Java APIs, a SOAP interface, and an HTTP REST interface. The Java APIs are based on the EVS 3.2 object model and the LexEVS Service object model.

The EVS 3.2 model, exposed as part of caCORE 3.2, has been re-released with LexEVS as the back-end terminology service in place of the proprietary Apelon DTS back end. The SOAP and HTTP REST interfaces are also based on the 3.2 object model. The SDK 4.0 was used to generate the EVS 3.2 Java API, as well as the SOAP and HTTP REST interfaces.

The only difference between the EVS 3.2 API exposed as part of the caCORE LexEVS 6.0 and the API exposed as part of caCORE 3.2 is the back-end terminology server used to retrieve the vocabulary data. The interface (API calls) are the same and should only require minor adjustments to user applications.

Info
titleNote

You cannot integrate caCORE 3.2 components with caCORE LexEVS 6.x. If you used multiple components of caCORE 3.2 (for example, EVS with caDSR), you need to continue to work with the caCORE 3.2 release until the other caCORE 4.0 components are available.

The LexEVS object model was developed by the Mayo Clinic. In its native form, the associated API assumes a local, non-distributed means of access. With caCORE LexEVS 6.x, a proxy layer enables EVS API clients to access the native LexEVS API from anywhere without having to worry about the underlying data sources. This is called the Distributed LexEVS (DLB) API.

The DLB Adapter is another option for caCORE LexEVS 6.x clients who choose to interface directly with the LexEVS API. This is essentially a set of convenience methods intended to simplify the use of the LexEVS API. For example, a series of method calls against the DLB API might equate to a single method call to the DLB Adapter.

Info
titleNote

The DLB Adapter is not intended to represent a complete set of convenience methods. As part of the caCORE LexEVS 6.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.

Accessing and using a caCORE LexEVS system requires the following steps:

  1. Ensure that the client application has access to the objects in the domain space.
  2. Formulate the query criteria using the domain objects.
  3. Establish a connection to the server.
  4. Submit the query objects and specify the desired class of objects to be returned.
  5. Use and manipulate the result set as desired.

caCORE LexEVS systems use four native application programming interfaces (APIs). Each interface uses the same paradigm to provide access to the caCORE LexEVS domain model, with minor changes specific to the syntax and structure of the clients. The following sections describe each API, identify installation and configuration requirements, and provide code examples.

The sequence diagram in Sequence diagram - caCORE 4.0 LexEVS API search mechanism illustrates the caCORE LexEVS API search mechanism implemented to access the NCI EVS vocabularies.

This graphic shows the search mechanism to access the NCI EVS vocabularies.

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:

  1. 'CodingScheme' - Restricts the query to the specified Coding Scheme, instead of querying every available Coding Scheme.
  2. CodingSchemeVersionOrTag' - Restricts the query to the specified Version of the Coding Scheme.

    Info
    titleNote

    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.

  3. '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.
  4. '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
    titleNote

    Lazy Loading may only be used in conjunction with specifying a Coding Scheme and Version with the 'CodingScheme' and 'CodingSchemeVersionOrTag' attributes above.

  5. '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

The following query is a Query By Example with No Query Options.

Include Page
QueryByExampleWithNoQueryOptions Snippet
QueryByExampleWithNoQueryOptions Snippet

Explanation of statements explains specific statements in the code by line number.

Line Number

Explanation

4

Creates an instance of a class that implements the LexEVSApplicationService interface. This interface defines the service methods used to access data objects.

7

Construct the Query By Example Object and populate it with the desired search critieria. For this example, seach for any 'Entity' with an 'entityCode' attribute equaling 'C1234'.

9

Calls the search method of the LexEVSApplicationService object.
This method returns a List Collection. This list will contain all of the 'Entity' Objects that match the search critieria. It this case, it will return all 'Entity' Objects with an 'entityCode' of "C1234".

The following example is a Query By Example with Query Options.

Include Page
QueryByExampleWithQueryOptions Snippet
QueryByExampleWithQueryOptions Snippet

Explanation of statements explains specific statements in the code by line number.

Line Number

Explanation

4

Creates an instance of a class that implements the LexEVSApplicationService interface. This interface defines the service methods used to access data objects.

7

Construct the QueryOptions Object.

8

Populate the QueryOptions with the desired Coding Scheme.

9

Construct a CodingSchemeVersionOrTag Object.

10

Populate the CodingSchemeVersionOrTag Object with the desired Version.

11

Populate the QueryOptions with the above CodingSchemeVersionOrTag Object.

12

Construct the Query By Example Object and populate it with the desired search critieria. For this example, seach for any 'Entity' with an 'entityCode' attribute equaling 'C1234'.

14

Calls the search method of the LexEVSApplicationService object, along with the QueryOptions.
This method returns a List Collection. This list will contain all of the 'Entity' Objects that match the search critieria, while being further modified by the QueryOptions. It this case, it will return all 'Entity' Objects with an 'entityCode' of "C1234" belonging to the CodingScheme "NCI Thesaurus" Version "09.10d".

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.

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://lexevsapi60.nci.nih.gov/lexevsapi60/services/lexevsapi60Service?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 lexevsapi60Service, which is located at http://lexevsapi60.nci.nih.gov/lexevsapi60/services/lexevsapi60Service. 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.

In the ./webServiceSoapClient contains a build.xml file that will construct a LexEVSAPI SOAP client. Before building, you may edit this build.xml file to customize the build process. Editable properties include 'wsdlURL' and 'webServiceNamespace'. An example configuration is below:

Code Block
<property name="wsdlURL" value="http://server.localhost/lexevsapi60/services/lexevsapi60Service?wsdl"/>
<property name="webServiceNamespace" value="http://server.localhost/lexevsapi60/services/lexevsapi60Service"/>

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:

Code Block
http://{server}/{servlet}?query={returnClass}&{criteria}
	&startIndex={index}
	&codingSchemeName={codingSchemeName}
	&codingSchemeVersion={codingSchemeVersion}

The following table explains the syntax, indicates whether specific elements are required, and gives examples.

Element

Meaning

Required

Example

server

Name of the Web server on which the caCORE LexEVS 6.0 Web application is deployed.

Yes

lexevsapi60.nci.nih.gov/lexevsapi60

servlet

URI and name of the servlet that will accept the HTTP GET requests.

Yes

lexevsapi60/GetXML
lexevsapi60/GetHTML

returnClass

Class name indicating the type of objects that this query should return.

Yes

query=DescLogicConcept

criteria

Search request criteria describing the requested objects.

Yes

DescLogicConcept @id=2

index

Starting index of the result set (Zero based).

No

startIndex=25

codingSchemeName

Restrict the query to a specific Coding Scheme Name.

No

{{codingSchemeName=NCI_Thesaurus }}

codingSchemeVersion

Restrict the query to a specific Coding Scheme Version.

No

Info
titleNote

Must be used in conjunction with a 'codingSchemeName'

codingSchemeVersion=09.12d

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.

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}]/...

The following table explains the syntax for criteria statements and gives examples.

Parameter

Meaning

Example

ClassName

The name of a class.

Entity

attributeName

The name of an attribute of the return class or an associated class

_entityCode

value

The value of an attribute.

C123*

Examples of Use

The examples in the following table 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.

Info
titleNote

The servlet name GetHTML in the examples is used for placement into a browser address bar. It would be replaced with GetXML for use in an application.

Query

Code Block
http://lexevsapi60.nci.nih.gov/lexevsapi60/GetHTML?query=Entity%5B@_entityCode=C1272*%5D 

Semantic Meaning

Find all objects of type Entity that contain an 'entityCode' matching the pattern 'C123*'.

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.

Controlling the Start Index

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.

Internal-Use Parameters

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
titleNote

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 as shown in the figure below. The caCORE System's LexEVSApplicationService class implements the LexBIGService interface, effectively exposing LexEVS via caCORE.

Since in many cases the objects returned from the LexBIGService 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 figure shows the DLB architecture (caCORE => Application Service === Spring Remoting === caCORE Server => LexBIG Client = >LexBIG Datastore).

This graphic shows DLB architecture as described above.

The DLB environment will be configured on the caCORE LexEVS Server (http://lexevsapi60.nci.nih.gov/lexevsapi60). 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 @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 LexBIGService inside an AOP Proxy with advice from a LexBIGMethodInterceptor ("the interceptor").

The following graphic shows a sequence diagram showing method interception. The interceptor is responsible for intercepting all client calls on the methods in each object. If a method is marked with the @lgClientSideSafe annotation, it proceeds normally. Otherwise, the object, method name, and parameters are sent to the caCORE LexEVS server for remote execution.

This graphic shows the sequence diagram described above.

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 lexevsapi-client.jar file, available for download on the NCICB Web site. The lexevsapi-client.jar file needs to be available in the classpath.

Example: 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
DistributedCodingSchemeListTest Java
DistributedCodingSchemeListTest Java

Wiki Markup
{scrollbar:icons=false}