oracle.hsgbu.hdr.hl7.rim

Interface Role

All Superinterfaces:

InfrastructureRoot, Serializable, Versioned

All Known Subinterfaces:

Access, Employee, LicensedEntity, Patient, QualifiedEntity

public interface Role
extends InfrastructureRoot, Versioned

A competency of the Entity playing the Role as identified, defined, guaranteed, or acknowledged by the Entity that scopes the Role.

Discussion: An Entity participates in an Act as in a particular Role. Note that a particular entity in a particular Role can participate in an act in many ways. Thus, a Person in the Role of a practitioner can participate in a patient encounter as a rounding physician or as an attending physician. The Role defines the competency of the Entity irrespective of any Act, as opposed to Participation, which are limited to the scope of an Act.

Each Role is "played" by one Entity, called the "player" and is "scoped" by another Entity, called the "scoper". Thus the Role of "patient" may be played by a person and scoped by the provider organization from which the patient will receive services. Similarly, the employer scopes an "employee" Role.

The identifier of the Role identifies the Entity playing the Role in that Role. This identifier is assigned by the scoping Entity to the player. The scoping Entity need not have issued the identifier, but it may have re-used an existing identifier for the Entity to also identify the Entity in the Role with the scoper.

Most attributes of Role are attributes of the playing entity while in the particular Role.

Oracle: Many of the subclasses of Role have restricted player and scoper entities.

Validation on attributes of a Role vary depending on whether the Role is "owned by" an entity or the Role participates in an Act. A Role can be owned by either its player or scoper entity. To create an owned Role, use the addPlayedRole or addScopedRole methods on Entity and its subclasses.

Owned roles' validation differs in the following ways:

• Owned roles' Ids are not required to be unique. An example of this is where a person's social security number is falsely stated, leading to the possibility that more than one person has the same social security number.
• HDR Provides the ability to substitute a reference object for most acts, roles or entities, but does not permit references to be made to an owned Role due to need to support non-unique Ids, as above.
• An owned Role must have at least a player or scoper Entity

See Also:

Entity, Act, Person, Entity.addPlayedRole(CS, CE, Entity, SET), Entity.addScopedRole(CS, CE, Entity, SET), ReferenceModifier, RoleFactory.makeReference(ReferenceModifier, CS, CE, Entity, Entity, SET, int), Entity.addPlayedRole(CS, CE, Entity, SET), Entity.addScopedRole(CS, CE, Entity, SET), ReferenceModifier, RoleFactory.makeReference(ReferenceModifier, CS, CE, Entity, Entity, SET, int)

Summary

Method Summary

Modifier and Type	Method and Description
void	addAddr(AD addr) Adds an address to the set of addresses.
void	addConfidentialityCode(CE confidentialityCode) Adds a confidentiality code to the set of codes.
void	addId(II id) Adds an Id to the set of Ids.
void	addName(EN name) Adds a name to the bag of names.
void	addPositionNumber(INT positionNumber) Adds a position number to the list of position numbers.
void	addTelecom(TEL telecom) Adds a TEL datatype to the bag of TELs.
BAG<AD>	getAddr() An address for the Entity while in the Role.
ED	getCertificateText() A textual or multimedia depiction of a certificate issued by the scoping Entity of a Role certifying that this Role is indeed played by the player Entity.
CS	getClassCode() A code specifying the major category of a Role as defined by HL7 vocabulary.
CE	getCode() A code further specifying the kind of Role.
SET<CE>	getConfidentialityCode() A code that controls the disclosure of information about this Role with respect to the playing Entity..
GTS	getEffectiveTime() An interval of time specifying the period during which the Role is in effect, if such time limit is applicable and known.
SET<II>	getId() A unique identifier for the player Entity in this Role.
BAG<EN>	getName() A non-unique textual identifier or moniker for the playing Entity intended for use principally when playing the Role...
BL	getNegationInd() An indicator specifying that the Role is a competency that is specifically not attributed to the Entity playing the Role.
Iterator	getParticipations() Returns all the retrieved participations in which this Role is the participant.
Iterator	getParticipations(ParticipationFetch partFetch) Gets participations returned based on this fetch object.
Entity	getPlayerEntity() Returns the Entity playing the Role.
Entity	getPlayerEntity(EntityFetch entityFetch) Gets player Entity returned based on this fetch object.
LIST<INT>	getPositionNumber() An integer specifying the position of the Entity playing the Role with respect to the Entity that scopes the Role.
RTO<PQ,PQ>	getQuantity() A ratio (numerator : denominator) specifying the relative quantities of the Entity playing the Role in the Entity scoping the Role, used for roles that represent composition relationships between the scoping and playing entities.
Entity	getScoperEntity() Returns the Entity scoping the Role.
Entity	getScoperEntity(EntityFetch entityFetch) Gets scoper Entity returned based on this fetch object.
CS	getStatusCode() A code specifying the state of this Role as defined in the state-transition model.
BAG<TEL>	getTelecom() A telecommunication address for the Entity while in the Role.
void	setAddr(BAG<AD> addr)
void	setCertificateText(ED certificateText)
void	setConfidentialityCode(SET<CE> confidentialityCode)
void	setEffectiveTime(GTS effectiveTime)
void	setName(BAG<EN> name)
void	setNegationInd(BL negationInd)
void	setPlayerEntity(Entity entity)
void	setPositionNumber(LIST<INT> positionNumber)
void	setQuantity(RTO<PQ,PQ> quantity)
void	setScoperEntity(Entity entity)
void	setStatusCode(CS statusCode)
void	setTelecom(BAG<TEL> telecom)

