commonj.connector.metadata.discovery.mutable
Interface ObjectWizard


public interface ObjectWizard

Represents a wizard that will walk a tool user (in one or more steps) through an operation of a selected object in the metadata tree. A wizard can add a child to a parent object, update an object, delete an object, or make a non-visible change to the object. The add, update, delete, or non-visible flavor of the wizard can be determined from the operation type attribute of the operation for the wizard. The actual operations allowed on any given object are determined by the MetadataDiscovery service implementation. A wizard can create a new MetadataObject, update, delete, or have an non-visible operation. The create is always initiated from the parent object. The update, delete, non-visible is always performed on the object itself. The wizard maintains a reference to the MetadataObject instance it is working on, the operation that is being performed on it, and the MetadataConnection being used to communicate with the EIS. Each step is intended to make progress towards accomplishing the single operation indicated for this ObjectWizard. Each step may define actions the user may take to complete this step of the operation.

It should be noted that object wizard does not necessarily imply a GUI. The wizard may be a simple command line tool too.

When the object wizard is created, it must be initialized to the first step in the wizard. the call to get the current step must then return the first step in the wizard and have a status of start. It might also be the case that the first step is the last step. If this is so, the first step must have a status of FINISH.

Since:
1.0
See Also:
Operation.getOperationType()

Method Summary
 void cancelOperation()
          Cancels the operation of the object wizard.
 MetadataObject completeCreateOperation()
          Deprecated. since 1.1 - see finishOperation()
 MetadataObject finishOperation()
          Complete the object wizard.
 ObjectWizardStep getCurrentStep()
          Get the current step for this wizard.
 MetadataConnection getMetadataConnection()
          Gets the metadata connection associated with the wizard.
 MetadataObject getMetadataObject()
          Gets the MetadataObject that the wizard is performing an operation on.
 ObjectWizardStep getNextStep(Action action)
          Deprecated. since 1.1
 Operation getOperation()
          Gets the operation being performed by the wizard.
 String getTitle()
          This function returns the title of the object wizard.
 void setToolContext(ToolContext toolContext)
          This function is used to set the ToolContext for the object wizard.
 

Method Detail

getMetadataConnection

MetadataConnection getMetadataConnection()
Gets the metadata connection associated with the wizard.

Returns:
MetadatConnection null must never be returned.

getMetadataObject

MetadataObject getMetadataObject()
Gets the MetadataObject that the wizard is performing an operation on. It is also sometimes referred to as the connect node.

Returns:
MetadataObject null must never be returned.

getOperation

Operation getOperation()
Gets the operation being performed by the wizard.

Returns:
Operation null must never be returned.

getNextStep

ObjectWizardStep getNextStep(Action action)
                             throws MetadataException
Deprecated. since 1.1

When the object wizard in created. It must initialize itself to the first step of the wizard. This function is used to walk through the remaining steps of the wizard. It might also be the case that the first step is the last step. If this is so, the status of the current step must be FINISH.

Continue the wizard by taking one of the defined actions on the current step. This results in the return of the next step in the wizard. You should continue making calls to getNextStep() until the returned ObjectWizardStep has status=Finish. You can determine the outcome of the wizard (Create/Delete/Update/Cancel) from the status field of the returned ObjectWizardStep. This should never return null.

In the case of a wizard that creates a new object, you must make a final call to completeCreateOperation() to obtain a handle to any MetadataObject instance that has been created by the wizard.

Parameters:
action - The action performed on the current step.
Returns:
The next step in the wizard (may be the last and have ObjectWizard status of ObjectWizardStatus.FINISH or ObjectWizardStatus.CANCEL). null must never be returned.
Throws:
MetadataException - Thrown if an unrecoverable error happens occurs in the wizard. The tool should abort the wizard and assume that no changes were made as a result of the wizard.
See Also:
completeCreateOperation()

getCurrentStep

ObjectWizardStep getCurrentStep()
Get the current step for this wizard. This method is idempotent as it has no side effects. On the instantiation of the object wizard, the wizard must automatically initialize itself to the first step. If getNextStep has not been called this call should return the first step of the wizard.

Returns:
The current step. This must never return null.

completeCreateOperation

MetadataObject completeCreateOperation()
                                       throws MetadataException
Deprecated. since 1.1 - see finishOperation()

Complete a create wizard. You should call this method only when the step returned by getCurrentStep() returns ObjectWizardStatus.FINISH from its getStatus() method (and only when the wizard itself has an OperationType of OperationType.CREATE). If any of these conditions are not met, a MetadataException is thrown. This method returns the newly created MetadataObject. This method is needed because the MetadataObject in the ObjectWizardStep for a create operation represents the parent of the newly created node, not the node itself.

Returns:
The MetadataObject that was created (and added to the parent) by this wizard, or null if the creation was not successful.
Throws:
MetadataException - If this is not a create wizard, or if the current step does not indicate that the wizard is finished.

getTitle

String getTitle()
This function returns the title of the object wizard. It may be used by the tool for display.

This is a locale specific object that must be separated to a ResourceBundle, translated, and retrieved using the locale of the tool environment.

Returns:
The title of the object wizard. This must never return null.
See Also:
ResourceBundle, MessageFormat

setToolContext

void setToolContext(ToolContext toolContext)
This function is used to set the ToolContext for the object wizard. This tool context may then be used by the tool to report progress and log informational messages.

Parameters:
toolContext - The tool context for the object wizard. This parameter must never be null.

cancelOperation

void cancelOperation()
                     throws MetadataException
Cancels the operation of the object wizard.

It is recommended that any changes that might occur to the metadata tree be committed in the last step of the wizard. CANCEL must revert the metadata tree to what it was before the operation was started and the tool should not have to refresh the tree.

Throws:
MetadataException - If there is an error in performing the cancel operation.
Since:
1.1

finishOperation

MetadataObject finishOperation()
                               throws MetadataException
Complete the object wizard. You should call this method only when the step returned by getCurrentStep() returns true from its canFinish() method.

If the wizard itself has an OperationType of OperationType.CREATE), this method returns the newly created MetadataObject. This is needed because the MetadataObject in the ObjectWizardStep for a create operation represents the parent of the newly created node, not the node itself. If the wizard has an OperationType of anything else, this method returns null.

Returns:
The MetadataObject that was created (and added to the parent) by this wizard, or null if there was no creation.
Throws:
MetadataException - If there is an error in performing the finish operation.
Since:
1.1