live.threads
Class ThreadedUserAction

java.lang.Object
  extended byjava.lang.Thread
      extended bylive.threads.ThreadedUserAction
All Implemented Interfaces:
Runnable
Direct Known Subclasses:
Runner, ThreadedZVMTasks.ActiveImagesQuery, ThreadedZVMTasks.Authenticate, ThreadedZVMTasks.ChangeMemory, ThreadedZVMTasks.ChangePassword, ThreadedZVMTasks.CloneGuest, ThreadedZVMTasks.CreateGuest, ThreadedZVMTasks.CreateMinidisk, ThreadedZVMTasks.CreateVSwitch, ThreadedZVMTasks.DeleteGuest, ThreadedZVMTasks.DeleteMinidisk, ThreadedZVMTasks.FindCommonFreeAddress, ThreadedZVMTasks.GetGroups, ThreadedZVMTasks.ImageActivate, ThreadedZVMTasks.ImageDeactivate, ThreadedZVMTasks.QueryAllGuestNames, ThreadedZVMTasks.QueryAllNetworks, ThreadedZVMTasks.QueryGuestInfo, ThreadedZVMTasks.QueryMinidisks, ThreadedZVMTasks.QueryNetworkMembers, ThreadedZVMTasks.QuerySharedStorage, ThreadedZVMTasks.SetGuestToGroup, ThreadedZVMTasks.SharedStorageAccessAdd, ThreadedZVMTasks.SharedStorageAccessQuery, ThreadedZVMTasks.SharedStorageAccessQueryNameList, ThreadedZVMTasks.SharedStorageAccessRemove, ThreadedZVMTasks.SharedStorageCreate, ThreadedZVMTasks.SharedStorageDelete, ThreadedZVMTasks.VSwitchCreateConnect, ThreadedZVMTasks.VSwitchDelete, ThreadedZVMTasks.VSwitchDetatch, WaitAction

public abstract class ThreadedUserAction
extends Thread

This function serves as a base class for all of the classes that will actually do useful work. For each action you want the user to be able to do, subclass this and implement three functions:

  1. runImpl()should perform the action
  2. description()should return a one-line summary of what is being done
  3. result()should return the, well, result of the operation once it is finished, or null if it is sitll ongoing.
When you want to start the task in a new thread, call one of startJoinForever(),startJoinTimeout(int), or startNoJoin(). (You could also call the inherited Thread.start()or run(), but in any application that uses any of the three custom functions it is recommended that the programmer use only those three to be consistant and even with the naming conventions.) Because most of what the subclass will be doing will require parameters, you have to set them in fields before calling Thread.start(), just like you do with any other thread. Finally, for any subclasses that use the ZVMTasks library, call init(ThreadInitInfo)before starting the action. (Probably do this in the constructor.) Then your subclass can simply use the protected field tasksto call the method(s). You could go through the process of making your subclass keep track of the appropriate info, but why do that when it's done for you? It is okay to pass init(ThreadInitInfo)a null parameter, or for either of the pieces of information in ThreadInitInfoto be null, but it's expected that this will be the case only in testing (for instance, the WaitActionclass) and possibly other exceptional situations.


Nested Class Summary
private static class ThreadedUserAction.IDFactory
          This is a wrapper class for an int; Integer won't work because you can't change it; See the init function for a discussion of why this is (or rather, may be) necessary.
 
Field Summary
private  ActiveThreadsInfo activeThreadLists
           
private  Cache cache
           
static int CANCELED
           
static int COMPLETE
           
protected  boolean done
           
static int ERROR
           
private  Exception exception
           
static int IN_PROGRESS
           
static int INDETERMINATE
           
private static ThreadedUserAction.IDFactory nextFreeID
           
static int PENDING
           
private  String resultString
           
private  int status
           