Methods inherited from interface oracle.hsgbu.hdr.hl7.rim.InfrastructureRoot

getControlAct, getToken, setToken

Methods inherited from interface oracle.hsgbu.hdr.hl7.fwk.Versioned

createNewVersion, getVersionNum, isCurrentVersion

Method Detail

getConfidentialityCode

SET<CE> getConfidentialityCode()

A code that controls the disclosure of information about this Role with respect to the playing Entity..

Discussion: It is important to note that the necessary confidentiality of the medical record cannot be achieved solely through confidentiality codes to mask individual record items from certain types of users. There are two important problems with per-item confidentiality: one is inference and the other is the danger of holding back information that may be critical in a certain care situation. Inference means that filtered sensitive information can still be assumed given the other information that was not filtered. The simplest form of inference is that even the existence of a test order for an HIV Western Blot test or a T4/T8 lymphocyte count is a strong indication for an existing HIV infection, even if the results are not known. Very often, diagnoses can be inferred from medication, such as Zidovudin for treatment of HIV infections. The problem of hiding individual items becomes especially difficult with current medications, since the continuing administration of the medication must be assured.

To mitigate some of the inference-risk, aggregations of data should assume the confidentiality level of the most confidential action in the aggregation.

setConfidentialityCode

void setConfidentialityCode(SET<CE> confidentialityCode)
                     throws HDRRimException

Throws:

HDRRimException

Membership code to be used:

CL_PAT_CONFIDENTIALITY_CODE

addConfidentialityCode

void addConfidentialityCode(CE confidentialityCode)
                     throws HDRRimException

Adds a confidentiality code to the set of codes.

Parameters:

confidentialityCode - The confidentiality code to add

Throws:

HDRRimException

getPlayerEntity

Entity getPlayerEntity()
                throws HDRRimException

Returns the Entity playing the Role. If multiple fetch objects were attached in the query and they had returned multiple versions of the player Entity, then calling this method would throw an Exception. This would return the player Entity when only one version of this has been fetched through query. If this method is called on a Role obtained through RoleFactory then this would return the player Entity attached in the Factory. If the Role is versioned through createNewVersion call, then we will carry forward the current version player Entity only. So calling this method here would either return the current version of player Entity or null, if the current version of player Entity was not fetched in the query.

For example the entity playing a patient could be a person

Returns:

The player Entity which has been retrieved.

Throws:

HDRRimException - When multiple versions of player Entity were fetched as part of the query.

getPlayerEntity

Entity getPlayerEntity(EntityFetch entityFetch)
                throws HDRRimException

Gets player Entity returned based on this fetch object. If this entityFetch object was used in the query, then this method would return the player Entity fetched due to this fetch object. Otherwise it would return null.

Parameters:

entityFetch - EntityFetch object containing the search criteria.

Returns:

The player Entity which has been retrieved using the specified fetch map.

Throws:

HDRRimException - under the following conditions:

• If the entityFetch is passed as null.
• If this Role is not a queried object (i.e. obtained through ActFactory or createNewVersion method).

getScoperEntity

Entity getScoperEntity()
                throws HDRRimException

Returns the Entity scoping the Role. If multiple fetch objects were attached in the query and they had returned multiple versions of the scoper Entity, then calling this method would throw an Exception. This would return the scoper Entity when only one version of this has been fetched through query. If this method is called on a Role obtained through RoleFactory then this would return the scoper Entity attached in the Factory. If the Role is versioned through createNewVersion call, then we will carry forward the current version scoper Entity only. So calling this method here would either return the current version of scoper Entity or null, if the current version of player Entity was not fetched in the query.

