org.osid.control

Interface ActionGroupAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

ActionGroupBatchAdminSession

public interface ActionGroupAdminSession
extends OsidSession

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

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

The delete operations delete ActionGroups. To unmap an ActionGroup from the current System, the ActionGroupSystemAssignmentSession should be used. These delete operations attempt to remove the ActionGroup 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	aliasAction(Id actionId, Id aliasId) Adds an Id to an Action for the purpose of creating compatibility.
void	aliasActionGroup(Id actionGroupId, Id aliasId) Adds an Id to an ActionGroup for the purpose of creating compatibility.
boolean	canCreateActionGroups() Tests if this user can create ActionGroups.
boolean	canCreateActionGroupWithRecordTypes(Type[] actionGroupRecordTypes) Tests if this user can create a single ActionGroup using the desired record types.
boolean	canCreateActionWithRecordTypes(Type[] actionRecordTypes) Tests if this user can create a single Action using the desired record types.
boolean	canDeleteActionGroups() Tests if this user can delete ActionGroups.
boolean	canDeleteActions() Tests if this user can delete Actions.
boolean	canManageActionAliases() Tests if this user can manage Id aliases for Actions.
boolean	canManageActionGroupAliases() Tests if this user can manage Id aliases for ActionGroups.
boolean	canSequenceActions() Tests if this user can order Actions.
boolean	canUpdateActionGroups() Tests if this user can update ActionGroups.
boolean	canUpdateActions() Tests if this user can update Actions.
Action	createAction(ActionForm actionForm) Creates a new Action.
ActionGroup	createActionGroup(ActionGroupForm actionGroupForm) Creates a new ActionGroup.
void	deleteAction(Id actionId) Deletes an Action.
void	deleteActionGroup(Id actionGroupId) Deletes an ActionGroup.
ActionForm	getActionFormForCreate(Id actionGroupId, Type[] actionRecordTypes) Gets the action form for creating new actions.
ActionForm	getActionFormForUpdate(Id actionId) Gets the action form for updating an existing action.
ActionGroupForm	getActionGroupFormForCreate(Type[] actionGroupRecordTypes) Gets the action group form for creating new action groups.
ActionGroupForm	getActionGroupFormForUpdate(Id actionGroupId) Gets the action group form for updating an existing action group.
System	getSystem() Gets the System associated with this session.
Id	getSystemId() Gets the System Id associated with this session.
void	moveActionAhead(Id actionId, Id actionGroupId, Id referenceId) Reorders actions in an action grpup by moving the specified action in front of a reference action.
void	moveActionBehind(Id actionId, Id actionGroupId, Id referenceId) Reorders actions in an action group by moving the specified action behind a reference action.
void	orderActions(Id[] actionIds, Id actionGroupId) Reorders a set of actions in an action group.
void	updateAction(ActionForm actionForm) Updates an existing action.
void	updateActionGroup(ActionGroupForm actionGroupForm) Updates an existing action group.

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.

canCreateActionGroups

boolean canCreateActionGroups()

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

Compliance:

mandatory - This method must be implemented.

canCreateActionGroupWithRecordTypes

boolean canCreateActionGroupWithRecordTypes(Type[] actionGroupRecordTypes)

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

Parameters:

actionGroupRecordTypes - array of action group record types

Returns:

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

Throws:

NullArgumentException - actionGroupRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getActionGroupFormForCreate

ActionGroupForm getActionGroupFormForCreate(Type[] actionGroupRecordTypes)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Gets the action group form for creating new action groups. A new form should be requested for each create transaction.

Parameters:

actionGroupRecordTypes - array of action group record types

Returns:

the action group form

Throws:

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

createActionGroup

ActionGroup createActionGroup(ActionGroupForm actionGroupForm)
                              throws OperationFailedException,
                                     PermissionDeniedException

Creates a new ActionGroup.

Parameters:

actionGroupForm - the form for this ActionGroup

Returns:

the new ActionGroup

Throws:

IllegalStateException - actionGroupForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - actionGroupForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - actionGroupForm did not originate from getActionGroupFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateActionGroups

boolean canUpdateActionGroups()

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

Compliance:

mandatory - This method must be implemented.

getActionGroupFormForUpdate

ActionGroupForm getActionGroupFormForUpdate(Id actionGroupId)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

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

Parameters:

actionGroupId - the Id of the ActionGroup

Returns:

the action group form

Throws:

NotFoundException - actionGroupId is not found

NullArgumentException - actionGroupId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateActionGroup

void updateActionGroup(ActionGroupForm actionGroupForm)
                       throws OperationFailedException,
                              PermissionDeniedException

Updates an existing action group.

