org.osid.tracking

Interface QueueLookupSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface QueueLookupSession
extends OsidSession

This session provides methods for retrieving Queue objects. The Queue represents a fixed connection between two Issues.

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 front office view: All queue methods in this session operate, retrieve and pertain to queues defined explicitly in the current front office. Using an isolated view is useful for managing Queues with the QueueAdminSession.
• federated front office view: All queue methods in this session operate, retrieve and pertain to all queues defined in this front office and any other queues implicitly available in this front office through front office inheritence.
• active queue view: active queue are returned from methods in this session
• any status queue view: active and inactive queues are returned from methods in this session

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 useFederatedFrontOfficeView() and useIsolatedFrontOfficeView() behave as a radio group and one should be selected before invoking any lookup methods.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupQueues() Tests if this user can perform Queue lookups.
FrontOffice	getFrontOffice() Gets the FrontOffice associated with this session.
Id	getFrontOfficeId() Gets the FrontOffice Id associated with this session.
Queue	getQueue(Id queueId) Gets the Queue specified by its Id.
QueueList	getQueues() Gets all Queues.
QueueList	getQueuesByGenusType(Type queueGenusType) Gets a QueueList corresponding to the given queue genus Type which does not include queues of genus types derived from the specified Type.
QueueList	getQueuesByIds(IdList queueIds) Gets a QueueList corresponding to the given IdList.
QueueList	getQueuesByParentGenusType(Type queueGenusType) Gets a QueueList corresponding to the given queue genus Type and include any additional queues with genus types derived from the specified Type.
QueueList	getQueuesByProvider(Id resourceId) Gets a QueueList for a provider.
QueueList	getQueuesByRecordType(Type queueRecordType) Gets a QueueList containing the given queue record Type.
void	useActiveQueueView() Only active queues are returned from methods in this session.
void	useAnyStatusQueueView() Borth active and inactive queues are returned from methods in this session.
void	useComparativeQueueView() 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	useFederatedFrontOfficeView() Federates the view for methods in this session.
void	useIsolatedFrontOfficeView() Isolates the view for methods in this session.
void	usePlenaryQueueView() A complete view of the Queue returns is desired.

Methods inherited from interface org.osid.OsidSession

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

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getFrontOfficeId

Id getFrontOfficeId()

Gets the FrontOffice Id associated with this session.

Returns:

the FrontOffice Id associated with this session

Compliance:

mandatory - This method must be implemented.

getFrontOffice

FrontOffice getFrontOffice()
                           throws OperationFailedException,
                                  PermissionDeniedException

Gets the FrontOffice associated with this session.

Returns:

the front office

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupQueues

boolean canLookupQueues()

Tests if this user can perform Queue 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.

useComparativeQueueView

void useComparativeQueueView()

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.

usePlenaryQueueView

void usePlenaryQueueView()

A complete view of the Queue 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.

useFederatedFrontOfficeView

void useFederatedFrontOfficeView()

Federates the view for methods in this session. A federated view will include queues in front offices which are children of this front office in the front office hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedFrontOfficeView

void useIsolatedFrontOfficeView()

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

Compliance:

mandatory - This method is must be implemented.

useActiveQueueView

void useActiveQueueView()

Only active queues are returned from methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyStatusQueueView

void useAnyStatusQueueView()

Borth active and inactive queues are returned from methods in this session.

Compliance:

mandatory - This method is must be implemented.

getQueue

Queue getQueue(Id queueId)
               throws NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

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

Parameters:

queueId - Id of the Queue

Returns:

the queue

Throws:

NotFoundException - queueId not found

NullArgumentException - queueId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getQueuesByIds

QueueList getQueuesByIds(IdList queueIds)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

Gets a QueueList corresponding to the given IdList. In plenary mode, the returned list contains all of the queues 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 Queues may be omitted from the list and may present the elements in any order including returning a unique set. In active mode, queues are returned that are currently active. In any status mode, active and inactive queues are returned.

Parameters:

queueIds - the list of Ids to retrieve

Returns:

the returned Queue list

Throws:

NotFoundException - an Id was not found

NullArgumentException - queueIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getQueuesByGenusType

QueueList getQueuesByGenusType(Type queueGenusType)
                               throws OperationFailedException,
                                      PermissionDeniedException

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

Parameters:

queueGenusType - a queue genus type

Returns:

the returned Queue list

Throws:

NullArgumentException - queueGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getQueuesByParentGenusType

QueueList getQueuesByParentGenusType(Type queueGenusType)
                                     throws OperationFailedException,
                                            PermissionDeniedException

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

Parameters:

queueGenusType - a queue genus type

Returns:

the returned Queue list

Throws:

NullArgumentException - queueGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getQueuesByRecordType

QueueList getQueuesByRecordType(Type queueRecordType)
                                throws OperationFailedException,
                                       PermissionDeniedException

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

Parameters:

queueRecordType - a queue record type

Returns:

the returned Queue list

Throws:

NullArgumentException - queueRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getQueuesByProvider

QueueList getQueuesByProvider(Id resourceId)
                              throws OperationFailedException,
                                     PermissionDeniedException

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

Parameters:

resourceId - a resource Id

Returns:

the returned Queue list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getQueues

QueueList getQueues()
                    throws OperationFailedException,
                           PermissionDeniedException

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

Returns:

a list of Queues

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.