For example the entity playing a patient would typically be an organization

Returns:

The scoper Entity which has been retrieved.

Throws:

HDRRimException - When multiple versions of scoper Entity were fetched as part of the query.

getScoperEntity

Entity getScoperEntity(EntityFetch entityFetch)
                throws HDRRimException

Gets scoper Entity returned based on this fetch object. If this entityFetch object was used in the query, then this method would return the scoper Entity fetched due to this fetch object. Otherwise it would return null.

Parameters:

entityFetch - EntityFetch object containing the search criteria

Returns:

The scoper Entity which has been retrieved using the specified fetch map.

Throws:

HDRRimException - under the following conditions:

• If the entityFetch is passed as null.
• If this Role is not a queried object (i.e. obtained through ActFactory or createNewVersion method).

getClassCode

CS getClassCode()

A code specifying the major category of a Role as defined by HL7 vocabulary.

Membership code to be used:

CL_ROL_CLASS_CODE

System Generated

The class code is set set on the Role by the Role factory.

getId

SET<II> getId()

A unique identifier for the player Entity in this Role. The II is unique across a broad class (Act, Entity, non-owned Role) rather than across the finer grained classes of HL7.

addId

void addId(II id)
    throws HDRRimException

Adds an Id to the set of Ids.

Parameters:

id - The id, must be a valid II. The II is unique across a broad class (Act, Entity, non-owned Role) rather than across the finer grained classes of HL7.

Throws:

HDRRimException - If this Role is a queried object.

getCode

CE getCode()

A code further specifying the kind of Role.

Discussion: The Role.code must conceptually be a proper specialization of Role.classCode. Role.code does not modify Role.classCode. Rather, each is a complete concept or a Role-like relationship between two entities, but Role.code may be more specific than Role.classCode.

The Role.code may not be coded if only an un-coded name for the type of Role is commonly used.

System Generated

The Role code is set set on the Role by the Role factory.

getNegationInd

BL getNegationInd()

An indicator specifying that the Role is a competency that is specifically not attributed to the Entity playing the Role.

Examples: 1.) This person is not our employee

2.) This mouthwash does not have alcohol as an ingredient.

Constraint:

Normally all roles are considered to be affirmative. (This attribute defaults to FALSE).

setNegationInd

void setNegationInd(BL negationInd)
             throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object.

getAddr

BAG<AD> getAddr()

An address for the Entity while in the Role.

setAddr

void setAddr(BAG<AD> addr)
      throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object.

addAddr

void addAddr(AD addr)
      throws HDRRimException

Adds an address to the set of addresses.

Parameters:

addr - The address as an AD type.

Throws:

HDRRimException - If this Role is a queried object.

getParticipations

Iterator getParticipations()

Returns all the retrieved participations in which this Role is the participant. If multiple participation fetch objects were attached in the query, then this method would return the union of all the results that the individual fetch objects have returned. If this method is called on a Role obtained through RoleFactory then this would return null unless this has been linked to any Act through addParticipation method. If this method is called on a Role versioned through createNewVersion call, then this would return all the retrieved participations in which this Role is the participant.

Returns:

An iterator that supports only a single pass through the collection. The collection will contain all the participations that has already been fetched.

getParticipations

Iterator getParticipations(ParticipationFetch partFetch)
                    throws HDRRimException

Gets participations returned based on this fetch object. If this participationFetch object was used in the query, then this method would return the participations fetched due to this fetch object. Otherwise it would return null. For example, from a particular patient, calling this method with a criteria like participation type is SUBJ will return an iterator to all participations, for that patient. This is the most common way to access clinical data associated with a patient or privileges associated with a staff member, etc.

Parameters:

partFetch - fetch object containing the search criteria.

Returns:

An iterator that supports only a single pass through the collection. The collection will contain only the participations that has already been fetched using this roleFetch.

Throws:

HDRRimException - under the following conditions:

• If the partFetch is passed as null.
• If this Role is not a queried object (i.e. obtained through ActFactory or createNewVersion method).

getTelecom

BAG<TEL> getTelecom()

A telecommunication address for the Entity while in the Role.

setTelecom

void setTelecom(BAG<TEL> telecom)
         throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object.

addTelecom

void addTelecom(TEL telecom)
         throws HDRRimException

Adds a TEL datatype to the bag of TELs.

Parameters:

telecom - The telecom data

Throws:

HDRRimException - If this Role is a queried object.

getStatusCode

CS getStatusCode()

A code specifying the state of this Role as defined in the state-transition model.

setStatusCode

void setStatusCode(CS statusCode)
            throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object.

Membership code to be used:

CL_ROL_STATUS_CODE

getEffectiveTime

GTS getEffectiveTime()

An interval of time specifying the period during which the Role is in effect, if such time limit is applicable and known.

Oracle: The balloted datatype is IVL<TS>

setEffectiveTime

void setEffectiveTime(GTS effectiveTime)
               throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object.

getCertificateText

ED getCertificateText()

A textual or multimedia depiction of a certificate issued by the scoping Entity of a Role certifying that this Role is indeed played by the player Entity.

Examples: The certificate can be represented in many different ways, either inline or by reference, according to the ED data type. Typical cases are:

1.) Paper-based certificate: the ED data type may refer to some document or file that can be retrieved through an electronic interface to a hardcopy archive.

2.) Electronic certificate: this attribute can represent virtually any electronic certification scheme, such as, an electronically (including digitally) signed electronic text document.

3.) Digital certificate (public key certificate): in particular, this attribute can represent digital certificates, as an inline data block or by reference to such data. The certificate data block would be constructed in accordance to a digital certificate standard, such as X509, SPKI, PGP, etc.

The certificate subject is the Entity that plays the Role. The certificate issuer is the Entity that scopes the Role.

setCertificateText

void setCertificateText(ED certificateText)
                 throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object.

getQuantity

RTO<PQ,PQ> getQuantity()

A ratio (numerator : denominator) specifying the relative quantities of the Entity playing the Role in the Entity scoping the Role, used for roles that represent composition relationships between the scoping and playing entities.

Examples: 1.) This syrup's (scoper) ingredients include 160 mg (numerator) Acetaminophen (player) per tablespoon (denominator).

2.) This herd (scoper) consists of 500 (numerator) cattle (player).

3.) A VAX 6630 computer (scoper) has 3 (numerator) CPUs (player) as parts.

4.) This package (scoper) contains 100 (numerator) pills (player).

Discussion: In composition-relationships (example,, has-parts, has-ingredient, has-content) the Role.quantity attribute specifies that a numerator amount of the target entity is comprised by a denominator amount of the source entity of such composition-relationship. For example, if a box (source) has-content 10 eggs (target), the relationship quantity is 10:1; if 0.6 mL contain 75 mg of FeSO4 the ingredient relationship quantity is 75 mg : 0.6 mL. Both numerator and denominator must be amount quantities (extensive quantities, i.e., a count number, mass, volume, amount of substance, amount of energy, etc.).

setQuantity

void setQuantity(RTO<PQ,PQ> quantity)
          throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object.

getPositionNumber

LIST<INT> getPositionNumber()

An integer specifying the position of the Entity playing the Role with respect to the Entity that scopes the Role.

Discussion: This attribute is primarily used with respect to containment roles. For example, some containers have discrete positions in which content may be located. Depending on the geometry of the container, the position may be referenced as a scalar ordinal number, or as a vector of ordinal numbers (coordinates). Coordinates always begin counting at 1.

Some containers may have customary ways of referring to the positions or no way at all. In the absence of any specific regulation for a specific container type, the rule of thumb is that the coordinate that is changed earlier is positioned first. For an automated blood chemistry analyzer with a square shaped tray, this means that the first coordinate is the one in which direction the tray moves at each step and the second coordinate is the one in which the tray moves only every 10 (or so) steps.

setPositionNumber

void setPositionNumber(LIST<INT> positionNumber)
                throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object.

addPositionNumber

void addPositionNumber(INT positionNumber)
                throws HDRRimException

Adds a position number to the list of position numbers.

Parameters:

positionNumber - The position number

Throws:

HDRRimException - If this Role is a queried object.

getName

BAG<EN> getName()

A non-unique textual identifier or moniker for the playing Entity intended for use principally when playing the Role...

Examples: Names used as an employee, as a licensed professional, etc.

Usage: In general, names are specified using Entity.name. Role.name is only used when the standard wishes to distinguish names that are appropriate for use when referring to the Entity in one Role as opposed to other Roles..

setName

void setName(BAG<EN> name)
      throws HDRRimException

Throws:

HDRRimException

addName

void addName(EN name)
      throws HDRRimException

Adds a name to the bag of names.

Parameters:

name - The name to add

Throws:

HDRRimException

setPlayerEntity

void setPlayerEntity(Entity entity)
              throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object If the entity is a owning entity for a Role

setScoperEntity

void setScoperEntity(Entity entity)
              throws HDRRimException

Throws:

HDRRimException - If this Role is a queried object If the entity is a owning entity for a Role