Parameters:

actionGroupForm - the form containing the elements to be updated

Throws:

IllegalStateException - actionGroupForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - actionGroupForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - actionGroupForm did not originate from getActionGroupFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteActionGroups

boolean canDeleteActionGroups()

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

Compliance:

mandatory - This method must be implemented.

deleteActionGroup

void deleteActionGroup(Id actionGroupId)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Deletes an ActionGroup.

Parameters:

actionGroupId - the Id of the ActionGroup to remove

Throws:

NotFoundException - actionGroupId not found

NullArgumentException - actionGroupId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageActionGroupAliases

boolean canManageActionGroupAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasActionGroup

void aliasActionGroup(Id actionGroupId,
                    Id aliasId)
                      throws AlreadyExistsException,
                             NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

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

Parameters:

actionGroupId - the Id of an ActionGroup

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - actionGroupId not found

NullArgumentException - actionGroupId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateActionWithRecordTypes

boolean canCreateActionWithRecordTypes(Type[] actionRecordTypes)

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

Parameters:

actionRecordTypes - array of action record types

Returns:

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

Throws:

NullArgumentException - actionRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getActionFormForCreate

ActionForm getActionFormForCreate(Id actionGroupId,
                                Type[] actionRecordTypes)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Gets the action form for creating new actions. A new form should be requested for each create transaction.

Parameters:

actionGroupId - an action group Id

actionRecordTypes - array of action record types

Returns:

the action form

Throws:

NotFoundException - actionGroupId is not found

NullArgumentException - actionGroupId or actionRecordTypes 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.

createAction

Action createAction(ActionForm actionForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Creates a new Action.

Parameters:

actionForm - the form for this Action

Returns:

the new Action

Throws:

IllegalStateException - actionForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - actionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - actionForm did not originate from getActionFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateActions

boolean canUpdateActions()

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

Compliance:

mandatory - This method must be implemented.

getActionFormForUpdate

ActionForm getActionFormForUpdate(Id actionId)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

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

Parameters:

actionId - the Id of the Action

Returns:

the action form

Throws:

NotFoundException - actionId is not found

NullArgumentException - actionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateAction

void updateAction(ActionForm actionForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Updates an existing action.

Parameters:

actionForm - the form containing the elements to be updated

Throws:

IllegalStateException - actionForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - actionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - actionForm did not originate from getActionFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteActions

boolean canDeleteActions()

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

Compliance:

mandatory - This method must be implemented.

deleteAction

void deleteAction(Id actionId)
                  throws NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Deletes an Action.

Parameters:

actionId - the Id of the Action to remove

Throws:

NotFoundException - actionId not found

NullArgumentException - actionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageActionAliases

boolean canManageActionAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasAction

void aliasAction(Id actionId,
               Id aliasId)
                 throws AlreadyExistsException,
                        NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

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

Parameters:

actionId - the Id of an Action

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - actionId not found

NullArgumentException - actionId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canSequenceActions

boolean canSequenceActions()

Tests if this user can order Actions. A return of true does not guarantee successful authorization. A return of false indicates that it is known sequencing operations will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer sequencing operations to an unauthorized user.

Returns:

false if Action ordering is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

moveActionAhead

void moveActionAhead(Id actionId,
                   Id actionGroupId,
                   Id referenceId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Reorders actions in an action grpup by moving the specified action in front of a reference action.

Parameters:

actionId - the Id of an Action

actionGroupId - the Id of an ActionGroup

referenceId - the reference action Id

Throws:

NotFoundException - actionId, actionGroupId, or referenceId not found or, actionId or referenceId not related to actionGroupId

NullArgumentException - actionId, actionGroupId, or referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

moveActionBehind

void moveActionBehind(Id actionId,
                    Id actionGroupId,
                    Id referenceId)
                      throws NotFoundException,
                             OperationFailedException,
                             PermissionDeniedException

Reorders actions in an action group by moving the specified action behind a reference action.

Parameters:

actionId - the Id of an Action

actionGroupId - the Id of an ActionGroup

referenceId - the reference action Id

Throws:

NotFoundException - actionId, actionGroupId, or referenceId not found or, actionId or referenceId not related to actionGroupId

NullArgumentException - actionId, actionGroupId, or referenceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

orderActions

void orderActions(Id[] actionIds,
                Id actionGroupId)
                  throws NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Reorders a set of actions in an action group.

Parameters:

actionIds - the Ids for a set of Actiond

actionGroupId - the Id of an ActionGroup

Throws:

NotFoundException - actionGroupId not found or, an actionId not related to actionGroupId

NullArgumentException - actionIds or actionGroupId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.