Interface RelevancyEnablerLookupSession

All Superinterfaces:

AutoCloseable, Closeable, OsidSession, OsidSession

public interface RelevancyEnablerLookupSession
extends OsidSession

This session provides methods for retrieving RelevancyEnablers .

This session defines views that offer differing behaviors when retrieving multiple objects.

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete set or is an error condition
• isolated ontology view: All relevancy enabler methods in this session operate, retrieve and pertain to relevancy enablers defined explicitly in the current ontology. Using an isolated view is useful for managing RelevancyEnablers with the RelevancyEnablerAdminSession .
• federated ontology view: All relevancy enabler methods in this session operate, retrieve and pertain to all relevancy enablers defined in this ontology and any other relevancy enablers implicitly available in this ontology through ontology inheritence.
• active relevancy enabler view: All relevancy enabler lookup methods return active relevancy enablers.
• any status relevancy enabler view: Relevancy enablers of any active or inactive status are returned from methods.

Generally, the comparative view should be used for most applications as it permits operation even if there is data that cannot be accessed. The methods useFederatedDistributorView() and useIsolatedDistributorView() behave as a radio group and one should be selected before invoking the methods in this session.

Method Summary

Modifier and Type	Method	Description
boolean	canLookupRelevancyEnablers()	Tests if this user can perform RelevancyEnablers lookups.
Ontology	getOntology()	Gets the Ontology associated with this session.
Id	getOntologyId()	Gets the Ontology Id associated with this session.
RelevancyEnabler	getRelevancyEnabler(Id relevancyEnablerId)	Gets the RelevancyEnabler specified by its Id .
RelevancyEnablerList	getRelevancyEnablers()	Gets all RelevancyEnablers .
RelevancyEnablerList	getRelevancyEnablersByGenusType(Type relevancyEnablerGenusType)	Gets a RelevancyEnablerList corresponding to the given relevancy enabler genus Type which does not include relevancy enablers of genus types derived from the specified Type .
RelevancyEnablerList	getRelevancyEnablersByIds(IdList relevancyEnablerIds)	Gets a RelevancyEnablerList corresponding to the given IdList .
RelevancyEnablerList	getRelevancyEnablersByParentGenusType(Type relevancyEnablerGenusType)	Gets a RelevancyEnablerList corresponding to the given relevancy enabler genus Type and include any additional relevancy enablers with genus types derived from the specified Type .
RelevancyEnablerList	getRelevancyEnablersByRecordType(Type relevancyEnablerRecordType)	Gets a RelevancyEnablerList containing the given relevancy enabler record Type .
RelevancyEnablerList	getRelevancyEnablersOnDate(DateTime from, DateTime to)	Gets a RelevancyEnablerList thate are effective for the entire given date range inclusive but not confined to the date range for any agent.
RelevancyEnablerList	getRelevancyEnablersOnDateWithAgent(Id agentId, DateTime from, DateTime to)	Gets a RelevancyEnablerList thate are effective for the entire given date range inclusive but not confined to the date range and evaluated against the given agent.
void	useActiveRelevancyEnablerView()	Only active relevancy enablers are returned by methods in this session.
void	useAnyStatusRelevancyEnablerView()	All active and inactive relevancy enablers are returned by methods in this session.
void	useComparativeRelevancyEnablerView()	The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useFederatedOntologyView()	Federates the view for methods in this session.
void	useIsolatedOntologyView()	Isolates the view for methods in this session.
void	usePlenaryRelevancyEnablerView()	A complete view of the RelevancyEnabler returns is desired.

Methods inherited from interface Closeable

close

Methods inherited from interface OsidSession

close

Modifier and Type	Method	Description
void	close()	Close this session.

Methods inherited from interface OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Modifier and Type	Method	Description
Agent	getAuthenticatedAgent()	Gets the agent authenticated to this session.
Id	getAuthenticatedAgentId()	Gets the Id of the agent authenticated to this session.
BigDecimal	getClockRate()	Gets the rate of the service clock.
Date	getDate()	Gets the service date which may be the current date or the effective date in which this session exists.
Agent	getEffectiveAgent()	Gets the effective agent in use by this session.
Id	getEffectiveAgentId()	Gets the Id of the effective agent in use by this session.
Type	getFormatType()	Gets the DisplayText format Type preference in effect for this session.
Locale	getLocale()	Gets the locale indicating the localization preferences in effect for this session.
boolean	isAuthenticated()	Tests if an agent is authenticated to this session.
Transaction	startTransaction()	Starts a new transaction for this sesson.
boolean	supportsTransactions()	Tests for the availability of transactions.

Method Details

getOntologyId

Id getOntologyId()

Gets the Ontology Id associated with this session.

Returns:

the Ontology Id associated with this session

Compliance:

mandatory - This method must be implemented.

getOntology

Ontology getOntology()
              throws OperationFailedException,
PermissionDeniedException

Gets the Ontology associated with this session.

Returns:

the ontology

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupRelevancyEnablers

boolean canLookupRelevancyEnablers()

Tests if this user can perform RelevancyEnablers lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt not to offer lookup operations to unauthorized users.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeRelevancyEnablerView

void useComparativeRelevancyEnablerView()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryRelevancyEnablerView

void usePlenaryRelevancyEnablerView()

A complete view of the RelevancyEnabler returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

Compliance:

mandatory - This method is must be implemented.

useFederatedOntologyView

void useFederatedOntologyView()

Federates the view for methods in this session. A federated view will include relevancy enablers in ontologies which are children of this ontology in the ontology hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedOntologyView

void useIsolatedOntologyView()

Isolates the view for methods in this session. An isolated view restricts lookups to this ontology only.

Compliance:

mandatory - This method is must be implemented.

useActiveRelevancyEnablerView

