|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface AgentConfig
Configure an agent.
Agent.getConfig(Object)
Method Summary | |
---|---|
int |
getAcceptedCapacity()
Returns the maximum number of messages an agent will immediately queue for processing. |
AgentLoader |
getAgentLoader()
Returns the loader used to create generated classes for the agent. |
AgentTasks |
getAgentTasks()
Returns the tasks used to execute calls. |
CallSite |
getCallSite(String method,
Class<?> result,
Class<?>... params)
Returns metadata and configuration settings for a specific method. |
CallStateListener<?> |
getCallStateListener()
Returns the default call state listener for this agent. |
CallStateListener<?> |
getCallStateListener(CallState state)
Returns the default call listener for a specific state. |
Object |
getData()
Returns the data previously associated with this agent. |
long |
getDeadcheckTimeout()
Returns the length of time synchronous calls wait before checking if the caller's thread has deadlocked. |
TimeUnit |
getDeadcheckTimeoutUnit()
Returns the deadlock check timeout unit. |
Executor |
getExecutor()
Returns the agent's executor. |
long |
getExpirationTimeout()
Returns the default call expiration timeout for call sites and calls not explicitly configured with expiration timeouts. |
TimeUnit |
getExpirationTimeoutUnit()
Returns the default call expiration timeout unit. |
List<Class<?>> |
getInterfaces()
Returns a read-only list of the interfaces implemented by the agent. |
int |
getPendingCapacity()
Returns the maximum number of callers the agent can suspend while waiting for new messages to be accepted. |
long |
getPendingTimeout()
Returns the length of time the caller will wait for the agent to accept a new message. |
TimeUnit |
getPendingTimeoutUnit()
Returns the pending timeout unit. |
Class<?> |
getTaskType()
Returns the class of agent's task instances. |
ExceptionHandler |
getUnhandledExceptionHandler()
Returns the agent's handler for unhandled exceptions. |
void |
setAcceptedCapacity(int value)
Sets the maximum number of messages an agent will immediately queue for processing. |
void |
setCallStateListener(CallState state,
CallStateListener<?> listener)
Sets a default call listener for the given state . |
void |
setCallStateListener(CallStateListener<?> listener)
Sets a default call state listener for this agent. |
void |
setData(Object data)
Associates data with this agent. |
void |
setDeadcheckTimeout(long value,
TimeUnit unit)
Sets the length of time synchronous calls wait before checking if the caller's thread has deadlocked. |
void |
setExecutor(Executor executor)
Changes the agent's executor. |
void |
setExpirationTimeout(long value,
TimeUnit unit)
Sets the default call expiration for call sites and calls not explicitly configured with expiration timeouts. |
void |
setPendingCapacity(int value)
Sets the maximum number of callers the agent can suspend while waiting for new messages to be accepted. |
void |
setPendingTimeout(long value,
TimeUnit unit)
Sets the length of time the caller will wait for the agent to accept a new message. |
void |
setUnhandledExceptionHandler(ExceptionHandler handler)
Changes the agent's handler for unhandled exceptions. |
Method Detail |
---|
AgentLoader getAgentLoader()
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)
List<Class<?>> getInterfaces()
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)
AgentTasks getAgentTasks()
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)
Class<?> getTaskType()
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)
int getAcceptedCapacity()
Integer.MAX_VALUE
.
getPendingCapacity()
,
Capacity
void setAcceptedCapacity(int value)
IllegalArgumentException
- value
is less than
1
.setPendingCapacity(int)
,
Capacity
int getPendingCapacity()
0
.
getAcceptedCapacity()
,
getPendingTimeout()
,
Capacity
void setPendingCapacity(int value)
IllegalArgumentException
- value
is less than 0
.setAcceptedCapacity(int)
,
setPendingTimeout(long, TimeUnit)
,
Capacity
long getPendingTimeout()
getPendingTimeoutUnit()
,
getAcceptedCapacity()
,
Capacity
TimeUnit getPendingTimeoutUnit()
getPendingTimeout()
,
Capacity
void setPendingTimeout(long value, TimeUnit unit)
IllegalArgumentException
- value
is less than 1
.
NullPointerException
- unit
is null
and
value
is not Long.MAX_VALUE
setPendingCapacity(int)
,
Capacity
long getExpirationTimeout()
getExpirationTimeoutUnit()
,
Expiration
TimeUnit getExpirationTimeoutUnit()
getExpirationTimeout()
,
Expiration
void setExpirationTimeout(long value, TimeUnit unit)
IllegalArgumentException
- value
is less than 1
.
NullPointerException
- unit
is null
and
value
is not Long.MAX_VALUE
Expiration
long getDeadcheckTimeout()
5
, and
the default TimeUnit
is SECONDS
.
See the Deadlock section in the package description for
org.curjent.agent
.
TimeUnit getDeadcheckTimeoutUnit()
getDeadcheckTimeout()
void setDeadcheckTimeout(long value, TimeUnit unit)
0
or never if the value is
Long.MAX_VALUE
.
This configuration option is mostly useful for testing and debugging purposes. The default timeout should be fine for most other purposes.
IllegalArgumentException
- value
is less than
0
.
NullPointerException
- unit
is null
and
value
is neither 0
nor
Long.MAX_VALUE
.getDeadcheckTimeout()
Executor getExecutor()
Agent.getDefaultExecutor()
void setExecutor(Executor executor)
The agent limits the number of worker threads it uses to the number of
available tasks (see AgentTasks
). (The agent may occasionally and
very briefly require additional threads for timing and efficiency
reasons. It also uses a thread to expire calls if the agents or any of
its call sites or calls are configured to expire.) This is in contrast to
traditional thread pooling solutions that limit the number of executing
tasks based on the number of available threads.
The executor for the agent must never block and must always execute commands in separate threads. The agent can stall or deadlock if the executor blocks, fails to execute the command, or executes the command synchronously in the caller's thread.
The executor may queue the command for execution later. This is the case, for example, with an executor that has a fixed number of threads but an unbounded queue for pending commands. However, queuing the command can stall the agent until the command is executed.
Alternatively, the executor can throw an exception when its
execute
method is called. The agent will stall, though, if
it does not already have at least one command executing. The exception is
propagated to the caller or the agent's exception handler, depending on
the context.
The recommended (and default) executor permits an unbounded number of
threads to execute (see, for example,
Executors.newCachedThreadPool()
).
NullPointerException
- Argument is nullExceptionHandler getUnhandledExceptionHandler()
setUnhandledExceptionHandler(ExceptionHandler)
for details on
what is considered an "unhandled" exception. The returned value is
always non-null. The default handler does nothing.
void setUnhandledExceptionHandler(ExceptionHandler handler)
AgentException
). An
unhandled exception includes all exceptions not thrown by a task,
such as exceptions thrown by the agent's Executor
,
AgentTasks
, etc. It also includes all task exceptions
not associated with synchronous or future calls (exceptions for
synchronous and future calls are propagated to the caller, either
directly for synchronous calls, or indirectly when the caller calls one
of the Future
's get
methods).
Unhandled exceptions are passed to the given handler but otherwise ignored. Exceptions thrown by the handler are caught and ignored.
A best practice is to set the handler in an agent's factory method or
class (that is, extend the factory pattern shown in the description for
Agent
to include configuration of the agent's unhandled exception
handler). A typical implementation will log the exception using the
application's standard logging mechanism, such as log4j or
java.util.logging
.
NullPointerException
- Argument is nullCallStateListener<?> getCallStateListener()
null
if none has been assigned.
setCallStateListener(CallStateListener)
void setCallStateListener(CallStateListener<?> listener)
listener
is null
. See
CallStateListener
for details on the relationship between an
agent's default listener and other listeners.
setCallStateListener(CallState, CallStateListener)
,
CallSite.setCallStateListener(CallStateListener)
,
CallSite.setCallStateListener(CallState, CallStateListener)
CallStateListener<?> getCallStateListener(CallState state)
null
if none has been assigned.
NullPointerException
- state
is null
setCallStateListener(CallState, CallStateListener)
void setCallStateListener(CallState state, CallStateListener<?> listener)
state
. Clears the
listener for the given state
if the given
listener
is null
. See CallStateListener
for details on the relationship between an agent's default listener for a
specific state and other listeners.
NullPointerException
- state
is null
setCallStateListener(CallStateListener)
,
CallSite.setCallStateListener(CallStateListener)
,
CallSite.setCallStateListener(CallState, CallStateListener)
CallSite getCallSite(String method, Class<?> result, Class<?>... params)
method
- The name of the method.result
- The method's return type. For methods returning objects,
use the object's class, such as myObject.getClass()
. For
primitives, use the primitive's class, such as int.class
.
For void, use void.class
.params
- The method's parameter types. May be empty or
null
for methods without parameters.
CallSiteNotFoundException
- Agent does not have a method with the
given name, return type, and parameters
NullPointerException
- method
or result
is null
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)
Object getData()
null
if none.
setData(Object)
void setData(Object data)
null
. In the following example, the agent designer assigns
application-specific metadata with each new agent that is used later in
its call listener:
public interface MyAgent { // various agent methods... interface Factory { MyAgent newAgent(); Factory INSTANCE = new Factory() { public MyAgent newAgent() { MyAgent agent = Agent.newInstance(MyAgent.class, new MyTask()); MyMetadata metadata = ...; // initialize the metadata AgentConfig config = Agent.getConfig(agent); config.setCallListener(new MyListener()); config.setData(metadata); return agent; } }; } } class MyListener implements CallStateListener { public void agentCall(AgentCall context) { AgentConfig config = Agent.getConfig(context.getCallSite().getAgent()); MyMetadata metadata = (MyMetadata)config.getData(); // use the metadata... } } // define MyTask...Data is independently associated with each new agent instance. Each call to
Agent.newInstance
, even with the same arguments, returns
a new agent with no associated data.
getData()
,
CallSite.setData(Object)
,
AgentCall.setData(Object)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |