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

This session creates, updates, and deletes Subscriptions. The data for create and update is provided by the consumer via the form object. OsidForms are requested for each create or update and may not be reused.

Create and update operations differ in their usage. To create a Subscription, a SubscriptionForm is requested using getSubscriptionFormForCreate() specifying the desired relationship peers and record Types or none if no record Types are needed. The returned SubscriptionForm will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the SubscriptionForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each SubscriptionForm corresponds to an attempted transaction.

For updates, SubscriptionForms are requested to the Subscription Id that is to be updated using getSubscriptionFormForUpdate(). Similarly, the SubscriptionForm has metadata about the data that can be updated and it can perform validation before submitting the update. The SubscriptionForm can only be used once for a successful update and cannot be reused.

The delete operations delete Subscriptions. To unmap a Subscription from the current Publisher, the SubscriptionPublisherAssignmentSession should be used. These delete operations attempt to remove the Subscription itself thus removing it from all known Publisher catalogs.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

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.
MethodcanCreateSubscriptions
Description

Tests if this user can create hournal entries. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Subscription will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

Returnboolean false if Subscription creation is not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethodcanCreateSubscriptionWithRecordTypes
Description

Tests if this user can create a single Subscription using the desired record interface types. While SubscriptionManager.getSubscriptionRecordTypes() can be used to examine which record interfaces are supported, this method tests which record(s) are required for creating a specific Subscription. Providing an empty array tests if a Subscription can be created with no records.

Parametersosid.type.Type[]subscriptionRecordTypesarray of subscription record types
Returnboolean true if Subscription creation using the specified record Types is supported, false otherwise
ErrorsNULL_ARGUMENT subscriptionRecordTypes is null
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionFormForCreate
Description

Gets the subscription form for creating new entries. A new form should be requested for each create transaction.

Parametersosid.id.IddispatchIdthe Id for the dispatch
osid.id.IdresourceIdthe Id for the resource
osid.type.Type[]subscriptionRecordTypesarray of subscription record types
Returnosid.subscription.SubscriptionFormthe subscription form
ErrorsNOT_FOUND dispatchId or resourceId is not found
NULL_ARGUMENT dispatchId, resourceId, or subscriptionRecordTypes is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
UNSUPPORTEDunable to get from for requested record types
CompliancemandatoryThis method must be implemented.
MethodcreateSubscription
Description

Creates a new Subscription.

Parametersosid.subscription.SubscriptionFormsubscriptionFormthe form for this Subscription
Returnosid.subscription.Subscriptionthe new Subscription
ErrorsILLEGAL_STATE subscriptionForm already used in a create transaction
INVALID_ARGUMENTone or more of the form elements is invalid
NULL_ARGUMENT resourceId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
UNSUPPORTED subscriptionForm did not originate from getSubscriptionFormForCreate()
CompliancemandatoryThis method must be implemented.
MethodcanUpdateSubscriptions
Description

Tests if this user can update subscriptions. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Subscription will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Returnboolean false if Subscription modification is not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethodgetSubscriptionFormForUpdate
Description

Gets the subscription form for updating an existing subscription. A new subscription form should be requested for each update transaction.

Parametersosid.id.IdsubscriptionIdthe Id of the Subscription
Returnosid.subscription.SubscriptionFormthe subscription form
ErrorsNOT_FOUND subscriptionId is not found
NULL_ARGUMENT subscriptionId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodupdateSubscription
Description

Updates an existing subscription.

Parametersosid.subscription.SubscriptionFormsubscriptionFormthe form containing the elements to be updated
ErrorsILLEGAL_STATE subscriptionForm already used in an update transaction
INVALID_ARGUMENTthe form contains an invalid value
NULL_ARGUMENT subscriptionId or subscriptionForm is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
UNSUPPORTED subscriptionForm did not originate from getSubscriptionFormForUpdate()
CompliancemandatoryThis method must be implemented.
MethodcanDeleteSubscriptions
Description

Tests if this user can delete subscriptions. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an Subscription will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.

Returnboolean false if Subscription deletion is not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoddeleteSubscription
Description

Deletes an Subscription.

Parametersosid.id.IdsubscriptionIdthe Id of the Subscription to remove
ErrorsNOT_FOUND subscriptionId not found
NULL_ARGUMENT subscriptionId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanManageSubscriptionAliases
Description

Tests if this user can manage Id aliases for Comnents. A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.

Returnboolean false if Subscription aliasing is not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethodaliasSubscription
Description

Adds an Id to a Subscription for the purpose of creating compatibility. The primary Id of the Subscription is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another subscription, it is reassigned to the given subscription Id.

Parametersosid.id.IdsubscriptionIdthe Id of a Subscription
osid.id.IdaliasIdthe alias Id
ErrorsALREADY_EXISTS aliasId is already assigned
NOT_FOUND subscriptionId not found
NULL_ARGUMENT subscriptionId or aliasId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.