Interface CatalogSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

    • 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.