 |
Page History
| Scrollbar | ||
|---|---|---|
|
| Page info | ||||
|---|---|---|---|---|
|
| Section | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| Warning | ||
|---|---|---|
| ||
Data services were deprecated in LexEVS 6.4.1 and removed in 6.5. The Java based remote method invocation will remain available for the time being. These services are replaced by a separate CTS2 compliant web service described in the CTS2 API. |
Introduction
The focus of documentation will be the Java based LexEVS remote method invocation service.
| Info | ||
|---|---|---|
| ||
See migration notes below for LexEVS Distributed 6.0, 6.1 to 6.2, 6.3 to 6.4.1, 6.5 |
LexEVSDistributed
The Distributed LexEVS Portion of LexEVSAPI extends a subclass of, or in 6.5 and later, implements LexEVSService. This interface is a framework for calling LexEVS API methods remotely, while enforcing restrictions on proprietary content. JavaDoc
...
| Info | ||
|---|---|---|
| ||
Overview
This exposes the LexEVS Service model via a Remote Method Invocation service.
LexEVS Installation and Configuration
The distributed LexEVS API is strictly a Java interface and requires Internet access for remote connectivity to the caCORE LexEVS server.
Client configuration is represented in a client project in github: https://github.com/lexevs/LexEVS_Distributed_Client
Using the distributed LexEVS API
Example code can be found at the above client project link for a number of use cases.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
package org.lexgrid.lexevs.remote.client;
import org.LexGrid.LexBIG.DataModel.Collections.CodingSchemeRenderingList;
import org.LexGrid.LexBIG.DataModel.InterfaceElements.CodingSchemeRendering;
import org.LexGrid.LexBIG.Exceptions.LBInvocationException;
import org.LexGrid.LexBIG.caCore.interfaces.LexEVSDistributed;
import gov.nih.nci.system.client.ApplicationServiceProvider;
public class MavenBasedPrototype {
LexEVSDistributed lbs = null;
private static String serviceUrl = "https://localhost.daplie.com:8443/lexevsapi64";
public void run() throws LBInvocationException{
try {
lbs = (LexEVSDistributed)ApplicationServiceProvider.getApplicationServiceFromUrl(serviceUrl, "EvsServiceInfo");
}
catch(Exception e){
System.out.println("Starting LexEVS Remote Client fails" + e);
}
CodingSchemeRenderingList list = lbs.getSupportedCodingSchemes();
for(CodingSchemeRendering rendering: list.getCodingSchemeRendering()){
System.out.println(rendering.getCodingSchemeSummary().getFormalName());
}
}
public static void main(String[] args) {
try {
new MavenBasedPrototype().run();
} catch (LBInvocationException e) {
e.printStackTrace();
}
}
} |
Background:
Architecture
The LexEVS API is exposed by the LexEVS caCORE System for remote access through the caCORE System's LexEVSApplicationService class which implements the LexBIGService interface.
The distributed LexEVS API environment will be configured on the LexEVS Server currently at (http://lexevsapi6.nci.nih.gov/lexevsapi64).
LexEVS Annotations
To address LexEVS DAOs, the LexEVS API integration incorporates:
...
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.
LexEVSDataService
| Warning | ||
|---|---|---|
| ||
See the CTS2 API for REST Services |
...
The caCORE-SDK Data Service Portion of LexEVSAPI. This extends the caCORE ApplicationService to provide additional direct to database query options. 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.
...
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.
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.
Info title Note 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
Examples of Use
The following query is a Query By Example with No Query Options.
...
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.
...
| Warning | ||
|---|---|---|
| ||
Building a Java SOAP Client
LexEVSAPI provides a tool to create a Java SOAP client capable of connecting to a LexEVSAPI SOAP service.
...
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:
...
Parameter | Meaning | Example |
|---|---|---|
| The name of a class. |
|
| The name of an attribute of the return class or an associated class |
|
| The value of an attribute. |
|
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.
...
Query |
| ||
|---|---|---|---|
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.
...
