org.osid.financials.budgeting

Interface BudgetAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

BudgetBatchAdminSession

public interface BudgetAdminSession
extends OsidSession

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

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

The delete operations delete Budgets. To unmap a Budget from the current Business, the BudgetBusinessAssignmentSession should be used. These delete operations attempt to remove the Budget 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	aliasBudget(Id budgetId, Id aliasId) Adds an Id to a Budget for the purpose of creating compatibility.
boolean	canCreateBudgets() Tests if this user can create Budgets.
boolean	canCreateBudgetWithRecordTypes(Type[] budgetRecordTypes) Tests if this user can create a single Budget using the desired record types.
boolean	canDeleteBudgets() Tests if this user can delete Budgets.
boolean	canManageBudgetAliases() Tests if this user can manage Id aliases for Budgets.
boolean	canUpdateBudgets() Tests if this user can update Budgets.
Budget	createBudget(BudgetForm budgetForm) Creates a new Budget.
void	deleteBudget(Id budgetId) Deletes a Budget.
BudgetForm	getBudgetFormForCreate(Id activityId, Id fiscalPeriodId, Type[] budgetRecordTypes) Gets the budget form for creating new budgets.
BudgetForm	getBudgetFormForUpdate(Id budgetId) Gets the budget form for updating an existing budget.
Business	getBusiness() Gets the Business associated with this session.
Id	getBusinessId() Gets the Business Id associated with this session.
void	updateBudget(BudgetForm budgetForm) Updates an existing budget.

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.

canCreateBudgets

boolean canCreateBudgets()

Tests if this user can create Budgets. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Budget 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 Budget creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateBudgetWithRecordTypes

boolean canCreateBudgetWithRecordTypes(Type[] budgetRecordTypes)

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

Parameters:

budgetRecordTypes - array of budget record types

Returns:

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

Throws:

NullArgumentException - budgetRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getBudgetFormForCreate

BudgetForm getBudgetFormForCreate(Id activityId,
                                Id fiscalPeriodId,
                                Type[] budgetRecordTypes)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Gets the budget form for creating new budgets. A new form should be requested for each create transaction.

Parameters:

activityId - the Id of the associated Activity

fiscalPeriodId - the Id of the fiscal period

budgetRecordTypes - array of budget record types

Returns:

the budget form

Throws:

NotFoundException - activityId or fiscalPeriodId not found

NullArgumentException - activityId, fiscalPeriodId, or budgetRecordTypes 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.

createBudget

Budget createBudget(BudgetForm budgetForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Creates a new Budget.

Parameters:

budgetForm - the form for this Budget

Returns:

the new Budget

Throws:

IllegalStateException - budgetForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - budgetForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - entryForm did not originate from getBudgetFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateBudgets

boolean canUpdateBudgets()

Tests if this user can update Budgets. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Budget 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 Budget modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getBudgetFormForUpdate

BudgetForm getBudgetFormForUpdate(Id budgetId)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

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

Parameters:

budgetId - the Id of the Budget

Returns:

the budget form

Throws:

NotFoundException - budgetId is not found

NullArgumentException - budgetId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateBudget

void updateBudget(BudgetForm budgetForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Updates an existing budget.

Parameters:

budgetForm - the form containing the elements to be updated

Throws:

IllegalStateException - budgetForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - budgetForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - entryForm did not originate from getBudgetFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteBudgets

boolean canDeleteBudgets()

Tests if this user can delete Budgets. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Budget 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 Budget deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteBudget

void deleteBudget(Id budgetId)
                  throws NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Deletes a Budget.

Parameters:

budgetId - the Id of the Budget to remove

Throws:

NotFoundException - budgetId not found

NullArgumentException - budgetId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageBudgetAliases

boolean canManageBudgetAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasBudget

void aliasBudget(Id budgetId,
               Id aliasId)
                 throws AlreadyExistsException,
                        NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

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

Parameters:

budgetId - the Id of a Budget

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - budgetId not found

NullArgumentException - budgetId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.