Interface AddressAdminSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
All Known Subinterfaces:
AddressBatchAdminSession
public interface AddressAdminSession extends OsidSession

This session creates, updates, and deletes Addresses . The data for create and update is provided by the consumer via the form object. OsidForms are requested for each create or update and may not be reused.

Create and update operations differ in their usage. To create an Address , an AddressForm is requested using getAddressFormForCreate() specifying the desired relationship peers and record Types or none if no record Types are needed. The returned AddressForm will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the AddressForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each AddressForm corresponds to an attempted transaction.

For updates, AddressForms are requested to the Address Id that is to be updated using getAddressFormForUpdate() . Similarly, the AddressForm has metadata about the data that can be updated and it can perform validation before submitting the update. The AddressForm can only be used once for a successful update and cannot be reused.

The delete operations delete Addresses . To unmap an Address from the current AddressBook , the AddressAddressBookAssignmentSession should be used. These delete operations attempt to remove the Address itself thus removing it from all known AddressBook catalogs.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

  • Method Details

    • getAddressBookId

      Id getAddressBookId()
      Gets the AddressBook Id associated with this session.
      Returns:
      the AddressBook Id associated with this session
      Compliance:
      mandatory - This method must be implemented.

    • getAddressBook

      AddressBook getAddressBook() throws OperationFailedException, PermissionDeniedException
      Gets the AddressBook associated with this session.
      Returns:
      the address book
      Throws:
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canCreateAddresses

      boolean canCreateAddresses()
      Tests if this user can create Addresses . A return of true does not guarantee successful authorization. A return of false indicates that it is known creating an Address will result in a PERMISSION_DENIED . This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.
      Returns:
      false if Address creation is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • canCreateAddressWithRecordTypes

      boolean canCreateAddressWithRecordTypes(Type[] addressRecordTypes)
      Tests if this user can create a single Address using the desired record types. While ContactManager.getAddressRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Address . Providing an empty array tests if an Address can be created with no records.
      Parameters:
      addressRecordTypes - array of address record types
      Returns:
      true if Address creation using the specified record Types is supported, false otherwise
      Throws:
      NullArgumentException - addressRecordTypes is null
      Compliance:
      mandatory - This method must be implemented.

    • getAddressFormForCreate

      AddressForm getAddressFormForCreate(Type[] addressRecordTypes) throws OperationFailedException, PermissionDeniedException
      Gets the address form for creating new addresses. A new form should be requested for each create transaction.
      Parameters:
      addressRecordTypes - array of address record types
      Returns:
      the address form
      Throws:
      NullArgumentException - addressRecordTypes is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - unable to get form for requested record types
      Compliance:
      mandatory - This method must be implemented.

    • createAddress

      Address createAddress(AddressForm addressForm) throws OperationFailedException, PermissionDeniedException
      Creates a new Address .
      Parameters:
      addressForm - the form for this Address
      Returns:
      the new Address
      Throws:
      IllegalStateException - addressForm already used in a create transaction
      InvalidArgumentException - one or more of the form elements is invalid
      NullArgumentException - addressForm is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - addressForm did not originate from getAddressFormForCreate()
      Compliance:
      mandatory - This method must be implemented.

    • canUpdateAddresses

      boolean canUpdateAddresses()
      Tests if this user can update Addresses . A return of true does not guarantee successful authorization. A return of false indicates that it is known updating an Address will result in a PERMISSION_DENIED . This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.
      Returns:
      false if Address modification is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • getAddressFormForUpdate

      AddressForm getAddressFormForUpdate(Id addressId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the address form for updating an existing address. A new address form should be requested for each update transaction.
      Parameters:
      addressId - the Id of the Address
      Returns:
      the address form
      Throws:
      NotFoundException - addressId is not found
      NullArgumentException - addressId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • updateAddress

      void updateAddress(AddressForm addressForm) throws OperationFailedException, PermissionDeniedException
      Updates an existing address.
      Parameters:
      addressForm - the form containing the elements to be updated
      Throws:
      IllegalStateException - addressForm already used in an update transaction
      InvalidArgumentException - the form contains an invalid value
      NullArgumentException - addressId or addressForm is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - addressForm did not originate from getAddressFormForUpdate()
      Compliance:
      mandatory - This method must be implemented.

    • canDeleteAddresses

      boolean canDeleteAddresses()
      Tests if this user can delete Addresses A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an Address will result in a PERMISSION_DENIED . This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.
      Returns:
      false if Address deletion is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • deleteAddress

      void deleteAddress(Id addressId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Deletes an Address .
      Parameters:
      addressId - the Id of the Address to remove
      Throws:
      NotFoundException - addressId not found
      NullArgumentException - addressId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canManageAddressAliases

      boolean canManageAddressAliases()
      Tests if this user can manage Id aliases for Addresses . A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.
      Returns:
      false if Address aliasing is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • aliasAddress

      void aliasAddress(Id addressId, Id aliasId) throws AlreadyExistsException, NotFoundException, OperationFailedException, PermissionDeniedException
      Adds an Id to an Address for the purpose of creating compatibility. The primary Id of the Address is determined by the provider. The new Id performs as an alias to the primary Id . If the alias is a pointer to another address, it is reassigned to the given address Id .
      Parameters:
      addressId - the Id of an Address
      aliasId - the alias Id
      Throws:
      AlreadyExistsException - aliasId is already assigned
      NotFoundException - addressId not found
      NullArgumentException - addressId or aliasId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.