com.sun.slamd.job
Class JobClass

java.lang.Object
  java.lang.Thread
      com.sun.slamd.job.JobClass

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

ADAddAndDelRateJobClass, ADAddRateJobClass, ADDelRateJobClass, AddRateJobClass, ADModRateJobClass, AuthRateJobClass, BSFJobClass, CalendarInitialPageRateJobClass, CombinedAddAndDelRateJobClass, CompRateJobClass, DelRateJobClass, DigestMD5AuthRateJobClass, ExecJobClass, HTTPGetRateJobClass, IdentityServerJobClass, IMAPCheckRateJobClass, ISAuthRateJobClass, ISJobClass, ISWLatencyCheckJobClass, LDAPLoadJobClass, LDAPPrimeJobClass, LDIF2DBImportRateJobClass, LoadVarianceJobClass, LogPlaybackJobClass, ModRateJobClass, MultiSearchLDAPLoadJobClass, NTAddAndDelRateJobClass, NTAddRateJobClass, NTDelRateJobClass, NTModRateJobClass, NullJobClass, POPCheckRateJobClass, RawSiteMinderJobClass, ReplicaLatencyCheckJobClass, ScriptedJobClass, SearchAndModJobClass, SearchRateJobClass, SiteMinderJobClass, SMTPSendRateJobClass, SolarisLDAPAuthRateJobClass, SQLModRateJobClass, SQLSearchRateJobClass, TCPReplayJobClass, TemplateBasedAddAndDelRateJobClass, TemplateBasedAddRateJobClass, ThroughputTestJobClass, WeightedAuthRateJobClass, WeightedLDAPLoadJobClass, WeightedModRateJobClass, WeightedSearchAndModJobClass, WeightedSearchRateJobClass, WeightedSiteMinderJobClass

public abstract class JobClass

extends java.lang.Thread

This class implements a thread that may be executed as a SLAMD job. Depending on the job configuration, multiple instances of this thread may operate concurrently on the same machine or across multiple machines. Anyone that wishes to implement their own custom job for SLAMD should only need to extend this class.

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

protected

JobClass() Creates a new job thread that is not running and that has not been requested to stop.

Method Summary

void	destroy() Provides a means for destroying this job thread if it does not respond to a graceful shutdown request.
boolean	enableRealTimeStats() Indicates whether real-time statistics collection has been enabled in the client with which this job is associated.
void	finalizeClient() Performs any per-client finalization that should be done for this job.
void	finalizeJob() Performs any per-job finalization that should be done for this job.
void	finalizeThread() Performs any per-thread finalization that should be done for this job.
int	getActiveThreadCount() Retrieves the number of threads that are currently active for this job.
java.lang.String	getClientID() Retrieves the client ID for this job thread.
int	getClientNumber() Retrieves the client number associated with this job thread.
ClientSideJob	getClientSideJob() Retrieves the client side job associated with this job class.
ParameterList	getClientSideParameterStubs() Retrieves a list of parameter "stubs" that specify all the parameters that should be available to clients.
int	getCollectionInterval() Retrieves the collection interval for this job thread.
java.lang.String	getJobCategoryName() Retrieves the name of the category in which this job class exists.
abstract java.lang.String	getJobDescription() Retrieves a description of the job performed by this job thread.
java.lang.String	getJobID() Retrieves the job ID of the job with which this job thread is currently associated.
abstract java.lang.String	getJobName() Retrieves the name of the job performed by this job thread.
abstract ParameterList	getParameterStubs() Retrieves a list of parameter "stubs" that should be used to indicate which parameters should be passed to the initialize method.
int	getScheduledDuration() Retrieves the scheduled duration for this job thread.
long	getShouldStopTime() Retrieves the time at which this job should stop, either because of the duration or the stop time.
RealTimeStatReporter	getStatReporter() Retrieves the real-time stat reporter that should be used for this job.
abstract StatTracker[]	getStatTrackers() Retrieves the stat trackers that are maintained for this job thread.
abstract StatTracker[]	getStatTrackerStubs(java.lang.String clientID, java.lang.String threadID, int collectionInterval) Retrieves the set of stat trackers that will be maintained by this job class.
java.lang.String	getThreadID() Retrieves the thread ID for this job thread.
int	getThreadNumber() Retrieves the thread number associated with this job thread.
void	indicateCompletedWithErrors() Indicates that this job thread has completed, but there were errors that may impact how the results should be interpreted.
void	indicateStoppedDueToError() Indicates that this job thread has been stopped because of an unrecoverable error.
void	initializeClient(java.lang.String clientID, ParameterList parameters) Performs initialization for this job on each client immediately before each thread is created to actually run the job.
void	initializeJob(ParameterList parameters) Performs a one-time initialization for this job.
void	initializeJobThread(java.lang.String clientID, java.lang.String threadID, int collectionInterval, ClientSideJob job, int duration, java.util.Date stopTime, long startTimeMillis, ParameterList parameters) Provides the job thread with all of the information that it needs to run.
abstract void	initializeThread(java.lang.String clientID, java.lang.String threadID, int collectionInterval, ParameterList parameters) Initializes this job thread to be used to actually run the job on the client.
boolean	isDeprecated(java.lang.StringBuffer message) Indicates whether this job class is deprecated.
boolean	isRunning() Indicates whether the job is currently running.
void	logMessage(java.lang.String message) Sends a status message regarding the progress of this job thread to the parent job so that it can be recorded in the SLAMD logger.
int	overrideCollectionInterval() Provides a means for job classes to have a level of control over the statistics collection interval that will be used for a job.
int	overrideNumClients() Provides a means for job classes to have a level of control over the number of clients that will be used to run a job.
int	overrideThreadsPerClient() Provides a means for job classes to have a level of control over the number of threads per client that will be used to run a job.
boolean	providesParameterTest() Indicates whether this job class implements logic that makes it possible to test the validity of job parameters before scheduling the job for execution (e.g., to see if the server is reachable using the information provided).
void	run() A wrapper for the runJob method (which actually does the real work for this job thread).
abstract void	runJob() The method that does all the real work for this job.
void	setClientNumber(int clientNumber) Specifies the client number to use for this job thread.
void	setClientSideJob(ClientSideJob job) Sets the client-side job that should be associated with this job class.
void	setThreadNumber(int threadNumber) Specifies the thread number for this job thread.
boolean	shouldStop() Indicates whether the job should stop processing for any reason.
static java.lang.String	stackTraceToString(java.lang.Exception e) Retrieves a string representation of the stack trace contained in the provided exception.
void	startJob() Indicates that the job should start running.
void	stopAndWait(int stopReason) Requests that the job stop running at the earliest convenient time, and then waits until the job has stopped completely.
void	stopJob(int stopReason) Requests that the job stop running at the earliest convenient time.
boolean	stopRequested() Indicates whether a request has been made to stop the job from an external source (e.g., from a call to the stopJob method).
boolean	testJobParameters(ParameterList parameters, java.util.ArrayList outputMessages) Provides a means of testing the provided job parameters to determine whether they are valid (e.g., to see if the server is reachable) before scheduling the job for execution.
void	validateJobInfo(int numClients, int threadsPerClient, int threadStartupDelay, java.util.Date startTime, java.util.Date stopTime, int duration, int collectionInterval, ParameterList parameters) Provides a means of validating the information used to schedule the job, including the scheduling information and list of parameters.
void	writeVerbose(java.lang.String message) Writes a message to the client message writer so that if it is running in verbose mode this information will be available to that client.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, 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, toString, yield

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JobClass

protected JobClass()

Creates a new job thread that is not running and that has not been requested to stop. This should be invoked by the constructor of all subclasses.

Method Detail

getJobName

public abstract java.lang.String getJobName()

Retrieves the name of the job performed by this job thread.

