Interface CustomerLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

    • 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(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.