oracle.hsgbu.ets.authoring

Interface ETSAuthoringService

public interface ETSAuthoringService

Provides methods to create, retire, modify, and remove objects from editable versions in the ETS repository.

Note: Editable terminologies are not MLS enabled and will only work with the base language (Base language is the constructed by concatenating the profile options value for ETS MLS Language Code(In uppercase) and for ETS MLS Country Code).

Method Summary

Modifier and Type	Method and Description
void	addAttributes(AttributableETSComponent[] components, CandidateETSAttribute[][] attributes, boolean dryRunFlag) Adds ETSAttribute objects to multiple AttributableETSComponent objects.
ConceptDescription[][]	addConceptDescriptions(Concept[] concepts, CandidateConceptDescription[][] candidateConcDescs, boolean dryRunFlag) Adds concept descriptions to editable CodingSchemeVersions.
Concept[]	addConcepts(CodingSchemeVersion version, CandidateConcept[] candidateConcepts, boolean dryRunFlag) Adds multiple concepts (and their descriptions and attributes) to an editable CodingSchemeVersion.
Relationship[]	addRelationships(CodingSchemeVersion version, CandidateRelationship[] candidateRels, boolean dryRunFlag) Adds multiple relationships to an editable CodingSchemeVersion.
void	changeStatus(RetirableETSComponent[] components, Date[] retireDate, int newStatus) Changes the status of multiple ETSComponent objects.
CodingSchemeVersion	createCodingSchemeVersion(String name, String description, CodingScheme codingScheme) Creates a new CodingSchemeVersion for the given editable coding scheme with the given version name and description..
CandidateClassification	newCandidateClassification() Returns a new instance of the CandidateClassification object.
CandidateConcept	newCandidateConcept() Returns a new instance of the CandidateConcept object.
CandidateConceptDescription	newCandidateConceptDescription() Returns a new instance of the CandidateConceptDescription object.
CandidateETSAttribute	newCandidateETSAttribute() Returns a new instance of the CandidateETSAttribute object.
CandidateRelationship	newCandidateRelationship() Returns a new instance of the CandidateRelationship object.
void	removeAttributes(AttributableETSComponent[] component, ETSAttribute[][] attributes, boolean dryRunFlag) Removes ETSAttribute objects from multiple AttributableETSComponent objects.
void	setTerminologyPreferredDescription(TerminologyConceptDescription description) Sets the terminology description of a concept to preferred.

Method Detail

addConcepts

Concept[] addConcepts(CodingSchemeVersion version,
                      CandidateConcept[] candidateConcepts,
                      boolean dryRunFlag)
               throws ETSUnsupportedOperationException,
                      ETSValidationException,
                      ETSDuplicateException,
                      ETSBadParameterException,
                      ETSDataException

Adds multiple concepts (and their descriptions and attributes) to an editable CodingSchemeVersion. This method can be called with dryRunFlag set to true to serve as a validation mechanism. Once validations are complete, this method can be called again with dryRunFlag set to false to commit any changes to the database.
NOTE: This method performs validations even if dryRunFlag is set to false when the method is first invoked.

Parameters:

version - The editable CodingSchemeVersion.

candidateConcepts - Array of CandidateConcept objects. This parameter must be validated.

dryRunFlag - Indicates if the CandidateConcept will be persisted into the database as a Concept. If false, the objects will be committed. If true, the objects will not be committed.

Returns:

Array of the added Concept objects if dryRunFlag is false, or null if dryRunFlag is true.

Throws:

ETSBadParameterException -

• If candidateConcepts is null.
• If candidateConcepts has any null members.
• If candidateConcepts contains multiple members with the same conceptCode attribute.
• If version is null.

ETSUnsupportedOperationException - If version is not an editable version.

ETSValidationException - If any of the following validations fail for CandidateConcept:

• Concept Code of CandidateConcept must not be null, an empty String, or longer than 50 characters.
• reassignedFromConcept code set on the CandidateConcept must not be an empty String or longer than 50 characters.
• Status code of CandidateConcept must be either "A" or "R".
• Retired date of CandidateConcept must be null if its status is "A".
• RelationshipTypeFlag of CandidateConcept must be one of the following constants: CandidateConcept.REL_TYPE_YES, CandidateConcept.REL_TYPE_NO, CandidateConcept.REL_TYPE_IS_CHILD_OF or CandidateConcept.REL_TYPE_IS_PARENT_OF.
• CandidateConcept must not have duplicates of attributes associated with it.
• CandidateConcept must not have CandidateAttributes with a name that is null, an empty String, or longer than 50 characters.
• CandidateConcept must not have CandidateAttributes with a value that is greater than 1000 characters.
• CandidateConcept must have no null CandidateDescriptions. One of its CandidateDescriptions must be set to preferred.
• If reassignedFrom code of CandidateConcept is not null, it must belong to an existing Concept in the version.
• The ExtendedTypeCode attribute of CandidateConcept cannot be more than six characters long or an empty String.
• CandidateConceptDescriptions of CandidateConcept should have:
  • A status code of "A" or "R".
  • A null retired date, if its status is "A".
  • No duplicate attributes associated with it.
  • No defined CandidateAttributes with a name that is null, an empty String, or longer than 50 characters.
  • No defined CandidateAttributes with a value that is greater than 1000 characters.
  • A term text field that is not null, an empty String, or longer than 4000 characters.
  • extendedTypeCode that is not an empty String or longer than six characters in length.

ETSDuplicateException - If the concept being added already exists in the version.

ETSDataException - If a data transport error has occurred.

addConceptDescriptions

ConceptDescription[][] addConceptDescriptions(Concept[] concepts,
                                              CandidateConceptDescription[][] candidateConcDescs,
                                              boolean dryRunFlag)
                                       throws ETSUnsupportedOperationException,
                                              ETSValidationException,
                                              ETSBadParameterException,
                                              ETSDataException

Adds concept descriptions to editable CodingSchemeVersions. Unlike addConcepts(CodingSchemeVersion, CandidateConcept[], boolean) and addRelationships(CodingSchemeVersion,CandidateRelationship[],boolean), this method can add ETSComponent objects across multiple editable versions in one call. The maintenance program needs to run to synchronize the Oracle Intermedia Text Indexes for text searches to work on the newly added description texts.
This method can be called with dryRunFlag set to true to serve as a validation mechanism. Once validations are complete, call this method again, with dryRunFlag set to false to commit any changes to the database.

NOTE: This method performs validations even if dryRunFlag is set to false when the method is first invoked.

Parameters:

concepts - Concept objects associated with the candidateConDescs. These Concept objects must belong to an editable CodingSchemeVersion.

candidateConcDescs - CandidateConceptDescription objects being validated and added to a CodingSchemeVersion as ConceptDescription objects created by the client application. Each inner array of descriptions is associated with the Concept in the concepts array that has the same index as the outer array index of the inner array. For example, the ConceptDescription defined in candConcDescs[1][0], candConcDescs [1][1], and candConcDescs [1][2] will be added to the Concept defined in concepts[1]. None of the descriptions should be set as the preferred description for its associated Concept. If the client application requires that one of these descriptions be set to preferred, then call the setTerminologyPreferredDescription(TerminologyConceptDescription) method.

dryRunFlag - Indicates whether CandidateConceptDescription objects will be persisted into the database as ConceptDescription objects. If false, the objects will be committed. If true, the objects will not be committed.

Returns:

Array of the ConceptDescriptions if dryRunFlag is false, or null if dryRunFlag is true.

Throws:

ETSUnsupportedOperationException - If a Concept does not belong to an editable version.

ETSValidationException - If any of the following validations fail for CandidateConceptDescription:

• Status code of CandidateDescription must be "A" or "R".
• Retired date of CandidateDescription must be null, if the status code of CandidateDescription is "A".
• CandidateDescription must not have duplicate attributes associated with it.
• CandidateConceptDescription must not have CandidateAttributes with a name that is null, an empty String, or longer than 50 characters.
• CandidateConceptDescription must not have CandidateAttributes with a value that is longer than 1000 characters.
• The TermText attribute of CandidateConceptDescription is not null, empty String, or longer than 4000 characters.
• CandidateDescription must not be the preferred description for its associated Concept.
• The extendedTypeCode attribute of CandidateDescription must not be more than six characters long or an empty String.

ETSBadParameterException -

• If Concept is null or has any null members.
• If candidateConDescs is null, has any null members or has an inner array length equal to zero. Outer array length of candidateConDescs must be the same as the array length of Concept.
• If the size of the outer array of candidateConDescs is not of the same length as the array of concepts.
• If Concept array has more than one member with the same VersionId and ConceptCode attributes.

ETSDataException - If a data transport error has occurred.

addRelationships

Relationship[] addRelationships(CodingSchemeVersion version,
                                CandidateRelationship[] candidateRels,
                                boolean dryRunFlag)
                         throws ETSUnsupportedOperationException,
                                ETSValidationException,
                                ETSBadParameterException,
                                ETSNotFoundException,
                                ETSDataException

Adds multiple relationships to an editable CodingSchemeVersion. This method can be called with dryRunFlag set to true to serve as a validation mechanism. Once validations are complete, this method can be called again with dryRunFlag set to false to commit any changes to the database.

NOTE: This method performs validations even if dryRunFlag is set to false when the method is first invoked.

Parameters:

version - The editable CodingSchemeVersion.

candidateRels - The Relationships being added.

dryRunFlag - Indicates whether CandidateRelationships will be persisted into the database as Relationships. If dryRunFlag is false, the objects will be committed. If true, the objects will not be committed.

Returns:

Array of the Relationships being added if dryRunFlag is false. Null is returned if dryRunFlag is true.

Throws:

ETSUnsupportedOperationException - If the version is not an editable version.

ETSValidationException - If any of the following validations fail for CandidateRelationship:

• Status code of CandidateRelationship must be "A" or "R".
• Retired date of CandidateRelationship must be null if the status code of CandidateRelationship is "A".
• CandidateRelationship must not have duplicate attributes associated with it.
• CandidateRelationship must not have CandidateAttributes with a name that is null, an empty String, or longer than 50 characters.
• CandidateRelationship must not have CandidateAttributes with a value greater than 1000 characters in length.
• CandidateRelationship must have non-null, distinct sourceConcept, relationTypeConcept, and targetConcept identifiers.
• Defined RelationshipType Concept of CandidateRelationship must have its RelationshipTypeFlag set to CandidateConcept.REL_TYPE_YES, CandidateConcept.REL_TYPE_IS_PARENT_OF or CandidateConcept.REL_TYPE_IS_CHILD_OF.

ETSBadParameterException -

• If CandidateRelationship is null or has any null members.
• If version is null.

ETSNotFoundException - If the Source, Target, or Relationship Type Concept identifiers defined in a Relationship object do not match any existing Concept in the version.

ETSDataException - If a data transport error has occurred.

addAttributes

void addAttributes(AttributableETSComponent[] components,
                   CandidateETSAttribute[][] attributes,
                   boolean dryRunFlag)
            throws ETSDataException,
                   ETSDuplicateException,
                   ETSBadParameterException,
                   ETSValidationException

Adds ETSAttribute objects to multiple AttributableETSComponent objects. This method can be called with dryRunFlag set to true to serve as a validation mechanism. Once validations are complete, this method can be called again with dryRunFlag set to false to commit any changes to the database to the database.

NOTE: This method performs validations even if dryRunFlag is set to false when the method is first invoked.

Parameters:

components - Array of AttributableETSComponent objects.

attributes - Array of CandidateETSAttribute objects to be added. Each of the inner arrays is associated with the ETSComponent in the corresponding index of the outer array in AttributableETSComponent. For example, the ETSAttribute defined in attributes[1][0], attributes[1][1] and attributes[1][2] will be added to the ETSComponent defined in components[1].

dryRunFlag - Indicates whether CandidateETSAttribute will be persisted into the database as ETSAttribute objects. If false, the objects will be committed. If true, the objects will not be committed.

Throws:

ETSDuplicateException - If AttributableETSComponent in components has an assigned ETSAttribute with the same name as one of the component's corresponding CandidateETSAttribute in attributes.

ETSBadParameterException -

• If components or attributes is null or has any null members. If the length of the inner array of attributes is zero. If outer array of attributes is of different lengths than the component array.

ETSValidationException -

• If the name of any of CandidateETSAttribute is null, is an empty String, or is greater than 50 characters.
• If value of any of CandidateETSAttribute is longer than 1000 characters.
• If duplicate attributes exist in attributes that are being added to a specific component.

ETSDataException - If a data transport error has occurred.

removeAttributes

void removeAttributes(AttributableETSComponent[] component,
                      ETSAttribute[][] attributes,
                      boolean dryRunFlag)
               throws ETSNotFoundException,
                      ETSBadParameterException,
                      ETSDataException

Removes ETSAttribute objects from multiple AttributableETSComponent objects.

Parameters:

component - Array of AttributableETSComponent objects.

attributes - Array of CandidateETSAttribute objects to be removed. Each inner array of these attributes must be associated with the corresponding index in the AttributableETSComponent array.

dryRunFlag - Indicates whether CandidateETSAttribute will be removed from the database. If false, the changes will be committed. If true, the changes will not be committed.

Throws:

ETSNotFoundException - If an ETSAttribute object being removed from its corresponding ETSComponent is not actually assigned to that component.

ETSBadParameterException -

• If the name of an attribute is an empty String or null.
• If AttributableETSComponent objects or CandidateETSAttribute objects is null or has any null members.

ETSDataException - If a data transport error has occurred.

changeStatus

void changeStatus(RetirableETSComponent[] components,
                  Date[] retireDate,
                  int newStatus)
           throws ETSUnsupportedOperationException,
                  ETSBadParameterException,
                  ETSDataException

Changes the status of multiple ETSComponent objects.

Parameters:

components - Components being retired or made active.

retireDate - The retired date of the ETSComponent object being retired. The retired date for the ETSComponent object being made active must be null.

newStatus - New status of the ETSComponent object. Status constants are defined in the ConceptList interface. Allowed constants are "STATUS_ACTIVE" or "STATUS_RETIRED" as defined in ConceptList. This parameter must also be different from the current status of the ETSComponent object.

Throws:

ETSUnsupportedOperationException - If any of the ETSComponent objects do not belong to an editable version.

ETSBadParameterException -

• If any of the identifiers of the components array is null or has a null member.
• If any of the elements of the components array is of the same status as newStatus.
• If any of the elements of the components array is being made active but the retired date of the ETSComponent being made active is not null.
• If newStatus is not "STATUS_ACTIVE" or "STATUS_RETIRED" as defined in ConceptList.

ETSDataException - If a data transport error has occurred.

setTerminologyPreferredDescription

void setTerminologyPreferredDescription(TerminologyConceptDescription description)
                                 throws ETSBadParameterException,
                                        ETSUnsupportedOperationException,
                                        ETSDataException

Sets the terminology description of a concept to preferred. This description must belong to an editable version.

Parameters:

description - Terminology description that is being set to preferred.

Throws:

ETSBadParameterException - If description is null or retired.

ETSUnsupportedOperationException - If the description does not belong to an editable CodingSchemeVersion.

ETSDataException - If a data transport error has occurred.

newCandidateConcept

CandidateConcept newCandidateConcept()

Returns a new instance of the CandidateConcept object.

Returns:

New instance of the CandidateConcept object.

newCandidateClassification

CandidateClassification newCandidateClassification()

Returns a new instance of the CandidateClassification object.

Returns:

a new instance of the CandidateClassification object.

newCandidateConceptDescription

CandidateConceptDescription newCandidateConceptDescription()

Returns a new instance of the CandidateConceptDescription object.

Returns:

New instance of the CandidateConceptDescription object.

newCandidateRelationship

CandidateRelationship newCandidateRelationship()

Returns a new instance of the CandidateRelationship object.

Returns:

New instance of the CandidateRelationship object.

newCandidateETSAttribute

CandidateETSAttribute newCandidateETSAttribute()

Returns a new instance of the CandidateETSAttribute object.

Returns:

a new instance of the CandidateETSAttribute object.

createCodingSchemeVersion

CodingSchemeVersion createCodingSchemeVersion(String name,
                                              String description,
                                              CodingScheme codingScheme)
                                       throws ETSDuplicateException,
                                              ETSBadParameterException,
                                              ETSDataException,
                                              ETSUnsupportedOperationException

Creates a new CodingSchemeVersion for the given editable coding scheme with the given version name and description.. The CodingSchemeVersion will be created as active for the coding scheme passed in. The CodingSchemeVersion will have the HISTORY_TYPE_CODE set to INTRAVERSION and the LOAD_DATE set to the system date.

Parameters:

name - Name of the new CodingSchemeVersion.

description - Description of the new CodingSchemeVersion.

codingScheme - the editable coding scheme that the CodingSchemeVersion will belong to

Returns:

Constructed CodingSchemeVersion.

Throws:

ETSDuplicateException - If the coding scheme has an existing version

ETSBadParameterException - If the name or the codingScheme parameter is null

ETSDataException - If a data transport error occurs.

ETSUnsupportedOperationException - If the coding scheme is not editable