org.osid.billing

Interface CustomerLookupSession

All Superinterfaces:

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

public interface CustomerLookupSession
extends OsidSession

This session defines methods for retrieving customers. A Customer is a Resource related to the billing system.

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 customer methods in this session operate, retrieve and pertain to customers defined explicitly in the current business. Using an isolated view is useful for managing Customers with the CustomerAdminSession.
• federated business view: All customer lookup methods in this session operate, retrieve and pertain to all customers defined in this business and any other customers implicitly available in this business through business inheritence.
• effective customer view: All customer lookup methods return customers where the current date falls in between the effective dates inclusive.
• any effective customer view: Customers 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.

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

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupCustomers() Tests if this user can perform Customer lookups.
Business	getBusiness() Gets the Business associated with this session.
Id	getBusinessId() Gets the Business Id associated with this session.
Customer	getCustomer(Id customerId) Gets the Customer specified by its Id.
CustomerList	getCustomers() Gets all Customers.
CustomerList	getCustomersByActivity(Id activityId) Gets a CustomerList having the given activity.
CustomerList	getCustomersByGenusType(Type customerGenusType) Gets a CustomerList corresponding to the given customer genus Type which does not include customers of types derived from the specified Type.
CustomerList	getCustomersByIds(IdList customerIds) Gets a CustomerList corresponding to the given IdList.
CustomerList	getCustomersByNumber(java.lang.String number) Gets a CustomerList related to the given customer number.
CustomerList	getCustomersByParentGenusType(Type customerGenusType) Gets a CustomerList corresponding to the given customer genus Type and include any additional customers with genus types derived from the specified Type.
CustomerList	getCustomersByRecordType(Type customerRecordType) Gets a CustomerList containing the given customer record Type.
CustomerList	getCustomersByResource(Id resourceId) Gets a CustomerList related to the given resource .
CustomerList	getCustomersByResourceOnDate(Id resourceId, DateTime from, DateTime to) Gets a CustomerList of the given resource and effective during the entire given date range inclusive but not confined to the date range.
CustomerList	getCustomersOnDate(DateTime from, DateTime to) Gets a CustomerList effective during the entire given date range inclusive but not confined to the date range.
void	useAnyEffectiveCustomerView() All customers of any effective dates are returned by methods in this session.
void	useComparativeCustomerView() 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	useEffectiveCustomerView() Only customers 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	usePlenaryCustomerView() A complete view of the Customer 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.

canLookupCustomers

boolean canLookupCustomers()

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

useComparativeCustomerView

void useComparativeCustomerView()

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.

usePlenaryCustomerView

void usePlenaryCustomerView()

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

useEffectiveCustomerView

void useEffectiveCustomerView()

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

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveCustomerView

void useAnyEffectiveCustomerView()

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

Compliance:

mandatory - This method is must be implemented.

getCustomer

Customer getCustomer(Id customerId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

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

Parameters:

customerId - the Id of the Customer to retrieve

Returns:

the returned Customer

Throws:

NotFoundException - no Customer found with the given Id

NullArgumentException - customerId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCustomersByIds

CustomerList getCustomersByIds(IdList customerIds)
                               throws NotFoundException,
                                      OperationFailedException,
                                      PermissionDeniedException

Gets a CustomerList corresponding to the given IdList. In plenary mode, the returned list contains all of the customers 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 Customers may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, customers are returned that are currently effective. In any effective mode, effective customers and those currently expired are returned.

Parameters:

customerIds - the list of Ids to retrieve

Returns:

the returned CustomerList list

Throws:

NotFoundException - an Id was not found

NullArgumentException - customerIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCustomersByGenusType

CustomerList getCustomersByGenusType(Type customerGenusType)
                                     throws OperationFailedException,
                                            PermissionDeniedException

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

Parameters:

customerGenusType - a customer genus type

Returns:

the returned CustomerList list

Throws:

NullArgumentException - customerGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCustomersByParentGenusType

CustomerList getCustomersByParentGenusType(Type customerGenusType)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

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

Parameters:

customerGenusType - a customer genus type

Returns:

the returned CustomerList list

Throws:

NullArgumentException - customerGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCustomersByRecordType

CustomerList getCustomersByRecordType(Type customerRecordType)
                                      throws OperationFailedException,
                                             PermissionDeniedException

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

Parameters:

customerRecordType - a customer record type

Returns:

the returned CustomerList list

Throws:

NullArgumentException - customerRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCustomersOnDate

CustomerList getCustomersOnDate(DateTime from,
                              DateTime to)
                                throws OperationFailedException,
                                       PermissionDeniedException

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

Parameters:

from - starting date

to - ending date

Returns:

the returned CustomerList 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.

getCustomersByNumber

CustomerList getCustomersByNumber(java.lang.String number)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets a CustomerList related to the given customer number. In plenary mode, the returned list contains all known customers or an error results. Otherwise, the returned list may contain only those customers that are accessible through this session. In effective mode, customers are returned that are currently effective. In any effective mode, effective customers and those currently expired are returned.

Parameters:

number - a customer number

Returns:

the returned CustomerList list

Throws:

NullArgumentException - number is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCustomersByResource

CustomerList getCustomersByResource(Id resourceId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a CustomerList related to the given resource . In plenary mode, the returned list contains all known customers or an error results. Otherwise, the returned list may contain only those customers that are accessible through this session. In effective mode, customers are returned that are currently effective. In any effective mode, effective customers and those currently expired are returned.

Parameters:

resourceId - a resource Id

Returns:

the returned CustomerList list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCustomersByResourceOnDate

CustomerList getCustomersByResourceOnDate(Id resourceId,
                                        DateTime from,
                                        DateTime to)
                                          throws OperationFailedException,
                                                 PermissionDeniedException

Gets a CustomerList of the given 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 customers or an error results. Otherwise, the returned list may contain only those customers that are accessible through this session. In effective mode, customers are returned that are currently effective in addition to being effective during the given date range. In any effective mode, effective customers and those currently expired are returned.

Parameters:

resourceId - a resource Id

from - starting date

to - ending date

Returns:

the returned CustomerList list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCustomersByActivity

CustomerList getCustomersByActivity(Id activityId)
                                    throws OperationFailedException,
                                           PermissionDeniedException

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

Parameters:

activityId - an activity Id

Returns:

the returned CustomerList list

Throws:

NullArgumentException - activityId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getCustomers

CustomerList getCustomers()
                          throws OperationFailedException,
                                 PermissionDeniedException

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

Returns:

a list of Customers

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.