oracle.hsgbu.ets.base

Interface ETSService

All Known Subinterfaces:

ETSAdministrationService

public interface ETSService

Provides a starting point for terminology services. Although it does not represent any data, this interface provides methods for finding CodingScheme, ConceptList, and UsageContext objects, which, in turn, can be used to find all other ETS objects.

See Also:

CodingScheme, ConceptList, UsageContext

Field Summary

Fields

Modifier and Type	Field and Description
static String	LOOKUP_GROUP_NAME Deprecated. Use the field on ConceptList instead.

Method Summary

Modifier and Type	Method and Description
Classification	findClassificationByCode(String code) Obtains a Classification based on its classification code.
CodingScheme	findCodingScheme(String etsID) Finds a CodingScheme object by its ETS identifier.
CodingSchemeVersion	findCodingSchemeVersion(String etsID) Finds a CodingSchemeVersion object by its ETS identifier.
Concept	findConcept(String etsId) Finds a Concept object by the specified ETS identifier.
ConceptListMember[]	findConceptListMembers(String[] groupNames, String[] conceptListNames, String[] membershipCodes, int prefetchDescriptions, boolean prefetchConcept) Bulk fetches multiple active ConceptListMember objects associated with the specified concept lists and membership codes.
Concept[]	findConcepts(String[] etsIds, boolean prefetchDescriptions) Fetches or validates the existence of a set of concepts.
Concept[]	findConcepts(String[] etsIds, int prefetchDescriptionOptions) Fetches or validates the existence of a set of concepts.
Concept[]	findConcepts(String[] etsIds, UsageContext[] usageContexts, int prefetchDescriptionOptions) Fetches or validates the existence of a set of concepts.
Concept[]	findConcepts(String[] etsIds, UsageContext[] usageContexts, int prefetchDescriptionOptions, Locale locale) Fetches or validates the existence of a set of concepts in a given Locale.
ConceptDescription	findDescription(String etsId) Finds a ConceptDescription object by the specified ETS identifier.
ConceptDescription[]	findDescriptionsForConceptIDs(String[] conceptIDArray) Finds all concept descriptions corresponding to an array of Concept identifiers.
LocalConceptDescription[]	findLocallyPreferredDescriptionsForConceptIDs(String[] conceptIDArray) Finds locally preferred concept descriptions corresponding to the array of Concept identifiers that was passed in.
Classification[]	findMatchingClassificationsByDescription(String termPattern) Finds classification by a String description search pattern.
Concept[]	findMatchingConceptsByDescriptionTerm(String termPattern) Finds Concept objects whose terminology description or local description matches the given text pattern.
Concept[]	findMatchingConceptsByDescriptionTerm(String termPattern, long maxResults) Finds Concept objects whose terminology description or local description matches the given text pattern.
Relationship	findRelationship(String etsId) Finds a Relationship object by the specified ETS identifier.
TerminologyConceptDescription[]	findTerminologyPreferredDescriptionsForConceptIDs(String[] conceptIDArray) Finds terminology preferred concept descriptions corresponding to the array of Concept identifiers that were passed in.
ETSAdministrationService	getAdministrationServiceInstance() Gets an instance of ETSAdministrationService.
CodingScheme[]	getAllCodingSchemes() Gets all CodingScheme objects in the system.
ConceptList[]	getAllConceptLists() Gets all ConceptList objects in the system.
ConceptList[]	getAllConceptLists(int status) Gets an array of all ConceptList objects in a specified state.
UsageContext[]	getAllUsageContexts() Gets all UsageContext objects in the system.
ETSAuthoringService	getAuthoringServiceInstance() Gets an instance of ETSAuthoringService.
CodingScheme	getCodingScheme(String schemeName) Gets a specific CodingScheme object based on its name.
CodingScheme	getCodingSchemeByOID(String oid) Gets a specific CodingScheme object based on its object identifier (OID).
ConceptList	getConceptList(String name) Gets a specific ConceptList based on its name from the default group as defined in ConceptList.DEFAULT_GROUP.
ConceptList	getConceptList(String groupName, String name) Gets ConceptList by group and name.
ConceptList	getConceptListByID(String clID) Gets a ConceptList based on its ETS ID.
String[]	getConceptListGroupNames() Gets all group names in the system.
ConceptList[]	getConceptListsByGroupName(String groupName) Gets all ConceptList objects that belong to a particular group.
String[]	getEquivalentConceptIDs(String conceptID, int equivalenceType) Finds all concepts equivalent to a given concept using the requested equivalence method.
String[]	getEquivalentConceptIDs(String conceptID, int equivalenceType, String equivalenceContext, boolean depthAll) Finds all concepts equivalent to a given concept using the requested mapping equivalence method.
String[]	getEquivalentConceptIDs(String conceptID, int equivalenceType, String equivalenceContext, boolean depthAll, String codingSchemeVersionID) Finds all concepts that are equivalent to a given concept and are contained within a specific CodingSchemeVersion using the requested mapping equivalence method.
ETSMappingService	getMappingServiceInstance() Gets an instance of ETSMappingService.
CodingScheme[]	getMatchingCodingSchemes(String namePattern) Gets the CodingScheme objects whose names match the specified SQL pattern.
ConceptList[]	getMatchingConceptLists(String namePattern) Gets the ConceptList objects that belong to the default group defined as ConceptList.DEFAULT_GROUP and have names that match the specified SQL pattern.
ConceptList[]	getMatchingConceptListsByDescription(String groupName, String descriptionPattern) Gets the ConceptList object belonging to the specified group and having a description that matches the specified SQL pattern.
UsageContext[]	getMatchingUsageContexts(String namePattern) Gets all UsageContext objects whose names match a given SQL pattern.
Date	getMaxDate() Gets the latest date stored in the database tables.
Date	getSystemDate() Gets the current system date (SYSDATE) from the database.
UsageContext	getUsageContext(String name) Gets a specific UsageContext object based on its name.
UsageContext	getUsageContextForExternalOwner(String ownerType, String ownerID) Gets the UsageContext associated with an owner identifier.
String[]	getUsageContextOwnerTypes() Retrieves all current UsageContextOwnerTypes.
boolean	isEquivalent(String conceptID1, String conceptID2, int equivalenceType) Indicates if two concepts are equivalent using the requested equivalence method.
boolean	isEquivalent(String conceptID1, String conceptID2, int equivalenceType, String equivalenceContext, boolean depthAllFlag) Indicates if this Concept is equivalent to another using the requested mapping equivalence method.
Concept[]	narrowConceptResults(String[] startingSetIDs, String searchPattern, boolean prefetchDescription) Narrows down a set of concept identifiers, retrieving only concepts whose identifiers are in the set and whose terminology-preferred description matches searchPattern
boolean	validateConceptListMembership(String groupName, String conceptlistName, String membershipCode) Validates that the specified concept list contains an active concept member with the passed in membership code.

