Administration
EVS Design
 |
 |
 |
 |
Table of Contents
|
 |
 |
 |
 |
Document Purpose
This document provides the detailed design and implementation of Enterprise Vocabulary Service (EVS) caGrid Service that will be deployed as part the caGrid 1.0 infrastructure.
The EVS caGrid service will allow programs to utilize the caGrid 1.0 infrastructure to access EVS information that is currently being produced by NCICB.
Implementation Overview
| Team Members | |
|---|---|
| Role | Name |
| Development Lead | Avinash Shanbhag |
| Documentation Lead | Wendy Erickson-hirons |
| Project Manager | Arumani Manisundaram |
| Test Lead | Avinash Shanbhag |
Description
The EVS grid service will be used to obtain data accessible via the caCORE 3.1 service. Please refer to the caCORE technical guide (Chapter 4: Enterprise Vocabulary Service) [1] for details on the caCORE 3.1 EVS APIs.
Scope
The EVS Grid service will provide programmatic access to the EVS domain objects that are available via the EVS information model.
The EVS grid service will be registered in Cancer Data Standards Repository (caDSR) under the following category:
| EVS Grid Service | |
|---|---|
| Context | caBIG |
| Classification Scheme | caGrid |
| Version | 1.0 |
The EVS grid service will provide access to the EVS information model registered in the caDSR under the following category:
| EVS Information Model | |
|---|---|
| Context | caCORE |
| Classification Scheme | caCORE |
| Version | 3.1 |
The following APIs will be made available thru the EVS grid service:
| Name of the Operation | Comments | Inputs For the Operation | Returned Information from the Operation |
|---|---|---|---|
| searchDescLogicConcept| | Searches a valid Vocabulary such as NCI Thesaurus and returns Description Logic concepts that meet the search criteria | The EVSDescLogicConceptSearchParams will contain Vocabulary Name, the search term and the maximum limit of returned objects | Array of DescLogicConcept objects |
| searchMetaThesaurus | Searches NCI meta thesaurus and returns Meta Thesaurus information that meet the search criteria | The EVSMetaThesaurusSearchParams will contain the search term, the CUI, source, short response, score and the maximum number of returned objects | Array of MetaThesaurusConcept objects |
| getHistoryRecords | Searches a valid vocabulary in NCI thesaurus for history information | The EVSHistoryRecordsSearchParams will contain vocabulary name and the concept code for which the history information is searched | Array of HistoryRecord objects |
| getVocabularyNames | Returns all the vocabularies present in the Description Logic | No Input | Array of DescLogicConceptVocabularyName objects |
| getMetaSources | Used to obtain Meta thesaurus sources | No Input | Array of Source objects |
| searchSourceByCode | Searches the Meta Thesaurus based on Source code | The EVSSourceSearchParams will contain Source code and abbreviation | Array of MetaThesaurusConcept Objects |
The API will access the following objects and from the caCORE 3.1 EVS information model:
- DescLogicConcept
- MetaThesaurusConcept
- HistoryRecord
The following objects are registered by the EVS grid service information model:
- DescLogicConceptVocabularyName
- EVSDescLogicConceptSearchParams
- EVSHistoryRecordsSearchParams
- EVSSourceSearchParams
Architecture
EVS Grid Service Class Diagram
 |
| _ |
EVS Grid Service Sequence Diagram
The sequence diagram for the operation "getMetaSources" is described below:
 |
