T
- the result type returned by doInBackground
and
get
methods in this classpublic abstract class SandboxWorker<T>
extends java.lang.Object
MetadataEnvironmentThread
that provides a neutral metadata
environment which is not tied to any sandbox. To run a task using this
class, create a subclass and place the task in doInBackground
method, create an instance of the subclass and invoke execute()
.
logException()
may be overridden.
A SandboxWorker
is designed to be executed only once.
Executing a SandboxWorker
more than once will not result in
invoking the doInBackground
method twice.
Constructor and Description |
---|
SandboxWorker()
Constructs a new instance with a randomly generated tracking ID.
|
SandboxWorker(java.lang.String trackingId)
Constructs a new instance with an optional tracking ID.
|
Modifier and Type | Method and Description |
---|---|
static boolean |
beginFineTrace(java.lang.String tracerName)
Begins tracing if
FINE is loggable. |
static boolean |
beginFineTrace(java.lang.String tracerName,
java.lang.String sandboxId)
Begins tracing for a sandbox if
FINE is loggable. |
static boolean |
beginTrace(java.util.logging.Level loggingLevel,
java.lang.String tracerName)
Begins tracing if the logging level is loggable.
|
protected abstract T |
doInBackground()
Runs the task and returns the result, or throws an exception
when necessary.
|
static boolean |
endTrace()
Stops tracing the current thread.
|
void |
execute()
Schedules the task for execution in a background thread.
|
static void |
fineTrace(java.lang.Object obj,
java.lang.String message)
Traces the current flow with a message logged at
FINE level. |
static void |
fineTraceADFContext(java.lang.Object obj,
java.lang.String message)
Traces the state of the
ADFContext and its associated objects
in the current flow and logs the information at FINE level. |
T |
get()
Waits if necessary for the task to complete, and returns the result.
|
T |
get(long timeout,
java.util.concurrent.TimeUnit unit)
Waits if necessary for at most the given time for the task to complete,
and returns the result.
|
java.lang.String |
getTrackingId()
Returns the tracking ID (which is never null) associated with this object.
|
static java.lang.String |
getTrackingIdFromCurrentThread()
Returns the tracking ID from the current thread if the current thread was
started by a
SandboxWorker . |
boolean |
isDone()
Returns
true if this task completed, including the case when
an exception is thrown. |
static boolean |
isFineTracing()
Returns
true if FINE is loggable and there is
a tracer associated with the current thread. |
boolean |
isStarted()
Returns
true if this task has been started. |
static boolean |
isTracing(java.util.logging.Level loggingLevel)
Returns
true if the logging level is loggable and there is
a tracer associated with the current thread. |
protected void |
logException(java.lang.Exception e)
Logs the exception thrown by
doInBackground() if any. |
protected MetadataEnvironmentThread.Resources |
newWorkerThreadResources(MetadataEnvironmentThread.Resources defaultResources)
Returns resources from the current thread used to initialize and finalize
the background thread that executes the task.
|
protected void |
throwableCaught(java.lang.Throwable t)
Invoked for possible clean-up when a
Throwable thrown by
doInBackground() is caught. |
static void |
trace(java.util.logging.Level loggingLevel,
java.lang.Object obj,
java.lang.String message)
Traces the current flow with a message.
|
static void |
traceADFContext(java.util.logging.Level loggingLevel,
java.lang.Object obj,
java.lang.String message)
Traces the state of the
ADFContext and its associated objects
in the current flow. |
public SandboxWorker()
public SandboxWorker(java.lang.String trackingId)
trackingId
- the unique ID used to locate this workerjava.lang.IllegalArgumentException
- if the tracking ID is nullpublic final java.lang.String getTrackingId()
protected abstract T doInBackground() throws java.lang.Exception
java.lang.Exception
- the exception as neededprotected void logException(java.lang.Exception e)
doInBackground()
if any.
By default the error is logged as a FINE
ADFLog
.
Subclasses may override this method. This method is also invoked in the
background thread.e
- the exception thrown by doInBackground()
protected void throwableCaught(java.lang.Throwable t)
Throwable
thrown by
doInBackground()
is caught.
Logging the Throwable
in this method may result in duplicate
log messages because Exception
objects are logged by method
logException
by default while Error
objects are
always logged as SEVERE
messages.t
- the Throwable
caughtpublic final void execute()
Executing a SandboxWorker
more than once will not result in
invoking the doInBackground
method twice.
public final T get() throws java.lang.InterruptedException, java.util.concurrent.ExecutionException
doInBackground
java.lang.InterruptedException
- if the current thread was interrupted while
waitingjava.util.concurrent.ExecutionException
- if an exception is thrown while running the
task. Use getCause()
to retrieve
the actual exception. The exception is either
the exception thrown by
doInBackground
or an unexpected
errorpublic final T get(long timeout, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException, java.util.concurrent.ExecutionException, java.util.concurrent.TimeoutException
timeout
- the maximum time to waitunit
- the time unit of the timeout argumentdoInBackground
java.lang.InterruptedException
- if the current thread was interrupted while
waitingjava.util.concurrent.ExecutionException
- if an exception is thrown while running the
task. Use getCause()
to retrieve
the actual exception. The exception is either
the exception thrown by
doInBackground
or an unexpected
errorjava.util.concurrent.TimeoutException
- if the wait timed outpublic final boolean isDone()
true
if this task completed, including the case when
an exception is thrown.true
if this task completed, including the case when
an exception is thrownpublic final boolean isStarted()
true
if this task has been started.true
if this task has been startedprotected MetadataEnvironmentThread.Resources newWorkerThreadResources(MetadataEnvironmentThread.Resources defaultResources)
execute()
. The returned object is then
used in the background to perform initialization and finalization.
Subclasses may override this method to supply custom resources or augment the initialization and finalization of the resources in the background thread.
defaultResources
- the default resources this class providespublic static java.lang.String getTrackingIdFromCurrentThread()
SandboxWorker
.SandboxWorker
; null
if
the current thread was not started by a
SandboxWorker
public static boolean beginTrace(java.util.logging.Level loggingLevel, java.lang.String tracerName)
loggingLevel
- the logging leveltracerName
- the name of the tracertrue
if the given level is loggable and the current
thread is not traced prior to this call; false
otherwisepublic static boolean beginFineTrace(java.lang.String tracerName)
FINE
is loggable.tracerName
- the name of the tracertrue
if FINE
is loggable and the current
thread is not associated with a tracer prior to this call;
false
otherwisepublic static boolean beginFineTrace(java.lang.String tracerName, java.lang.String sandboxId)
FINE
is loggable. The name
of the sandbox will be part of the tracer ID if available.tracerName
- the name of the tracersandboxId
- the ID of the sandbox which the tracing is fortrue
if FINE
is loggable and the current
thread is not associated with a tracer prior to this call;
false
otherwisepublic static boolean endTrace()
true
if tracing was enabled for the current thread
prior to this call; false
otherwisepublic static boolean isTracing(java.util.logging.Level loggingLevel)
true
if the logging level is loggable and there is
a tracer associated with the current thread. This method may be invoked
when a call to trace
requires significant preparation of the
arguments.loggingLevel
- the level to be testedtrue
if the logging level is loggable and there is
a tracer associated with the current threadpublic static boolean isFineTracing()
true
if FINE
is loggable and there is
a tracer associated with the current thread. This method may be invoked
when a call to trace
requires significant preparation of the
arguments.true
if FINE
is loggable and there is
a tracer associated with the current threadpublic static void trace(java.util.logging.Level loggingLevel, java.lang.Object obj, java.lang.String message)
loggingLevel
- the level where the message is loggedobj
- the object where the message is frommessage
- the messagepublic static void fineTrace(java.lang.Object obj, java.lang.String message)
FINE
level.obj
- the object where the message is frommessage
- the messagepublic static void traceADFContext(java.util.logging.Level loggingLevel, java.lang.Object obj, java.lang.String message)
ADFContext
and its associated objects
in the current flow.loggingLevel
- the level where the information is loggedobj
- the object that relies on the current ADFContext
message
- the message; null
if not applicablepublic static void fineTraceADFContext(java.lang.Object obj, java.lang.String message)
ADFContext
and its associated objects
in the current flow and logs the information at FINE
level.obj
- the object that relies on the current ADFContext
message
- the message; null
if not applicable