org.osid.rules

Interface EngineAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

public interface EngineAdminSession
extends OsidSession

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

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

The delete operations delete Engines. It is safer to remove all mappings to the Engine catalogs before deletion.

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	aliasEngine(Id engineId, Id aliasId) Adds an Id to an Engine for the purpose of creating compatibility.
boolean	canCreateEngines() Tests if this user can create Engines.
boolean	canCreateEngineWithRecordTypes(Type[] engineRecordTypes) Tests if this user can create a single Engine using the desired record interface types.
boolean	canDeleteEngines() Tests if this user can delete Engines.
boolean	canManageEngineAliases() Tests if this user can manage Id aliases for Engines.
boolean	canUpdateEngines() Tests if this user can update Engines.
Engine	createEngine(EngineForm engineForm) Creates a new Engine.
void	deleteEngine(Id engineId) Deletes an Engine.
EngineForm	getEngineFormForCreate(Type[] engineRecordTypes) Gets the engine form for creating new engines.
EngineForm	getEngineFormForUpdate(Id engineId) Gets the engine form for updating an existing engine.
void	updateEngine(EngineForm engineForm) Updates an existing engine.

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

canCreateEngines

boolean canCreateEngines()

Tests if this user can create Engines. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating an Engine 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 Engine creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateEngineWithRecordTypes

boolean canCreateEngineWithRecordTypes(Type[] engineRecordTypes)

Tests if this user can create a single Engine using the desired record interface types. While RulesManager.getEngineRecordTypes() can be used to examine which record interfaces are supported, this method tests which record(s) are required for creating a specific Engine. Providing an empty array tests if an Engine can be created with no records.

Parameters:

engineRecordTypes - array of engine record types

Returns:

true if Engine creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - engineRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getEngineFormForCreate

EngineForm getEngineFormForCreate(Type[] engineRecordTypes)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets the engine form for creating new engines. A new form should be requested for each create transaction.

Parameters:

engineRecordTypes - array of engine record types

Returns:

the engine form

Throws:

NullArgumentException - engineRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form with requested record types

Compliance:

mandatory - This method must be implemented.

createEngine

Engine createEngine(EngineForm engineForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Creates a new Engine.

Parameters:

engineForm - the form for this Engine

Returns:

the new Engine

Throws:

IllegalStateException - engineForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - engineForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - engineForm did not originate from getEngineFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateEngines

boolean canUpdateEngines()

Tests if this user can update Engines. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating an Engine 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 Engine modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getEngineFormForUpdate

EngineForm getEngineFormForUpdate(Id engineId)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Gets the engine form for updating an existing engine. A new engine form should be requested for each update transaction.

Parameters:

engineId - the Id of the Engine

Returns:

the engine form

Throws:

NotFoundException - engineId is not found

NullArgumentException - engineId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateEngine

void updateEngine(EngineForm engineForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Updates an existing engine.

Parameters:

engineForm - the form containing the elements to be updated

Throws:

IllegalStateException - engineForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - engineForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - engineForm did not originate from getEngineFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteEngines

boolean canDeleteEngines()

Tests if this user can delete Engines. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an Engine 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 Engine deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteEngine

void deleteEngine(Id engineId)
                  throws NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Deletes an Engine.

Parameters:

engineId - the Id of the Engine to remove

Throws:

NotFoundException - engineId not found

NullArgumentException - engineId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageEngineAliases

boolean canManageEngineAliases()

Tests if this user can manage Id aliases for Engines. 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 Engine aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasEngine

void aliasEngine(Id engineId,
               Id aliasId)
                 throws AlreadyExistsException,
                        NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Adds an Id to an Engine for the purpose of creating compatibility. The primary Id of the Engine is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another engine it is reassigned to the given engine Id.

Parameters:

engineId - the Id of an Engine

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - engineId not found

NullArgumentException - engineId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.