| _ |
The same classes will be interacting for all the operations in the service.
Assumptions
- The EVS service will be based on the latest caCORE 3.1 Add the appropriate caCORE version numberpatch release built by NCICB before caGrid 1.0 code freeze
- The caCORE 3.1 patch release will be available and deployed at NCICB at the following URL: http://cabio.nci.nih.gov/cacore31/http/remoteService
- The caCORE 3.1 EVS domain model will be loaded in GME in the following namespace: gme://caCORE.caCORE/3.1/
- The EVS service will not have any method level security. All security requirements will be handled by the actual deployment of the underlying caCORE 3.1 EVS service
- The EVS service will be deployed as a "core" service by caGrid 1.0 at NCICB
Dependencies
- caCORE 3.1 EVS service needs to be available and running correctly
- The caCORE 3.1 EVS domain model needs to be registered in caDSR
- The EVS service input classes needs to be registered in caDSR
- The EVS service and operations will use the Introduce toolkit to generate the appropriate structure for registering the service into caDSR
- A concept code for "core" Grid service will be provided by the EVS team
Issues
- None
Third Party Tools
- Introduce Toolkit
- Globus Toolkit (4.0.2 or appropriate version supported by caGrid 1.0)
- caGrid 1.0 core infrastructure
Implementation Contents
Server
The EVS grid service will be deployed as a core grid service at NCICB.
Algorithms
- None
Batch Processes
- None
APIs
getMetaSources
Input:
None
Output:
gov.nih.nci.evs.domain.Source[]
Exception:
RemoteException
Description:
This method will return an array of gov.nih.nci.evs.domain.Source objects that are published by the caCORE 3.1 EVS service.
Implementation Details:
The API will use the caCORE 3.1 API to query the EVS service as follows:
Step 1: Connect to the caCORE 3.1 service running at NCICB
appService = ApplicationServiceProvider.getRemoteInstance(EVSConstants.CACORE_31_URL);
Step 2: Build a gov.nih.nci.evs.query.EVSQueryImpl object and set the operation as "getMetaSources" as follows:
EVSQuery metaSearch = new EVSQueryImpl();metaSearch.getMetaSources();
Step 3: Invoke the EVS search API on the caCORE 3.1 service as follows:
Results = (List)appService.evsSearch(metaSearch);
getVocabularyNames
Input:
None
Output:
gov.nih.nci.cagrid.evs.service.DescLogicConceptVocabularyName []
Exception:
RemoteException
Description:
This method will return an array of gov.nih.nci.cagrid.evs.service.DescLogicConceptVocabularyName objects that contain the vocabulary names that are supported by the caCORE 3.1 EVS service.
Implementation Details:
The API will use the caCORE 3.1 API to query the EVS service as follows:
Step 1: Connect to the caCORE 3.1 service running at NCICB
appService = ApplicationServiceProvider.getRemoteInstance(EVSConstants.CACORE_31_URL);
Step 2: Build a gov.nih.nci.evs.query.EVSQueryImpl object and set the operation as "getVocabularyNames" as follows:
_EVSQuery evsSearch = new EVSQueryImpl();
evsSearch.getVocabularyNames();_
Step 3: Invoke the EVS search API on the caCORE 3.1 service as follows:
Results = (List)appService.evsSearch(evsSearch);
searchDescLogicConcept
Input:
gov.nih.nci.cagrid.evs.service.EVSDescLogicConceptSearchParams
Output:
gov.nih.nci.evs.domain.DescLogicConcept[]
Exception:
RemoteExceptionInvalidInputExceptionType
Description:
This method will return an array of gov.nih.nci.evs.domain.DescLogicConcept objects that are published by the caCORE 3.1 EVS service.
The API will take following input: valid vocabulary name (present in the list from the getVocabularyNames, a valid search term that either corresponds to the concept "name" or concept "code" and return the appropriate array of gov.nih.nci.evs.domain.DescLogicConcept objects. All the "associated" objects and attributes corresponding to the caCORE EVS 3.1 information model can be navigated, except for the following:
- Instances of gov.nih.nci.evs.domain.EdgeProperties are not populated currently by the EVS 1.0 core service. These objects are used to specify relationship between a concept and its immediate parent when a DefaultMutableTree is generated. And, the EVS 1.0 core service does NOT produce a Tree.
- Instances of gov.nih.nci.evs.domain.Qualifier are not populated by the EVS 1.0 core service.
- Instances of gov.nih.nci.evs.domain.TreeNode are not populated by the EVS 1.0 core service.
Implementation Details:
The API will use the caCORE 3.1 API to query the EVS service as follows:
Step 1: Connect to the caCORE 3.1 service running at NCICB
appService = ApplicationServiceProvider.getRemoteInstance(EVSConstants.CACORE_31_URL);
Step 2a: Determine if the search term set in the input (EVSDescLogicConceptSearchParams.searchTerm) is a concept code or a name.
Step 2b: If the search term is a "concept code", then build a gov.nih.nci.evs.query.EVSQueryImpl object and set the operation as "getDescLogicConceptNameByCode" as follows:
EVSQuery evsSearch = new EVSQueryImpl();evsSearch. getDescLogicConceptNameByCode(EVSDescLogicConceptSearchParams.getVocabularyName(),
EVSDescLogicConceptSearchParams.getSearchTerm());
Step 2c: If the search term is a "concept name", then build a gov.nih.nci.evs.query.EVSQueryImpl object and set the operation as "searchDescLogicConcepts" as follows:
EVSQuery evsSearch = new EVSQueryImpl();evsSearch. searchDescLogicConcepts (EVSDescLogicConceptSearchParams.getVocabularyName(),EVSDescLogicConceptSearchParams.getSearchTerm());
Step 3: Invoke the EVS search API on the caCORE 3.1 service as follows:
Results = (List)appService.evsSearch(evsSearch);
 | Note: It the search term is a "concept code", then the result from Step 3 is the "name" corresponding to the concept code. This "name" is then used to call Step 2c and Step 3 again to obtain the results. |
getHistoryRecords
Input:
gov.nih.nci.cagrid.evs.service.EVSHistoryRecordsSearchParams
Output:
gov.nih.nci.evs.domain.HistoryRecord[]
Exception:
RemoteExceptionInvalidInputExceptionType
Description:
This method will return an array of gov.nih.nci.evs.domain.HistoryRecord objects that are published by the caCORE 3.1 EVS service.
The API will take following input: valid vocabulary name (present in the list from the getVocabularyNames ) and a valid concept "code" and return the appropriate array of gov.nih.nci.evs.domain.HistoryRecord objects. All the "associated" objects and attributes corresponding to the caCORE EVS 3.1 information model can be navigated.
Implementation Details:
The API will use the caCORE 3.1 API to query the EVS service as follows:
Step 1: Connect to the caCORE 3.1 service running at NCICB
appService = ApplicationServiceProvider.getRemoteInstance(EVSConstants.CACORE_31_URL);
Step 2: Build a gov.nih.nci.evs.query.EVSQueryImpl object and set the operation as "getVocabularyNames" as follows:
EVSQuery evsSearch = new EVSQueryImpl();evsSearch.getHistoryRecords(EVSHistoryRecordsSearchParams.getVocabularyName(),
EVSHistoryRecordsSearchParams.getConceptCode());
Step 3: Invoke the EVS search API on the caCORE 3.1 service as follows:
Results = (List)appService.evsSearch(evsSearch);
searchMetaThesaurus
Input:
gov.nih.nci.cagrid.evs.service.EVSMetaThesaurusSearchParams
Output:
gov.nih.nci.evs.domain.MetaThesaurusConcept[]
Exception:
RemoteExceptionInvalidInputExceptionType
Description:
This method will return an array of gov.nih.nci.evs.domain.MetaThesaurusConcept objects that are published by the caCORE 3.1 EVS service.
The API will take following input:
- Valid Meta Thesaurus source abbreviation (present in the list from the API getMetaSources. A value of "*" indicates that the search term will be queried against ALL available sources
- Search term refers to the concept "name" to be searched in the appropriate source or all sources as indicated above
- The appropriate settings of the tuning parameters to indicate whether the search term is a Concept Unique Identifier (CUI) or a regular search term. If the search term is a CUI, then, the search term is validated to adhere to the following restrictions:
- The CUI begins with the letter "C"
- The CUI has a maximum length of 8 characters
The API will return the appropriate array of gov.nih.nci.evs.domain. MetaThesaurusConcept objects. All the "associated" objects and attributes corresponding to the caCORE EVS 3.1 information model can be navigated.
Implementation Details:
The API will use the caCORE 3.1 API to query the EVS service as follows:
Step 1: Connect to the caCORE 3.1 service running at NCICB
appService = ApplicationServiceProvider.getRemoteInstance(EVSConstants.CACORE_31_URL);
Step 2: Build a gov.nih.nci.evs.query.EVSQueryImpl object and set the operation as "searchMetaThesaurus" as follows:
EVSQuery evsSearch = new EVSQueryImpl();evsSearch.searchMetaThesaurus(EVSMetaThesaurusSearchParams.getSearchTerm(),
EVSMetaThesaurusSearchParams.getLimit(),
EVSMetaThesaurusSearchParams.getSource(),
EVSMetaThesaurusSearchParams.isCui(),
EVSMetaThesaurusSearchParams.isShortResponse(),
EVSMetaThesaurusSearchParams.isScore());
Step 3: Invoke the EVS search API on the caCORE 3.1 service as follows:
Results = (List)appService.evsSearch(evsSearch);
searchSourceByCode
Input:
gov.nih.nci.cagrid.evs.service.EVSSourceSearchParams
Output:
gov.nih.nci.evs.domain.MetaThesaurusConcept[]
Exception:
RemoteExceptionInvalidInputExceptionType
Description:
This method will return an array of gov.nih.nci.evs.domain.MetaThesaurusConcept objects that are published by the caCORE 3.1 EVS service.
The API will take following input:
- A valid Meta Thesaurus source abbreviation (present in the list from the API getMetaSources. The ALL sources value of "" is *NOT PERMITTED for this API.
- A valid value for "code". Some of the concepts in the Meta Thesaurus do not have code associated with them and are displayed in the NCI Meta Thesaurus Browser with the value of "NOCODE". The "NOCODE" value is NOT VALID input for the API.
Implementation Details:
The API will use the caCORE 3.1 API to query the EVS service as follows:
Step 1: Connect to the caCORE 3.1 service running at NCICB
appService = ApplicationServiceProvider.getRemoteInstance(EVSConstants.CACORE_31_URL);
Step 2: Build a gov.nih.nci.evs.query.EVSQueryImpl object and set the operation as "searchSourceByCode" as follows:
EVSQuery evsSearch = new EVSQueryImpl();evsSearch.searchSourceByCode(EVSSourceSearchParams.getCode(),
EVSSourceSearchParams.getSourceAbbreviation());
Step 3: Invoke the EVS search API on the caCORE 3.1 service as follows:
Results = (List)appService.evsSearch(evsSearch);
Error Handling
Error Connecting to caCORE 3.1 Service
All the APIs will throw an exception (java.rmi.RemoteException) if caCORE 3.1 service was unavailable. The following error message will be wrapped into the error "message"
"Error in connecting to the caCORE Service. Please check that the following URI is working correctly: <caCORE 3.1 URL>"
The actual code will be as shown below:
throw new ServiceException("Error in connecting to the caCORE Service. Please " +"check that the following URI is working correctly: " + EVSConstants.CACORE_31_URL, re);
Input Error
All the APIs that accept "inputs" will also throw the exception (gov.nih.nci.cagrid.evsgridservice.stubs.types.InvalidInputExceptionType) if invalid inputs are passed to the API.
The detailed fault will be described in the "faultString" attribute of the class, as shown below:
InvalidInputExceptionType fault = new InvalidInputExceptionType();fault.setFaultString("Invalid inputs: EVSSourceSearchParams object cannot be NULL");throw fault;
Database Changes
- None
Client
The Introduce toolkit generates a "client" class that will be provided to the users.
JSP/HTML
None
Servlet
None
Error Handling
None
Security Issues
All the information accessed by the EVS 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 EVS services will take advantage of all improvements made to the caCORE 3.1 EVS services. However, there will not be any additional performance improvements done to the EVS Grid service.
Internationalization
Not Internationalized
Installation / Packaging
The service will be installed and deployed as part of caGrid 1.0 core service at NCICB.
Migration
No migration changes
Documentation Considerations
The EVS grid service client API will be described in the caGrid 1.0 User Guide and the Programmers Guide.
System Testing
The System test case for the EVS grid service is described in the following:
| Package | gov.nci.nih.cagrid.tests.core.steps. |
| Class | EvsCheckServiceStep |
| Main method | runStep |
The actual methods and the test cases that are tested by the "Main method" are described below:
| API | Test Cases | Test Results |
|---|---|---|
| testMetaThesaurus |
|
|
| testSearchMetaThesaurusConcept | Calls the API "searchMetaThesaurus" with empty value for Search term. | The API will throw "InvalidInputExceptionType" exception with the detailed message in the FaultString attribute |
| testGetHistoryRecords |
|
|
| testSearchSourceByCode |
|
|
| testGetDescriptionLogicConcept |
|
|
| testGetVocabularyNames |
|
|
| testSearchDescLogicConcept |
|
|
Test Guidelines
The test cases are integrated with the caGrid 1.0 test framework.
Test Cases
See System Testing.
Test Results
See System Testing.
Change History
Content changes to this document from the previous to the current level are indicated by revision bars (|) unless a complete rewrite is indicated.
Table 2 - Implementation Specification Document Change Log
| Implementation Specification Document Change Log | |||
|---|---|---|---|
| Version/Date | Approved By | Change Description and Explanation | D - Draft; A - For Review/ Approval; R - Re-Approval, Plan of Record Change |
| 10/2/2006 | Initial Version | D | |
| 11/17/2006 | Added content | D | |
| 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 APPROVAL
Approvers List
The individuals listed in this section constitute the approvers list for the Integration Test Plan document. Formal approval must be received from all approvers prior to the initiation of the next steps in the process.
| Title | Name |
|---|---|
| Project Manager | Arumani Manisundaram |
| Development Manager | Scott Oster |
Reviewers List
The individuals listed in this section constitute the reviewers list for the Master Test Plan document. Formal approval is not required from the reviewers, however, it is desirable to have all reviewers review and comment on the document. Reviewers may choose to concentrate on reviewing only those sections that are in their area of responsibility, rather than the entire document.
| Title | Name |
|---|---|
| Technical Writer | Wendy Ericson-hirons |
END OF DOCUMENT