protected  ZVMTasks tasks
          If init(ThreadInitInfo)has been called with a non-null argument for which ThreadInitInfo.getConnectionInfo()is non-null, this will reference a ZVMTasks object which will make the connection to the server with the authentication parameters defined in init(ThreadInitInfo)'s connectionInfo#getConnectionInfo().
private  int thisThreadsID
           
private  Date timeEnded
           
private  Date timeStarted
           
private  boolean track
           
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
ThreadedUserAction()
           
 
Method Summary
abstract  String description()
          This method returns a friendly description of the action the object represents.
protected  Cache getCache()
          Returns the cache
 Exception getException()
          Returns the exception thrown
 int getID()
          Returns the ID of the thread
 int getStatus()
          Returns the status.
 Date getTimeFinished()
          This method returns the time at which the thread finished its task and died.
 Date getTimeStarted()
          This method returns the time at which the thread was started.
 void init(ThreadInitInfo initInfo)
          Sets the object that tracks the threads.
 void init(ThreadInitInfo initInfo, boolean list)
          Sets the object that tracks the threads.
 boolean isFinished()
          Whether the thread is finished.
abstract  Object rawResult()
          This returns the result of the call in a manner that is defined by the subclass.
 String result()
          This returns the result in some manner or other.
 void run()
          This should be not called by hand under most circumstances [OPTIONAL: except for queries].
protected abstract  void runImpl()
          This function should be implemented to do whatever task the class was created to do.
 void setCanceled()
          Sets the status and resultString to canceled.
 void setComplete()
          Sets status and resultString to Complete.
 void setError()
          Sets the status and resultString to Error
 void setError(Exception e)
          Sets the status to error and the resultString to a specified message
 void setIndeterminate()
          Sets status and resultString to Indeterminate.
 void setIndeterminate(String message)
          Sets the status of a task to indeterminate and the resultString to a specified message
 void setInProgress()
          Sets status and resultString to In Progress.
 void startJoinForever()
          This function begins the action, returning when it completes.
 boolean startJoinTimeout(int timeout_ms)
          This function begins the action, returning when it completes, unless it takes more than timeout_ms milliseconds, in which case it returns at that point.
 void startNoJoin()
          This function begins the action, returning immediately.
 String toString()
          This method returns a friendly description of the action the object represents.
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

timeStarted

private Date timeStarted

timeEnded

private Date timeEnded

activeThreadLists

private ActiveThreadsInfo activeThreadLists

cache

private Cache cache

tasks

protected ZVMTasks tasks
If init(ThreadInitInfo)has been called with a non-null argument for which ThreadInitInfo.getConnectionInfo()is non-null, this will reference a ZVMTasks object which will make the connection to the server with the authentication parameters defined in init(ThreadInitInfo)'s connectionInfo#getConnectionInfo().


done

protected boolean done

track

private boolean track

nextFreeID

private static ThreadedUserAction.IDFactory nextFreeID

thisThreadsID

private int thisThreadsID

exception

private Exception exception

PENDING

public static final int PENDING
See Also:
Constant Field Values

IN_PROGRESS

public static final int IN_PROGRESS
See Also:
Constant Field Values

COMPLETE

public static final int COMPLETE
See Also:
Constant Field Values

ERROR

public static final int ERROR
See Also:
Constant Field Values

CANCELED

public static final int CANCELED
See Also:
Constant Field Values

INDETERMINATE

public static final int INDETERMINATE
See Also:
Constant Field Values

status

private int status

resultString

private String resultString
Constructor Detail

ThreadedUserAction

public ThreadedUserAction()
Method Detail

init

public final void init(ThreadInitInfo initInfo,
                       boolean list)
Sets the object that tracks the threads.

Parameters:
initInfo - The object with server login information and thread lists
list - Should this thread be included in the ActiveThreadsInfo lists

init

public final void init(ThreadInitInfo initInfo)
Sets the object that tracks the threads.

Parameters:
initInfo - The object with server login information and thread lists

getTimeStarted

