org.osid.subscription

Interface SubscriptionAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

All Known Subinterfaces:

SubscriptionBatchAdminSession

public interface SubscriptionAdminSession
extends OsidSession

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.

Method Summary

Methods

Modifier and Type	Method and Description
void	aliasSubscription(Id subscriptionId, Id aliasId) Adds an Id to a Subscription for the purpose of creating compatibility.
boolean	canCreateSubscriptions() Tests if this user can create hournal entries.
boolean	canCreateSubscriptionWithRecordTypes(Type[] subscriptionRecordTypes) Tests if this user can create a single Subscription using the desired record interface types.
boolean	canDeleteSubscriptions() Tests if this user can delete subscriptions.
boolean	canManageSubscriptionAliases() Tests if this user can manage Id aliases for Comnents.
boolean	canUpdateSubscriptions() Tests if this user can update subscriptions.
Subscription	createSubscription(SubscriptionForm subscriptionForm) Creates a new Subscription.
void	deleteSubscription(Id subscriptionId) Deletes an Subscription.
Publisher	getPublisher() Gets the Publisher associated with this session.
Id	getPublisherId() Gets the Publisher Id associated with this session.
SubscriptionForm	getSubscriptionFormForCreate(Id dispatchId, Id resourceId, Type[] subscriptionRecordTypes) Gets the subscription form for creating new entries.
SubscriptionForm	getSubscriptionFormForUpdate(Id subscriptionId) Gets the subscription form for updating an existing subscription.
void	updateSubscription(SubscriptionForm subscriptionForm) Updates an existing subscription.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

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.

canCreateSubscriptions

boolean canCreateSubscriptions()

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.

Returns:

false if Subscription creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateSubscriptionWithRecordTypes

boolean canCreateSubscriptionWithRecordTypes(Type[] subscriptionRecordTypes)

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.

Parameters:

subscriptionRecordTypes - array of subscription record types

Returns:

true if Subscription creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - subscriptionRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getSubscriptionFormForCreate

SubscriptionForm getSubscriptionFormForCreate(Id dispatchId,
                                            Id resourceId,
                                            Type[] subscriptionRecordTypes)
                                              throws NotFoundException,
                                                     OperationFailedException,
                                                     PermissionDeniedException

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

Parameters:

dispatchId - the Id for the dispatch

resourceId - the Id for the resource

subscriptionRecordTypes - array of subscription record types

Returns:

the subscription form

Throws:

NotFoundException - dispatchId or resourceId is not found

NullArgumentException - dispatchId, resourceId, or subscriptionRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get from for requested record types

Compliance:

mandatory - This method must be implemented.

createSubscription

Subscription createSubscription(SubscriptionForm subscriptionForm)
                                throws OperationFailedException,
                                       PermissionDeniedException

Creates a new Subscription.

Parameters:

subscriptionForm - the form for this Subscription

Returns:

the new Subscription

Throws:

IllegalStateException - subscriptionForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - subscriptionForm did not originate from getSubscriptionFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateSubscriptions

boolean canUpdateSubscriptions()

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.

Returns:

false if Subscription modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getSubscriptionFormForUpdate

SubscriptionForm getSubscriptionFormForUpdate(Id subscriptionId)
                                              throws NotFoundException,
                                                     OperationFailedException,
                                                     PermissionDeniedException

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

Parameters:

subscriptionId - the Id of the Subscription

Returns:

the subscription form

Throws:

NotFoundException - subscriptionId is not found

NullArgumentException - subscriptionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateSubscription

void updateSubscription(SubscriptionForm subscriptionForm)
                        throws OperationFailedException,
                               PermissionDeniedException

Updates an existing subscription.

Parameters:

subscriptionForm - the form containing the elements to be updated

Throws:

IllegalStateException - subscriptionForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - subscriptionId or subscriptionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - subscriptionForm did not originate from getSubscriptionFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteSubscriptions

boolean canDeleteSubscriptions()

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.

Returns:

false if Subscription deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteSubscription

void deleteSubscription(Id subscriptionId)
                        throws NotFoundException,
                               OperationFailedException,
                               PermissionDeniedException

Deletes an Subscription.

Parameters:

subscriptionId - the Id of the Subscription to remove

Throws:

NotFoundException - subscriptionId not found

NullArgumentException - subscriptionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageSubscriptionAliases

boolean canManageSubscriptionAliases()

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.

Returns:

false if Subscription aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasSubscription

void aliasSubscription(Id subscriptionId,
                     Id aliasId)
                       throws AlreadyExistsException,
                              NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

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.

Parameters:

subscriptionId - the Id of a Subscription

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - subscriptionId not found

NullArgumentException - subscriptionId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.