Field Detail

LOOKUP_GROUP_NAME

static final String LOOKUP_GROUP_NAME

Deprecated. Use the field on ConceptList instead.

The name of the concept list group to which CTB lookup types belong.

See Also:

Constant Field Values

Method Detail

findCodingScheme

CodingScheme findCodingScheme(String etsID)
                       throws ETSNotFoundException,
                              ETSBadParameterException,
                              ETSDataException

Finds a CodingScheme object by its ETS identifier. This method uses server-side caching.

Parameters:

etsID - The ETS identifier of the coding scheme to find

Returns:

The CodingScheme object.

Throws:

ETSNotFoundException - If the coding scheme is not found.

ETSBadParameterException - If etsID is null.

ETSDataException - If a data transport error occurs.

findCodingSchemeVersion

CodingSchemeVersion findCodingSchemeVersion(String etsID)
                                     throws ETSNotFoundException,
                                            ETSBadParameterException,
                                            ETSDataException

Finds a CodingSchemeVersion object by its ETS identifier. This method uses server-side caching.

Parameters:

etsID - The ETS identifier of the coding scheme version to find.

Returns:

The CodingSchemeVersion object.

Throws:

ETSNotFoundException - If the CodingSchemeVersion object is not found

ETSBadParameterException - If etsID is null.

ETSDataException - If a data transport error occurs.

findConcept

Concept findConcept(String etsId)
             throws ETSNotFoundException,
                    ETSBadParameterException,
                    ETSDataException

Finds a Concept object by the specified ETS identifier. This method uses server-side caching.

Parameters:

etsId - The ETS identifier of the Concept to find.

Returns:

The Concept object.

Throws:

ETSNotFoundException - If the Concept object is not found.

ETSBadParameterException - If a null argument is passed in.

ETSDataException - If a data transport error occurs.

findRelationship

Relationship findRelationship(String etsId)
                       throws ETSNotFoundException,
                              ETSBadParameterException,
                              ETSDataException

Finds a Relationship object by the specified ETS identifier.

Parameters:

etsId - The ETS identifier of the relationship to find.

Returns:

The Relationship object.

Throws:

ETSNotFoundException - If the Relationship object is not found.

ETSBadParameterException - If a null argument is passed in.

ETSDataException - If a data transport error occurs.

findDescription

ConceptDescription findDescription(String etsId)
                            throws ETSNotFoundException,
                                   ETSBadParameterException,
                                   ETSDataException

Finds a ConceptDescription object by the specified ETS identifier. This includes both locally defined and terminology-defined descriptions.

Parameters:

etsId - The ETS identifier of the description to find.

Returns:

A ConceptDescription object.

Throws:

ETSNotFoundException - If the description is not found.

ETSBadParameterException - If a null argument is passed in.

ETSDataException - If a data transport error occurs.

getConceptList

ConceptList getConceptList(String name)
                    throws ETSNotFoundException,
                           ETSBadParameterException,
                           ETSDataException

Gets a specific ConceptList based on its name from the default group as defined in ConceptList.DEFAULT_GROUP. This method uses server-side caching.

Parameters:

name - The name of the ConceptList to be retrieved.

Returns:

The ConceptList object.

Throws:

ETSNotFoundException - If the specified ConceptList does not exist.

ETSBadParameterException - If an invalid name argument is passed in.

ETSDataException - If a data transport error occurs.

getConceptListByID

ConceptList getConceptListByID(String clID)
                        throws ETSBadParameterException,
                               ETSNotFoundException,
                               ETSDataException

Gets a ConceptList based on its ETS ID. This method uses server-side caching.

Parameters:

clID - The ETS ID of the ConceptList to find.

Returns:

The ConceptList object.

Throws:

ETSNotFoundException - If the ConceptList is not found.

ETSBadParameterException - If a null argument is passed in.

ETSDataException - If a data transport error occurs.

getMatchingConceptLists

ConceptList[] getMatchingConceptLists(String namePattern)
                               throws ETSDataException,
                                      ETSBadParameterException

Gets the ConceptList objects that belong to the default group defined as ConceptList.DEFAULT_GROUP and have names that match the specified SQL pattern.

Parameters:

namePattern - A standard SQL pattern-matching string that is be compared to the names of ConceptList objects.

Returns:

An array of ConceptList objects, or a zero-length array if no match is found.

Throws:

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If a null pattern argument is passed in.

getAllConceptLists

ConceptList[] getAllConceptLists()
                          throws ETSDataException

Gets all ConceptList objects in the system.

Returns:

An array of zero or more ConceptList objects.

Throws:

ETSDataException - If a data transport error occurs.

getCodingScheme

CodingScheme getCodingScheme(String schemeName)
                      throws ETSNotFoundException,
                             ETSDataException,
                             ETSBadParameterException

Gets a specific CodingScheme object based on its name. This method uses server-side caching.

Parameters:

schemeName - The name of the CodingScheme object to be retrieved.

Returns:

The CodingScheme object.

Throws:

ETSNotFoundException - If the specified CodingScheme object does not exist

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If name argument is invalid.

getCodingSchemeByOID

CodingScheme getCodingSchemeByOID(String oid)
                           throws ETSNotFoundException,
                                  ETSDataException,
                                  ETSBadParameterException

Gets a specific CodingScheme object based on its object identifier (OID). This method uses server-side caching.

Parameters:

oid - The OID of the CodingScheme object to be retrieved

Returns:

The CodingScheme object.

Throws:

ETSNotFoundException - If the specified CodingScheme OID does not exist

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If OID argument is invalid.

getMatchingCodingSchemes

CodingScheme[] getMatchingCodingSchemes(String namePattern)
                                 throws ETSDataException,
                                        ETSBadParameterException

Gets the CodingScheme objects whose names match the specified SQL pattern.

Parameters:

namePattern - A standard SQL pattern-matching string that is compared to the name of each CodingScheme object.

Returns:

An array of CodingScheme objects, or a zero-length array if no CodingScheme objects match.

Throws:

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If pattern passed in is invalid.

getAllCodingSchemes

CodingScheme[] getAllCodingSchemes()
                            throws ETSDataException

Gets all CodingScheme objects in the system.

Returns:

An array of zero or more CodingScheme objects.

Throws:

ETSDataException - If a data transport error occurs.

getUsageContext

UsageContext getUsageContext(String name)
                      throws ETSNotFoundException,
                             ETSDataException,
                             ETSBadParameterException

Gets a specific UsageContext object based on its name.

Parameters:

name - The name of the UsageContext object to be retrieved

Returns:

A UsageContext object.

Throws:

ETSNotFoundException - If the specified UsageContext object does not exist.

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If an invalid name argument is passed in.

getMatchingUsageContexts

UsageContext[] getMatchingUsageContexts(String namePattern)
                                 throws ETSBadParameterException,
                                        ETSDataException

Gets all UsageContext objects whose names match a given SQL pattern.

Parameters:

namePattern - A standard SQL pattern-matching string that is compared to the names of UsageContext objects.

Returns:

An array of UsageContext objects, or a zero-length array.

Throws:

ETSBadParameterException - If a bad pattern is passed in.

ETSDataException - If a data transport error occurs.

getAllUsageContexts

UsageContext[] getAllUsageContexts()
                            throws ETSDataException

Gets all UsageContext objects in the system.

Returns:

An array of zero or more UsageContext objects.

Throws:

ETSDataException - If a data transport error occurs.

getAdministrationServiceInstance

ETSAdministrationService getAdministrationServiceInstance()

Gets an instance of ETSAdministrationService. This service is used for managing objects in the ETS repository.

Returns:

A constructed ETSAdministrationService instance.

getAuthoringServiceInstance

ETSAuthoringService getAuthoringServiceInstance()

Gets an instance of ETSAuthoringService. This service is used for adding, removing, and updating ETS components within an editable CodingScheme.

Returns:

A constructed ETSAuthoringService instance.

getMappingServiceInstance

ETSMappingService getMappingServiceInstance()

Gets an instance of ETSMappingService. This service is used to load and navigate ETS map sets.

Returns:

A constructed ETSMappingService instance.

getAllConceptLists

ConceptList[] getAllConceptLists(int status)
                          throws ETSDataException,
                                 ETSBadParameterException

Gets an array of all ConceptList objects in a specified state.

Parameters:

status - The status of ConceptList objects to be retrieved. Status constants are defined in the ConceptList interface. The following constants are applicable: STATUS_ACTIVE, STATUS_RETIRED, and STATUS_ALL.

Returns:

All ConceptList objects that are in the status specified at present date. If no ConceptList object is found, this method returns an empty array.

Throws:

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If the passed in status is not a valid constant.

getConceptListGroupNames

String[] getConceptListGroupNames()
                           throws ETSDataException

Gets all group names in the system. The maximum length of this attribute is 50.

Returns:

All group names in the system.

Throws:

ETSDataException - If a data transport error occurs.

getConceptList

