org.osid.billing.payment

Interface PaymentLookupSession

All Superinterfaces:

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

public interface PaymentLookupSession
extends OsidSession

This session defines methods for retrieving payments.

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 payment methods in this session operate, retrieve and pertain to payments defined explicitly in the current business. Using an isolated view is useful for managing Payments with the PaymentAdminSession.
• federated business view: All payment lookup methods in this session operate, retrieve and pertain to all payments defined in this business and any other payments implicitly available in this business through business inheritence.

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

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupPayments() Tests if this user can perform Payment lookups.
Business	getBusiness() Gets the Business associated with this session.
Id	getBusinessId() Gets the Business Id associated with this session.
Payment	getPayment(Id paymentId) Gets the Payment specified by its Id.
PaymentList	getPayments() Gets all Payments.
PaymentList	getPaymentsByGenusType(Type paymentGenusType) Gets a PaymentList corresponding to the given payment genus Type which does not include payments of types derived from the specified Type.
PaymentList	getPaymentsByIds(IdList paymentIds) Gets a PaymentList corresponding to the given IdList.
PaymentList	getPaymentsByParentGenusType(Type paymentGenusType) Gets a PaymentList corresponding to the given payment genus Type and include any additional payments with genus types derived from the specified Type.
PaymentList	getPaymentsByPeriod(Id periodId) Gets a PaymentList in the given period.
PaymentList	getPaymentsByPeriodForCustomer(Id customerId, Id periodId) Gets a PaymentList for the given customer and billing period.
PaymentList	getPaymentsByPeriodForPayer(Id payerId, Id periodId) Gets a PaymentList for the given payer in a billing period.
PaymentList	getPaymentsByPeriodForPayerAndCustomer(Id payerId, Id customerId, Id periodId) Gets a PaymentList for the given payer and customer in a billing period.
PaymentList	getPaymentsByRecordType(Type paymentRecordType) Gets a PaymentList containing the given payment record Type.
PaymentList	getPaymentsForCustomer(Id customerId) Gets a PaymentList for the given customer.
PaymentList	getPaymentsForCustomerOnDate(Id customerId, DateTime from, DateTime to) Gets a PaymentList for the given customer made within the given date range inclusive.
PaymentList	getPaymentsForPayer(Id payerId) Gets a PaymentList for the given payer.
PaymentList	getPaymentsForPayerAndCustomer(Id payerId, Id customerId) Gets a PaymentList for the given payer and customer.
PaymentList	getPaymentsForPayerAndCustomerOnDate(Id payerId, Id customerId, DateTime from, DateTime to) Gets a PaymentList for the given customer and payer made within the given date range inclusive.
PaymentList	getPaymentsForPayerOnDate(Id payerId, DateTime from, DateTime to) Gets a PaymentList for the given payer made within the given date range inclusive.
void	useComparativePaymentView() 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	useFederatedBusinessView() Federates the view for methods in this session.
void	useIsolatedBusinessView() Isolates the view for methods in this session.
void	usePlenaryPaymentView() A complete view of the Payment 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.

canLookupPayments

boolean canLookupPayments()

Tests if this user can perform Payment 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.

useComparativePaymentView

void useComparativePaymentView()

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.

usePlenaryPaymentView

void usePlenaryPaymentView()

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

getPayment

