 |
Page History
...
| Code Block |
|---|
1 public static void main(String[] args)
2 {
3 try {
4 LexEVSApplicationService appService =
5 (LexEVSApplicationService)ApplicationServiceProvider.
6 getApplicationService("EvsServiceInfo");
7 QueryOptions queryOptions = new QueryOptions();
8 queryOptions.setCodingScheme("NCI Thesaurus");
9 CodingSchemeVersionOrTag csvt = new CodingSchemeVersionOrTag();
10 csvt.setVersion("09.10d");
11 queryOptions.setCodingSchemeVersionOrTag(csvt);
12 Entity entity = new Entity()
13 entity.setEntityCode("C1234");
14 List<Entity> list = appService.search(Entity.class, entity, queryOptions);
15 } catch(ApplicationException ex){
16 }
17 }
|
Explanation of statements in The following table 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.
...
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 lexevsapi50Service, 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:
| Code Block |
|---|
http://{server}/{servlet}?query={returnClass}&{criteria}
&startIndex={index}
&codingSchemeName={codingSchemeName}
&codingSchemeVersion={codingSchemeVersion} |
Table 4.12 The following table explains the URL syntax used by the caCORE LexEVS XML-HTTP interface, indicates whether specific elements are required, and gives examples.
Element | Meaning | Required | Example |
|---|---|---|---|
| Name of the Web server on which the caCORE LexEVS 5.0 Web application is deployed. | Yes | |
| URI and name of the servlet that will accept the HTTP GET requests. | Yes | |
...
| Class name indicating the type of objects that this query should return. | Yes |
| Search request criteria describing the requested objects. | Yes |
| Starting index of the result set. | No |
| Restrict the query to a specific Coding Scheme Name. | No |
| Restrict the query to a specific Coding Scheme Version. | No |
...
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:
...
| 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 within XML-HTTP queries and gives examples.
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. | |
Table 4.13 - Criteria statements within XML-HTTP queries
Examples of Use
The examples in Table 4.14 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. Note that the The servlet name GetXML in each of the examples can be replaced with GetHTML to view with layout and markup in a browser.
Query | {{ http://evsapi.nci.nih.gov/evsapi41/GetXML?query=DescLogicConcept[_entityCode=C123* }} |
|---|---|
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.
- 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 | ||
|---|---|---|
|
...
When specifying attribute values in the query string, note that use of the following characters generates an error: |
Distributed LexBIG API
Overview
In place of the existing EVS 3.2 object model, caCORE LexEVS is making a gradual transition toward a pure LexBIG back-end terminology server and exposure of the LexBIG 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 LexBIG, caCORE LexEVS can publicly expose the open source terminology service API without requiring a custom API layer.
Architecture
The LexBIG API is exposed by the LexEVS caCORE System for remote, distributed access (Figure 4.5). The caCORE System's LexEVSApplicationService class implements the LexBIGService interface, effectively exposing LexBIG 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 LexBIG objects and forward them to the caCORE server so that they execute within the LexBIG environment.
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 LexBIG database and other resources. The client must therefore go through the caCORE LexEVS server to access any LexBIG data.
LexBIG Annotations
To address LexBIG DAOs, the LexBIG 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 LexBIG API that is accessible to the caCORE LexEVS user had to be considered and annotated if necessary.
Aspect Oriented Programming Proxies
LexBIG integration with caCORE LexEVS was accomplished using Spring Aspect Oriented Programming (AOP) to proxy the LexBIG 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 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.
Figure 4.6 - Sequence diagram showing method interception
LexBIG API Documentation
The Mayo Clinic wrote the LexBIG 5.0 API. Documentation describing the LexBIG Service Model is available on the LexGRID Vocabulary Services for caBIG GForge site at https://gforge.nci.nih.gov/frs/?group_id=14.
LexBIG 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. For more information, see VKC:Installing and Configuring the LexEVS 5.0 Java API.
Example of Use
Example 4.6: Using the DLB API
...