ConceptList getConceptList(String groupName,
                           String name)
                    throws ETSBadParameterException,
                           ETSNotFoundException,
                           ETSDataException

Gets ConceptList by group and name. This method uses server-side caching.

Parameters:

groupName - The name of the group to which the ConceptList to be retrieved belongs. If null, the default group name is defined by the constant, ConceptList.DEFAULT_GROUP.

name - The name of the ConceptList.

Returns:

The ConceptList object.

Throws:

ETSBadParameterException - If name is null or an empty string, or if groupName is an empty string or null.

ETSNotFoundException - If the specified group does not exist, or if the ConceptList does not exist

ETSDataException - If a data transport error occurs.

getConceptListsByGroupName

ConceptList[] getConceptListsByGroupName(String groupName)
                                  throws ETSBadParameterException,
                                         ETSDataException

Gets all ConceptList objects that belong to a particular group.

Parameters:

groupName - Name of group.

Returns:

An array of ConceptList objects belonging to the group. If no ConceptList belongs to the group, the method returns an empty array.

Throws:

ETSBadParameterException - If groupName is an empty string, null, or a non-existing group name.

ETSDataException - If a data transport error occurs.

getUsageContextOwnerTypes

String[] getUsageContextOwnerTypes()
                            throws ETSDataException

Retrieves all current UsageContextOwnerTypes. The maximum length of this attribute is 30.

Returns:

An array of strings representing the owner types that are currently registered, or an empty array if no UsageContext mapping exists.

Throws:

ETSDataException - If a data transport error occurs.

getUsageContextForExternalOwner

UsageContext getUsageContextForExternalOwner(String ownerType,
                                             String ownerID)
                                      throws ETSNotFoundException,
                                             ETSDataException,
                                             ETSBadParameterException

Gets the UsageContext associated with an owner identifier. ETS offers a simple mapping between external identifiers and UsageContext objects as a convenience. These mappings have no direct effect on the behavior of ETS. However, these mappings are useful for applications that find the most appropriate UsageContext for a particular user, organization, or profession.

Parameters:

ownerType - The type of owner identifier that defines an identifier space. Examples of owner type are organization identifiers and staff members.

ownerID - The identifier of the external owner.

Returns:

The UsageContext associated with the owner type and ID.

Throws:

ETSNotFoundException - If no code>UsageContext is found for the passed in values.

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If the ownerType or ownerID parameters are null, or if they are zero-length strings.

narrowConceptResults

Concept[] narrowConceptResults(String[] startingSetIDs,
                               String searchPattern,
                               boolean prefetchDescription)
                        throws ETSBadParameterException,
                               ETSDataException

Narrows down a set of concept identifiers, retrieving only concepts whose identifiers are in the set and whose terminology-preferred description matches searchPattern

NOTE: This method is used mainly by user-interactive applications. This method can also prefetch the concepts preferred description.

Parameters:

startingSetIDs - The set of concept identifiers to search within.

searchPattern - The search pattern with which the concepts' description has to be matched. It can be an intermediate SQL search pattern such as "%xxx%"

prefetchDescription - boolean value indicating if this method also returns the preferred description of each concept returned.

Returns:

An array(possibly zero-length) of concepts, and their prefetched descriptions.

Throws:

ETSBadParameterException -

• If null parameters are passed in.
• If the startingSetIDs has null string values contained.
• If searchPattern is an empty string.
• If the passed in array's length is zero, or if the intermediate search pattern does not have at least three alphanumeric characters.

  NOTE: % is not an alphanumeric character.

ETSDataException - If a data transport error occurs.

findConcepts

Concept[] findConcepts(String[] etsIds,
                       boolean prefetchDescriptions)
                throws ETSBadParameterException,
                       ETSDataException

Fetches or validates the existence of a set of concepts. If the prefetch flag is set to true, the descriptions will be requested in the base language (Base language is constructed by concatenating profile options value for ETS MLS Language Code(In uppercase) and for ETS MLS Country Code). If the base language is mapped to another language then the descriptions will be retrieved in the mapped language instead. See the main package description for more information regarding mappings.

Parameters:

etsIds - An array of ETS identifiers to validate.

prefetchDescriptions - If true, this method attempts a bulk prefetch of the terminology preferred descriptions for the retrieved Concept objects.

Returns:

An array of Concept objects corresponding to the array of ETS identifiers passed in. If an ETS identifier does not match a Concept object, the corresponding index of the return array will be null.

Throws:

ETSBadParameterException - If one of the elements of the etsIds array is null.

ETSDataException -

• If a data transport error occurs.
• If no language mapping information exists for the base language and territory.
• If no terminology descriptions are found (when doing a prefetch).

findConcepts

Concept[] findConcepts(String[] etsIds,
                       int prefetchDescriptionOptions)
                throws ETSBadParameterException,
                       ETSDataException

Fetches or validates the existence of a set of concepts. This method uses server-side caching. If the prefetch flag is set to a prefetch option, the descriptions will be requested in the base language (Base language is constructed by concatenating profile options value for ETS MLS Language Code(In uppercase) and for ETS MLS Country Code). If the base language is mapped to another language then the descriptions will be retrieved in the mapped language instead (for terminology descriptions). If no local descriptions are found in the base language, the language that the base language is mapped to will be used to look up local descriptions. See the main package description for more information regarding mappings.

