org.osid.financials.budgeting

Interface BudgetLookupSession

All Superinterfaces:

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

public interface BudgetLookupSession
extends OsidSession

This session defines methods for retrieving budgets.

This lookup session defines several views:

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete result set or is an error condition
• isolated business view: All budget methods in this session operate, retrieve and pertain to budgets defined explicitly in the current business. Using an isolated view is useful for managing Budgets with the BudgetAdminSession.
• federated business view: All budget lookup methods in this session operate, retrieve and pertain to all budgets defined in this business and any other budgets implicitly available in this business through business inheritence.
• effective budget view: All budget lookup methods return budgets where the current date falls in between the effective dates inclusive.
• any effective budget view: Budgets of any effective date are returned from methods.

The methods useFederatedBusinessView() and useIsolatedBusinessView() behave as a radio group and one should be selected before invoking any lookup methods.

Budgets may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the Budget.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupBudgets() Tests if this user can perform Budget lookups.
Budget	getBudget(Id budgetId) Gets the Budget specified by its Id.
BudgetList	getBudgets() Gets all Budgets.
BudgetList	getBudgetsByGenusType(Type budgetGenusType) Gets a BudgetList corresponding to the given budget genus Type which does not include budgets of types derived from the specified Type.
BudgetList	getBudgetsByIds(IdList budgetIds) Gets a BudgetList corresponding to the given IdList.
BudgetList	getBudgetsByParentGenusType(Type budgetGenusType) Gets a BudgetList corresponding to the given budget genus Type and include any additional budgets with genus types derived from the specified Type.
BudgetList	getBudgetsByRecordType(Type budgetRecordType) Gets a BudgetList containing the given budget record Type.
BudgetList	getBudgetsForActivity(Id activityId) Gets a BudgetList for the given activity.
BudgetList	getBudgetsForActivityAndFiscalPeriod(Id activityId, Id fiscalPeriodId) Gets a BudgetList for the given activity and fiscal period.
BudgetList	getBudgetsForActivityAndFiscalPeriodOnDate(Id activityId, Id fiscalPeriodId, DateTime from, DateTime to) Gets a BudgetList for the given activity, fiscal period, and effective during the entire given date range inclusive but not confined to the date range.
BudgetList	getBudgetsForActivityOnDate(Id activityId, DateTime from, DateTime to) Gets a BudgetList for the given activity and effective during the entire given date range inclusive but not confined to the date range.
BudgetList	getBudgetsForFiscalPeriod(Id fiscalPeriodId) Gets a BudgetList for the given fiscal period.
BudgetList	getBudgetsForFiscalPeriodOnDate(Id fiscalPeriodId, DateTime from, DateTime to) Gets a BudgetList for the given fiscal period and effective during the entire given date range inclusive but not confined to the date range.
BudgetList	getBudgetsOnDate(DateTime from, DateTime to) Gets a BudgetList effective during the entire given date range inclusive but not confined to the date range.
Business	getBusiness() Gets the Business associated with this session.
Id	getBusinessId() Gets the Business Id associated with this session.
void	useAnyEffectiveBudgetView() All budgets of any effective dates are returned by methods in this session.
void	useComparativeBudgetView() The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useEffectiveBudgetView() Only budgets whose effective dates are current are returned by methods in this session.
void	useFederatedBusinessView() Federates the view for methods in this session.
void	useIsolatedBusinessView() Isolates the view for methods in this session.
void	usePlenaryBudgetView() A complete view of the Budget returns is desired.

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.

canLookupBudgets

boolean canLookupBudgets()

Tests if this user can perform Budget lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not offer lookup operations to unauthorized users.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeBudgetView

void useComparativeBudgetView()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryBudgetView

void usePlenaryBudgetView()

A complete view of the Budget returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

Compliance:

mandatory - This method is must be implemented.

useFederatedBusinessView

void useFederatedBusinessView()

Federates the view for methods in this session. A federated view will include budgets in catalogs which are children of this catalog in the business hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedBusinessView

void useIsolatedBusinessView()

Isolates the view for methods in this session. An isolated view restricts retrievals to this business only.

Compliance:

mandatory - This method is must be implemented.

useEffectiveBudgetView

void useEffectiveBudgetView()

Only budgets whose effective dates are current are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveBudgetView

void useAnyEffectiveBudgetView()

All budgets of any effective dates are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

getBudget

Budget getBudget(Id budgetId)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Gets the Budget specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Budget may have a different Id than requested, such as the case where a duplicate Id was assigned to a Budget and retained for compatibility. In effective mode, budgets are returned that are currently effective. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

budgetId - the Id of the Budget to retrieve

Returns:

the returned Budget

Throws:

NotFoundException - no Budget found with the given Id