Returns:

The name of the job performed by this job thread.

getJobDescription

public abstract java.lang.String getJobDescription()

Retrieves a description of the job performed by this job thread.

Returns:

A description of the job performed by this job thread.

getJobCategoryName

public java.lang.String getJobCategoryName()

Retrieves the name of the category in which this job class exists. This is used to help arrange the job classes in the administrative interface.

Returns:

The name of the category in which this job class exists.

overrideNumClients

public int overrideNumClients()

Provides a means for job classes to have a level of control over the number of clients that will be used to run a job. If a job class implements this method and returns a value greater than 0, then that number of clients will always be used to run the job, and the form allowing the user to schedule a job will not show the "Number of Clients" field. By default, the user will be allowed to choose the number of clients.

Returns:

The number of clients that should be used to run this job, or -1 if the user should be allowed to specify the number of clients.

overrideThreadsPerClient

public int overrideThreadsPerClient()

Provides a means for job classes to have a level of control over the number of threads per client that will be used to run a job. If a job class implements this method and returns a value greater than 0, then that number of threads per client will always be used to run the job, and the form allowing the user to schedule a job will not show the "Threads per Client" field. By default, the user will be allowed to choose the number of threads per client.

Returns:

The number of threads per client that should be used to run this job, or -1 if the user should be allowed to specify the number of threads per client.

overrideCollectionInterval

public int overrideCollectionInterval()

Provides a means for job classes to have a level of control over the statistics collection interval that will be used for a job. If a job class implements this method and returns a value greater than 0, then that collection interval will always be used to run the job, and the form that allows the user to schedule a job will not show the "Statistics Collection Interval" field. By default, the user will be allowed to choose the statistics collection interval.

Returns:

The collection interval that should be used for this job, or -1 if the user should be allowed to specify the collection interval.

getParameterStubs

public abstract ParameterList getParameterStubs()

Retrieves a list of parameter "stubs" that should be used to indicate which parameters should be passed to the initialize method. These stubs do not need to have values (although they can be given default values).

Returns:

A list of the parameter stubs that can be used to determine which parameters must/may be provided to the initialize method.

getClientSideParameterStubs

public ParameterList getClientSideParameterStubs()

Retrieves a list of parameter "stubs" that specify all the parameters that should be available to clients. This will generally be exactly the same as the list returned by the getParameterStubs method, but in some cases the list of parameters scheduled in the configuration directory may differ a little (e.g., to be able to handle dynamically-generated parameters created at the time the job is scheduled).

Returns:

A list of parameter "stubs" that specify all the parameters that should be available to clients.

getStatTrackerStubs

public abstract StatTracker[] getStatTrackerStubs(java.lang.String clientID,
                                                  java.lang.String threadID,
                                                  int collectionInterval)

Retrieves the set of stat trackers that will be maintained by this job class. The stat trackers returned by this method do not have to actually contain any statistics -- the display name and stat tracker class should be the only information that callers of this method should rely upon. Note that this list can be different from the list of statistics actually collected by the job in some cases (e.g., if the job may not return all the stat trackers it advertises in all cases, or if the job may return stat trackers that it did not advertise), but it is a possibility that only the stat trackers returned by this method will be accessible for some features in the SLAMD server.

Parameters:

clientID - The client ID that should be used for the returned stat trackers.

threadID - The thread ID that should be used for the returned stat trackers.

collectionInterval - The collection interval that should be used for the returned stat trackers.

Returns:

The set of stat trackers that will be maintained by this job class.

getStatTrackers

public abstract StatTracker[] getStatTrackers()

Retrieves the stat trackers that are maintained for this job thread.

Returns:

The stat trackers that are maintained for this job thread.

getClientNumber

public int getClientNumber()

Retrieves the client number associated with this job thread. This provides a rudimentary capability for a job to have different behaviors on different clients. The first client that receives a job request will be client 0, the next will be client 1, etc.

Returns:

The client number associated with this job thread.