Parameters:

etsIds - An array of ETS identifiers to validate.

prefetchDescriptionOptions - This argument can be one of the following constants defined in Concept interface:

• TERMINOLOGY_PREFERRED: Prefetches the terminology-preferred description.
• LOCAL_PREFERRED: Prefetches the locally preferred description.
• TERMINOLOGY_PREFERRED_AND_LOCAL_PREFERRED: Prefetches both terminology-preferred and locally preferred description.
• NONE: Does not perform any prefetch.

Returns:

An array of Concept objects corresponding to the array of ETS identifiers passed in. If an ETS identifier does not match a concept, the corresponding index of the return array will be null.

Throws:

ETSBadParameterException - If one of the elements of the etsIds array is null, or if prefetchDescriptionOptions is not one of the valid integer constants.

ETSDataException -

• If a data transport error occurs.
• If no language mapping information exists for the base language and territory.
• If no terminology descriptions are found (when doing a prefetch).

findConcepts

Concept[] findConcepts(String[] etsIds,
                       UsageContext[] usageContexts,
                       int prefetchDescriptionOptions)
                throws ETSBadParameterException,
                       ETSDataException

Fetches or validates the existence of a set of concepts. This method uses server-side caching. If the prefetch flag is set to a prefetch option, the descriptions will be requested in the base language (Base language is constructed by concatenating profile options value for ETS MLS Language Code(In uppercase) and for ETS MLS Country Code). If the base language is mapped to another language then the descriptions will be retrieved in the mapped language instead (for terminology descriptions). If no local descriptions are found in the base language, the language that the base language is mapped to will be used to look up local descriptions. See the main package description for more information regarding mappings.

Parameters:

etsIds - An array of ETS identifiers to validate.

usageContexts - An array of UsageContext objects. Descriptions that are linked to the concepts by these usage contexts are prefetched. Members of this array can be null.

prefetchDescriptionOptions - This argument can be one of the following constants defined in Concept interface:

• TERMINOLOGY_PREFERRED: Prefetches the terminology-preferred description.
• LOCAL_PREFERRED: Prefetches the locally preferred description.
• TERMINOLOGY_PREFERRED_AND_LOCAL_PREFERRED: Prefetches both terminology-preferred and locally preferred description.
• NONE: does not perform any pre-fetch.

Returns:

An array of Concept objects corresponding to the array of ETS identifiers passed in. If an ETS identifier does not match a concept, the corresponding index of the return array will be null. Prefetched descriptions are also returned within the Concept objects

Throws:

ETSBadParameterException - If etsIds contains a null ETS identifier or prefetchDescriptionOptions is not one of the valid integer constants. This exception is also thrown if etsIds is null or if etsIds and usageContexts have different sized array lengths.

ETSDataException -

• If a data transport error occurs.
• If no language mapping information exists for the base language and territory.
• If no terminology descriptions are found (when doing a prefetch).

findConcepts

Concept[] findConcepts(String[] etsIds,
                       UsageContext[] usageContexts,
                       int prefetchDescriptionOptions,
                       Locale locale)
                throws ETSBadParameterException,
                       ETSDataException

Fetches or validates the existence of a set of concepts in a given Locale. This method uses server-side caching. If the given Locale is mapped to a different Locale then the descriptions will be retrieved in the mapped Locale instead (for terminology descriptions). If no local descriptions are found in the requested Locale, the mapped Locale will be used to look up local descriptions. See the main package description for more information regarding mappings.

Parameters:

etsIds - An array of ETS identifiers to validate.

locale - Locale to prefetch descriptions in. The Locale should only consist of a language and territory. If the Locale object is null, the retrieved description will default to the base language (Base language is constructed by concatenating profile options value for ETS MLS Language Code(In uppercase) and for ETS MLS Country Code).

usageContexts - An array of UsageContext objects. Descriptions that are linked to the concepts by these usage contexts are prefetched. Members of this array can be null.

prefetchDescriptionOptions - This argument can be one of the following constants defined in Concept interface:

• TERMINOLOGY_PREFERRED: Prefetches the terminology-preferred description.
• LOCAL_PREFERRED: Prefetches the locally preferred description.
• TERMINOLOGY_PREFERRED_AND_LOCAL_PREFERRED: Prefetches both terminology-preferred and locally preferred description.
• NONE: does not perform any pre-fetch.

Returns:

An array of Concept objects corresponding to the array of ETS identifiers passed in for the given Locale. If an ETS identifier does not match a concept, the corresponding index of the return array will be null. Prefetched descriptions are also returned within the Concept objects as per the given Locale.

Throws:

ETSBadParameterException -

• if etsIds contains a null ETS identifier
• if prefetchDescriptionOptions is not one of the valid integer constants
• if etsIds is null
• if etsIds and usageContexts have different sized array lengths
• if the passed Locale parameter is not valid
• if the Locale contains a variant value

ETSDataException -

• If a data transport error occurs.
• If the Locale parameter is valid, but no language mapping information exists for that language and territory.
• If no terminology descriptions are found (when doing a prefetch).

Since:

5.3

getMatchingConceptListsByDescription

ConceptList[] getMatchingConceptListsByDescription(String groupName,
                                                   String descriptionPattern)
                                            throws ETSDataException,
                                                   ETSBadParameterException

