org.osid.hold

Interface BlockAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, 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 Summary

Methods

Modifier and Type	Method and Description
void	aliasBlock(Id blockId, Id aliasId) Adds an Id to a Block for the purpose of creating compatibility.
boolean	canCreateBlocks() Tests if this user can create Blocks.
boolean	canCreateBlockWithRecordTypes(Type[] blockRecordTypes) Tests if this user can create a single Block using the desired record types.
boolean	canDeleteBlocks() Tests if this user can delete Blocks.
boolean	canManageBlockAliases() Tests if this user can manage Id aliases for Blocks.
boolean	canUpdateBlocks() Tests if this user can update Blocks.
Block	createBlock(BlockForm blockForm) Creates a new Block.
void	deleteBlock(Id blockId) Deletes a Block.
BlockForm	getBlockFormForCreate(Type[] blockRecordTypes) Gets the block form for creating new blocks.
BlockForm	getBlockFormForUpdate(Id blockId) Gets the block form for updating an existing block.
Oubliette	getOubliette() Gets the Oubliette associated with this session.
Id	getOublietteId() Gets the Oubliette Id associated with this session.
void	updateBlock(BlockForm blockForm) Updates an existing block.

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

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.