setClientNumber

public void setClientNumber(int clientNumber)

Specifies the client number to use for this job thread.

Parameters:

clientNumber - The client number to use for this job thread.

getThreadNumber

public int getThreadNumber()

Retrieves the thread number associated with this job thread. Note that this value is the thread number for this client. Other clients will have a thread with the same thread number.

Returns:

The thread number associated with this job thread.

setThreadNumber

public void setThreadNumber(int threadNumber)

Specifies the thread number for this job thread.

Parameters:

threadNumber - The thread number to use for this job thread.

validateJobInfo

public void validateJobInfo(int numClients,
                            int threadsPerClient,
                            int threadStartupDelay,
                            java.util.Date startTime,
                            java.util.Date stopTime,
                            int duration,
                            int collectionInterval,
                            ParameterList parameters)
                     throws InvalidValueException

Provides a means of validating the information used to schedule the job, including the scheduling information and list of parameters.

Parameters:

numClients - The number of clients that should be used to run the job.

threadsPerClient - The number of threads that should be created on each client to run the job.

threadStartupDelay - The delay in milliseconds that should be used when starting the client threads.

startTime - The time that the job should start running.

stopTime - The time that the job should stop running.

duration - The maximum length of time in seconds that the job should be allowed to run.

collectionInterval - The collection interval that should be used when gathering statistics for the job.

parameters - The set of parameters provided to this job that can be used to customize its behavior.

Throws:

InvalidValueException - If the provided information is not appropriate for running this job.

providesParameterTest

public boolean providesParameterTest()

Indicates whether this job class implements logic that makes it possible to test the validity of job parameters before scheduling the job for execution (e.g., to see if the server is reachable using the information provided). By default, this method returns false to indicate that this is not provided, but actual implementations may override this method to return true and should also override the testJobParameters method to implement the actual test.

Returns:

true if this job provides a means of testing the job parameters, or false if not.

testJobParameters

public boolean testJobParameters(ParameterList parameters,
                                 java.util.ArrayList outputMessages)

Provides a means of testing the provided job parameters to determine whether they are valid (e.g., to see if the server is reachable) before scheduling the job for execution. This method will be executed by the SLAMD server system itself and not by any of the clients.

Parameters:

parameters - The job parameters to be tested.

outputMessages - The lines of output that were generated as part of the testing process. Each line of output should be added to this list as a separate string, and empty strings (but not null values) are allowed to provide separation between different messages. No formatting should be provided for these messages, however, since they may be displayed in either an HTML or plain text interface.

Returns:

true if the test completed successfully, or false if not. Note that even if the test did not complete successfully, the user will be presented with a warning but will still be allowed to schedule the job using the provided parameters. This is necessary because the parameters may still be valid even if the server couldn't validate them at the time the job was scheduled (e.g., if the server wasn't running or could not be reached by the SLAMD server even though it could be by the clients).

isDeprecated

public boolean isDeprecated(java.lang.StringBuffer message)

Indicates whether this job class is deprecated. If it is deprecated, then a warning will be displayed whenever the user attempts to schedule the job. A job that is deprecated will not behave any differently, but merely serves as a warning that a better option may exist for the same type of test.

Parameters:

message - The buffer to which a message may be appended that provides additional information about the deprecation.

Returns:

true if this job class has been deprecated, or false if not.

initializeJob

public void initializeJob(ParameterList parameters)
                   throws UnableToRunException

Performs a one-time initialization for this job. This initialization is performed on the SLAMD server immediately before the job is sent to the clients for processing. Note that the work performed by this method should only be in the form of interaction with something external. Changes to instance variables or other items internal to this method will not be reflected on clients.

Parameters:

parameters - The set of parameters provided to this job that can be used to customize its behavior.

Throws:

UnableToRunException - If the job initialization could not be completed successfully and the job is unable to run.

initializeClient

public void initializeClient(java.lang.String clientID,
                             ParameterList parameters)
                      throws UnableToRunException