void useActiveRelevancyEnablerView()

Only active relevancy enablers are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyStatusRelevancyEnablerView

void useAnyStatusRelevancyEnablerView()

All active and inactive relevancy enablers are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

getRelevancyEnabler

RelevancyEnabler getRelevancyEnabler(Id relevancyEnablerId)
                              throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets the RelevancyEnabler specified by its Id . In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned RelevancyEnabler may have a different Id than requested, such as the case where a duplicate Id was assigned to a RelevancyEnabler and retained for compatibility. In active mode, relevancy enablers are returned that are currently active. In any status mode, active and inactive relevancy enablers are returned.

Parameters:

relevancyEnablerId - Id of the RelevancyEnabler

Returns:

the relevancy enabler

Throws:

NotFoundException - relevancyEnablerId not found

NullArgumentException - relevancyEnablerId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getRelevancyEnablersByIds

RelevancyEnablerList getRelevancyEnablersByIds(IdList relevancyEnablerIds)
                                        throws NotFoundException,
OperationFailedException,
PermissionDeniedException

Gets a RelevancyEnablerList corresponding to the given IdList . In plenary mode, the returned list contains all of the relevancy enablers specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible RelevancyEnablers may be omitted from the list and may present the elements in any order including returning a unique set. In active mode, relevancy enablers are returned that are currently active. In any status mode, active and inactive relevancy enablers are returned.

Parameters:

relevancyEnablerIds - the list of Ids to retrieve

Returns:

the returned RelevancyEnabler list

Throws:

NotFoundException - an Id was not found

NullArgumentException - relevancyEnablerIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelevancyEnablersByGenusType

RelevancyEnablerList getRelevancyEnablersByGenusType(Type relevancyEnablerGenusType)
                                              throws OperationFailedException,
PermissionDeniedException

Gets a RelevancyEnablerList corresponding to the given relevancy enabler genus Type which does not include relevancy enablers of genus types derived from the specified Type . In plenary mode, the returned list contains all known relevancy enablers or an error results. Otherwise, the returned list may contain only those relevancy enablers that are accessible through this session. In active mode, relevancy enablers are returned that are currently active. In any status mode, active and inactive relevancy enablers are returned.

Parameters:

relevancyEnablerGenusType - a relevancy enabler genus type

Returns:

the returned RelevancyEnabler list

Throws:

NullArgumentException - relevancyEnablerGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelevancyEnablersByParentGenusType

RelevancyEnablerList getRelevancyEnablersByParentGenusType(Type relevancyEnablerGenusType)
                                                    throws OperationFailedException,
PermissionDeniedException

Gets a RelevancyEnablerList corresponding to the given relevancy enabler genus Type and include any additional relevancy enablers with genus types derived from the specified Type . In plenary mode, the returned list contains all known relevancy enablers or an error results. Otherwise, the returned list may contain only those relevancy enablers that are accessible through this session. In active mode, relevancy enablers are returned that are currently active. In any status mode, active and inactive relevancy enablers are returned.

Parameters:

relevancyEnablerGenusType - a relevancy enabler genus type

Returns:

the returned RelevancyEnabler list

Throws:

NullArgumentException - relevancyEnablerGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelevancyEnablersByRecordType

RelevancyEnablerList getRelevancyEnablersByRecordType(Type relevancyEnablerRecordType)
                                               throws OperationFailedException,
PermissionDeniedException

Gets a RelevancyEnablerList containing the given relevancy enabler record Type . In plenary mode, the returned list contains all known relevancy enablers or an error results. Otherwise, the returned list may contain only those relevancy enablers that are accessible through this session. In active mode, relevancy enablers are returned that are currently active. In any status mode, active and inactive relevancy enablers are returned.

Parameters:

relevancyEnablerRecordType - a relevancy enabler record type

Returns:

the returned RelevancyEnabler list

Throws:

NullArgumentException - relevancyEnablerRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelevancyEnablersOnDate

RelevancyEnablerList getRelevancyEnablersOnDate(DateTime from,
 DateTime to)
                                         throws OperationFailedException,
PermissionDeniedException

Gets a RelevancyEnablerList thate are effective for the entire given date range inclusive but not confined to the date range for any agent. In plenary mode, the returned list contains all known relevancy enablers or an error results. Otherwise, the returned list may contain only those relevancy enablers that are accessible through this session. In active mode, relevancy enablers are returned that are currently active. In any status mode, active and inactive relevancy enablers are returned.

Parameters:

from - a start date

to - an end date

Returns:

the returned RelevancyEnabler list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelevancyEnablersOnDateWithAgent

RelevancyEnablerList getRelevancyEnablersOnDateWithAgent(Id agentId,
 DateTime from,
 DateTime to)
                                                  throws OperationFailedException,
PermissionDeniedException

Gets a RelevancyEnablerList thate are effective for the entire given date range inclusive but not confined to the date range and evaluated against the given agent. In plenary mode, the returned list contains all known relevancy enablers or an error results. Otherwise, the returned list may contain only those relevancy enablers that are accessible through this session. In active mode, relevancy enablers are returned that are currently active. In any status mode, active and inactive relevancy enablers are returned.

Parameters:

agentId - an agent Id

from - a start date

to - an end date

Returns:

the returned RelevancyEnabler list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - agentId, from , or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRelevancyEnablers

RelevancyEnablerList getRelevancyEnablers()
                                   throws OperationFailedException,
PermissionDeniedException

Gets all RelevancyEnablers . In plenary mode, the returned list contains all known relevancy enablers or an error results. Otherwise, the returned list may contain only those relevancy enablers that are accessible through this session. In active mode, relevancy enablers are returned that are currently active. In any status mode, active and inactive relevancy enablers are returned.

Returns:

the returned RelevancyEnabler list

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.