{scrollbar:icons=false}
h1. {page-info:title}
{section}
{column:width=75%}
{panel:title=Contents of this Page}
{toc:minLevel=2}
{panel}
{column}
{column}
{align:right}{include:Menu LexEVS 6.0 CTS2 to Include}{align}
{column}
{section}

h2. Introduction
LexEVS CTS2 Usage Context Query API provides capability to query Usage Context available in the system and also to query the binding between Value Set and Concept Domain in conjunction with Usage Context. In LexEVS, the Usage Context is essentially an entity of type 'usageContext' in a code system version. Using LexEVS CTS 2 Authoring or Loader interfaces, you could create a Code System specially for Usage Context entities, but this is not necessary, but will be convenient to have Usage Context entries in specific code system(s).

h2. Interface
org.lexevs.cts2.query.UsageContextQueryOperation is the main interface for all the queries against Usage Context. This interface can be accessed using main LexEVSCTS2 interface, like:

{code}
org.lexevs.cts2.query.UsageContextQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
{code}

h2. Query Functions
Here are the major query functions available using UsageContextQueryOperation interface:

h3. getUsageContextCodingScheme
This function returns detailed usage context code system.

{{getUsageContextCodingScheme(String codeSystemNameOrURI, String codeSystemVersion)}}

|| *Description:* | Gets the usage context code system. |
|| *Input:* |  * *_java.lang.String codeSystemNameOrURI_* - (*Mandatory*) Name or URI of the code system that contains usage context entities.
 * *_java.lang.String codeSystemVersion_* - (Optional) Version of of the code system that contains usage context entities. |
|| *Output:* | *_org.LexGrid.codingSchemes.CodingScheme_* - Detailed usage context Code System |
|| *Exception:* |  *_org.LexGrid.LexBIG.Exceptions.LBException_* |
|| *Sample Call:* | * _Step 1:_ Instantiate UsageContextQueryOperation if it is not done yet:
{code}
org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
{code}
* _Step 2:_ Call getUsageContextCodingScheme method to get detailed Usage Context code system:
{code}
org.LexGrid.codingSchemes.CodingScheme usageContextCS = ucQuery.getUsageContextCodingScheme("usageContextCodingScheme", "1.0"); 
{code} |


h3. getUsageContextEntity
This function returns detailed Usage Context entity.

{{getUsageContextEntity(String usageContextId, String namespace, String codeSystemNameOrURI, String codeSystemVersion)}}

|| *Description:* | Returns Usage Context entity object. |
|| *Input:* | * *_java.lang.String usageContextId_* - (*Mandatory*) ID of a Usage Context.
 * *_java.lang.String namespace_* - (Optional) Namespace of a Usage Context.
 * *_java.lang.String codeSystemNameOrURI_* - (*Mandatory*) Name or URI of code system that contains the Usage Context.
 * *_java.lang.String codeSystemVersion_* - (Optional) Version of code system that contains the Usage Context. |
|| *Output:* |  *_org.LexGrid.concepts.Entity_* - Detailed Usage Context Entity |
|| *Exception:* |  *_org.LexGrid.LexBIG.Exceptions.LBException_* |
|| *Sample Call:* | * _Step 1:_ Instantiate UsageContextQueryOperation if it is not done yet:
{code}
org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
{code}
* _Step 2:_ Call getUsageContextEntity method to get detailed Usage Context Entity:
{code}
org.LexGrid.concepts.Entity usageContextEntity = ucQuery.getUsageContextEntity("ActAdjudicationInformationCode", null, "usageContextCodingScheme", "1.0"); |
{code}

h3. getUsageContextEntitisWithName
This function returns all the Usage Context entities that matches the name supplied.

{{getUsageContextEntitisWithName(String usageContextName, String codeSystemNameOrURI, String codeSystemVersion, SearchDesignationOption option, String matchAlgorithm, String language)}}

|| *Description:* | Returns list of Usage Context entities matching the name provided. |
|| *Input:* |  * *_java.lang.String usageContextName_* - (*Mandatory*) Name of a Usage Context to match.
 * *_java.lang.String codeSystemNameOrURI_* - (*Mandatory*) Name or URI of code system that contains the Usage Context.
 * *_java.lang.String codeSystemVersion_* - (Optional) Version of code system that contains the Usage Context.
 * *_org.LexGrid.LexBIG.LexBIGService.CodedNodeSet.SearchDesignationOption option_* - (Optional) Indicates the designations to search (one of the enumerated type SearchDesignationOption).
 * *_java.lang.String matchAlgorithm_* - (*Mandatory*) Local name of the match algorithm - possible algorithms are returned in LexEVSCTS2.getSupportedSearchAlgorithmNames().
 * *_java.lang.String language_* - (Optional) Language of search string. If missing, uses the default language specified in the context. |
