Page History

page-info

:title}
{panel:title=Contents of this Page}
{toc:minLevel=2}
{panel}

h2. Introduction
This document is a section of the [LexEVS 5.x Programmer's Guide]. It is new for LexEVS v5.1. 

The Pick List Services are integrated parts of the LexEVS core API. They provide the ability to:
* Load Pick List definitions programmatically into the LexGrid repository using the domain objects that are available via the LexGrid logical model
* Apply user restrictions (ex: pickListId) and dynamically resolve the definitions at run time

The LexEVS Pick List Services expose the API particularly for the Pick List elements of the LexGrid Logical Model. For more information on LexGrid model see [http://informatics.mayo.edu/|http://informatics.mayo.edu/].

h2.

 Pick List Class Diagram

These classes implement the LexEVS Pick List API.

|| Class Name

 || Description ||
| PickListsServices | Class to handle list of Pick List Definitions. |
| PickListServices | Class to handle individual Pick List Definition objects to and fro database. |
| PLEntryServices | Class to handle Pick List Entry objects to and fro database. |
| LexEVSPickListServices | Primary interface for LexEVS Pick List API. |
| LexEVSPickListServicesImpl | Implementation of LexEVSPickListServices which is primary interface for LexEVS Pick List API. |
| LoadPickList | Imports the Pick List Definitions in the source file, provided in LexGrid canonical format, to the LexBIG repository. |
| ResolvedPickListEntyList | Class to hold list of resolved pick list entries. |
| ResolvedPickListEntry | Bean for resolved pick list entries. |

The following figure shows the classes in a diagram.

!LexEVS_5.1_Value_domain_PLClassDiagram.jpg|alt="Value Domain PL Class Diagram as described above."!

h2. LexEVS Pick List Service API

h3. Administrative Functions

LexEVS PickListServices provides administrative functions to load and remove pick list definitions.

h4. Loading Pick List Definitions

There are three methods that could be used to load Pick List Definitions:
* loadPickList(PickListDefinition pldef, String systemReleaseURI)
* loadPickList(InputStream inputStream, boolean failOnAllErrors)
* loadPickList(String xmlFileLocation, boolean failOnAllErrors)

h5. loadPickList(PickListDefinition pldef, String systemReleaseURI)

|| Description: | Loads supplied Pick List Definition object |
|| Input: | _org.LexGrid.emf.valueDomains.PickListDefinition

_,
_String_ |
|| Output: | none |
|| Exception: | _LBException_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to load the Pick List Definition object and the System Release URI that this definition belongs to.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl();

{code}
* _Step 2:_ Create and populate the PickListDefinition object.

{code

}
PickListDefinition can be created using _org.LexGrid.emf.valueDomains.PickListDefinition pickList = org.LexGrid.emf.valueDomains.ValuedomainsFactory.eINSTANCE.createPickListDefinition();
Data for pickList object can be populated by using set methods:
pickList.setPickListId(pickListId);
pickList.setRepresentsValueDomain(vdURI);
pickList.setCompleteDomain(true);
pickList.setDefaultEntityCodeNamespace(ecns);
pickList.setDefaultLanguage("en");
pickList.setDefaultSortOrder("asc");
pickList.setIsActive(true);
pickList.setEntityDescription(red);
{code}

Similarly, PickListEntryNode, Property, and Mapping objects can be created and assigned to the pickList object.

{code

}
pickList.getPickListEntryNode.add(pickListEntry);
pickList.setProperties(propertisObject);
pickList.setMappings(mappingsObject);

{code}
* _Step 3:_ Call the load method by passing the Pick List Definition object and the System Release URI.

{code

}
pls.loadPickList(pickList,"Release 2009");

{code} |

h5. loadPickList(InputStream inputStream, boolean failOnAllErrors)

|| Description:

 | Loads Pick List Definitions found in inputStream.

 |
|| Input:

 | _java.io.InputStream

_
_boolean_ |
|| Output: | none |
|| Exception: | _Exception_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to load all Pick List Definitions from the inputstream.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet:
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl()

;
{code}
* _Step 2:_ Call load method by passing the inputSteam and boolean flag whether to stop on load errors: _pls.loadPickList(inputStream, true);

_ |

h5. loadPickList(String xmlFileLocation, boolean failOnAllErrors)

|| Description:

 | Loads Pick List Definitions found in input xml file.

 |
|| Input:

 | _java.lang.String

_
_boolean_ |
|| Output: | none |
|| Exception: | _Exception_ |
|| Implementation Details: | *_Implementation:_*
_Step 1_: Call this method on the associated LexEVS Pick List Service instance to load all Pick List Definitions found in an XML file that is in LexGrid format.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl();

{code}
* _Step 2:_ Call load method by passing the inputfile location and boolean flag whether to stop on load errors:

{code

}
pls.loadPickList(inputXMLFile, true);

{code} |


h4. Remove Pick List Definition

{{removePickList(String pickListId)

}}

|| Description: | Removes supplied Pick List Definition from the system. |
|| Input: | _java.lang.String

_ |
|| Output:

 | none |
|| Exception: | _org.LexGrid.LexBIG.Exceptions.LBException_,

_org.LexGrid.managedobj.RemoveException

_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to remove Pick List Definition from the system that matches the supplied pickListId.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl();

{code}
* _Step 2:_ Call removePickList method:

{code

}
vds.removePickList ("AUTO:AllDomesticANDGM");

{code} |

h3. Validate XML Resources

{{validate}}

|| Description: | Perform validation of the candidate resource without loading data. |
|| Input: | _java.net.URI

_
_int_ |
|| Output: | none |
|| Exception: | _Org.LexGrid.LexBIG.Exceptions.LBParameterException

_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to validate the XML file that is in LexGrid format. This call will not load the data in an XML file.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl();

{code}
* _Step 2:_ Call validate method for validation by supplying URI of the XML file and validation level.

Supported validationLevels include:

{code

}
0 = Verify document is well-formed
1 = Verify document is valid
_pls.validate(uriOfXMLFile, true);

{code} |


h3. Query Functions

Following are some of the query functions provided by LexEVS PickListServices.

h4. getPickListDefinitionById

{{getPickListDefinitionById(String pickListId)}}

|| Description: | Returns pickList definition for supplied pickListId. |
|| Input: | _java.lang.String_ |
|| Output: | _org.LexGrid.emf.valueDomains.PickListDefinition

_ |
|| Exception:

 | _org.LexGrid.LexBIG.Exceptions.LBException

_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to get Pick List Definition for supplied pickListId.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl();

{code}
* _Step 2:_ Call getPickListDefinitionById method:

{code

}
PickListDefinition plDef = pls.getPickListDefinitionById("AUTO:DomesticAutoMakers");

{code} |


h4. getPickListDefinitionsForDomain

{{getPickListDefinitionsForDomain(URI valueDomainURI)

}}

|| Description:

 | Returns all the pickList definitions that represent the supplied valueDomain URI.

 |
|| Input:

 | _java.net.URI

_ |
|| Output:

 | _org.LexGrid.emf.valueDomains.PickListDefinition[]

_ |
|| Exception:

 | _org.LexGrid.LexBIG.Exceptions.LBException

_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to get all the Pick List Definitions that are represented by supplied Value Domain URI.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl();

{code}
* _Step 2:_ Call getPickListDefinitionsForDomain method:

{code

}
PickListDefinition[] plDefs = pls.getPickListDefinitionsForDomain(valueDomainURI);

{code} |

h4. getPickListValueDomain

{{getPickListValueDomain(String pickListId)}}

|| Description: | Returns a URI of the represented valueDomain of the pickList. |
|| Input: | _java.lang.String

_ |
|| Output:

 | _java.net.URI

_ |
|| Exception:

 | _org.LexGrid.LexBIG.Exceptions.LBException

_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to get a Value Domain URI represented by supplied pickListId.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl();

{code}
* _Step 2:_ Call getPickListValueDomain method:

{code

}
URI vdURI = pls.getPickListValueDomain ("AUTO:DomesticAutoMakers");

{code} |


h4. listPickListIds

{{listPickListIds()}}

|| Description: | Returns a list of pickListIds that are available in the system. |
|| Input: | none |
|| Output: | _java.util.List<java.lang.String>

_ |
|| Exception:

 | _org.LexGrid.LexBIG.Exceptions.LBException

_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to get all the PickListIds that are loaded in the system.
 *_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl();

{code}
* _Step 2:_ Call listPickListIds method:

{code

}
List<String> plList = pls.listPickListIds()

;
{code} |

h4. resolvePickList

{{resolvePickList(String pickListId, boolean sortByText)

}}

|| Description:

 | Resolves pickList definition for supplied pickListId.

 |
|| Input:

 | _java.langString,

_
_boolean_ |
|| Output: | _org.lexgrid.valuedomain.dto.ResolvedPickListEntryList

_ |
|| Exception:

 | _org.LexGrid.LexBIG.Exceptions.LBException

_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to get the resolved Pick List Entries for the supplied pickListId. Optionally, if sortByTests is true, sort the pickText in the list.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl()

;
{code}
* _Step 2:_ Call resolvePickList method:

{code

}
ResolvedPickListEntryList pleList = pls.resolvePickList ("AUTO:DomesticAutoMakers", true);

{code} |


h4. resolvePickListForTerm

{{resolvePickListForTerm(String pickListId, String term, String matchAlgorithm, String language, String\[\] context, boolean sortByText)}}

|| Description:

 | Resolves pickList definition by

 applying  supplied arguments. |
|| Input: | _java.lang.String

_
_java.lang.String

_
_java.lang.String

_
_java.lang.String

_
_java.lang.String[]

_
_boolean_ |
|| Output: | _org.lexgrid.valuedomain.dto.ResolvedPickListEntryList

_ |
|| Exception:

 | _org.LexGrid.LexBIG.Exceptions.LBException

_ |
|| Implementation Details: | *_Implementation:_*
_Step 1:_ Call this method on the associated LexEVS Pick List Service instance to get list of Pick List Entries that match the term supplied and meet other supplied restrictions.
*_Sample Call:_*
* _Step 1:_ Instantiate LexEVSPickListServices if it is not done yet :
{code}
org.lexgrid.valuedomain.LexEVSPickListServices pls = new org.lexgrid.valuedomain.impl.LexEVSPickListServicesImpl();

{code}
* _Step 2:_ Call resolvePickListForTerm method:

{code

}
ResolvedPickListEntryList pleList = pls.resolvePickListForTerm ("AUTO:DomesticAutoMakers","Jaguar", MatchAlgorithms.exactMatch.name(), "en", null, true);

{code} |

h3. Resolved Pick List Objects

h4. ResolvedPickListEntry

ResolvedPickListEntry contains resolved Pick List Entry Nodes.

h4. ResolvedPickListEntryList

ResolvedPickListEntryList contains the list of resolved Pick List Entries. Also provides helpful features to add, remove, enumerate Pick List Entries.

h3. Error Handling

Both LexEVS Pick List services uses org.LexGrid.LexBIG.Impl.loaders.MessageDirector to direct all fatal, error, warning, info messages with appropriate messages to the LexBIG log files in the 'log' folder of LexEVS install directory.

Along with MessageDirector, the services will also make use of org.LexGrid.LexBIG.exception.LBException to throw any fatal and error messages to the log file as well as to console.

h2.

 Load Scripts

Scripts to load Pick List Definitions into LexEVS system will be located under 'Admin' folder of LexEVS install directory. These loader scripts will only load data in an XML file that is in LexGrid format.

LoadPickList.bat for Windows environment and LoadPickList.sh for Unix environment.

Both of these scripts take in the following parameters:

{code

}
 -in 
   Input <uri> 
   URI or path specifying location of the source file.
 -v 
   Validate <int> 
   Perform validation of the candidate resource without loading data. Supported levels of validation include:

     0 = Verify document is well-formed
     1 = Verify document is valid 
{code}

Example:

{code

}
 sh LoadPickList.sh \-in "file:///path/to/file.xml"

h2. Installation / Packaging

Pick List service are integrated parts of core LexEVS API and are packaged and installed with other LexEVS services.

h2. System Testing

The System test case for the LexEVS Value Domain service is performed using the JUnit test suite:

{{org.LexGrid.LexBIG.Impl.testUtility.PickListAllTests

}}

This test suite will be run as part of regular LexEVS test suites AllTestsAllConfigs and AllTestsNormalConfigs.

{scrollbar

:icons

=false}