Interface EngineAdminSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 . This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

  • Method Details

    • 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 types. While SearchManager.getEngineRecordTypes() can be used to examine which records 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 a form with given 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 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:
      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 - engineId or 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.