org.osid.cataloging

Interface CatalogSession

All Superinterfaces:

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

public interface CatalogSession
extends OsidSession

This session provides methods to retrieve Id to Catalog mappings. An Id may appear in multiple Catalogs. Each Catalog may have its own authorizations as to who is allowed to look at it.

This lookup session defines several views:

• federated view: entries are accessible from the specified Catalog and any descendant catalogs in the Catalog hierarchy
• isolated view: entries are accessible from the specified Catalog only
• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete result set or is an error condition

Generally, the comparative view should be used for most applications as it permits operation even if there a particular element is inaccessible. For example, a hierarchy output can be plugged into a lookup method to retrieve all objects known to a hierarchy, but it may not be necessary to break execution if a node from the hierarchy no longer exists. However, some administrative applications may need to know whether it had retrieved an entire set of objects and may sacrifice some interoperability for the sake of precision.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupMappings() Tests if this user can perform lookups of Id to Catalog mappings.
IdList	getCatalogIdsById(Id id) Gets the Catalog Ids mapped to an Id.
CatalogList	getCatalogsById(Id id) Gets the Catalogs mapped to an Id.
IdList	getIdsByCatalog(Id catalogId) Gets the list of Ids map to a Catalog.
IdList	getIdsByCatalogs(IdList catalogIds) Gets the list of Ids map to a lst of Catalogs.
void	useComparativeCatalogView() 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	useFederatedCatalogView() Federates the view for methods in this session.
void	useIsolatedCatalogView() Isolates the view for methods in this session.
void	usePlenaryCatalogView() A complete view of the Id and Catalog 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

canLookupMappings

boolean canLookupMappings()

Tests if this user can perform lookups of Id to Catalog mappings. A return of true does not guarantee successful authorization. A return of false indicates that it is known lookup 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 looking up mappings is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeCatalogView

void useComparativeCatalogView()

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.

usePlenaryCatalogView

void usePlenaryCatalogView()

A complete view of the Id and Catalog 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.

useFederatedCatalogView

void useFederatedCatalogView()

Federates the view for methods in this session. A federated view will include entries from descendant catalogs in the catalog hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedCatalogView

void useIsolatedCatalogView()

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

Compliance:

mandatory - This method is must be implemented.

getIdsByCatalog

IdList getIdsByCatalog(Id catalogId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Gets the list of Ids map to a Catalog.

Parameters:

catalogId - a catalog Id

Returns:

list of Ids mapped to the given catalogId

Throws:

NotFoundException - catalogId is not found

NullArgumentException - catalogId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getIdsByCatalogs

IdList getIdsByCatalogs(IdList catalogIds)
                        throws OperationFailedException,
                               PermissionDeniedException

Gets the list of Ids map to a lst of Catalogs.

Parameters:

catalogIds - an Id

Returns:

list of catalogs containing the given Id

Throws:

NullArgumentException - catalogIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCatalogIdsById

IdList getCatalogIdsById(Id id)
                         throws OperationFailedException,
                                PermissionDeniedException

Gets the Catalog Ids mapped to an Id.

Parameters:

id - an Id

Returns:

list of catalog Ids containing the given Id

Throws:

NullArgumentException - id is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCatalogsById

CatalogList getCatalogsById(Id id)
                            throws OperationFailedException,
                                   PermissionDeniedException

Gets the Catalogs mapped to an Id.

Parameters:

id - an Id

Returns:

list of catalogs containing the given Id

Throws:

NullArgumentException - id is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.