Interface ProvisionLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
public interface ProvisionLookupSession extends OsidSession

This session provides methods for retrieving Provision objects. The Provision represents a fixed connection between two Provisions .

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 distributor view: All provision methods in this session operate, retrieve and pertain to provisions defined explicitly in the current distributor. Using an isolated view is useful for managing Provisions with the ProvisionAdminSession .
  • federated distributor view: All provision methods in this session operate, retrieve and pertain to all provisions defined in this distributor and any other provisions implicitly available in this distributor through distributor inheritence.
  • effective provision view: All provision lookup methods return provisions where the current date falls in between the effective dates inclusive.
  • any effective provision view: Provisions of any effective date 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 any lookup methods.

  • Method Details

    • getDistributorId

      Id getDistributorId()
      Gets the Distributor Id associated with this session.
      Returns:
      the Distributor Id associated with this session
      Compliance:
      mandatory - This method must be implemented.

    • getDistributor

      Distributor getDistributor() throws OperationFailedException, PermissionDeniedException
      Gets the Distributor associated with this session.
      Returns:
      the distributor
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canLookupProvisions

      boolean canLookupProvisions()
      Tests if this user can perform Provision 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.

    • useComparativeProvisionView

      void useComparativeProvisionView()
      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.

    • usePlenaryProvisionView

      void usePlenaryProvisionView()
      A complete view of the Provision 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.

    • useFederatedDistributorView

      void useFederatedDistributorView()
      Federates the view for methods in this session. A federated view will include provisions in distributors which are children of this distributor in the distributor hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedDistributorView

      void useIsolatedDistributorView()
      Isolates the view for methods in this session. An isolated view restricts lookups to this distributor only.
      Compliance:
      mandatory - This method is must be implemented.

    • useEffectiveProvisionView

      void useEffectiveProvisionView()
      Only provisions whose effective dates are current are returned by methods in this session.
      Compliance:
      mandatory - This method is must be implemented.

    • useAnyEffectiveProvisionView

      void useAnyEffectiveProvisionView()
      All provisions of any effective dates are returned by methods in this session.
      Compliance:
      mandatory - This method is must be implemented.

    • getProvision

      Provision getProvision(Id provisionId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the Provision specified by its Id . In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Provision may have a different Id than requested, such as the case where a duplicate Id was assigned to a Provision and retained for compatibility. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      provisionId - Id of the Provision
      Returns:
      the provision
      Throws:
      NotFoundException - provisionId not found
      NullArgumentException - provisionId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method is must be implemented.

    • getProvisionsByIds

      ProvisionList getProvisionsByIds(IdList provisionIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets a ProvisionList corresponding to the given IdList . In plenary mode, the returned list contains all of the provisions 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 Provisions may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      provisionIds - the list of Ids to retrieve
      Returns:
      the returned Provision list
      Throws:
      NotFoundException - an Id was not found
      NullArgumentException - provisionIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsByGenusType

      ProvisionList getProvisionsByGenusType(Type provisionGenusType) throws OperationFailedException, PermissionDeniedException
      Gets a ProvisionList corresponding to the given provision genus Type which does not include provisions of genus types derived from the specified Type . In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      provisionGenusType - a provision genus type
      Returns:
      the returned Provision list
      Throws:
      NullArgumentException - provisionGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsByParentGenusType

      ProvisionList getProvisionsByParentGenusType(Type provisionGenusType) throws OperationFailedException, PermissionDeniedException
      Gets a ProvisionList corresponding to the given provision genus Type and include any additional provisions with genus types derived from the specified Type . In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      provisionGenusType - a provision genus type
      Returns:
      the returned Provision list
      Throws:
      NullArgumentException - provisionGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsByRecordType

      ProvisionList getProvisionsByRecordType(Type provisionRecordType) throws OperationFailedException, PermissionDeniedException
      Gets a ProvisionList containing the given provision record Type . In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      provisionRecordType - a provision record type
      Returns:
      the returned Provision list
      Throws:
      NullArgumentException - provisionRecordType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsOnDate

      ProvisionList getProvisionsOnDate(DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective in addition to being effective in the guven date range. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      from - start of date range
      to - end of date range
      Returns:
      the returned Provision 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.

    • getProvisionsForBroker

      ProvisionList getProvisionsForBroker(Id brokerId) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions for a supplied broker. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      brokerId - a broker Id
      Returns:
      the returned Provision list
      Throws:
      NullArgumentException - brokerId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsForBrokerOnDate

      ProvisionList getProvisionsForBrokerOnDate(Id brokerId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions for a supplied broker. and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective in addition to being effective in the guven date range. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      brokerId - a broker Id
      from - start of date range
      to - end of date range
      Returns:
      the returned Provision list
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - brokerId, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsForProvisionable

      ProvisionList getProvisionsForProvisionable(Id provisionableId) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions for a provisionable. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      provisionableId - a provisionable Id
      Returns:
      the returned Provision list
      Throws:
      NullArgumentException - provisionableId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsForProvisionableOnDate

      ProvisionList getProvisionsForProvisionableOnDate(Id provisionableId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions for a provisionable and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective in addition to being effective in the guven date range. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      provisionableId - a provisionable Id
      from - start of date range
      to - end of date range
      Returns:
      the returned Provision list
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - provisionableId, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsForRecipient

      ProvisionList getProvisionsForRecipient(Id resourceId) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions for a recipient resource. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      resourceId - a resource Id
      Returns:
      the returned Provision list
      Throws:
      NullArgumentException - resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsForRecipientOnDate

      ProvisionList getProvisionsForRecipientOnDate(Id resourceId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions for a recipient resource and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective in addition to being effective in the guven date range. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      resourceId - a resource Id
      from - start of date range
      to - end of date range
      Returns:
      the returned Provision list
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - resourceId, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsForProvisionableAndRecipient

      ProvisionList getProvisionsForProvisionableAndRecipient(Id provisionableId, Id recipientId) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions for a resource and recipient. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      provisionableId - a provisionable Id
      recipientId - a recipient resource Id
      Returns:
      the returned Provision list
      Throws:
      NullArgumentException - provisionableId or recipientId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsForProvisionableAndRecipientOnDate

      ProvisionList getProvisionsForProvisionableAndRecipientOnDate(Id provisionableId, Id recipientId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions for a resource and request and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective in addition to being effective in the guven date range. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      provisionableId - a provisionable Id
      recipientId - a recipient resource Id
      from - start of date range
      to - end of date range
      Returns:
      the returned Provision list
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - provisionableId, recipientId, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisionsForRequest

      ProvisionList getProvisionsForRequest(Id requestId) throws OperationFailedException, PermissionDeniedException
      Gets a list of provisions for a request. In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Parameters:
      requestId - a request Id
      Returns:
      the returned Provision list
      Throws:
      NullArgumentException - requestId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getProvisions

      ProvisionList getProvisions() throws OperationFailedException, PermissionDeniedException
      Gets all Provisions . In plenary mode, the returned list contains all known provisions or an error results. Otherwise, the returned list may contain only those provisions that are accessible through this session. In effective mode, provisions are returned that are currently effective. In any effective mode, effective provisions and those currently expired are returned.
      Returns:
      a list of Provisions
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.