org.osid.financials.budgeting

Interface BudgetEntryAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

BudgetEntryBatchAdminSession

public interface BudgetEntryAdminSession
extends OsidSession

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

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

The delete operations delete BudgetEntryForms. To unmap an BudgetEntry from the current Business, the BudgetEntryBusinessAssignmentSession should be used. These delete operations attempt to remove the BudgetEntryForm 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	aliasBudgetEntry(Id budgetEntryId, Id aliasId) Adds an Id to an BudgetEntry for the purpose of creating compatibility.
boolean	canCreateBudgetEntries() Tests if this user can create BudgetEntries.
boolean	canCreateBudgetEntryWithRecordTypes(Type[] budgetEntryRecordTypes) Tests if this user can create a single BudgetEntry using the desired record types.
boolean	canDeleteBudgetEntries() Tests if this user can delete BudgetEntries.
boolean	canManageBudgetEntryAliases() Tests if this user can manage Id aliases for BudgetEntries.
boolean	canUpdateBudgetEntries() Tests if this user can update BudgetEntries.
BudgetEntry	createBudgetEntry(BudgetEntryForm entryForm) Creates a new BudgetEntry.
void	deleteBudgetEntry(Id budgetEntryId) Deletes an BudgetEntry.
BudgetEntryForm	getBudgetEntryFormForCreate(Id budgetId, Id accountId, Type[] budgetEntryRecordTypes) Gets the budget entry form for creating new budget entries.
BudgetEntryForm	getBudgetEntryFormForUpdate(Id budgetEntryId) Gets the budget entry form for updating an existing budget entries.
Business	getBusiness() Gets the Business associated with this session.
Id	getBusinessId() Gets the Business Id associated with this session.
void	updateBudgetEntry(BudgetEntryForm budgetEntryForm) Updates an existing budget entries.

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.

canCreateBudgetEntries

boolean canCreateBudgetEntries()

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

Compliance:

mandatory - This method must be implemented.

canCreateBudgetEntryWithRecordTypes

boolean canCreateBudgetEntryWithRecordTypes(Type[] budgetEntryRecordTypes)

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

Parameters:

budgetEntryRecordTypes - array of budget entry record types

Returns:

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

Throws:

NullArgumentException - budgetEntryRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getBudgetEntryFormForCreate

BudgetEntryForm getBudgetEntryFormForCreate(Id budgetId,
                                          Id accountId,
                                          Type[] budgetEntryRecordTypes)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

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

Parameters:

budgetId - a budget Id

accountId - an account Id

budgetEntryRecordTypes - array of budget entry record types

Returns:

the budget entry form

Throws:

NotFoundException - budgetId or accountId is not found

NullArgumentException - budgetId, accountId, or budgetEntryRecordTypes 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.

createBudgetEntry

BudgetEntry createBudgetEntry(BudgetEntryForm entryForm)
                              throws OperationFailedException,
                                     PermissionDeniedException

Creates a new BudgetEntry.

Parameters:

entryForm - the form for this BudgetEntry

Returns:

the new BudgetEntry

Throws:

IllegalStateException - entryForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - entryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - entryForm did not originate from getBudgetEntryFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateBudgetEntries

boolean canUpdateBudgetEntries()

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

Compliance:

mandatory - This method must be implemented.

getBudgetEntryFormForUpdate

BudgetEntryForm getBudgetEntryFormForUpdate(Id budgetEntryId)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

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

Parameters:

budgetEntryId - the Id of the BudgetEntry

Returns:

the budget entry form

Throws:

NotFoundException - budgetEntryId is not found

NullArgumentException - budgetEntryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateBudgetEntry

void updateBudgetEntry(BudgetEntryForm budgetEntryForm)
                       throws OperationFailedException,
                              PermissionDeniedException

Updates an existing budget entries.

Parameters:

budgetEntryForm - the form containing the elements to be updated

Throws:

IllegalStateException - budgetEntryForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - budgetEntryForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - entryForm did not originate from getBudgetEntryFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteBudgetEntries

boolean canDeleteBudgetEntries()

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

Compliance:

mandatory - This method must be implemented.

deleteBudgetEntry

void deleteBudgetEntry(Id budgetEntryId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Deletes an BudgetEntry.

Parameters:

budgetEntryId - the Id of the BudgetEntry to remove

Throws:

NotFoundException - budgetEntryId not found

NullArgumentException - budgetEntryId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageBudgetEntryAliases

boolean canManageBudgetEntryAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasBudgetEntry

void aliasBudgetEntry(Id budgetEntryId,
                    Id aliasId)
                      throws AlreadyExistsException,
                             NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

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

Parameters:

budgetEntryId - the Id of an BudgetEntry

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - budgetEntryId not found

NullArgumentException - budgetEntryId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.