NullArgumentException - budgetId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsByIds

BudgetList getBudgetsByIds(IdList budgetIds)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Gets a BudgetList corresponding to the given IdList. In plenary mode, the returned list contains all of the budgets specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Budgets may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, budgets are returned that are currently effective. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

budgetIds - the list of Ids to retrieve

Returns:

the returned Budget list

Throws:

NotFoundException - an Id was not found

NullArgumentException - budgetIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsByGenusType

BudgetList getBudgetsByGenusType(Type budgetGenusType)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Gets a BudgetList corresponding to the given budget genus Type which does not include budgets of types derived from the specified Type. In plenary mode, the returned list contains all known budgets or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

budgetGenusType - a budget genus type

Returns:

the returned Budget list

Throws:

NullArgumentException - budgetGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsByParentGenusType

BudgetList getBudgetsByParentGenusType(Type budgetGenusType)
                                       throws OperationFailedException,
                                              PermissionDeniedException

Gets a BudgetList corresponding to the given budget genus Type and include any additional budgets with genus types derived from the specified Type. In plenary mode, the returned list contains all known budgets or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

budgetGenusType - a budget genus type

Returns:

the returned Budget list

Throws:

NullArgumentException - budgetGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsByRecordType

BudgetList getBudgetsByRecordType(Type budgetRecordType)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets a BudgetList containing the given budget record Type. In plenary mode, the returned list contains all known mode,s or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

budgetRecordType - a budget record type

Returns:

the returned Budget list

Throws:

NullArgumentException - budgetRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsOnDate

BudgetList getBudgetsOnDate(DateTime from,
                          DateTime to)
                            throws OperationFailedException,
                                   PermissionDeniedException

Gets a BudgetList effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known budgets or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

from - start of date range

to - end of date range

Returns:

the returned Budget list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsForActivity

BudgetList getBudgetsForActivity(Id activityId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Gets a BudgetList for the given activity. In plenary mode, the returned list contains all known mode,s or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

activityId - an activity Id

Returns:

the returned Budget list

Throws:

NullArgumentException - activityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsForActivityOnDate

BudgetList getBudgetsForActivityOnDate(Id activityId,
                                     DateTime from,
                                     DateTime to)
                                       throws OperationFailedException,
                                              PermissionDeniedException

Gets a BudgetList for the given activity and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known budgets or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

activityId - an activity Id

from - start of date range

to - end of date range

Returns:

the returned Budget list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - activityId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsForFiscalPeriod

BudgetList getBudgetsForFiscalPeriod(Id fiscalPeriodId)
                                     throws OperationFailedException,
                                            PermissionDeniedException

Gets a BudgetList for the given fiscal period. In plenary mode, the returned list contains all known mode,s or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

fiscalPeriodId - a fiscal period Id

Returns:

the returned Budget list

Throws:

NullArgumentException - fiscalPeriodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsForFiscalPeriodOnDate

BudgetList getBudgetsForFiscalPeriodOnDate(Id fiscalPeriodId,
                                         DateTime from,
                                         DateTime to)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Gets a BudgetList for the given fiscal period and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known budgets or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

fiscalPeriodId - a fiscal period Id

from - start of date range

to - end of date range

Returns:

the returned Budget list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - fiscalPeriodId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsForActivityAndFiscalPeriod

BudgetList getBudgetsForActivityAndFiscalPeriod(Id activityId,
                                              Id fiscalPeriodId)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

Gets a BudgetList for the given activity and fiscal period. In plenary mode, the returned list contains all known mode,s or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

activityId - an activity Id

fiscalPeriodId - a fiscal period Id

Returns:

the returned Budget list

Throws:

NullArgumentException - activityId or fiscalPeriodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgetsForActivityAndFiscalPeriodOnDate

BudgetList getBudgetsForActivityAndFiscalPeriodOnDate(Id activityId,
                                                    Id fiscalPeriodId,
                                                    DateTime from,
                                                    DateTime to)
                                                      throws OperationFailedException,
                                                             PermissionDeniedException

Gets a BudgetList for the given activity, fiscal period, and effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known budgets or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective budgets and those currently expired are returned.

Parameters:

activityId - an activity Id

fiscalPeriodId - a fiscal period Id

from - start of date range

to - end of date range

Returns:

the returned Budget list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - activityId, fiscalPeriodId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBudgets

BudgetList getBudgets()
                      throws OperationFailedException,
                             PermissionDeniedException

Gets all Budgets. In plenary mode, the returned list contains all known budgets or an error results. Otherwise, the returned list may contain only those budgets that are accessible through this session. In effective mode, budgets are returned that are currently effective. In any effective mode, effective budgets and those currently expired are returned.

Returns:

a list of Budgets

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.