Gets the ConceptList object belonging to the specified group and having a description that matches the specified SQL pattern.

Parameters:

groupName - The group to search within for matching concept lists. If null, search through all available groups for matching concept lists.

NOTE: This is an equality check, not a pattern-matching one.

descriptionPattern - A standard SQL pattern-matching string that will be compared to the descriptions of ConceptList objects.

Returns:

An array of ConceptList objects, or a zero-length array if no matches are found.

Throws:

ETSDataException - If a data transport error occurs.

ETSBadParameterException -

• If groupName does not exist, or is an empty string.
• If descriptionPattern is null or an empty string.

isEquivalent

boolean isEquivalent(String conceptID1,
                     String conceptID2,
                     int equivalenceType)
              throws ETSDataException,
                     ETSNotFoundException,
                     ETSBadParameterException

Indicates if two concepts are equivalent using the requested equivalence method. This method performs at least as well as the getEquivalentConceptIDs(java.lang.String, int) method and may perform significantly better in some cases.

Parameters:

conceptID1 - The first concept identifier to be compared.

conceptID2 - The second concept identifier to be compared.

equivalenceType - The type of equivalence to be used. If the value of this parameter is EQUIVALENCE_TYPE_MAPPING (in the Concept interface), this method will use the default equivalence context DEFAULT_EQUIVALENCE_CONTEXT (in the Concept interface) and look for all possible cross map links.

Returns:

true If the concepts are considered equivalent using the specified method

Throws:

ETSDataException - If a data transport error occurs.

ETSNotFoundException - If conceptID1 or conceptID2 is not a valid concept.

ETSBadParameterException - If the concept identifier is empty or null, or if the equivalence type is not recognized.

getEquivalentConceptIDs

String[] getEquivalentConceptIDs(String conceptID,
                                 int equivalenceType)
                          throws ETSDataException,
                                 ETSNotFoundException,
                                 ETSBadParameterException

Finds all concepts equivalent to a given concept using the requested equivalence method. This method can make use of server-side caching. The maximum length of this attribute is 30.

Parameters:

conceptID - The identifier of the concept to be queried

equivalenceType - The type of equivalence to be used. If its value is EQUIVALENCE_TYPE_MAPPING, this method will use the default equivalence context DEFAULT_EQUIVALENCE_CONTEXT (in the Concept interface) and look for all possible cross map links.

Returns:

Array of concept identifiers that is equivalent to the passed concept, including the passed concept itself. The return is guaranteed to contain at least the conceptID that was passed as a parameter (return length is at least 1).

Throws:

ETSDataException - If a data transport error occurs.

ETSNotFoundException - If a concept identifier is not a valid concept.

ETSBadParameterException - If the conceptID parameter is empty or null, or if the equivalence type is not recognized.

validateConceptListMembership

boolean validateConceptListMembership(String groupName,
                                      String conceptlistName,
                                      String membershipCode)
                               throws ETSDataException,
                                      ETSBadParameterException,
                                      ETSNotFoundException

Validates that the specified concept list contains an active concept member with the passed in membership code.

Parameters:

groupName - The name of the group to which the concept list belongs.

conceptlistName - The name of the concept list to validate against.

membershipCode - The membership code of the concept member being validated.

Throws:

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If conceptlistName, membershipCode, or groupName are null or empty strings.

ETSNotFoundException - If a concept list with the specified conceptListName or groupName does not exist

isEquivalent

boolean isEquivalent(String conceptID1,
                     String conceptID2,
                     int equivalenceType,
                     String equivalenceContext,
                     boolean depthAllFlag)
              throws ETSDataException,
                     ETSNotFoundException,
                     ETSBadParameterException

Indicates if this Concept is equivalent to another using the requested mapping equivalence method. This method only determines if the two concepts are mapping equivalence. To see if they are semantic equivalence, use isEquivalent.

Parameters:

conceptID1 - The first concept identifier to be compared.

conceptID2 - The second concept identifier to be compared.

equivalenceType - The type of equivalence to be used. This method accepts only the EQUIVALENCE_TYPE_MAPPING equivalence type in the Concept interface.

equivalenceContext - The equivalence context of the mapping equivalence, such as SYSTEM. The equivalence context has to be registered through the ConceptList.

depthAllFlag - Flag value of the depth of equivalence assertions that mapping equivalence service goes. If the flag value is true, this method considers all concepts in the set of concepts that are either directly equivalent (explicitly asserted to be equivalent through a cross map or a change file) or transitively equivalent (inferred to be equivalent by transitively chaining direct equivalence assertions) to this Concept. If the flag value is false, this method only considers the concepts that are directly equivalent.

Returns:

true if the concepts are considered mapping equivalence using the specified method.

Throws:

ETSDataException - If a data transport error occurs.

ETSNotFoundException - If conceptID1 or conceptID2 is not a valid concept.

ETSBadParameterException - If the concept is null or if the equivalence type is not EQUIVALENCE_TYPE_MAPPING, or if the equivalence context does not exist.

getEquivalentConceptIDs

String[] getEquivalentConceptIDs(String conceptID,
                                 int equivalenceType,
                                 String equivalenceContext,
                                 boolean depthAll)
                          throws ETSDataException,
                                 ETSNotFoundException,
                                 ETSBadParameterException

