All Packages Class Hierarchy This Package Previous Next Index
Class com.sgi.sysadm.ui.Task
java.lang.Object
|
+----java.awt.Component
|
+----java.awt.Container
|
+----javax.swing.JComponent
|
+----javax.swing.JPanel
|
+----com.sgi.sysadm.ui.Task
- public abstract class Task
- extends JPanel
Task is an abstract class for creating sysadm Task user
interfaces. For more information on writing a Task, see the
How to Write a Task
tutorial.
Task provides services such as initializing TaskData, checking privileges,
and managing a control panel.
Task interacts with its subclasses as follows:
-
Task.Task() initializes itself and sets up public and private TaskData
attributes as defined in {taskname}P.properties. Task also sets the
default preferred interface (Form or Guide) from the property
Task.PREFERRED_UI (see Task.setPreferredUI() below).
-
Task.setTaskDataAttr() is called by clients (such as RunTask) to
set their own values for public TaskData. TaskData usually
corresponds to data that a user can input to the Task. For
example, a user name and modem name could be TaskData to the
Create PPP Connection Task. TaskData can also be used
to control the behavior of a Task. For example, the Create PPP
Connection Task might define a boolean TaskData attribute that controls
whether or not advanced options are displayed.
-
subclass.setOperands() allows clients to set Task operands. Operands are
the objects that a Task will operate on. For example, the Create PPP
Connection task would not have any operands, but a user account
Item selector name (or list of user account Item selectors) would
be an operand to the Delete PPP Connection.
Because operands may be passed to Tasks by a class with no
specific knowledge about the Task (e.g. TaskShelfPanel), no ordering of
operands should be assumed or required by the Task. The number
and type of operands should be checked by subclass.setOperands(),
but any verification that requires access to the server should be
postponed until subclass.verifyPrereqsBeforeCheckPrivs() or
subclass.verifyPrereqsAfterCheckPrivs() is called because
setOperands() is synchronous.
Tasks that accept operands must set the property
Task.OPERAND_TYPE_ACCEPTED to the Item type that the Task
accepts, and override Task.setOperands() to check and store any
operand(s) passed. If the Task will accept any operand type, set
the value of this property to Task.ALL_OPERAND_TYPES. Tasks that
do not accept operands need not define the
Task.OPERAND_TYPE_ACCEPTED property nor override setOperands();
the base class will post an error if a Task client attempts to
pass in operands.
-
Task.setPreferredUI() allows clients to determine whether the Form
or Guide is the preferred user interface. If a Task has both types of
interfaces, this preference will be used to decide which interface to
use when the Task is first displayed. Calling this method overrides
the property Task.PREFERRED_UI.
-
Task.verifyPrereqs() is called by Task clients (such as RunTask) after
they have set TaskData attributes and Task operands. verifyPrereqs()
first calls verifyPrereqsBeforeCheckPrivs(), then it attempts to obtain
privileges, and finally it calls verifyPrereqsAfterCheckPrivs(). A
failure at any of these three stages aborts the operation and the client
is notified of the failure via a ResultListener.
Task implements trivial versions of verifyPrereqsBeforeCheckPrivs() and
verifyPrereqsAfterCheckPrivs() that simply call
ResultListener.succeeded(). The subclass should override these
methods as needed. If verification in either of these methods
consists of multiple asynchronous calls that must be performed in
sequence (also known as chaining), the subclass may use the
version of
TaskContext.dataOK()
that takes a Vector of TaskDataVerifiers to simplify the chaining logic.
NOTE: the reason verification is split into BeforeCheckPrivs() and
AfterCheckPrivs() calls is for convenience to the user. The idea
is to notify the user of a failure as early as possible in order to
prevent unnecessary input of root password for privileges. For
example, it would be very annoying for the user to find out that
the server state is invalid for a particular task after entering
the root password when the task could have checked the server and
posted an error before attempting to obtain privileges.
-
When Task is notified via the AncestorListener interface that it is
about to become visible for the first time, Task calls
subclass.registerInterfaces(). subclass.registerInterfaces() should
create a Form and/or Guide, and register these interfaces by calling
Task.setForm() and Task.setGuide() respectively. Task will then display
the preferred interface if both exist, or the one registered interface
otherwise.
-
Task displays a TaskControlPanel to allow the user to drive
the Task interface. TaskControlListener events are passed along to
the Form and Guide as appropriate.
-
Task.getTaskDataAttr() is called by clients to get the value of a
public TaskData attribute. For example, the client may want to
get the value of something entered by the User and pass it along to
another Task.
-
When the user presses the "OK" button, indicating that the task should
be performed, Task first calls
TaskContext.allDataOK(TaskDataVerifier.MUST_BE_SET) to verify that all
of the TaskData attributes are valid and consistent. After successful
verification of TaskData, Task then calls subclass.ok() so that the
subclass can run the privileged command(s). The privileged
command is run via a java.lang.Process object that is either under the
control of the sysadm infrastructure or the subclass, as desired. Here
are six of the ways the subclass can run
and interact with the
privileged command(s):
- runPriv(String privcmdName) displays a busy dialog, passes all TaskData
to the named privileged command, and calls taskSucceeded() or
taskFailed().
- runPriv(String privcmdName, TaskData taskData) displays a busy dialog,
passes the specified TaskData to the named privileged command, and
calls taskSucceeded() or taskFailed(). An OutputStream is
returned so that the subclass can pass private data (such as
passwords) or control data to the privileged command Process via
standard input.
- runPriv(String privcmdName, TaskData taskData, ResultListener listener)
passes the specified TaskData to the named privileged command and calls
listener.succeeded() if the privcmd succeeds or
listener.failed() if the privcmd fails. An OutputStream is
returned so that the subclass can pass private data (such as
passwords) or control data to the privileged command Process via
standard input. The subclass is responsible for posting a busy
dialog, and calling taskSucceeded() or taskFailed().
- runPriv(String privcmdName, TaskData taskData, ProcessListener listener)
passes the specified TaskData to the named privileged command. It
adds the ProcessListener to the privileged command Process so
that the subclass gets notified of ProcessEvents. An OutputStream is
returned so that the subclass can pass private data (such as
passwords) or control data to the privileged command Process via
standard input. When using this version of runPriv(), the
subclass is responsible for posting a busy dialog, if any, and
responding to ProcessEvents. In particular, the subclass must
call taskSucceeded() or taskFailed() when the privileged
command Process(es) exit(s).
- runPriv(String privcmdName, TaskData taskData, Category category,
ItemTester itemTester, int eventType) is like runPriv(String, TaskData),
except that if the privcmd succeeds and the given ItemTester is not
null, runPriv() waits to call taskSucceeded() until the specified event
type has occurred in the Category on an Item matching the ItemTester.
(If this does not happen before Task.eventTimeout seconds, it
calls taskFailed().)
You might want to do this when the Task is launched from a metatask, and
subsequent steps cannot be performed until after the changes caused by
the Task's privcmd have been propagated back to the client. In general,
it's probably better to not use this feature unless absolutely
necessary, as it means the user spends longer staring at an hourglass.
- The subclass can create its own Process directly (e.g. by using
TaskContext.getHostContext().getPrivBroker().runPriv()) and have
full flexibility over interaction with the privileged
command(s). In this case the subclass is responsible for
posting any busy dialogs and for calling taskSucceeded() or
taskFailed(). If you need to wait on an event, you should be able to
use waitForEvent() for this; see the notes above on waiting for
events.
If the Task is successful, TaskDoneListeners may wish to display
result information. These clients will call getResultViewPanel() to
request a ResultViewPanel that they can display as a dialog or
inside some part of their UI. getResultViewPanel will call
Subclass.createResultViewPanel after first checking that
Task.succeeded() was called.
Specific tasks must have an associated properties file that resides
in the same package as {taskname}.class named
{taskname}P.properties. The package containing the task may
also define a properties file named PackageP.properties to provide
fallback values for all tasks in the package.
- See Also:
- Process, RunTask, Form, Guide, TaskContext, TaskDataVerifier
-
ALL_OPERAND_TYPES
- The String Task.allOperandTypes is the value a Task
should use for the property Task.operandTypeAccepted if
the Task will accept an operand of any type.
-
BOTTOM_INSET
- The property Task.bottomInset is an integer that defines the inset,
in points, between the bottom of the task container and the task
interface.
-
DEMO_NO_PREREQS
- A system property that controls whether Task verifies prereqs
before showing the UI.
-
DEMO_NO_RUNPRIV
- A system property that controls whether runPriv actually makes a
call to the server.
-
EVENT_TIMEOUT
- If a Task will wait for an event on an Item after its privcmd
succeeds before returning the success to the user, the property
Task.eventTimeout determines how many seconds it will wait for
the event before giving up.
-
EVENT_TIMEOUT_REASON
- If a Task will wait for an event on an Item after its privcmd
succeeds before returning the success to the user, the property
Task.eventTimeoutReason is the message which will be displayed
if the event fails to arrive before the Task times out.
-
EVENT_TYPE_ADD
- The flag passed to runPriv() and waitForEvent() to indicate that they
should wait for an add event on the desired Item.
-
EVENT_TYPE_CHANGE
- The flag passed to runPriv() and waitForEvent() to indicate that they
should wait for a modify event on the desired Item.
-
EVENT_TYPE_NONE
- The flag passed to runPriv() and waitForEvent() to indicate that they
shouldn't wait for an event.
-
EVENT_TYPE_REMOVE
- The flag passed to runPriv() and waitForEvent() to indicate that they
should wait for a remove event on the desired Item.
-
FORM_UI
- String intended as an argument to Task.setPreferredUI() to set the
Form interface as the preferred interface.
-
GUIDE_UI
- String intended as an argument to Task.setPreferredUI() to set the
Guide interface as the preferred interface.
-
HEIGHT_IN_POINTS
- The property Task.heightInPoints is an integer that sets
the height of the task interface (both Form and Guide), in
points.
-
HELP_KEY
- The property Task.helpKey is a String containing the
help tag within HELP_BOOK of the help text for this task.
-
ITEM_TESTER
- Task.itemTester is a String containing the
CLASSPATH
relative name of a class that determines whether the task
is relevant to a particular Item.
-
KEYWORDS
- The property Task.keywords is a String containing a
whitespace separated list of words the user may use when
searching for this task.
-
LEFT_INSET
- The property Task.leftInset is an integer that defines the inset,
in points, between the left side of the task container and the task
interface.
-
LONG_NAME
- The property Task.longName is a String describing the purpose
of the task.
-
OPERAND_TYPE_ACCEPTED
- The property Task.operandTypeAccepted is a String that
specifies what type of operand the Task accepts.
-
PREFERRED_UI
- The property Task.preferredUI is a string that determines which
user interface, Form or Guide, will be displayed at startup if a task
has both interfaces.
-
PRIV_LIST
- The property set Task.privList<n> describes the set of
privileges needed to perform a task.
-
PRODUCT_ATTRIBUTES
-
The property set Task.ProductAttributes<n> is a
string array that specifies the products from which to request
product attributes.
-
PUBLIC_DATA
- The property set Task.publicData<n> describes the set of
TaskData attributes that can be set by clients of the task.
-
RIGHT_INSET
- The property Task.rightInset is an integer that defines
the inset, in points, between the right side of the task
container and the task interface.
-
RUN_ONCE_ATTRIBUTES
- The property set Task.runOnceAttributes<n> is a
String array that specifies the TaskData attributes that should
be used for controlling run once behavior of a task.
-
SHARED_PROPERTIES
- The property set Task.sharedProperties<n>
describes the set of properties files that should be pushed
onto the Task ResourceStack, in order, before the
{taskname}P.properties file.
-
SHORT_NAME
- The property Task.shortName is a String containing the short name
for the task.
-
SHOW_CANCEL_BUTTON
- The property Task.showCancelButton is a boolean that
controls whether the Cancel button is shown on the Task.
-
TASK_SHELF_ICON
- Task.taskShelfIcon is a String containing the
CLASSPATH
relative name of the icon
image file of an icon to display along with the short name
of the task in a TaskShelf.
-
TITLE_FORMAT
- The property Task.titleFormat is a format string that includes
two arguments: {0} for the task name and {1} for the server name.
-
TOP_INSET
- The property Task.topInset is an integer that defines the inset,
in points, between the top of the task container and the task interface.
-
WIDTH_IN_POINTS
- The property Task.widthInPoints is an integer that sets
the width of the task interface (both Form and Guide), in
points.
-
Task(TaskContext)
- Constructor.
-
addTaskDoneListener(TaskDoneListener)
- Register interest in task completion.
-
addTitleListener(TitleListener)
- Register interest in changes to the Task title.
-
checkPrivs(ResultListener)
- checkPrivs() is a service provided by the base class for
checking and obtaining the privileges needed to perform the Task.
-
checkPrivs(TaskLoader[], ResultListener)
- Checks all privileges needed for several tasks.
-
createResultViewPanel()
- Called by the base class to obtain a ResultViewPanel from the
subclass.
-
getResultViewPanel()
- Called by clients of the task when the task has been completed
successfully.
-
getTaskDataAttr(String)
- Get a specific public TaskData attribute.
-
getTaskTitle()
- Get the current title of the Task
-
ok()
- After the User presses the OK button, the base class will
verify TaskData and then call subclass.ok() to initiate
performance of the task operation.
-
registerInterfaces()
- registerInterfaces() is called by the base class to request
registration of the Task user interface.
-
removeTaskDoneListener(TaskDoneListener)
- Unregister interest in task completion.
-
removeTitleListener(TitleListener)
- Unregister interest in changes to the Task title.
-
runPriv(String)
- Subclasses should call this version of runPriv() if the task can
be performed by running a single privcmd, the privcmd does not accept
any private data (such as passwords) via stdin, it is reasonable to
send all TaskData attributes to the privcmd, and task failure can be
handled by displaying the privcmd output and error text in a standard
error dialog.
-
runPriv(String, String)
- Subclasses should call this version of runPriv() if the task can
be performed by running a single privcmd, the privcmd accepts some
private data (such as passwords) via stdin, and task failure can be
handled by displaying the privcmd output and error text in a standard
error dialog.
-
runPriv(String, String, ProcessListener)
- Subclasses should call this version of runPriv() if the task needs
full control over privileged command input and output and needs to
regain control when the privileged command exits.
-
runPriv(String, String, ResultListener)
- Subclasses should call this version of runPriv() if the multiple
privcmds are needed to accomplish the task or the subclass wants to
regain control after the privcmd completes.
-
runPriv(String, String[])
- Subclasses should call this version of runPriv() if the task can
be performed by running a single privcmd, the privcmd accepts some
private data (such as passwords) via stdin, and task failure can be
handled by displaying the privcmd output and error text in a standard
error dialog.
-
runPriv(String, String[], ProcessListener)
- Subclasses should call this version of runPriv() if the task needs
full control over privileged command input and output and needs to
regain control when the privileged command exits.
-
runPriv(String, String[], ResultListener)
- Subclasses should call this version of runPriv() if the multiple
privcmds are needed to accomplish the task or the subclass wants to
regain control after the privcmd completes.
-
runPriv(String, TaskData)
- Subclasses should call this version of runPriv() if the task can
be performed by running a single privcmd, the privcmd accepts some
private data (such as passwords) via stdin, and task failure can be
handled by displaying the privcmd output and error text in a standard
error dialog.
-
runPriv(String, TaskData, Category, ItemTester, int)
- This version of runPriv() is just like runPriv(String, TaskData), but if
its ItemTester argument is non-null and its eventType isn't
EVENT_TYPE_NONE, it delays success until the specified event type has
occurred in the Category on an Item matching the ItemTester.
-
runPriv(String, TaskData, ProcessListener)
- Subclasses should call this version of runPriv() if the task needs
full control over privileged command input and output and needs to
regain control when the privileged command exits.
-
runPriv(String, TaskData, ResultListener)
- Subclasses should call this version of runPriv() if the multiple
privcmds are needed to accomplish the task or the subclass wants to
regain control after the privcmd completes.
-
setForm(Form)
- Register a Form interface to use for this Task.
-
setGuide(Guide)
- Register a Guide interface to use for this Task.
-
setOperands(Vector)
- Called by the Task client to pass operands to the task.
-
setPreferredUI(String)
- Set the preferred user interface.
-
setTaskDataAttr(Attribute)
- Set the value of a specific public data attribute.
-
setTaskDataAttr(String, String)
- Set the value of a specific public data item by key and value.
-
taskDone(TaskResult)
- Notify TaskDoneListeners that the task has completed successfully or
has been cancelled.
-
taskFailed(ResultEvent)
- Notify the Task base class that the Task operation failed.
-
taskSucceeded(ResultEvent)
- Notify the Task base class that the Task operation succeeded
after a call to subclass.ok().
-
verifyPrereqs(ResultListener)
- Verify the TaskData attributes, Task operands, and state of the
system being administered to make sure it is reasonable to
go ahead with this Task.
-
verifyPrereqsAfterCheckPrivs(ResultListener)
- A trivial verification that always calls listener.succeeded().
-
verifyPrereqsBeforeCheckPrivs(ResultListener)
- A trivial verification that always calls listener.succeeded().
-
waitForEvent(ResultListener, Category, ItemTester, int)
- Wait for an event on a specific Item.
PRIV_LIST
public static final String PRIV_LIST
- The property set Task.privList<n> describes the set of
privileges needed to perform a task. Each privilege must be given its
own property name, with Task.privList as the base. For example,
a task that has two privileges would describe them in the
{taskname}P.properties file as follows:
Task.privList0 = firstPrivilege
Task.privList1 = secondPrivilege
PUBLIC_DATA
public static final String PUBLIC_DATA
- The property set Task.publicData<n> describes the set of
TaskData attributes that can be set by clients of the task. The TaskData
attributes are identified by their key. Any TaskData attribute not
included in this set will be inaccessible to task clients. Each public
data attribute must be given its own property name, with
Task.publicData as the base. For example, the Create PPP
Connection Task would describe its public data attributes "loginName"
and "modemName" as follows:
Task.publicData0 = loginName
Task.publicData1 = modemName
SHORT_NAME
public static final String SHORT_NAME
- The property Task.shortName is a String containing the short name
for the task. This property is intended for the initial title of a
frame containing the task, the title of dialogs posted by the task, and
the task name in lists of tasks. For example, "Create PPP
Connection" would be an appropriate short name.
LONG_NAME
public static final String LONG_NAME
- The property Task.longName is a String describing the purpose
of the task. This property is intended to be the default Form page
title, so should only be a single line. For example, "Create a
New PPP Connection" would be an appropriate long name.
ITEM_TESTER
public static final String ITEM_TESTER
- Task.itemTester is a String containing the
CLASSPATH
relative name of a class that determines whether the task
is relevant to a particular Item. TaskLoader.getItemTester()
uses this property to determine what ItemTester class to load
and return.
- See Also:
- TaskLoader
TASK_SHELF_ICON
public static final String TASK_SHELF_ICON
- Task.taskShelfIcon is a String containing the
CLASSPATH
relative name of the icon
image file of an icon to display along with the short name
of the task in a TaskShelf.
PREFERRED_UI
public static final String PREFERRED_UI
- The property Task.preferredUI is a string that determines which
user interface, Form or Guide, will be displayed at startup if a task
has both interfaces. Valid values are form and guide.
The default value is defined in com.sgi.sysadm.ui.TaskContextP.properties.
This property may be overridden by clients of Task by calling
Task.setPreferredUI().
WIDTH_IN_POINTS
public static final String WIDTH_IN_POINTS
- The property Task.widthInPoints is an integer that sets
the width of the task interface (both Form and Guide), in
points. If the
corresponding property specifying the height of the task interface
is missing, the height calculated from the width using the
golden ratio.
The default value of this property is defined in
com.sgi.sysadm.ui.TaskContextP.properties. Overriding this property
in {package}.PackageP.properties or {package}.{taskname}P.properties
is discouraged because of the resizing that will have to occur in
containers that are used to display multiple tasks in sequence.
HEIGHT_IN_POINTS
public static final String HEIGHT_IN_POINTS
- The property Task.heightInPoints is an integer that sets
the height of the task interface (both Form and Guide), in
points.
FORM_UI
public static final String FORM_UI
- String intended as an argument to Task.setPreferredUI() to set the
Form interface as the preferred interface.
GUIDE_UI
public static final String GUIDE_UI
- String intended as an argument to Task.setPreferredUI() to set the
Guide interface as the preferred interface.
TOP_INSET
public static final String TOP_INSET
- The property Task.topInset is an integer that defines the inset,
in points, between the top of the task container and the task interface.
The default value for this property is provided in
com.sgi.sysadm.ui.TaskContextP.properties and it may be overridden in
either {package}.PackageP.properties or {package}.{taskname}P.properties.
LEFT_INSET
public static final String LEFT_INSET
- The property Task.leftInset is an integer that defines the inset,
in points, between the left side of the task container and the task
interface.
The default value for this property is provided in
com.sgi.sysadm.ui.TaskContextP.properties and it may be overridden in
either {package}.PackageP.properties or {package}.{taskname}P.properties.
BOTTOM_INSET
public static final String BOTTOM_INSET
- The property Task.bottomInset is an integer that defines the inset,
in points, between the bottom of the task container and the task
interface.
The default value for this property is provided in
com.sgi.sysadm.ui.TaskContextP.properties and it may be overridden in
either {package}.PackageP.properties or {package}.{taskname}P.properties.
RIGHT_INSET
public static final String RIGHT_INSET
- The property Task.rightInset is an integer that defines
the inset, in points, between the right side of the task
container and the task interface.
The default value for this property is provided in
com.sgi.sysadm.ui.TaskContextP.properties and it may be overridden in
either {package}.PackageP.properties or
{package}.{taskname}P.properties.
TITLE_FORMAT
public static final String TITLE_FORMAT
- The property Task.titleFormat is a format string that includes
two arguments: {0} for the task name and {1} for the server name. The
format string is used to format the Task window title string.
The title string is used as-is when the Form interface is
displayed and is incorporated into the Guide.TITLE_FORMAT
string when the Guide interface is displayed.
Task subclasses that wish to add dynamic information to the
Task window title (as opposed to rearranging or reordering the
format string) may call TaskContext.setTaskTitle() anytime
after the Task constructor has completed.
A default value for this property is provided in TaskContextP.properties
and it may be overridden in either {package}.PackageP.properties or
{package}.{taskname}P.properties.
PRODUCT_ATTRIBUTES
public static final String PRODUCT_ATTRIBUTES
- The property set Task.ProductAttributes<n> is a
string array that specifies the products from which to request
product attributes.
Any product attributes set will be placed into the TaskData
before setOperands() or verifyPrereqs() are called.
RUN_ONCE_ATTRIBUTES
public static final String RUN_ONCE_ATTRIBUTES
- The property set Task.runOnceAttributes<n> is a
String array that specifies the TaskData attributes that should
be used for controlling run once behavior of a task. After
product attributes
have been set, the launch code in TaskFrame checks
to see if a TaskFrame instance for a Task of the same class
already exists with identical TaskData values for the keys in
RUN_ONCE_ATTRIBUTES. If such an instance already
exists, it is used instead of creating a new one.
OPERAND_TYPE_ACCEPTED
public static final String OPERAND_TYPE_ACCEPTED
- The property Task.operandTypeAccepted is a String that
specifies what type of operand the Task accepts. It is
used by the infrastructure to determine whether or not to pass
operands. For example, if an ItemView passes its Item to a
TaskShelfPanel, the TaskShelfPanel will only pass that item to
tasks that accept operands of that item type.
ALL_OPERAND_TYPES
public static final String ALL_OPERAND_TYPES
- The String Task.allOperandTypes is the value a Task
should use for the property Task.operandTypeAccepted if
the Task will accept an operand of any type.
KEYWORDS
public static final String KEYWORDS
- The property Task.keywords is a String containing a
whitespace separated list of words the user may use when
searching for this task.
There is no default value provided for this property.
HELP_KEY
public static final String HELP_KEY
- The property Task.helpKey is a String containing the
help tag within HELP_BOOK of the help text for this task.
SHARED_PROPERTIES
public static final String SHARED_PROPERTIES
- The property set Task.sharedProperties<n>
describes the set of properties files that should be pushed
onto the Task ResourceStack, in order, before the
{taskname}P.properties file. These shared properties files are
useful for properties that will be shared by a group of Tasks
in a particular product. Properties that are shared by all of
the Tasks in a product should use the PackageP.properties file,
which will be pushed onto the ResourceStack automatically.
DEMO_NO_RUNPRIV
public static final String DEMO_NO_RUNPRIV
- A system property that controls whether runPriv actually makes a
call to the server. If this property is defined,
Task.runPriv() will always call taskSucceeded() without
attempting to contact the server.
DEMO_NO_PREREQS
public static final String DEMO_NO_PREREQS
- A system property that controls whether Task verifies prereqs
before showing the UI. If set, no prereqs will be checked.
This can be used to see a UI that would not normally be visible
due to prereqs failing. Note: Verifing prereqs often
has side effects in the Task (e.g. setting TaskData), so the
Task may not work as expected.
SHOW_CANCEL_BUTTON
public static final String SHOW_CANCEL_BUTTON
- The property Task.showCancelButton is a boolean that
controls whether the Cancel button is shown on the Task. It
should be "true" or "false".
EVENT_TIMEOUT
public static final String EVENT_TIMEOUT
- If a Task will wait for an event on an Item after its privcmd
succeeds before returning the success to the user, the property
Task.eventTimeout determines how many seconds it will wait for
the event before giving up.
EVENT_TIMEOUT_REASON
public static final String EVENT_TIMEOUT_REASON
- If a Task will wait for an event on an Item after its privcmd
succeeds before returning the success to the user, the property
Task.eventTimeoutReason is the message which will be displayed
if the event fails to arrive before the Task times out. If your task
waits for an event, you may want to provide a less-generic message for
this property.
EVENT_TYPE_NONE
protected static final int EVENT_TYPE_NONE
- The flag passed to runPriv() and waitForEvent() to indicate that they
shouldn't wait for an event.
EVENT_TYPE_ADD
protected static final int EVENT_TYPE_ADD
- The flag passed to runPriv() and waitForEvent() to indicate that they
should wait for an add event on the desired Item.
EVENT_TYPE_CHANGE
protected static final int EVENT_TYPE_CHANGE
- The flag passed to runPriv() and waitForEvent() to indicate that they
should wait for a modify event on the desired Item.
EVENT_TYPE_REMOVE
protected static final int EVENT_TYPE_REMOVE
- The flag passed to runPriv() and waitForEvent() to indicate that they
should wait for a remove event on the desired Item.
Task
public Task(TaskContext taskContext)
- Constructor.
- Parameters:
- taskContext - The context for this task.
addTaskDoneListener
public void addTaskDoneListener(TaskDoneListener listener)
- Register interest in task completion.
- Parameters:
- listener - Listener interested in task completion.
removeTaskDoneListener
public void removeTaskDoneListener(TaskDoneListener listener)
- Unregister interest in task completion.
- Parameters:
- listener - Listener no longer interested in task completion.
taskDone
public void taskDone(TaskResult result)
- Notify TaskDoneListeners that the task has completed successfully or
has been cancelled.
- Parameters:
- result - A TaskResult describing whether the Task succeeded or
was cancelled.
taskSucceeded
protected void taskSucceeded(ResultEvent event)
- Notify the Task base class that the Task operation succeeded
after a call to subclass.ok(). The base class will clear the
busy cursor set when OK was pressed and call taskDone().
- Parameters:
- event - A ResultEvent that contains privcmd output text
as the result and privcmd error text as the
reason. May be null.
taskFailed
protected void taskFailed(ResultEvent event)
- Notify the Task base class that the Task operation failed. The base
class will post an error if event is non-null,
and then clear the busy cursor set when the OK button was
pressed. The Task UI will remain open (Task.taskDone() will
not be called) to allow the User to make a change and try again.
- Parameters:
- event - A ResultEvent that contains privcmd output text as
the result and privcmd error text as the reason.
That text will be displayed in an error dialog.
Pass null if no error dialog should be displayed.
setOperands
public void setOperands(Vector operands) throws TaskInitFailedException
- Called by the Task client to pass operands to the task. The
subclass must override this method if the task accepts
operands, as determined by the property Task.OPERAND_TYPE_ACCEPTED.
Any verification that requires privileges or contact with the server
must be postponed until verifyPrereqsBeforeCheckPrivs() or
verifyPrereqsAfterCheckPrivs() is called because this is a
synchronous method.
If Task.OPERAND_TYPE_ACCEPTED is not defined, then the subclass
need not override this method and the base class implementation will
confirm that operands is null or empty. If the Task
client is attempting to pass one or more operands,
TaskInitFailedException will be thrown with the generic error
message Task.Error.noOperandsAccepted.
- Parameters:
- operands - A (possibly null or empty) vector of task operands.
- Throws: TaskInitFailedException
- Thrown with error
code INVALID_OPERANDS if the type or number of operands
is invalid.
verifyPrereqs
public void verifyPrereqs(ResultListener clientListener)
- Verify the TaskData attributes, Task operands, and state of the
system being administered to make sure it is reasonable to
go ahead with this Task.
Task.verifyPrereqs() is called by Task clients (such as RunTask) after
they have set TaskData attributes and Task operands. verifyPrereqs()
first calls verifyPrereqsBeforeCheckPrivs(), then it attempts to obtain
privileges, and finally it calls verifyPrereqsAfterCheckPrivs(). A
failure at any of these three stages aborts the operation and
clientListener.failed is called.
Task implements trivial versions of verifyPrereqsBeforeCheckPrivs() and
verifyPrereqsAfterCheckPrivs() that simply call
ResultListener.succeeded(). Subclasses should override these methods
as needed. If verification consists of multiple asynchronous calls that
must be chained together, the subclass may use the version of
TaskContext.dataOK() that takes a Vector of TaskDataVerifiers to
simplify the chaining logic.
- Parameters:
- clientListener - A ResultListener to notify of successful or
failed prereq verification.
verifyPrereqsBeforeCheckPrivs
protected void verifyPrereqsBeforeCheckPrivs(ResultListener listener)
- A trivial verification that always calls listener.succeeded().
Subclasses should override this method to do whatever prerequitiste
verification is possible before privileges have been obtained. For
example, the subclass may be able to determine that the server is in an
invalid state without privileges, but must wait until privileges are
obtained to confirm the existence of an Item.
- Parameters:
- listener - A Result Listener to notify of a successful or failed
prereq verification.
verifyPrereqsAfterCheckPrivs
protected void verifyPrereqsAfterCheckPrivs(ResultListener listener)
- A trivial verification that always calls listener.succeeded().
Subclasses should override this method to do prerequisite verification
that requires privileges.
- Parameters:
- listener - A Result Listener to notify of a successful or failed
prereq verification.
registerInterfaces
public abstract void registerInterfaces()
- registerInterfaces() is called by the base class to request
registration of the Task user interface. registerUI() should create a
Form and/or Guide, and must register these interfaces by calling
Task.setForm() and Task.setGuide() respectively.
ok
public abstract void ok()
- After the User presses the OK button, the base class will
verify TaskData and then call subclass.ok() to initiate
performance of the task operation. The subclass must call one of
taskSucceeded() or taskFailed() when processing of the OK
request has been completed (some versions of runPriv() do this
automatically). Otherwise input to the Task will
remain blocked and the cursor will remain busy.
getResultViewPanel
public final ResultViewPanel getResultViewPanel()
- Called by clients of the task when the task has been completed
successfully. This method checks to make sure that
Task.taskSucceeded() has been called and then calls
Subclass.createResultViewPanel to obtain a ResultViewPanel
containing task-specific information about the result of the
task. If Task.taskSucceeded() has not been called, this method
will call Log.fatal().
createResultViewPanel
protected abstract ResultViewPanel createResultViewPanel()
- Called by the base class to obtain a ResultViewPanel from the
subclass.
If it's really not possible to provide a coherent message about
the results of your Task, this method may return null.
addTitleListener
public void addTitleListener(TitleListener listener)
- Register interest in changes to the Task title.
- Parameters:
- listener - Object interested in changes to the Task title.
removeTitleListener
public void removeTitleListener(TitleListener listener)
- Unregister interest in changes to the Task title.
- Parameters:
- listener - Object no longer interested in changes to the Task title.
getTaskTitle
public String getTaskTitle()
- Get the current title of the Task
- Returns:
- The Task's title
setTaskDataAttr
public void setTaskDataAttr(String key,
String value) throws TaskInitFailedException
- Set the value of a specific public data item by key and value.
- Parameters:
- key - Name of public TaskData attribute to set.
- value - New value of the public TaskData attribute.
- Throws: TaskInitFailedException
- Thrown with error
code INVALID_DATA_ATTR if key is not a valid
public data attribute of this task.
setTaskDataAttr
public void setTaskDataAttr(Attribute attr) throws TaskInitFailedException
- Set the value of a specific public data attribute.
- Parameters:
- attr - Attribute to replace.
- Throws: TaskInitFailedException
- Thrown with error
code INVALID_DATA_ATTR if attr is not a valid
public data attribute of this task.
getTaskDataAttr
public Attribute getTaskDataAttr(String key)
- Get a specific public TaskData attribute.
- Parameters:
- key - Name of the public TaskData attribute to get.
- Returns:
- An Attribute, if "key" describes a public TaskData attribute,
null otherwise.
setPreferredUI
public void setPreferredUI(String preferredUI)
- Set the preferred user interface. If a Task has both Form and Guide
interfaces, this preference will be used to decide which interface to
use when the Task is first displayed. Calling this method overrides
the property Task.PREFERRED_UI.
- Parameters:
- preferredUI - Task.FORM_UI if Form is the preferred interface,
Task.GUIDE_UI if Guide is the preferred interface.
checkPrivs
protected void checkPrivs(ResultListener listener)
- checkPrivs() is a service provided by the base class for
checking and obtaining the privileges needed to perform the Task.
- Parameters:
- listener - Gets notified of the result of the check.
setForm
protected void setForm(Form form)
- Register a Form interface to use for this Task. An
assertion will fail
if this method is called more than once per Task instance.
- Parameters:
- form - Form interface to register for this Task.
setGuide
protected void setGuide(Guide guide)
- Register a Guide interface to use for this Task. An
assertion will fail
if this method is called more than once per Task instance.
- Parameters:
- guide - Guide interface to register for this Task.
runPriv
protected void runPriv(String privcmdName)
- Subclasses should call this version of runPriv() if the task can
be performed by running a single privcmd, the privcmd does not accept
any private data (such as passwords) via stdin, it is reasonable to
send all TaskData attributes to the privcmd, and task failure can be
handled by displaying the privcmd output and error text in a standard
error dialog.
runPriv() will post a busy dialog while the privileged command
Process is running. When the privileged command exits,
runPriv() will call taskSucceeded() if the exit code is zero,
or it will call taskFailed().
- Parameters:
- privcmdName - Name of the privileged command to run.
runPriv
protected OutputStream runPriv(String privcmdName,
TaskData taskData)
- Subclasses should call this version of runPriv() if the task can
be performed by running a single privcmd, the privcmd accepts some
private data (such as passwords) via stdin, and task failure can be
handled by displaying the privcmd output and error text in a standard
error dialog.
runPriv() will post a busy dialog while the privileged command
Process is running. When the privileged command exits,
runPriv() will call taskSucceeded() if the exit code is zero,
or it will call taskFailed().
- Parameters:
- privcmdName - Name of the privileged command to run.
- taskData - TaskData attributes to be sent to the privileged command
via the command line.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
runPriv
protected OutputStream runPriv(String privcmdName,
TaskData taskData,
Category category,
ItemTester itemTester,
int eventType)
- This version of runPriv() is just like runPriv(String, TaskData), but if
its ItemTester argument is non-null and its eventType isn't
EVENT_TYPE_NONE, it delays success until the specified event type has
occurred in the Category on an Item matching the ItemTester. If this
does not happen within Task.eventTimeout seconds, it calls
taskFailed().
You might want to do this when the Task is launched from a metatask, and
subsequent steps cannot be performed until after the changes caused by
the Task's privcmd have been propagated back to the client. In general,
it's probably better to not use this feature unless absolutely
necessary, as it means the user spends longer staring at an hourglass.
If the eventType is EVENT_TYPE_CHANGE, the ItemFinder should match the
Item in its new (modified) state, not its state before modification.
For other information on how this method determines whether the expected
event has been received, see the waitForEvent
method.
- Parameters:
- privcmdName - Name of the privileged command to run.
- taskData - TaskData attributes to be sent to the privileged command
via the command line.
- category - Category to be monitored for the event. If itemTester
is null or the eventType is EVENT_TYPE_NONE, this is
ignored.
- itemTester - ItemTester used to determine whether Category events
are for the Item of interest. If this is null, no
event will be waited for.
- eventType - The type of event expected on the item. This must be
EVENT_TYPE_NONE, EVENT_TYPE_ADD, EVENT_TYPE_CHANGE, or
EVENT_TYPE_REMOVE. If this is EVENT_TYPE_NONE, no
event will be waited for.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
- See Also:
- waitForEvent
runPriv
protected OutputStream runPriv(String privcmdName,
TaskData taskData,
ResultListener listener)
- Subclasses should call this version of runPriv() if the multiple
privcmds are needed to accomplish the task or the subclass wants to
regain control after the privcmd completes.
The caller is responsible for posting a busy dialog while the
privileged command(s) run(s), then clearing that dialog and calling
taskSucceeded() or taskFailed() as appropriate when the
privileged command(s) succeed(s) or fail(s).
If the exit code of the privileged command Process is zero,
runPriv will call listener.succeeded, otherwise runPriv will call
listener.failed. The ResultEvent passed to the listener
will contain the privileged command Process output text as the
result and the privcmd error text as the reason.
- Parameters:
- privcmdName - Name of the privileged command to run.
- taskData - TaskData attributes to be sent to the privileged command
via the command line.
- listener - ResultListener to be notified when the privileged
command completes.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
runPriv
protected OutputStream runPriv(String privcmdName,
TaskData taskData,
ProcessListener listener)
- Subclasses should call this version of runPriv() if the task needs
full control over privileged command input and output and needs to
regain control when the privileged command exits. For example, a task
that runs multiple privileged commands or displays privileged command
output as it arrives would use this version of runPriv().
The subclass is responsible for displaying a busy dialog, if any,
while the privileged command is running, as well as for responding
to privileged command exit (via ProcessListener.processExited())
by calling Task.taskSucceeded() for successful completion or
Task.taskFailed() on failure.
- Parameters:
- privcmdName - Name of the privileged command to run.
- taskData - TaskData attributes to be sent to the privileged command
via the command line.
- listener - A ProcessListener for monitoring privilege command
output and exit status. May not be null.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
runPriv
protected OutputStream runPriv(String privcmdName,
String argString)
- Subclasses should call this version of runPriv() if the task can
be performed by running a single privcmd, the privcmd accepts some
private data (such as passwords) via stdin, and task failure can be
handled by displaying the privcmd output and error text in a standard
error dialog.
runPriv() will post a busy dialog while the privileged command
Process is running. When the privileged command exits,
runPriv() will call taskSucceeded() if the exit code is zero,
or it will call taskFailed().
- Parameters:
- privcmdName - Name of the privileged command to run.
- argString - A String containing the command line arguments
for privileged command.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
runPriv
protected OutputStream runPriv(String privcmdName,
String argString,
ResultListener listener)
- Subclasses should call this version of runPriv() if the multiple
privcmds are needed to accomplish the task or the subclass wants to
regain control after the privcmd completes.
The caller is responsible for posting a busy dialog while the
privileged command(s) run(s), then clearing that dialog and calling
taskSucceeded() or taskFailed() as appropriate when the
privileged command(s) succeed(s) or fail(s).
If the exit code of the privileged command Process is zero,
runPriv will call listener.succeeded, otherwise runPriv will call
listener.failed. The ResultEvent passed to the listener
will contain the privileged command Process output text as the
result and the privcmd error text as the reason.
- Parameters:
- privcmdName - Name of the privileged command to run.
- argString - A String containing the command line arguments
for privileged command.
- listener - ResultListener to be notified when the privileged
command completes.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
runPriv
protected OutputStream runPriv(String privcmdName,
String argString,
ProcessListener listener)
- Subclasses should call this version of runPriv() if the task needs
full control over privileged command input and output and needs to
regain control when the privileged command exits. For example, a task
that runs multiple privileged commands or displays privileged command
output as it arrives would use this version of runPriv().
The subclass is responsible for displaying a busy dialog, if any,
while the privileged command is running, as well as for responding
to privileged command exit (via ProcessListener.processExited())
by calling Task.taskSucceeded() for successful completion or
Task.taskFailed() on failure.
- Parameters:
- privcmdName - Name of the privileged command to run.
- argString - A String containing the command line arguments
for privileged command.
- listener - A ProcessListener for monitoring privilege command
output and exit status. May not be null.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
runPriv
protected OutputStream runPriv(String privcmdName,
String argVector[])
- Subclasses should call this version of runPriv() if the task can
be performed by running a single privcmd, the privcmd accepts some
private data (such as passwords) via stdin, and task failure can be
handled by displaying the privcmd output and error text in a standard
error dialog.
runPriv() will post a busy dialog while the privileged command
Process is running. When the privileged command exits,
runPriv() will call taskSucceeded() if the exit code is zero,
or it will call taskFailed().
- Parameters:
- privcmdName - Name of the privileged command to run.
- argVector - A String array containing the command line arguments
for privileged command.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
runPriv
protected OutputStream runPriv(String privcmdName,
String argVector[],
ResultListener listener)
- Subclasses should call this version of runPriv() if the multiple
privcmds are needed to accomplish the task or the subclass wants to
regain control after the privcmd completes.
The caller is responsible for posting a busy dialog while the
privileged command(s) run(s), then clearing that dialog and calling
taskSucceeded() or taskFailed() as appropriate when the
privileged command(s) succeed(s) or fail(s).
If the exit code of the privileged command Process is zero,
runPriv will call listener.succeeded, otherwise runPriv will call
listener.failed. The ResultEvent passed to the listener
will contain the privileged command Process output text as the
result and the privcmd error text as the reason.
- Parameters:
- privcmdName - Name of the privileged command to run.
- argVector - A String array containing the command line arguments
for privileged command.
- listener - ResultListener to be notified when the privileged
command completes.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
runPriv
protected OutputStream runPriv(String privcmdName,
String argVector[],
ProcessListener listener)
- Subclasses should call this version of runPriv() if the task needs
full control over privileged command input and output and needs to
regain control when the privileged command exits. For example, a task
that runs multiple privileged commands or displays privileged command
output as it arrives would use this version of runPriv().
The subclass is responsible for displaying a busy dialog, if any,
while the privileged command is running, as well as for responding
to privileged command exit (via ProcessListener.processExited())
by calling Task.taskSucceeded() for successful completion or
Task.taskFailed() on failure.
- Parameters:
- privcmdName - Name of the privileged command to run.
- argVector - A String array containing the command line arguments
for privileged command.
- listener - A ProcessListener for monitoring privilege command
output and exit status. May not be null.
- Returns:
- An OutputStream that clients can use to send private data or
control data to the privileged command. The caller is
responsible for closing the OutputStream.
waitForEvent
protected void waitForEvent(ResultListener listener,
Category category,
ItemTester tester,
int eventType)
- Wait for an event on a specific Item. The Category & ItemTester
identify the Item, and the
eventType
indicates
whether to wait for an add, a change, or a removal.
If the expected event is EVENT_TYPE_ADD, listener.succeeded() is called
when an Item matching the ItemTester is added, or if it's already in the
Category.
If the expected event is EVENT_TYPE_CHANGE, listener.succeeded() is
called when an Item is changed to match the ItemTester, or if an item
matching the ItemTester is already in the Category.
If the expected event is EVENT_TYPE_REMOVE, listener.succeeded() is
called when an Item matching the ItemTester is removed, or if the item
isn't already in the Category when monitoring begins.
If the expected event is EVENT_TYPE_NONE, this method will assert out.
- Parameters:
- listener - The ResultListener to call succeeded() on when the
expected event is received, or failed() on if the event
isn't received within Task.eventTimeout
seconds. Must not be null.
- category - The Category to listen on for events. May not be null.
- tester - The ItemTester which will identify the Item on which we're
waiting for the event on. Must not be null.
- eventType - The type of event we're waiting for. Must be
EVENT_TYPE_ADD, EVENT_TYPE_CHANGE, or EVENT_TYPE_REMOVE.
checkPrivs
protected void checkPrivs(TaskLoader tasks[],
ResultListener listener)
- Checks all privileges needed for several tasks. It gets all of
the privileges out of all of the ResourceFiles and checks them
all in one batch. If any privilege is not granted,
listener.failed() will be called.
- Parameters:
- tasks - An array of task loaders
- listener - The listener to notify of success or failure.
All Packages Class Hierarchy This Package Previous Next Index