OSID Logo
OSID Specifications
acknowledgement package
Version 3.0.0
Release Candidate Preview
Interfaceosid.acknowledgement.CreditLookupSession
Implementsosid.OsidSession
Description

This session defines methods for retrieving credits.

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 billing view: All credit methods in this session operate, retrieve and pertain to credits defined explicitly in the current billing. Using an isolated view is useful for managing credits with the CreditAdminSession.
  • federated billing view: All credit lookup methods in this session operate, retrieve and pertain to all credits defined in this billing and any other billings implicitly available in this billing through billing inheritence.
  • effective credit view: All credit lookup methods return credits where the current date falls in between the effective dates inclusive.
  • any effective credit view: Credits of any effective date are returned from methods.

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

MethodgetBillingId
Description

Gets the Billing Id associated with this session.

Returnosid.id.Idthe Billing Id associated with this session
CompliancemandatoryThis method must be implemented.
MethodgetBilling
Description

Gets the Billing associated with this session.

Returnosid.acknowledgement.Billingthe billing
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanLookupCredits
Description

Tests if this user can examine this billing. 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 opt not to offer these operations.

Returnboolean false if billing reading methods are not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoduseComparativeCreditView
Description

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.

CompliancemandatoryThis method is must be implemented.
MethodusePlenaryCreditView
Description

A complete view of the Credit 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.

CompliancemandatoryThis method is must be implemented.
MethoduseFederatedBillingView
Description

Federates the view for methods in this session. A federated view will include credits in billings which are children of this billing in the billing hierarchy.

CompliancemandatoryThis method is must be implemented.
MethoduseIsolatedBillingView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseEffectiveCreditView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseAnyEffectiveCreditView
Description

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

CompliancemandatoryThis method is must be implemented.
MethodgetCredit
Description

Gets the Credit specified by its Id.

In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Credit may have a different Id than requested, such as the case where a duplicate Id was assigned to a Credit and retained for compatibility.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdcreditIdthe Id of the Credit to retrieve
Returnosid.acknowledgement.Creditthe returned Credit
ErrorsNOT_FOUNDno Credit found with the given Id
NULL_ARGUMENT creditId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByIds
Description

Gets a CreditList corresponding to the given IdList.

In plenary mode, the returned list contains all of the credits 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 credits may be omitted from the list and may present the elements in any order including returning a unique set.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdListcreditIdsthe list of Ids to retrieve
Returnosid.acknowledgement.CreditListthe returned Credit list
ErrorsNOT_FOUNDan Id was not found
NULL_ARGUMENT creditIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByGenusType
Description

Gets a CreditList corresponding to the given credit genus Type which does not include credits of types derived from the specified Type.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.type.TypecreditGenusTypea credits genus type
Returnosid.acknowledgement.CreditListthe returned Credit list
ErrorsNULL_ARGUMENT creditGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByParentGenusType
Description

Gets a CreditList corresponding to the given credit genus Type and include any additional credits with genus types derived from the specified Type.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.type.TypecreditGenusTypea credit genus type
Returnosid.acknowledgement.CreditListthe returned Credit list
ErrorsNULL_ARGUMENT creditGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByRecordType
Description

Gets a CreditList containing the given credit record Type.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.type.TypecreditRecordTypea credit record type
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsNULL_ARGUMENT creditRecordType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsOnDate
Description

Gets a CreditList effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByGenusTypeOnDate
Description

Gets a list of credits of the given genus type and effective entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.type.TypecreditGenusTypea credit genus Type
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT creditGenusType, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsForResource
Description

Gets a CreditList for the given resource Id.

In plenary mode, the returned list contains all of the credits corresponding to the given peer, including duplicates, or an error results if a credit is inaccessible. Otherwise, inaccessible Credits may be omitted from the list.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdresourceIdthe Id of the resource
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsNULL_ARGUMENT resourceId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsForResourceOnDate
Description

Gets a list of credits for a resource 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 credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdresourceIda resource Id
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT resourceId, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByGenusTypeForResource
Description

Gets a list of credits by a genus type for a resource.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdresourceIda resource Id
osid.type.TypecreditGenusTypea credit genus Type
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsNULL_ARGUMENT creditGenusType or resourceId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByGenusTypeForResourceOnDate
Description

Gets a list of credits by genus type for a resource 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 credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdresourceIda resource Id
osid.type.TypecreditGenusTypea credit genus Type
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT resourceId, creditGenusType, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsForReference
Description

Gets a CreditList for the given reference Id.

In plenary mode, the returned list contains all of the credits corresponding to the given peer, including duplicates, or an error results if a credit is inaccessible. Otherwise, inaccessible Credits may be omitted from the list.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdreferenceIda reference Id
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsNULL_ARGUMENT referenceId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsForReferenceOnDate
Description

Gets a list of credits for a reference and effective entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdreferenceIda reference Id
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT referenceId, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByGenusTypeForReference
Description

Gets a list of credits by a genus type for a reference.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdreferenceIda reference Id
osid.type.TypecreditGenusTypea credit genus Type
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsNULL_ARGUMENT referenceId or creditGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByGenusTypeForReferenceOnDate
Description

Gets a list of credits of the given genus type for a reference and effective entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdreferenceIda reference Id
osid.type.TypecreditGenusTypea credit genus Type
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT referenceId, creditGenusType, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsForResourceAndReference
Description

Gets a CreditList for the given resource and reference.

In plenary mode, the returned list contains all of the credits corresponding to the given resource and reference, including duplicates, or an error results if a credit is inaccessible. Otherwise, inaccessible Credits may be omitted from the list.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdresourceIda resource Id
osid.id.IdreferenceIda reference Id
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsNULL_ARGUMENT resourceId or referenceId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsForResourceAndReferenceOnDate
Description

Gets a CreditList corresponding to the given resource and reference and effective entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all of the credits corresponding to the given peer, including duplicates, or an error results if a credit is inaccessible. Otherwise, inaccessible Credits may be omitted from the list.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdresourceIda resource Id
osid.id.IdreferenceIda reference Id
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT resourceId or referenceId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByGenusTypeForResourceAndReference
Description

Gets a CreditList of the given genus type for the given resource and reference.

In plenary mode, the returned list contains all of the credits corresponding to the given resource and reference, including duplicates, or an error results if a credit is inaccessible. Otherwise, inaccessible Credits may be omitted from the list.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdresourceIda resource Id
osid.id.IdreferenceIda reference Id
osid.type.TypecreditGenusTypea credit genus Type
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsNULL_ARGUMENT resourceId, referenceId, or creditGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCreditsByGenusTypeForResourceAndReferenceOnDate
Description

Gets a CreditList of the given genus type corresponding to the given resource and reference and effective entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all of the credits corresponding to the given peer, including duplicates, or an error results if a credit is inaccessible. Otherwise, inaccessible Credits may be omitted from the list.

In effective mode, credits are returned that are currently effective in addition to being effective in the given date range. In any effective mode, effective credits and those currently expired are returned.

Parametersosid.id.IdresourceIda resource Id
osid.id.IdreferenceIda reference Id
osid.type.TypecreditGenusTypea credit genus Type
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.acknowledgement.CreditListthe returned CreditList
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT resourceId, referenceId, creditGenusType, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetCredits
Description

Gets all credits.

In plenary mode, the returned list contains all known credits or an error results. Otherwise, the returned list may contain only those credits that are accessible through this session.

In effective mode, credits are returned that are currently effective. In any effective mode, effective credits and those currently expired are returned.

Returnosid.acknowledgement.CreditLista list of credits
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.