Performs initialization for this job on each client immediately before each thread is created to actually run the job. Note that if any changes are to be made to variables that should be available to the individual threads, then those variables should be declared as static.

Parameters:

clientID - The ID assigned to the client running this job.

parameters - The set of parameters provided to this job that can be used to customize its behavior.

Throws:

UnableToRunException - If the client initialization could not be completed successfully and the job is unable to run.

initializeThread

public abstract void initializeThread(java.lang.String clientID,
                                      java.lang.String threadID,
                                      int collectionInterval,
                                      ParameterList parameters)
                               throws UnableToRunException

Initializes this job thread to be used to actually run the job on the client. The provided parameter list should be processed to customize the behavior of this job thread, and any other initialization that needs to be done in order for the job to run should be performed here as well (e.g., creating and initializing the status counters).

Parameters:

clientID - The client ID for this job thread.

threadID - The thread ID for this job thread.

collectionInterval - The length of time in seconds to use as the statistics collection interval.

parameters - The set of parameters provided to this job that can be used to customize its behavior.

Throws:

UnableToRunException - If the thread initialization could not be completed successfully and the job is unable to run.

runJob

public abstract void runJob()

The method that does all the real work for this job. It performs the task associated with the job thread based on the information provided through the parameter list passed into the initialize method.

getActiveThreadCount

public int getActiveThreadCount()

Retrieves the number of threads that are currently active for this job.

Returns:

The number of threads that are currently active for this job.

finalizeThread

public void finalizeThread()

Performs any per-thread finalization that should be done for this job. By default, no action is performed.

finalizeClient

public void finalizeClient()

Performs any per-client finalization that should be done for this job. By default, no action is performed.

finalizeJob

public void finalizeJob()

Performs any per-job finalization that should be done for this job. By default, no action is performed.

initializeJobThread

public final void initializeJobThread(java.lang.String clientID,
                                      java.lang.String threadID,
                                      int collectionInterval,
                                      ClientSideJob job,
                                      int duration,
                                      java.util.Date stopTime,
                                      long startTimeMillis,
                                      ParameterList parameters)
                               throws UnableToRunException

Provides the job thread with all of the information that it needs to run. This should be extended by actual job thread implementations, but the version in this method should always be invoked first using super.initialize(threadID, job, parameters) before any custom code.

Parameters:

clientID - The client ID that will be used to identify the client to the parent job.

threadID - The thread ID that will be used to identify this thread to the parent job.

collectionInterval - The interval in seconds that should be used when gathering statistics during job processing.

job - The parent job that is controlling this thread.

duration - The length of time in seconds that the job should be allowed to run. A value of -1 indicates an unlimited duration.

stopTime - The time at which the job should stop running. A value of null indicates no specified stop time.

startTimeMillis - The time this thread should start running in milliseconds since January 1, 1970.

parameters - The list of parameters (containing values) that should be used to control the operation of this job.

Throws:

UnableToRunException

getClientSideJob

public final ClientSideJob getClientSideJob()

Retrieves the client side job associated with this job class.

Returns:

The client side job associated with this job class.

setClientSideJob

public final void setClientSideJob(ClientSideJob job)

Sets the client-side job that should be associated with this job class.

Parameters:

job - The client-side job that should be associated with this job class.

getJobID

public java.lang.String getJobID()

Retrieves the job ID of the job with which this job thread is currently associated.

Returns:

The job ID of the job with which this job thread is currently associated, or null if this thread is not associated with any job.

getClientID

public final java.lang.String getClientID()

Retrieves the client ID for this job thread.

Returns:

The client ID for this job thread.

getThreadID

public final java.lang.String getThreadID()

Retrieves the thread ID for this job thread.

Returns:

The thread ID for this job thread.

getCollectionInterval

public final int getCollectionInterval()

Retrieves the collection interval for this job thread.

Returns:

The collection interval for this job thread.

getScheduledDuration

public final int getScheduledDuration()