Payment getPayment(Id paymentId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

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

Parameters:

paymentId - the Id of the Payment to retrieve

Returns:

the returned Payment

Throws:

NotFoundException - no Payment found with the given Id

NullArgumentException - paymentId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsByIds

PaymentList getPaymentsByIds(IdList paymentIds)
                             throws NotFoundException,
                                    OperationFailedException,
                                    PermissionDeniedException

Gets a PaymentList corresponding to the given IdList. In plenary mode, the returned list contains all of the payments 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 Payments may be omitted from the list and may present the elements in any order including returning a unique set.

Parameters:

paymentIds - the list of Ids to retrieve

Returns:

the returned Payment list

Throws:

NotFoundException - an Id was not found

NullArgumentException - paymentIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsByGenusType

PaymentList getPaymentsByGenusType(Type paymentGenusType)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets a PaymentList corresponding to the given payment genus Type which does not include payments of types derived from the specified Type. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

paymentGenusType - a payment genus type

Returns:

the returned Payment list

Throws:

NullArgumentException - paymentGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsByParentGenusType

PaymentList getPaymentsByParentGenusType(Type paymentGenusType)
                                         throws OperationFailedException,
                                                PermissionDeniedException

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

Parameters:

paymentGenusType - a payment genus type

Returns:

the returned Payment list

Throws:

NullArgumentException - paymentGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsByRecordType

PaymentList getPaymentsByRecordType(Type paymentRecordType)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a PaymentList containing the given payment record Type. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

paymentRecordType - a payment record type

Returns:

the returned Payment list

Throws:

NullArgumentException - paymentRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsByPeriod

PaymentList getPaymentsByPeriod(Id periodId)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets a PaymentList in the given period. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

periodId - a period Id

Returns:

the returned Payment list

Throws:

NullArgumentException - periodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsForPayer

PaymentList getPaymentsForPayer(Id payerId)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets a PaymentList for the given payer. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

payerId - a payer Id

Returns:

the returned Payment list

Throws:

NullArgumentException - payerId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsByPeriodForPayer

PaymentList getPaymentsByPeriodForPayer(Id payerId,
                                      Id periodId)
                                        throws OperationFailedException,
                                               PermissionDeniedException

Gets a PaymentList for the given payer in a billing period. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

payerId - a payer Id

periodId - a period Id

Returns:

the returned Payment list

Throws:

NullArgumentException - payerId or periodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsForPayerOnDate

PaymentList getPaymentsForPayerOnDate(Id payerId,
                                    DateTime from,
                                    DateTime to)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Gets a PaymentList for the given payer made within the given date range inclusive. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

payerId - a payer Id

from - start of date range

to - end of date range

Returns:

the returned Payment list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - payerId or periodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsForCustomer

PaymentList getPaymentsForCustomer(Id customerId)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets a PaymentList for the given customer. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

customerId - a customer Id

Returns:

the returned Payment list

Throws:

NullArgumentException - customerId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsByPeriodForCustomer

PaymentList getPaymentsByPeriodForCustomer(Id customerId,
                                         Id periodId)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Gets a PaymentList for the given customer and billing period. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

customerId - a customer Id

periodId - a period Id

Returns:

the returned Payment list

Throws:

NullArgumentException - customerId or periodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsForCustomerOnDate

PaymentList getPaymentsForCustomerOnDate(Id customerId,
                                       DateTime from,
                                       DateTime to)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets a PaymentList for the given customer made within the given date range inclusive. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

customerId - a customer Id

from - start of date range

to - end of date range

Returns:

the returned Payment list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - customerId or periodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsForPayerAndCustomer

PaymentList getPaymentsForPayerAndCustomer(Id payerId,
                                         Id customerId)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

Gets a PaymentList for the given payer and customer. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

payerId - a payer Id

customerId - a customerId Id

Returns:

the returned Payment list

Throws:

NullArgumentException - payerId or customerId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsByPeriodForPayerAndCustomer

PaymentList getPaymentsByPeriodForPayerAndCustomer(Id payerId,
                                                 Id customerId,
                                                 Id periodId)
                                                   throws OperationFailedException,
                                                          PermissionDeniedException

Gets a PaymentList for the given payer and customer in a billing period. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

payerId - a payer Id

customerId - a customerId Id

periodId - a period Id

Returns:

the returned Payment list

Throws:

NullArgumentException - payerId, customerId, or periodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPaymentsForPayerAndCustomerOnDate

PaymentList getPaymentsForPayerAndCustomerOnDate(Id payerId,
                                               Id customerId,
                                               DateTime from,
                                               DateTime to)
                                                 throws OperationFailedException,
                                                        PermissionDeniedException

Gets a PaymentList for the given customer and payer made within the given date range inclusive. In plenary mode, the returned list contains all known payments or an error results. Otherwise, the returned list may contain only those payments that are accessible through this session.

Parameters:

payerId - a payer Id

customerId - a customerId Id

from - start of date range

to - end of date range

Returns:

the returned Payment list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - payerId, customerId, or periodId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getPayments

PaymentList getPayments()
                        throws OperationFailedException,
                               PermissionDeniedException

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

Returns:

a list of Payments

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.