org.osid.inquiry

Interface AuditLookupSession

All Superinterfaces:

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

public interface AuditLookupSession
extends OsidSession

This session provides methods for retrieving Audits. The Audit represents a set of inputs .

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 inquest view: All audit methods in this session operate, retrieve and pertain to audits defined explicitly in the current inquest. Using an isolated view is useful for managing Audits with the AuditAdminSession.
• federated inquest view: All audit methods in this session operate, retrieve and pertain to all audits defined in this inquest and any other audits implicitly available in this inquest through inquest inheritence.
• active audit view: active audits are returned from methods in this session
• any status audit view: active and inactive audits 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 useFederatedInquestView() and useIsolatedInquestView() behave as a radio group and one should be selected before invoking the methods in this session.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupAudits() Tests if this user can perform Audit lookups.
Audit	getAudit(Id auditId) Gets the Audit specified by its Id.
AuditList	getAudits() Gets all Audits.
AuditList	getAuditsByGenusType(Type auditGenusType) Gets an AuditList corresponding to the given audit genus Type which does not include audits of genus types derived from the specified Type.
AuditList	getAuditsByIds(IdList auditIds) Gets an AuditList corresponding to the given IdList.
AuditList	getAuditsByParentGenusType(Type auditGenusType) Gets an AuditList corresponding to the given audit genus Type and include any additional audits with genus types derived from the specified Type.
AuditList	getAuditsByProvider(Id resourceId) Gets an AuditList by provider.
AuditList	getAuditsByRecordType(Type auditRecordType) Gets an AuditList containing the given audit record Type.
Inquest	getInquest() Gets the Inquest associated with this session.
Id	getInquestId() Gets the Inquest Id associated with this session.
void	useActiveAuditView() Only active audits are returned from methods in this session.
void	useAnyStatusAuditView() Borth active and inactive audits are returned from methods in this session.
void	useComparativeAuditView() 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	useFederatedInquestView() Federates the view for methods in this session.
void	useIsolatedInquestView() Isolates the view for methods in this session.
void	usePlenaryAuditView() A complete view of the AuditConstrainer 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

getInquestId

Id getInquestId()

Gets the Inquest Id associated with this session.

Returns:

the Inquest Id associated with this session

Compliance:

mandatory - This method must be implemented.

getInquest

Inquest getInquest()
                   throws OperationFailedException,
                          PermissionDeniedException

Gets the Inquest associated with this session.

Returns:

the inquest

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupAudits

boolean canLookupAudits()

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

useComparativeAuditView

void useComparativeAuditView()

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.

usePlenaryAuditView

void usePlenaryAuditView()

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

useFederatedInquestView

void useFederatedInquestView()

Federates the view for methods in this session. A federated view will include audit constrainers in inquests which are children of this inquest in the inquest hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedInquestView

void useIsolatedInquestView()

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

Compliance:

mandatory - This method is must be implemented.

useActiveAuditView

void useActiveAuditView()

Only active audits are returned from methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyStatusAuditView

void useAnyStatusAuditView()

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

Compliance:

mandatory - This method is must be implemented.

getAudit

Audit getAudit(Id auditId)
               throws NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

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

Parameters:

auditId - Id of the Audit

Returns:

the audit

Throws:

NotFoundException - auditId not found

NullArgumentException - auditId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getAuditsByIds

AuditList getAuditsByIds(IdList auditIds)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

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

Parameters:

auditIds - the list of Ids to retrieve

Returns:

the returned Audit list

Throws:

NotFoundException - an Id was not found

NullArgumentException - auditIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getAuditsByGenusType

AuditList getAuditsByGenusType(Type auditGenusType)
                               throws OperationFailedException,
                                      PermissionDeniedException

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

Parameters:

auditGenusType - an audit genus type

Returns:

the returned Audit list

Throws:

NullArgumentException - auditGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getAuditsByParentGenusType

AuditList getAuditsByParentGenusType(Type auditGenusType)
                                     throws OperationFailedException,
                                            PermissionDeniedException

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

Parameters:

auditGenusType - an audit genus type

Returns:

the returned Audit list

Throws:

NullArgumentException - auditGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getAuditsByRecordType

AuditList getAuditsByRecordType(Type auditRecordType)
                                throws OperationFailedException,
                                       PermissionDeniedException

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

Parameters:

auditRecordType - an audit record type

Returns:

the returned Audit list

Throws:

NullArgumentException - auditRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getAuditsByProvider

AuditList getAuditsByProvider(Id resourceId)
                              throws OperationFailedException,
                                     PermissionDeniedException

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

Parameters:

resourceId - a resource Id

Returns:

the returned Audit list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getAudits

AuditList getAudits()
                    throws OperationFailedException,
                           PermissionDeniedException

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

Returns:

a list of Audits

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.