Interface AddressBookLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
public interface AddressBookLookupSession extends OsidSession

This session provides methods for retrieving AddressBooks . The AddressBook represents a collection of contacts.

This session defines views that offer differing behaviors when retrieving multiple objects.

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete set or is an error condition

  • Method Details

    • canLookupAddressBooks

      boolean canLookupAddressBooks()
      Tests if this user can perform AddressBook 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.

    • useComparativeAddressBookView

      void useComparativeAddressBookView()
      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.

    • usePlenaryAddressBookView

      void usePlenaryAddressBookView()
      A complete view of the AddressBook 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.

    • getAddressBook

      AddressBook getAddressBook(Id jouralId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the AddressBook specified by its Id . In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned AddressBook may have a different Id than requested, such as the case where a duplicate Id was assigned to an AddressBook and retained for compatibility.
      Parameters:
      jouralId - Id of the AddressBook
      Returns:
      the address book
      Throws:
      NotFoundException - addressBookId not found
      NullArgumentException - addressBookId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method is must be implemented.

    • getAddressBooksByIds

      AddressBookList getAddressBooksByIds(IdList addressBookIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets an AddressBookList corresponding to the given IdList .In plenary mode, the returned list contains all of the address books 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 AddressBooks may be omitted from the list and may present the elements in any order including returning a unique set.
      Parameters:
      addressBookIds - the list of Ids to retrieve
      Returns:
      the returned AddressBook list
      Throws:
      NotFoundException - an Id was not found
      NullArgumentException - addressBookIds is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAddressBooksByGenusType

      AddressBookList getAddressBooksByGenusType(Type addressBookGenusType) throws OperationFailedException, PermissionDeniedException
      Gets an AddressBookList corresponding to the given address book genus Type which does not include address books of genus types derived from the specified Type . In plenary mode, the returned list contains all known address books or an error results. Otherwise, the returned list may contain only those address books that are accessible through this session.
      Parameters:
      addressBookGenusType - an address book genus type
      Returns:
      the returned AddressBook list
      Throws:
      NullArgumentException - addressBookGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAddressBooksByParentGenusType

      AddressBookList getAddressBooksByParentGenusType(Type addressBookGenusType) throws OperationFailedException, PermissionDeniedException
      Gets an AddressBookList corresponding to the given address book genus Type and include any additional address books with genus types derived from the specified Type . In plenary mode, the returned list contains all known address books or an error results. Otherwise, the returned list may contain only those address books that are accessible through this session.
      Parameters:
      addressBookGenusType - an address book genus type
      Returns:
      the returned AddressBook list
      Throws:
      NullArgumentException - addressBookGenusType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAddressBooksByRecordType

      AddressBookList getAddressBooksByRecordType(Type addressBookRecordType) throws OperationFailedException, PermissionDeniedException
      Gets an AddressBookList containing the given address book record Type .In plenary mode, the returned list contains all known address books or an error results. Otherwise, the returned list may contain only those address books that are accessible through this session.
      Parameters:
      addressBookRecordType - an address book record type
      Returns:
      the returned AddressBook list
      Throws:
      NullArgumentException - addressBookRecordType is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAddressBooksByProvider

      AddressBookList getAddressBooksByProvider(Id resourceId) throws OperationFailedException, PermissionDeniedException
      Gets an AddressBookList from the given provider. In plenary mode, the returned list contains all known address books or an error results. Otherwise, the returned list may contain only those address books that are accessible through this session.
      Parameters:
      resourceId - a resource Id
      Returns:
      the returned AddressBook list
      Throws:
      NullArgumentException - resourceId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • getAddressBooks

      AddressBookList getAddressBooks() throws OperationFailedException, PermissionDeniedException
      Gets all AddressBooks . In plenary mode, the returned list contains all known address books or an error results. Otherwise, the returned list may contain only those address books that are accessible through this session.
      Returns:
      a list of AddressBooks
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.