org.osid.subscription

Interface MySubscriptionAdminSession

All Superinterfaces:

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

public interface MySubscriptionAdminSession
extends OsidSession

This session creates and removes subscriptions foe the authenticated Agent. The data for create and update is provided by the consumer via the form object.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canSubscribe() Tests if this user can create hournal entries.
boolean	canSubscribeWithRecordTypes(Type[] subscriptionRecordTypes) Tests if this user can create a single Subscription using the desired record types.
boolean	canUnsubscribe() Tests if this user can delete their own subscriptions.
boolean	canUpdateMySubscriptions() Tests if this user can update subscriptions.
Publisher	getPublisher() Gets the Publisher associated with this session.
Id	getPublisherId() Gets the Publisher Id associated with this session.
SubscriptionForm	getSubscriptionFormForCreate(Id dispatchId, Type[] subscriptionRecordTypes) Gets the subscription form for creating new entries.
SubscriptionForm	getSubscriptionFormForUpdate(Id subscriptionId) Gets the subscription form for updating an existing subscription.
Subscription	subscribe(SubscriptionForm subscriptionForm) Creates a new Subscription.
void	unsubscribe(Id subscriptionId) Deletes an Subscription.
void	updateMySubscription(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.

canSubscribe

boolean canSubscribe()

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.

canSubscribeWithRecordTypes

boolean canSubscribeWithRecordTypes(Type[] subscriptionRecordTypes)

Tests if this user can create a single Subscription using the desired record types. While SubscriptionManager.getSubscriptionRecordTypes() can be used to examine which records 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,
                                            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

subscriptionRecordTypes - array of subscription record types

Returns:

the subscription form

Throws:

NotFoundException - dispatchId is not found

NullArgumentException - dispatchId or subscriptionRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested recod types

Compliance:

mandatory - This method must be implemented.

subscribe

Subscription subscribe(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 - subscriptionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - subscriptionForm did not originate from getSubscriptionFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateMySubscriptions

boolean canUpdateMySubscriptions()

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 for this user

NullArgumentException - subscriptionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateMySubscription

void updateMySubscription(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.

canUnsubscribe

boolean canUnsubscribe()

Tests if this user can delete their own 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.

unsubscribe

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

Deletes an Subscription.

Parameters:

subscriptionId - the Id of the Subscription to remove

Throws:

NotFoundException - subscriber not subscribed to subscriptionId

NullArgumentException - subscriptionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.