Interface BlockAdminSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
All Known Subinterfaces:
BlockBatchAdminSession
public interface BlockAdminSession extends OsidSession

This session creates, updates, and deletes Blocks . 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 a Block , a BlockForm is requested using getBlockFormForCreate() specifying the desired relationship peers and record Types or none if no record Types are needed. The returned BlockForm 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 BlockForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each BlockForm corresponds to an attempted transaction.

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

The delete operations delete Blocks . To unmap a Block from the current Oubliette , the BlockOublietteAssignmentSession should be used. These delete operations attempt to remove the Block itself thus removing it from all known Oubliette catalogs.

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

  • Method Details

    • getOublietteId

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

    • getOubliette

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

    • canCreateBlocks

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

    • canCreateBlockWithRecordTypes

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

    • getBlockFormForCreate

      BlockForm getBlockFormForCreate(Type[] blockRecordTypes) throws OperationFailedException, PermissionDeniedException
      Gets the block form for creating new blocks. A new form should be requested for each create transaction.
      Parameters:
      blockRecordTypes - array of block record types
      Returns:
      the block form
      Throws:
      NullArgumentException - blockRecordTypes 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.

    • createBlock

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

    • canUpdateBlocks

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

    • getBlockFormForUpdate

      BlockForm getBlockFormForUpdate(Id blockId) throws NotFoundException, OperationFailedException
      Gets the block form for updating an existing block. A new block form should be requested for each update transaction.
      Parameters:
      blockId - the Id of the Block
      Returns:
      the block form
      Throws:
      NotFoundException - blockId is not found
      NullArgumentException - blockId is null
      OperationFailedException - unable to complete request
      Compliance:
      mandatory - This method must be implemented.

    • updateBlock

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

    • canDeleteBlocks

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

    • deleteBlock

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

    • canManageBlockAliases

      boolean canManageBlockAliases()
      Tests if this user can manage Id aliases for Blocks . 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 Block aliasing is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • aliasBlock

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