Interface SubscriptionLookupSession

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

This session defines methods for retrieving subscriptions.

This lookup session defines several views:

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete result set or is an error condition
  • isolated publisher view: All subscription methods in this session operate, retrieve and pertain to subscriptions defined explicitly in the current publisher. Using an isolated view is useful for managing subscriptions with the SubscriptionAdminSession .
  • federated publisher view: All subscription lookup methods in this session operate, retrieve and pertain to all subscriptions defined in this publisher and any other publishers implicitly available in this publisher through publisher inheritence.
  • effective subscription view: All subscription lookup methods return subscriptions where the current date falls in between the effective dates inclusive.
  • any effective subscription view: Subscriptions of any effective date are returned from methods.

The methods useFederatedPublisherView() and useIsolatedPublisherView() behave as a radio group and one should be selected before invoking any lookup methods.

  • Method Details

    • getPublisherId

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

    • getPublisher

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

    • canLookupSubscriptions

      boolean canLookupSubscriptions()
      Tests if this user can lookup subscriptions. 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 these operations.
      Returns:
      false if subscription lookup methods are not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • useComparativeSubscriptionView

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

    • usePlenarySubscriptionView

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

    • useFederatedPublisherView

      void useFederatedPublisherView()
      Federates the view for methods in this session. A federated view will include entries in publishers which are children of this publisher in the publisher hierarchy.
      Compliance:
      mandatory - This method is must be implemented.

    • useIsolatedPublisherView

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

    • useEffectiveSubscriptionView

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

    • useAnyEffectiveSubscriptionView

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

    • getSubscription

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

    • getSubscriptionsByIds

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

    • getSubscriptionsByGenusType

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

    • getSubscriptionsByParentGenusType

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

    • getSubscriptionsByRecordType

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

    • getSubscriptionsOnDate

      SubscriptionList getSubscriptionsOnDate(DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a SubscriptionList effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known subscriptions or an error results. Otherwise, the returned list may contain only those subscriptions that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      from - starting date
      to - ending date
      Returns:
      the returned Subscriptions 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.

    • getSubscriptionsByGenusTypeOnDate

      SubscriptionList getSubscriptionsByGenusTypeOnDate(Type subscriptionGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a SubscriptionList of a subscription genus type 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 subscriptions or an error results. Otherwise, the returned list may contain only those subscriptions that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      subscriptionGenusType - a subscription genus type
      from - starting date
      to - ending date
      Returns:
      the returned Subscriptions list
      Throws:
      InvalidArgumentException - from is greater than to
      NullArgumentException - subscriptionGenusType, from , or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptionsForSubscriber

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

    • getSubscriptionsForSubscriberOnDate

      SubscriptionList getSubscriptionsForSubscriberOnDate(Id resourceId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of all subscriptions corresponding to a subscriber Id 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 subscriptions or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      resourceId - a resource Id
      from - from date
      to - to date
      Returns:
      the returned SubscriptionList
      Throws:
      InvalidArgumentException - to is less than from
      NullArgumentException - resourceId, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptionsByGenusTypeForSubscriber

      SubscriptionList getSubscriptionsByGenusTypeForSubscriber(Id resourceId, Type subscriptionGenusType) throws OperationFailedException, PermissionDeniedException
      Gets a list of subscriptions of the given genus type corresponding to a subscriber Id . In plenary mode, the returned list contains all known subscriptions or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      resourceId - the Id of the resource
      subscriptionGenusType - a subscription genus type
      Returns:
      the returned SubscriptionList
      Throws:
      NullArgumentException - resourceId or subscriptionGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptionsByGenusTypeForSubscriberOnDate

      SubscriptionList getSubscriptionsByGenusTypeForSubscriberOnDate(Id resourceId, Type subscriptionGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of all subscriptions of the given genus type corresponding to a subscriber Id 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 subscriptions or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      resourceId - a resource Id
      subscriptionGenusType - a subscription genus type
      from - from date
      to - to date
      Returns:
      the returned SubscriptionList
      Throws:
      InvalidArgumentException - to is less than from
      NullArgumentException - resourceId, subscriptionGenusType, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptionsForDispatch

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

    • getSubscriptionsForDispatchOnDate

      SubscriptionList getSubscriptionsForDispatchOnDate(Id dispatchId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of all subscriptions corresponding to a dispatch Id 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 subscriptions or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      dispatchId - a dispatch Id
      from - from date
      to - to date
      Returns:
      the returned SubscriptionList
      Throws:
      InvalidArgumentException - to is less than from
      NullArgumentException - dispatchId, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptionsByGenusTypeForDispatch

      SubscriptionList getSubscriptionsByGenusTypeForDispatch(Id dispatchId, Type subscriptionGenusType) throws OperationFailedException, PermissionDeniedException
      Gets a list of all subscriptions of the given genus type corresponding to a dispatch Id . In plenary mode, the returned list contains all known subscriptions or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      dispatchId - the Id of the dispatch
      subscriptionGenusType - a subscription genus type
      Returns:
      the returned SubscriptionList
      Throws:
      NullArgumentException - dispatchId or subscriptionGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptionsByGenusTypeForDispatchOnDate

      SubscriptionList getSubscriptionsByGenusTypeForDispatchOnDate(Id dispatchId, Type subscriptionGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of all subscriptions of the given genus type corresponding to a dispatch Id 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 subscriptions or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      dispatchId - a dispatch Id
      subscriptionGenusType - a subscription genus type
      from - from date
      to - to date
      Returns:
      the returned SubscriptionList
      Throws:
      InvalidArgumentException - to is less than from
      NullArgumentException - dispatchId, subscriptionGenusType, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptionsForSubscriberAndDispatch

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

    • getSubscriptionsForSubscriberAndDispatchOnDate

      SubscriptionList getSubscriptionsForSubscriberAndDispatchOnDate(Id resourceId, Id dispatchId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of all subscriptions corresponding to a subscriber and dispatch Id 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 subscriptions or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      resourceId - the Id of the resource
      dispatchId - a dispatch Id
      from - from date
      to - to date
      Returns:
      the returned SubscriptionList
      Throws:
      InvalidArgumentException - to is less than from
      NullArgumentException - resourceId, dispatchI, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptionsByGenusTypeForSubscriberAndDispatch

      SubscriptionList getSubscriptionsByGenusTypeForSubscriberAndDispatch(Id resourceId, Id dispatchId, Type subscriptionGenusType) throws OperationFailedException, PermissionDeniedException
      Gets a list of all subscriptions of the given genus type corresponding to a susbcriber and dispatch Id . In plenary mode, the returned list contains all known subscriptions or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      resourceId - the Id of the resource
      dispatchId - the Id of the dispatch
      subscriptionGenusType - a subscription genus type
      Returns:
      the returned SubscriptionList
      Throws:
      NullArgumentException - resourceId, dispatchId or subscriptionGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptionsByGenusTypeForSubscriberAndDispatchOnDate

      SubscriptionList getSubscriptionsByGenusTypeForSubscriberAndDispatchOnDate(Id resourceId, Id dispatchId, Type subscriptionGenusType, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
      Gets a list of all subscriptions of the given genus type corresponding to a subscriber and dispatch Id 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 subscriptions or an error results. Otherwise, the returned list may contain only those entries that are accessible through this session. In effective mode, subscriptions are returned that are currently effective. In any effective mode, effective subscriptions and those currently expired are returned.
      Parameters:
      resourceId - the Id of the resource
      dispatchId - a dispatch Id
      subscriptionGenusType - a subscription genus type
      from - from date
      to - to date
      Returns:
      the returned SubscriptionList
      Throws:
      InvalidArgumentException - to is less than from
      NullArgumentException - resourceId, dispatch, subscriptionGenusType, from or to is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getSubscriptions

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