Finds all concepts equivalent to a given concept using the requested mapping equivalence method. The concept identifiers include both mapping and semantic equivalence concepts. To get only semantic equivalence concepts, use the getEquivalentConceptIDs. This method can make use of server-side caching

Parameters:

conceptID - The identifier of the concept to be queried.

equivalenceType - The type of equivalence to be used. This method accepts only the EQUIVALENCE_TYPE_MAPPING equivalence type in the Concept interface.

equivalenceContext - The equivalence context of the mapping equivalence, such as SYSTEM. It has to be registered through the ConceptList.

depthAll - Flag value of the depth of equivalence assertions that mapping equivalence service goes. If the flag value is true, this method considers all concepts in the set of concepts that are either directly equivalent (explicitly asserted to be equivalent through a cross map or a change file) or transitively equivalent (inferred to be equivalent by transitively chaining direct equivalence assertions) to this Concept. If the flag value is false, this method only considers the concepts that are directly equivalent.

Returns:

Array of concept identifiers that are mapping equivalence to the passed concept, including the passed concept itself. The return is guaranteed to contain at least the concept identifiers that were passed in as a parameter (return length is at least 1).

Throws:

ETSDataException - If a data transport error occurs.

ETSNotFoundException - If a concept identifier is not a valid concept.

ETSBadParameterException - If the concept identifier parameter is empty or null, or if the equivalence type is not EQUIVALENCE_TYPE_MAPPING, or if the equivalence context does not exist.

getEquivalentConceptIDs

String[] getEquivalentConceptIDs(String conceptID,
                                 int equivalenceType,
                                 String equivalenceContext,
                                 boolean depthAll,
                                 String codingSchemeVersionID)
                          throws ETSDataException,
                                 ETSNotFoundException,
                                 ETSBadParameterException

Finds all concepts that are equivalent to a given concept and are contained within a specific CodingSchemeVersion using the requested mapping equivalence method. This method can make use of server-side caching

Parameters:

conceptID - The identifier of the concept to be queried

equivalenceType - The type of equivalence to be used. This method accepts only the EQUIVALENCE_TYPE_MAPPING equivalence type in the Concept interface.

equivalenceContext - The equivalence context of the mapping equivalence, such as SYSTEM. It has to be registered through the ConceptList.

depthAll - Flag value of the depth of equivalence assertions that mapping equivalence service goes. If the flag value is true, this method considers all concepts in the set of concepts that are either directly equivalent (explicitly asserted to be equivalent through a cross map or a change file) or transitively equivalent (inferred to be equivalent by transitively chaining direct equivalence assertions) to this Concept. If the flag value is false, this method only considers the concepts that are directly equivalent.

codingSchemeVersionID - The identifier value of target coding scheme version where the method is looking for the mapping equivalence concepts.

Returns:

Array of concept identifiers that are mapping equivalence to the passed concept, including the identifier of the passed concept itself. The return is guaranteed to contain at least the concept identifier that was passed as a parameter (return length is at least 1).

Throws:

ETSDataException - If a data transport error occurs.

ETSNotFoundException - If concept identifier is not a valid concept.

ETSBadParameterException - If the concept identifier is empty or null, or if the equivalence type is not EQUIVALENCE_TYPE_MAPPING, or if the equivalence context does not exist.

findLocallyPreferredDescriptionsForConceptIDs

LocalConceptDescription[] findLocallyPreferredDescriptionsForConceptIDs(String[] conceptIDArray)
                                                                 throws ETSDataException,
                                                                        ETSBadParameterException

Finds locally preferred concept descriptions corresponding to the array of Concept identifiers that was passed in.

Parameters:

conceptIDArray - An array of Concept identifiers.

Returns:

An array of locally preferred concepts descriptions corresponding to the array of concept identifiers that was passed in. If a Concept identifier does not have match concept description, the corresponding index of the return array will be null.

Throws:

ETSBadParameterException - If conceptIDArray contains a null conceptIDArray.

ETSDataException - If a data transport error occurs.

findTerminologyPreferredDescriptionsForConceptIDs

TerminologyConceptDescription[] findTerminologyPreferredDescriptionsForConceptIDs(String[] conceptIDArray)
                                                                           throws ETSDataException,
                                                                                  ETSBadParameterException

Finds terminology preferred concept descriptions corresponding to the array of Concept identifiers that were passed in.

Parameters:

conceptIDArray - An array of Concept identifiers.

Returns:

Array of terminology preferred concepts descriptions

Throws:

ETSBadParameterException - If conceptIDArray contains a null conceptIDArray.

ETSDataException - If a data transport error occurs.

findDescriptionsForConceptIDs

ConceptDescription[] findDescriptionsForConceptIDs(String[] conceptIDArray)
                                            throws ETSDataException,
                                                   ETSBadParameterException

Finds all concept descriptions corresponding to an array of Concept identifiers.

Parameters:

conceptIDArray - An array of Concept identifiers.

Returns:

Array of ConceptDescription objects

Throws:

ETSBadParameterException - If the conceptIDArray array contains a null conceptIDArray.

ETSDataException - If a data transport error occurs.

findMatchingConceptsByDescriptionTerm

Concept[] findMatchingConceptsByDescriptionTerm(String termPattern)
                                         throws ETSDataException,
                                                ETSBadParameterException

