org.osid.control

Interface InputAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

InputBatchAdminSession

public interface InputAdminSession
extends OsidSession

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

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

The delete operations delete Inputs. To unmap a Input from the current System, the InputSystemAssignmentSession should be used. These delete operations attempt to remove the Input itself thus removing it from all known System 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	aliasInput(Id inputId, Id aliasId) Adds an Id to a Input for the purpose of creating compatibility.
boolean	canCreateInputs() Tests if this user can create Inputs.
boolean	canCreateInputWithRecordTypes(Type[] inputRecordTypes) Tests if this user can create a single Input using the desired record types.
boolean	canDeleteInputs() Tests if this user can delete Inputs.
boolean	canManageInputAliases() Tests if this user can manage Id aliases for Inputs.
boolean	canUpdateInputs() Tests if this user can update Inputs.
Input	createInput(InputForm inputForm) Creates a new Input.
void	deleteInput(Id inputId) Deletes a Input.
InputForm	getInputFormForCreate(Id deviceId, Id controllerId, Type[] inputRecordTypes) Gets the input form for creating new inputs.
InputForm	getInputFormForUpdate(Id inputId) Gets the input form for updating an existing input.
System	getSystem() Gets the System associated with this session.
Id	getSystemId() Gets the System Id associated with this session.
void	updateInput(InputForm inputForm) Updates an existing input.

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

getSystemId

Id getSystemId()

Gets the System Id associated with this session.

Returns:

the System Id associated with this session

Compliance:

mandatory - This method must be implemented.

getSystem

System getSystem()
                 throws OperationFailedException,
                        PermissionDeniedException

Gets the System associated with this session.

Returns:

the system

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateInputs

boolean canCreateInputs()

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

Compliance:

mandatory - This method must be implemented.

canCreateInputWithRecordTypes

boolean canCreateInputWithRecordTypes(Type[] inputRecordTypes)

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

Parameters:

inputRecordTypes - array of input record types

Returns:

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

Throws:

NullArgumentException - inputRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getInputFormForCreate

InputForm getInputFormForCreate(Id deviceId,
                              Id controllerId,
                              Type[] inputRecordTypes)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

Gets the input form for creating new inputs. A new form should be requested for each create transaction.

Parameters:

deviceId - a device Id

controllerId - a controller Id

inputRecordTypes - array of input record types

Returns:

the input form

Throws:

NotFoundException - deviceId or controllerId is not found

NullArgumentException - deviceId, controllerId, or inputRecordTypes 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.

createInput

Input createInput(InputForm inputForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Creates a new Input.

Parameters:

inputForm - the form for this Input

Returns:

the new Input

Throws:

IllegalStateException - inputForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - inputForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - inputForm did not originate from getInputFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateInputs

boolean canUpdateInputs()

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

Compliance:

mandatory - This method must be implemented.

getInputFormForUpdate

InputForm getInputFormForUpdate(Id inputId)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

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

Parameters:

inputId - the Id of the Input

Returns:

the input form

Throws:

NotFoundException - inputId is not found

NullArgumentException - inputId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateInput

void updateInput(InputForm inputForm)
                 throws OperationFailedException,
                        PermissionDeniedException

Updates an existing input.

Parameters:

inputForm - the form containing the elements to be updated

Throws:

IllegalStateException - inputForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - inputForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - inputForm did not originate from getInputFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteInputs

boolean canDeleteInputs()

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

Compliance:

mandatory - This method must be implemented.

deleteInput

void deleteInput(Id inputId)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Deletes a Input.

Parameters:

inputId - the Id of the Input to remove

Throws:

NotFoundException - inputId not found

NullArgumentException - inputId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageInputAliases

boolean canManageInputAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasInput

void aliasInput(Id inputId,
              Id aliasId)
                throws AlreadyExistsException,
                       NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

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

Parameters:

inputId - the Id of a Input

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - inputId not found

NullArgumentException - inputId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.