org.osid.billing

Interface PeriodAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

PeriodBatchAdminSession

public interface PeriodAdminSession
extends OsidSession

This session creates, updates, and deletes Periods. 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 period, a PeriodForm is requested using getPeriodFormForCreate() specifying the desired relationship peers and record Types or none if no record Types are needed. The returned PeriodForm 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 PeriodForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each PeriodForm corresponds to an attempted transaction.

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

The delete operations delete Periods. To unmap a Period from the current Business, the PeriodBusinessAssignmentSession should be used. These delete operations attempt to remove the Period itself thus removing it from all known Business 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	aliasPeriod(Id periodId, Id aliasId) Adds an Id to a Period for the purpose of creating compatibility.
boolean	canCreatePeriods() Tests if this user can create Periods.
boolean	canCreatePeriodWithRecordTypes(Type[] periodRecordTypes) Tests if this user can create a single Period using the desired record types.
boolean	canDeletePeriods() Tests if this user can delete Periods.
boolean	canManagePeriodAliases() Tests if this user can manage Id aliases for Periods.
boolean	canUpdatePeriods() Tests if this user can update Periods.
Period	createPeriod(PeriodForm periodForm) Creates a new Period.
void	deletePeriod(Id periodId) Deletes a Period.
Business	getBusiness() Gets the Business associated with this session.
Id	getBusinessId() Gets the Business Id associated with this session.
PeriodForm	getPeriodFormForCreate(Type[] periodRecordTypes) Gets the period form for creating new periods.
PeriodForm	getPeriodFormForUpdate(Id periodId) Gets the period form for updating an existing period.
void	updatePeriod(PeriodForm periodForm) Updates an existing period.

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

getBusinessId

Id getBusinessId()

Gets the Business Id associated with this session.

Returns:

the Business Id associated with this session

Compliance:

mandatory - This method must be implemented.

getBusiness

Business getBusiness()
                     throws OperationFailedException,
                            PermissionDeniedException

Gets the Business associated with this session.

Returns:

the business

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreatePeriods

boolean canCreatePeriods()

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

Returns:

false if Period creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreatePeriodWithRecordTypes

boolean canCreatePeriodWithRecordTypes(Type[] periodRecordTypes)

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

Parameters:

periodRecordTypes - array of period record types

Returns:

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

Throws:

NullArgumentException - periodRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getPeriodFormForCreate

PeriodForm getPeriodFormForCreate(Type[] periodRecordTypes)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets the period form for creating new periods. A new form should be requested for each create transaction.

Parameters:

periodRecordTypes - array of period record types

Returns:

the period form

Throws:

NullArgumentException - periodRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createPeriod

Period createPeriod(PeriodForm periodForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Creates a new Period.

Parameters:

periodForm - the form for this Period

Returns:

the new Period

Throws:

IllegalStateException - periodForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - periodForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - periodForm did not originate from getPeriodFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdatePeriods

boolean canUpdatePeriods()

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

Returns:

false if Period modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getPeriodFormForUpdate

PeriodForm getPeriodFormForUpdate(Id periodId)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

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

Parameters:

periodId - the Id of the Period

Returns:

the period form

Throws:

NotFoundException - periodId is not found

NullArgumentException - periodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updatePeriod

void updatePeriod(PeriodForm periodForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Updates an existing period.

Parameters:

periodForm - the form containing the elements to be updated

Throws:

IllegalStateException - periodForm already used in anjupdate transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - periodId or periodForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - periodForm did not originate from getPeriodFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeletePeriods

boolean canDeletePeriods()

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

Returns:

false if Period deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deletePeriod

void deletePeriod(Id periodId)
                  throws NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Deletes a Period.

Parameters:

periodId - the Id of the Period to remove

Throws:

NotFoundException - periodId not found

NullArgumentException - periodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManagePeriodAliases

boolean canManagePeriodAliases()

Tests if this user can manage Id aliases for Periods. 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 Period aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasPeriod

void aliasPeriod(Id periodId,
               Id aliasId)
                 throws AlreadyExistsException,
                        NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

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

Parameters:

periodId - the Id of a Period

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - periodId not found

NullArgumentException - periodId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.