Finds Concept objects whose terminology description or local description matches the given text pattern. The concepts created are of a specific type. If the termPattern parameter matches a SNOMED concept description and an FDB concept description, this method creates a SNOMED and an FDB concept, but returns them in a single array of parent Concept type.

This method does not make a distinction between languages and will search for any matching descriptions, in all of the installed languages.

Parameters:

termPattern - The text pattern to be matched with descriptions.

Returns:

An array of Concept objects.

Throws:

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If termPattern is null or if it has too few non-% characters.

findMatchingConceptsByDescriptionTerm

Concept[] findMatchingConceptsByDescriptionTerm(String termPattern,
                                                long maxResults)
                                         throws ETSDataException,
                                                ETSBadParameterException

Finds Concept objects whose terminology description or local description matches the given text pattern. The concepts created are of a specific type. If the termPattern parameter matches a SNOMED concept description and an FDB concept description, this method creates a SNOMED and an FDB concept, but returns them in a single array of parent Concept type.

This method does not make a distinction between languages and will search for any matching descriptions, in all of the installed languages.

Parameters:

termPattern - The text pattern to be matched with descriptions.

maxResults - The maximum number of Concept objects to return in the array, or -1 if all of the results should be returned.

Returns:

An array of Concept objects.

Throws:

ETSDataException - If a data transport error occurs.

ETSBadParameterException - If termPattern is null or if it has too few non-% characters.

findConceptListMembers

ConceptListMember[] findConceptListMembers(String[] groupNames,
                                           String[] conceptListNames,
                                           String[] membershipCodes,
                                           int prefetchDescriptions,
                                           boolean prefetchConcept)
                                    throws ETSBadParameterException,
                                           ETSDataException

Bulk fetches multiple active ConceptListMember objects associated with the specified concept lists and membership codes. The descriptions of the ConceptListMember objects and underlying concepts can be prefetched to reduce the number of total network round trips.

Parameters:

groupNames - An array of group names to which the concept list associated with the corresponding index value for the conceptListName array, belongs.

conceptListNames - An array of concept list names that represent the concept lists from which this method retrieves ConceptListMember objects.

membershipCodes - An array of membership codes, which, along with corresponding index in the group names and the array of concept list names, obtains the ConceptListMember objects to be returned

prefetchDescriptions - An integer constant specifying which concept description texts to prefetch for all of the returned ConceptListMember objects.

Allowable constants are

• MEMBER_DESC_PRINT
• MEMBER_DESC_SHORT
• MEMBER_DESC_LONG
• MEMBER_DESC_ALL
• MEMBER_DESC_NONE
• MEMBER_DESC_TERMINOLOGY_PREF
• MEMBER_DESC_LOCALLY_PREF

These constants are defined in this interface. You can define an integer variable to pass in, by performing an OR operation on the descriptions that need to be prefetched. For example, to prefetch only the print name and the local preferred descriptions, pass in the following variable:

 int myConstant = MEMBER_DESC_SHORT | MEMBER_DESC_LOCALLY_PREF;

NOTE: This parameter is set the same for all ConceptListMember objects that are returned.

prefetchConcept - A boolean value specifying whether to prefetch the Concept associated with the ConceptListMember objects. true indicates that the Concept object is prefetched and stored. false indicates that it will not be prefetched and a null object will be stored instead.

NOTE: This parameter is set the same for all ConceptListMember objects that are returned.

Returns:

An array of ConceptListMember objects corresponding to the arrays of group names, concept list names, and membership codes that were passed in. If these array values for a particular index do not match an active ConceptListMember, the corresponding index in the return array will be null.

Throws:

ETSBadParameterException -

• If any one of the arrays of group names, concept list names, or membership codes are null objects, or if any of these arrays contain a null object.
• If these arrays are of different lengths.
• If the value of prefetchDescriptions is not one of the acceptable states.

ETSDataException - If a data transport error occurs.

getSystemDate

Date getSystemDate()
            throws oracle.hsgbu.ets.exceptions.common.ETSDAOException

Gets the current system date (SYSDATE) from the database.

Returns:

Current system date from the database.

Throws:

oracle.hsgbu.ets.exceptions.common.ETSDAOException - If a data transport error occurs.

getMaxDate

Date getMaxDate()
         throws oracle.hsgbu.ets.exceptions.common.ETSDAOException

Gets the latest date stored in the database tables.

Returns:

The latest date stored in database.

Throws:

oracle.hsgbu.ets.exceptions.common.ETSDAOException - If a data transport error occurs.

findClassificationByCode

Classification findClassificationByCode(String code)
                                 throws ETSNotFoundException,
                                        ETSBadParameterException,
                                        ETSDataException

Obtains a Classification based on its classification code.

Parameters:

code - Classification code.

Returns:

Classification based on its classification code.

Throws:

ETSNotFoundException - If code is not found.

ETSBadParameterException - If code is null.

ETSDataException - If a data transport error has occurred.

findMatchingClassificationsByDescription

Classification[] findMatchingClassificationsByDescription(String termPattern)
                                                   throws ETSDataException,
                                                          ETSBadParameterException

Finds classification by a String description search pattern.

Parameters:

termPattern - String representing the search pattern.

Returns:

Array of Classification objects that have matching description, or a zero-length array if no match is found.

Throws:

ETSDataException - If a data transport error has occurred.

ETSBadParameterException - If the passed parameter is null.