org.osid.workflow

Interface StepAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

StepBatchAdminSession

public interface StepAdminSession
extends OsidSession

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

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

The delete operations delete Steps. To unmap a Step from the current Office, the StepOfficeAssignmentSession should be used. These delete operations attempt to remove the Step itself thus removing it from all known Office 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	aliasStep(Id stepId, Id aliasId) Adds an Id to a Step for the purpose of creating compatibility.
boolean	canCreateSteps() Tests if this user can create Steps.
boolean	canCreateStepWithRecordTypes(Type[] stepRecordTypes) Tests if this user can create a single Step using the desired record types.
boolean	canDeleteSteps() Tests if this user can delete Steps.
boolean	canManageStepAliases() Tests if this user can manage Id aliases for Steps.
boolean	canUpdateSteps() Tests if this user can update Steps.
Step	createStep(StepForm stepForm) Creates a new Step.
void	deleteStep(Id stepId) Deletes a Step.
Office	getOffice() Gets the Office associated with this session.
Id	getOfficeId() Gets the Office Id associated with this session.
StepForm	getStepFormForCreate(Id processId, Type[] stepRecordTypes) Gets the step form for creating new steps.
StepForm	getStepFormForUpdate(Id stepId) Gets the step form for updating an existing step.
void	updateStep(StepForm stepForm) Updates an existing step.

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

getOfficeId

Id getOfficeId()

Gets the Office Id associated with this session.

Returns:

the Office Id associated with this session

Compliance:

mandatory - This method must be implemented.

getOffice

Office getOffice()
                 throws OperationFailedException,
                        PermissionDeniedException

Gets the Office associated with this session.

Returns:

the office

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateSteps

boolean canCreateSteps()

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

Compliance:

mandatory - This method must be implemented.

canCreateStepWithRecordTypes

boolean canCreateStepWithRecordTypes(Type[] stepRecordTypes)

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

Parameters:

stepRecordTypes - array of step record types

Returns:

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

Throws:

NullArgumentException - stepRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getStepFormForCreate

StepForm getStepFormForCreate(Id processId,
                            Type[] stepRecordTypes)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

Gets the step form for creating new steps. A new form should be requested for each create transaction.

Parameters:

processId - a process Id

stepRecordTypes - array of step record types

Returns:

the step form

Throws:

NotFoundException - processId is not found

NullArgumentException - processId or stepRecordTypes 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.

createStep

Step createStep(StepForm stepForm)
                throws OperationFailedException,
                       PermissionDeniedException

Creates a new Step.

Parameters:

stepForm - the form for this Step

Returns:

the new Step

Throws:

IllegalStateException - stepForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - stepForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - stepForm did not originate from getStepFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateSteps

boolean canUpdateSteps()

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

Compliance:

mandatory - This method must be implemented.

getStepFormForUpdate

StepForm getStepFormForUpdate(Id stepId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

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

Parameters:

stepId - the Id of the Step

Returns:

the step form

Throws:

NotFoundException - stepId is not found

NullArgumentException - stepId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateStep

void updateStep(StepForm stepForm)
                throws OperationFailedException,
                       PermissionDeniedException

Updates an existing step.

Parameters:

stepForm - the form containing the elements to be updated

Throws:

IllegalStateException - stepForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - stepForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - stepForm did not originate from getStepFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteSteps

boolean canDeleteSteps()

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

Compliance:

mandatory - This method must be implemented.

deleteStep

void deleteStep(Id stepId)
                throws NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

Deletes a Step.

Parameters:

stepId - the Id of the Step to remove

Throws:

NotFoundException - stepId not found

NullArgumentException - stepId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageStepAliases

boolean canManageStepAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasStep

void aliasStep(Id stepId,
             Id aliasId)
               throws AlreadyExistsException,
                      NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

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

Parameters:

stepId - the Id of a Step

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - stepId not found

NullArgumentException - stepId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.