public Date getTimeStarted()
This method returns the time at which the thread was started. (Since it would technically be possible for a thread to be started multiple times from the same object, it returns the last time the thread was started.)

Returns:
The time at which the thread was last started
See Also:
getTimeFinished()

getTimeFinished

public Date getTimeFinished()
This method returns the time at which the thread finished its task and died. (Like getTimeStarted(), technically this is the last time the thread died.

Returns:
The time at which the thread last died
See Also:
getTimeStarted()

toString

public String toString()
This method returns a friendly description of the action the object represents. This is more meant for errors and such (not SMAPI errors, coding errors) where the toString()method is called automatically, so the description is prepended with the class name. For the description without this prefix, such as for displaying the status page, use the abstract description()method instead.

Returns:
A human-readable summary of the action being performed, prefixed with "ThreadedUserAction: "
See Also:
description()

run

public void run()
This should be not called by hand under most circumstances [OPTIONAL: except for queries]. This function is mostly a possthrough to the abstract runImpl(), but also sets the starting and ending times. Instead of calling this, you probably want to call Thread.start(), which will start a new thread and begin executing run()there.

See Also:
runImpl(), Thread.start()

runImpl

protected abstract void runImpl()
                         throws Exception
This function should be implemented to do whatever task the class was created to do. You shouldn't call this function yourself; it's called automatically by run(). (But you probably shouldn't call run()yourself either.)

Throws:
Exception
See Also:
run()

description

public abstract String description()
This method returns a friendly description of the action the object represents. Unlike the toString()method, this is meant to be used in, for example, the status page and anywhere else where the end user will see it.

Returns:
A human-readable summary of the action being performed
See Also:
toString()

result

public String result()
This returns the result in some manner or other. It should be suitable for display in the status page. May return HTML that can appear as the child of TD tags.

Returns:
String result

rawResult

public abstract Object rawResult()
This returns the result of the call in a manner that is defined by the subclass. It should probably simply pass through the return value from the ZVMTasks call.

Returns:
The result of the action. (See subclasses for individual definitions.)

startJoinForever

public void startJoinForever()
This function begins the action, returning when it completes. It is equivalent to calling either: 1.run()(which does not start a new thread, avoiding the oveheard of going to the JVM; the current implementation), or 2.Thread.start()then Thread.join(), which starts the thread and then joins the calling and action threads until the latter dies. (Actually, the two methods are not exactly equivalent, as you can interrput a thread that's running, causing join to throw an InterruptedException exception. There is no equivalent to this with #1 above. However, I'm pretty sure this exception should never be raised.)


startJoinTimeout

public boolean startJoinTimeout(int timeout_ms)
This function begins the action, returning when it completes, unless it takes more than timeout_ms milliseconds, in which case it returns at that point.

Returns:
True if the thread finished before the timeout expired

isFinished

public boolean isFinished()
Whether the thread is finished.

Returns:
boolean

startNoJoin

public void startNoJoin()
This function begins the action, returning immediately. It is equivalent to simply calling Thread.start().


getID

public int getID()
Returns the ID of the thread

Returns:
int Thread's ID

setInProgress

public void setInProgress()
Sets status and resultString to In Progress.


setComplete

public void setComplete()
Sets status and resultString to Complete.


setIndeterminate

public void setIndeterminate()
Sets status and resultString to Indeterminate.


setIndeterminate

public void setIndeterminate(String message)
Sets the status of a task to indeterminate and the resultString to a specified message

Parameters:
message - Message to display

setError

public void setError()
Sets the status and resultString to Error


setError

public void setError(Exception e)
Sets the status to error and the resultString to a specified message

Parameters:
e - Exception to get the error message from

setCanceled

public void setCanceled()
Sets the status and resultString to canceled.


getStatus

public int getStatus()
Returns the status.

Returns:
int status

getCache

protected Cache getCache()
Returns the cache

Returns:
Cache

getException

public Exception getException()
Returns the exception thrown

Returns:
Exception


Copyright © 2005