Retrieves the scheduled duration for this job thread.

Returns:

The scheduled duration for this job thread.

getShouldStopTime

public final long getShouldStopTime()

Retrieves the time at which this job should stop, either because of the duration or the stop time.

Returns:

The time at which this job should stop, either because of the duration or the stop time.

startJob

public final void startJob()
                    throws AlreadyRunningException

Indicates that the job should start running. It performs some necessary administrative work and then starts the job thread. This may not be overridden by subclasses, so any work that is intended to be done before the job actually starts should be done in the initialize method.

Throws:

AlreadyRunningException - If this job thread is already running.

stopJob

public final void stopJob(int stopReason)

Requests that the job stop running at the earliest convenient time. There is no guarantee that the job has actually stopped running by the time that this method returns.

Parameters:

stopReason - The reason that the job should stop running.

stopAndWait

public final void stopAndWait(int stopReason)

Requests that the job stop running at the earliest convenient time, and then waits until the job has stopped completely. When this method returns, it is safe to assume that the job is no longer running.

Parameters:

stopReason - The reason that the job should stop running.

isRunning

public final boolean isRunning()

Indicates whether the job is currently running.

Returns:

true if the job is running, or false if it is not.

stopRequested

public final boolean stopRequested()

Indicates whether a request has been made to stop the job from an external source (e.g., from a call to the stopJob method). Note that there may be other reasons that the job should stop running (for example, if a time limit has been set and has been reached). Therefore, the shouldStop method should be used to determine whether the job should stop processing altogether.

Returns:

true if a request has been made to stop this job, or false if not.

shouldStop

public final boolean shouldStop()

Indicates whether the job should stop processing for any reason. This should be checked periodically from the runJob method to determine whether it is time to stop running.

Returns:

true if the job should stop running, or false if there is no reason for it to stop.

enableRealTimeStats

public final boolean enableRealTimeStats()

Indicates whether real-time statistics collection has been enabled in the client with which this job is associated.

Returns:

true if the associated client has enabled real-time statistics collection, or false if not.

getStatReporter

public final RealTimeStatReporter getStatReporter()

Retrieves the real-time stat reporter that should be used for this job.

Returns:

The real-time stat reporter that should be used for this job, or null if none should be used.

destroy

public void destroy()

Provides a means for destroying this job thread if it does not respond to a graceful shutdown request. The default implementation does nothing, but an actual job class may wish to do something like close a connection to a remote server that could cause the thread to terminate.

indicateCompletedWithErrors

public final void indicateCompletedWithErrors()

Indicates that this job thread has completed, but there were errors that may impact how the results should be interpreted.

indicateStoppedDueToError

public final void indicateStoppedDueToError()

Indicates that this job thread has been stopped because of an unrecoverable error.

writeVerbose

public final void writeVerbose(java.lang.String message)

Writes a message to the client message writer so that if it is running in verbose mode this information will be available to that client. This message will not be displayed if the client is not operating in verbose mode, nor will it be sent back to the SLAMD server to be included in the log.

Parameters:

message - The message to be written.

logMessage

public final void logMessage(java.lang.String message)

Sends a status message regarding the progress of this job thread to the parent job so that it can be recorded in the SLAMD logger. It will be logged using a job status log level (which is enabled by default), so only significant events (e.g., exceptions) should be announced using this method. Less significant events should be logged using the logVerboseStatusMessage method.

Parameters:

message - The message to be logged.

run

public final void run()

A wrapper for the runJob method (which actually does the real work for this job thread). It takes care of setting a flag used to determine if the job is currently running or not, and will properly unset it when the job is no longer running, even if it stopped running because of an uncaught exception. This method may not be overridden by subclasses.

stackTraceToString

public static java.lang.String stackTraceToString(java.lang.Exception e)

Retrieves a string representation of the stack trace contained in the provided exception.

Parameters:

e - The exception for which to retrieve the stack trace.

Returns:

The string representation