org.osid.control

Interface SettingAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

SettingBatchAdminSession

public interface SettingAdminSession
extends OsidSession

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

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

The delete operations delete Settings. To unmap a Setting from the current System, the SettingSystemAssignmentSession should be used. These delete operations attempt to remove the Setting 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	aliasSetting(Id settingId, Id aliasId) Adds an Id to a Setting for the purpose of creating compatibility.
boolean	canCreateSettings() Tests if this user can create settings.
boolean	canCreateSettingWithRecordTypes(Type[] settingRecordTypes) Tests if this user can create a single Setting using the desired record types.
boolean	canDeleteSettings() Tests if this user can delete settings.
boolean	canManageSettingAliases() Tests if this user can manage Id aliases for Settings.
boolean	canUpdateSettings() Tests if this user can update settings.
Setting	createSetting(SettingForm settingForm) Creates a new Setting.
void	deleteSetting(Id settingId) Deletes a Setting.
SettingForm	getSettingFormForCreate(Id controllerId, Type[] settingRecordTypes) Gets the setting form for creating new settings.
SettingForm	getSettingFormForUpdate(Id settingId) Gets the setting form for updating an existing setting.
System	getSystem() Gets the System associated with this session.
Id	getSystemId() Gets the System Id associated with this session.
void	updateSetting(SettingForm settingForm) Updates an existing setting.

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.

canCreateSettings

boolean canCreateSettings()

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

Compliance:

mandatory - This method must be implemented.

canCreateSettingWithRecordTypes

boolean canCreateSettingWithRecordTypes(Type[] settingRecordTypes)

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

Parameters:

settingRecordTypes - array of setting record types

Returns:

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

Throws:

NullArgumentException - settingRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getSettingFormForCreate

SettingForm getSettingFormForCreate(Id controllerId,
                                  Type[] settingRecordTypes)
                                    throws NotFoundException,
                                           OperationFailedException,
                                           PermissionDeniedException

Gets the setting form for creating new settings. A new form should be requested for each create transaction.

Parameters:

controllerId - the Id for the controller

settingRecordTypes - array of setting record types

Returns:

the setting form

Throws:

NotFoundException - controllerId is not found

NullArgumentException - controllerId 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.

createSetting

Setting createSetting(SettingForm settingForm)
                      throws NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Creates a new Setting.

Parameters:

settingForm - the form for this Setting

Returns:

the new Setting

Throws:

IllegalStateException - settingForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NotFoundException - resourceId or inputId is not found

NullArgumentException - settingForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - settingForm did not originate from getSettingFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateSettings

boolean canUpdateSettings()

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

Compliance:

mandatory - This method must be implemented.

getSettingFormForUpdate

SettingForm getSettingFormForUpdate(Id settingId)
                                    throws NotFoundException,
                                           OperationFailedException,
                                           PermissionDeniedException

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

Parameters:

settingId - the Id of the Setting

Returns:

the setting form

Throws:

NotFoundException - settingId is not found

NullArgumentException - settingId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateSetting

void updateSetting(SettingForm settingForm)
                   throws OperationFailedException,
                          PermissionDeniedException

Updates an existing setting.

Parameters:

settingForm - the form containing the elements to be updated

Throws:

IllegalStateException - settingForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - settingForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - settingForm did not originate from getSettingFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteSettings

boolean canDeleteSettings()

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

Compliance:

mandatory - This method must be implemented.

deleteSetting

void deleteSetting(Id settingId)
                   throws NotFoundException,
                          OperationFailedException,
                          PermissionDeniedException

Deletes a Setting.

Parameters:

settingId - the Id of the Setting to remove

Throws:

NotFoundException - settingId not found

NullArgumentException - settingId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageSettingAliases

boolean canManageSettingAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasSetting

void aliasSetting(Id settingId,
                Id aliasId)
                  throws AlreadyExistsException,
                         NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

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

Parameters:

settingId - the Id of a Setting

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - settingId not found

NullArgumentException - settingId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.