|| *Output:* |  *_java.util.List<org.LexGrid.concepts.Entity>_* - List of detailed Usage Context entities that match supplied name. |
|| *Exception:* |  *_org.LexGrid.LexBIG.Exceptions.LBException_* |
|| *Sample Call:* | * _Step 1:_ Instantiate UsageContextQueryOperation if it is not done yet:
{code}
org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
{code}
* _Step 2:_ Call getUsageContextEntitisWithName method by passing the name to search:
{code}
java.util.List<org.LexGrid.concepts.Entity> usageContextEntities = ucQuery.getUsageContextEntitisWithName("code", "usageContextCodingScheme", null, null, "subString", null); |
{code}


h3. getUsageContextCodedNodeSet
This is a helper function that returns Coded Node Set(CNS) for Usage Context entities. Further restrictions like, matchingDesignation, Status, Properties, etc., can be applied on this CNS and than resolved.

{{getUsageContextCodedNodeSet(String codeSystemNameOrURI, String codeSystemVersion)}}

|| *Description:* | Returns coded node set for UsageContext entities. |
|| *Input:* |  * *_java.lang.String codeSystemNameOrURI_* - (*Mandatory*) Name or URI of code system that contains the Usage Context.
 * *_java.lang.String codeSystemVersion_* - (Optional) Version of code system that contains the Usage Context. |
|| *Output:* |  *_org.LexGrid.LexBIG.LexBIGService.CodedNodeSet_* - Unresolved Usage Context coded node set. |
|| *Exception:* |  *_org.LexGrid.LexBIG.Exceptions.LBException_* |
|| *Sample Call:* | * _Step 1:_ Instantiate UsageContextQueryOperation if it is not done yet:
{code}
org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
{code}
* _Step 2:_ Call getUsageContextCodedNodeSet to get Usage Context Coded node Set:
{code}
CodedNodeSet usageContextCNS = ucQuery.getUsageContextCodedNodeSet("usageContextCodingScheme", null);
{code}
* _Step 3:_ Apply restrictions to the CNS and resolve:
{code}
usageContextCNS.restrictToMatchingProperties(null, new PropertyType[] { PropertyType.PRESENTATION }, "Auto", "startsWith", null);
org.LexGrid.LexBIG.DataModel.Core.ResolvedConceptReference[] rcr = usageContextCNS.resolveToList(null, null, null, 1).getResolvedConceptReference(); 
{code} |


h3. listAllUsageContextEntities
This function returns all the Usage Context entities found in supplied code system version.

{{listAllUsageContextEntities(String codeSystemNameOrURI, String codeSystemVersion)}}

|| *Description:* | Returns all the Usage Context entities found in supplied code system version. |
|| *Input:* |  * *_java.lang.String codeSystemNameOrURI_* - (*Mandatory*) Name or URI of code system that contains the Usage Context.
 * *_java.lang.String codeSystemVersion_* - (Optional) Version of code system that contains the Usage Context. |
|| *Output:* | *_java.util.List<org.LexGrid.concepts.Entity>_* - List of Usage Context entities found in supplied code system version. |
|| *Exception:* |  *_org.LexGrid.LexBIG.Exceptions.LBException_* |
|| *Sample Call:* | * _Step 1:_ Instantiate UsageContextQueryOperation if it is not done yet:
{code}
org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
{code}
* _Step 2:_ Call listAllUsageContextEntities to get all Usage Context entities:
{code}
java.util.List<org.LexGrid.concepts.Entity> usageContexts = ucQuery.listAllUsageContextEntities("usageContextCodingScheme", "1.0"); 
{code} |


h3. listAllUsageContextIds
This function is similar to previous one, but instead of returning detailed Usage Context entities, it just returns identifiers of the Usage Context.

{{listAllUsageContextIds(String codeSystemNameOrURI, String codeSystemVersion)}}

|| *Description:* | Returns all the Usage Context identifiers found in supplied code system version. |
|| *Input:* |  * *_java.lang.String codeSystemNameOrURI_* - (*Mandatory*) Name or URI of code system that contains the Usage Context.
 * *_java.lang.String codeSystemVersion_* - (Optional) Version of code system that contains the Usage Context. |
|| *Output:* |  *_java.util.List<String>_* - List of Usage Context identifiers found in supplied code system version. |
|| *Exception:* |  *_org.LexGrid.LexBIG.Exceptions.LBException_* |
|| *Sample Call:* | * _Step 1:_ Instantiate UsageContextQueryOperation if it is not done yet:
{code}
org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
{code}
* _Step 2:_ Call listAllUsageContextIds to get all Usage Context identifiers:
{code}
java.util.List<java.lang.String> usageContextIds = ucQuery.listAllUsageContextIds("usageContextCodingScheme", "1.0"); 
{code}  |
\\
{scrollbar:icons=false}