OSID Logo
OSID Specifications
subscription package
Version 3.0.0
Release Candidate Preview
Interfaceosid.subscription.SubscriptionLookupSession
Implementsosid.OsidSession
Description

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.

MethodgetPublisherId
Description

Gets the Publisher Id associated with this session.

Returnosid.id.Idthe Publisher Id associated with this session
CompliancemandatoryThis method must be implemented.
MethodgetPublisher
Description

Gets the Publisher associated with this session.

Returnosid.subscription.Publisherthe publisher
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanLookupSubscriptions
Description

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.

Returnboolean false if subscription lookup methods are not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoduseComparativeSubscriptionView
Description

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.

CompliancemandatoryThis method is must be implemented.
MethodusePlenarySubscriptionView
Description

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.

CompliancemandatoryThis method is must be implemented.
MethoduseFederatedPublisherView
Description

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.

CompliancemandatoryThis method is must be implemented.
MethoduseIsolatedPublisherView
Description

Isolates the view for methods in this session. An isolated view restricts retrievals to this publisher only.

CompliancemandatoryThis method is must be implemented.
MethoduseEffectiveSubscriptionView
Description

Only subscriptions whose effective dates are current are returned by methods in this session.

CompliancemandatoryThis method is must be implemented.
MethoduseAnyEffectiveSubscriptionView
Description

All subscriptions of any effective dates are returned by methods in this session.

CompliancemandatoryThis method is must be implemented.
MethodgetSubscription
Description

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.

Parametersosid.id.IdsubscriptionIdthe Id of the Subscription to retrieve
Returnosid.subscription.Subscriptionthe returned Subscription
ErrorsNOT_FOUNDno Subscription found with the given Id
NULL_ARGUMENT subscriptionId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByIds
Description

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.

Parametersosid.id.IdListsubscriptionIdsthe list of Ids to retrieve
Returnosid.subscription.SubscriptionListthe returned Subscription list
ErrorsNOT_FOUNDan Id was not found
NULL_ARGUMENT subscriptionIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByGenusType
Description

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.

Parametersosid.type.TypesubscriptionGenusTypea subscription genus type
Returnosid.subscription.SubscriptionListthe returned Subscription list
ErrorsNULL_ARGUMENT subscriptionGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByParentGenusType
Description

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.

Parametersosid.type.TypesubscriptionGenusTypea subscription genus type
Returnosid.subscription.SubscriptionListthe returned Subscriptions list
ErrorsNULL_ARGUMENT subscriptionGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByRecordType
Description

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.

Parametersosid.type.TypesubscriptionRecordTypea subscription record type
Returnosid.subscription.SubscriptionListthe returned Subscriptions list
ErrorsNULL_ARGUMENT subscriptionRecordType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsOnDate
Description

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.

Parametersosid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.subscription.SubscriptionListthe returned Subscriptions list
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByGenusTypeOnDate
Description

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.

Parametersosid.type.TypesubscriptionGenusTypea subscription genus type
osid.calendaring.DateTimefromstarting date
osid.calendaring.DateTimetoending date
Returnosid.subscription.SubscriptionListthe returned Subscriptions list
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT subscriptionGenusType, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsForSubscriber
Description

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.

Parametersosid.id.IdresourceIdthe Id of the resource
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsNULL_ARGUMENT resourceId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsForSubscriberOnDate
Description

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.

Parametersosid.id.IdresourceIda resource Id
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT resourceId, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByGenusTypeForSubscriber
Description

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.

Parametersosid.id.IdresourceIdthe Id of the resource
osid.type.TypesubscriptionGenusTypea subscription genus type
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsNULL_ARGUMENT resourceId or subscriptionGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByGenusTypeForSubscriberOnDate
Description

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.

Parametersosid.id.IdresourceIda resource Id
osid.type.TypesubscriptionGenusTypea subscription genus type
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT resourceId, subscriptionGenusType, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsForDispatch
Description

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.

Parametersosid.id.IddispatchIdthe Id of the dispatch
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsNULL_ARGUMENT dispatchId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsForDispatchOnDate
Description

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.

Parametersosid.id.IddispatchIda dispatch Id
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT dispatchId, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByGenusTypeForDispatch
Description

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.

Parametersosid.id.IddispatchIdthe Id of the dispatch
osid.type.TypesubscriptionGenusTypea subscription genus type
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsNULL_ARGUMENT dispatchId or subscriptionGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByGenusTypeForDispatchOnDate
Description

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.

Parametersosid.id.IddispatchIda dispatch Id
osid.type.TypesubscriptionGenusTypea subscription genus type
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT dispatchId, subscriptionGenusType, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsForSubscriberAndDispatch
Description

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.

Parametersosid.id.IdresourceIdthe Id of the resource
osid.id.IddispatchIdthe Id of the dispatch
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsNULL_ARGUMENT resourceId or dispatchId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsForSubscriberAndDispatchOnDate
Description

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.

Parametersosid.id.IdresourceIdthe Id of the resource
osid.id.IddispatchIda dispatch Id
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT resourceId, dispatchI, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByGenusTypeForSubscriberAndDispatch
Description

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.

Parametersosid.id.IdresourceIdthe Id of the resource
osid.id.IddispatchIdthe Id of the dispatch
osid.type.TypesubscriptionGenusTypea subscription genus type
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsNULL_ARGUMENT resourceId, dispatchId or subscriptionGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionsByGenusTypeForSubscriberAndDispatchOnDate
Description

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.

Parametersosid.id.IdresourceIdthe Id of the resource
osid.id.IddispatchIda dispatch Id
osid.type.TypesubscriptionGenusTypea subscription genus type
osid.calendaring.DateTimefromfrom date
osid.calendaring.DateTimetoto date
Returnosid.subscription.SubscriptionListthe returned SubscriptionList
ErrorsINVALID_ARGUMENT to is less than from
NULL_ARGUMENT resourceId, dispatch, subscriptionGenusType, from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptions
Description

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.

Returnosid.subscription.SubscriptionLista list of subscriptions
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.