 |
Page History
Revision History
Content changes to this document from the previous to the current level are indicated by revision bars (|) unless a complete rewrite is indicated.
Date | Version | Description | Author |
|---|---|---|---|
07/29/2008 | 1.0 | Initial document | Kevin Peterson |
8/30/2008 | 1.1 | Revised for Security and Exception Handling | Kevin Peterson |
Note: If this document has been inspected, please indicate the inspection date that each version is based on in the "Change Description and Explanation" area. Entries in this log must be maintained for at least 3 years. |
Document Purpose
This document provides the detailed design and implementation of LexBIG Enterprise Vocabulary Service (LexEVS) caGrid Service. It should be noted that the LexEVS Grid Service is no longer part of the caGrid 1.1 infrastructure and will be deployed as a separate unit. This is a change from the previous release of the LexEVS Grid Service.
The LexEVS caGrid service will allow programs to utilize the caGrid 1.2 infrastructure to access LexEVS information that is currently being produced by NCICB.
Implementation Overview
Team Members
Table 1 - Team Members
Role | Name |
|---|---|
Development Lead | Kevin Peterson |
Documentation Lead | Kevin Peterson |
Project Manager | Tom Johnson |
Description
The LexEVS grid service will be used to obtain data accessible via the EVS API 4.2 service, specifically, the Distributed LexBIG services. Please refer to the caCORE EVS API 4.0 technical guide for details on the EVS API 4.2 EVS APIs, and the LexBIG 2.3 Technical and Admin guide for details about LexBIG 2.3.
For more Documentation, Build/Deployment instructions and examples, visit the project documentation home at: http://gforge.nci.nih.gov/docman/index.php?group_id=491&selected_doc_group_id=3749&language_id=1
Scope
The LexEVS Grid service will provide programmatic access to the LexBIG domain objects that are available via the LexBIG information model.
...
Context | caBIG |
Classification Scheme | LexBIG |
Version | LexBIG_v2_3_rv1 |
Architecture
The LexEVS Grid Service is implemented to expose the API and Model of LexBIG 2.3. For more information on LexBIG, see http://informatics.mayo.edu
...
Below is the LexEVS Grid Service Architecture, viewed from inside of the Web Service Container. For more information on how Service Contexts and Resources are used, see the "Service Contexts and State" section below.
LexEVS Grid Service Class Diagram
The LexEVS Grid Service is built on the LexGrid/LexBIG model and implementation.
For more information about this model, visit (LexBIG) https://gforge.nci.nih.gov/plugins/scmsvn/viewcvs.php/LexBIG_Core_Services/LexBIG-2.3/lexbig/lbModel/?root=lexevs
and (LexGrid) https://gforge.nci.nih.gov/plugins/scmsvn/viewcvs.php/LexBIG_Core_Services/LexBIG-2.3/lgModel/?root=lexevs
...
For information specific to the LexEVS Grid Service, visit: https://gforge.nci.nih.gov/plugins/scmsvn/viewcvs.php/LexBIG_Core_Services/LexBIG-2.3/lexbig/lbModel.cagrid/?root=lexevs
This link contains Class Diagrams and descriptions for input/output parameters, as well as other information concerning the Silver Level Compliance submission package.
LexEVS Grid Service Sequence Diagram
The sequence diagram for the operation "getSupportedCodingSchemes" is described below:
...
General Call Sequence Example:
Assumptions
- The LexEVS service will be based on the latest EVSAPI 4.2 patch release built by NCICB.
- The LexBIG 2.3 domain model will be loaded in the GME and caDSR.
- The LexEVS Grid Service will not have any method level security. All security requirements will be handled by the actual deployment of the underlying EVSAPI 4.2 service. Please see the "Security" section below for more information on how the LexEVS Grid Service utilizes this security.
- The LexEVS Grid Service will not be deployed as a "core" service by caGrid at NCICB as was previously done, but rather will now be deployed as a standalone service.
- The LexEVS Grid Service release schedule will no longer be coupled to the caGrid deployment schedule as previously done.
- Multiple version of LexEVS Grid Service may be active at the same instance in time depending solely on the availability of the underlining EVSAPI service.
Dependencies
- EVSAPI 4.2 service needs to be available and running correctly.
- The LexBIG 2.3 domain model needs to be registered in caDSR.
- The LexEVS service and operations will use the Introduce toolkit to generate the appropriate structure for registering the service into caDSR.
Issues
- None
Third Party Tools
- Introduce Toolkit
- Globus Toolkit (4.0.3) or appropriate version supported by caGrid 1.2
- caGrid 1.2 core infrastructure
Implementation Contents
Server
The LexEVS Grid Service will be deployed as a "stand alone" grid service at NCICB.
Algorithms
None
Batch Processes
None
APIs
The main Service API exposed by the LexEVS Grid service will be the http://informatics.mayo.edu/LexGrid/downloads/javadocGrid/org/LexGrid/LexBIG/cagrid/interfaces/LexBIGServiceGrid.html Interface. All other APIs will not be directly exposed, but will be made available through Service Contexts.
...
*Main Service API * http://informatics.mayo.edu/LexGrid/downloads/javadocGrid/org/LexGrid/LexBIG/cagrid/interfaces/LexBIGServiceGrid.html
Using the API
To use the LexEVS Grid Services, either org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceAdapter or org.LexGrid.LexBIG.cagrid.adapters.LexBIGServiceGridAdapter objects may be instantiated. These are two different Interfaces for accessing the Grid Services.
...
LexBIGServiceGrid lbs = new LexBIGServiceGridAdapter("http://...");
getCodingSchemeConcepts
Description: | Returns the set of all (or all active) concepts in the specified coding scheme. |
Input: |
...
Step 4: Invoke the LexBIG caGrid service as follows:
CodedNodeSetGrid cns = lbs.getCodingSchemeConcepts(codingScheme, csvt); |
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: |
...
Filter filter = lbs.getFilter(extension); |
getSortAlgorithm
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.Sort. |
Exception: | RemoteException |
Implementation Details: |
...
Filter filter = lbs.getSortAlgorithm(extension); |
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: |
...
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: |
...
Step 4: Invoke the LexBIG caGrid service as follows:
CodedNodeSetGrid cns = lbs.resolveCodingScheme(codingScheme, csvt); |
getNodeGraph
Description: | Returns the node graph as represented in the particular relationship set in the coding scheme. |
Input: |
...
Step 5: Invoke the LexBIG caGrid service as follows, providing String parameters for the desired Coding Scheme and Relationship Name:
CodedNodeGraphGrid cng = client.getNodeGraph(codingScheme, csvt, container); |
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 LexBIG 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 LexBIG 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: |
...
Step 4: Return the LexBIGServiceConvenienceMethodsClient to the user. This LexBIGServiceConvenienceMethodsClient has the above org.LexGrid.LexBIG.Extensions.Generic.LexBIGServiceConvenienceMethods as a Resource. An org.LexGrid.LexBIG.cagrid.LexBIGCaGridServices.service.CodedNodeGraphClient object is built from the above Reference. |
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: |
...
Step 3: Invoke the LexBIG caGrid service as follows:
HistoryServiceGrid history = lbs.getHistoryService(codingScheme); |
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: |
...
Step 2: Invoke the LexBIG caGrid service as follows:
SortDescriptionList sortDescList = lbs.getSortAlgorithms(sortContext); |
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: |
...
Step 5: Invoke the LexBIG caGrid service as follows:
CodingSchemeCopyRight copyright = lbs.resolveCodingSchemeCopyright(codingScheme, csvt); |
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 |
Exception: | RemoteException |
Implementation Details: |
...
LexBIGServiceGrid lbsg = lbs.setSecurityToken(codingScheme, metaToken); |
API Examples
For an example clients, service calls, and SOAP messages, see http://gforge.nci.nih.gov/docman/index.php?group_id=491&selected_doc_group_id=3880&language_id=1
...
| Code Block |
|---|
ResolvedConceptReference[] rcref = rcrlist.getResolvedConceptReference();
for (int i = 0; i < rcref.length; i++) {
System.out.println(rcref[i].getConceptCode());
System.out.println(rcref[i].getReferencedEntry().
getPresentation()[0].getText().getContent());
} |
Service Contexts and State
Along with the Main Service (described above), the Server will also host the following Service Contexts. These Service Contexts are not meant to be called directly as Grid Services. The main function of these Service Contexts is to provide additional functionality to the Main Service.
...
6. These API calls are separate calls but statefully maintained on the server via the Resource.
Error Handling
Error Connecting to LexEVS Grid Service
...
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).
Database Changes
None
Client
The Introduce toolkit generates a "client" class that will be provided to the users.
JSP/HTML
None
Servlet
None
Security Issues
Security in the LexEVS Grid Service is implemented in the Distributed LexBIG layer. The information in this section explains how the LexEVS Grid Services utilize this security implementation. For more information about the Distributed LexBIG Security Implementation, see this documentation: http://gforge.nci.nih.gov/tracker/download.php/366/1462/10884/4060/Distributed_LexBIG_%20AccessTo_Licensed_Vocabulary_implemenation.doc
...
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.
Performance
The LexEVS service will take advantage of all improvements made to the EVSAPI services with the exception of lazy loading. LexEVS grid service, being in nature a web service is currently not taking advantage of lazy loading since objects are transferred as fully populated objects. However, future releases of LexEVS Grid Service may refractor the interface in such as way as to take advantage of some of the benefits brought about by the inclusion of lazy loading in to EVSAPI service.
LexEVS Grid Services utilize the performance enhancements of the LexBIG API.
For more information about LexBIG performance (which LexEVS Grid Services are dependent on), see http://informatics.mayo.edu
Internationalization
Not Internationalized
Installation / Packaging
The service will be installed and deployed as a "stand alone" service at NCICB.
Migration
Both the current version of LexEVS grid service and a previous version may be "in service" simultaneously if the corresponding underlying EVSAPI service is also "in service" to manage migration of clients.