org.curjent.agent
Interface AgentConfig

All Known Implementing Classes:
Config

public interface AgentConfig

Configure an agent.

See Also:
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

getAgentLoader

AgentLoader getAgentLoader()
Returns the loader used to create generated classes for the agent.

See Also:
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)

getInterfaces

List<Class<?>> getInterfaces()
Returns a read-only list of the interfaces implemented by the agent.

See Also:
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)

getAgentTasks

AgentTasks getAgentTasks()
Returns the tasks used to execute calls. The returned implementation may or may not be thread-safe and usable outside the agent.

See Also:
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)

getTaskType

Class<?> getTaskType()
Returns the class of agent's task instances.

See Also:
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)

getAcceptedCapacity

int getAcceptedCapacity()
Returns the maximum number of messages an agent will immediately queue for processing. Default is Integer.MAX_VALUE.

See Also:
getPendingCapacity(), Capacity

setAcceptedCapacity

void setAcceptedCapacity(int value)
Sets the maximum number of messages an agent will immediately queue for processing.

Throws:
IllegalArgumentException - value is less than 1.
See Also:
setPendingCapacity(int), Capacity

getPendingCapacity

int getPendingCapacity()
Returns the maximum number of callers the agent can suspend while waiting for new messages to be accepted. Default is 0.

See Also:
getAcceptedCapacity(), getPendingTimeout(), Capacity

setPendingCapacity

void setPendingCapacity(int value)
Sets the maximum number of callers the agent can suspend while waiting for new messages to be accepted.

Throws:
IllegalArgumentException - value is less than 0.
See Also:
setAcceptedCapacity(int), setPendingTimeout(long, TimeUnit), Capacity

getPendingTimeout

long getPendingTimeout()
Returns the length of time the caller will wait for the agent to accept a new message.

See Also:
getPendingTimeoutUnit(), getAcceptedCapacity(), Capacity

getPendingTimeoutUnit

TimeUnit getPendingTimeoutUnit()
Returns the pending timeout unit.

See Also:
getPendingTimeout(), Capacity

setPendingTimeout

void setPendingTimeout(long value,
                       TimeUnit unit)
Sets the length of time the caller will wait for the agent to accept a new message.

Throws:
IllegalArgumentException - value is less than 1.
NullPointerException - unit is null and value is not Long.MAX_VALUE
See Also:
setPendingCapacity(int), Capacity

getExpirationTimeout

long getExpirationTimeout()
Returns the default call expiration timeout for call sites and calls not explicitly configured with expiration timeouts.

See Also:
getExpirationTimeoutUnit(), Expiration

getExpirationTimeoutUnit

TimeUnit getExpirationTimeoutUnit()
Returns the default call expiration timeout unit.

See Also:
getExpirationTimeout(), Expiration

setExpirationTimeout

void setExpirationTimeout(long value,
                          TimeUnit unit)
Sets the default call expiration for call sites and calls not explicitly configured with expiration timeouts.

Throws:
IllegalArgumentException - value is less than 1.
NullPointerException - unit is null and value is not Long.MAX_VALUE
See Also:
Expiration

getDeadcheckTimeout

long getDeadcheckTimeout()
Returns the length of time synchronous calls wait before checking if the caller's thread has deadlocked. The default value is 5, and the default TimeUnit is SECONDS.

See the Deadlock section in the package description for org.curjent.agent.


getDeadcheckTimeoutUnit

TimeUnit getDeadcheckTimeoutUnit()
Returns the deadlock check timeout unit.

See Also:
getDeadcheckTimeout()

setDeadcheckTimeout

void setDeadcheckTimeout(long value,
                         TimeUnit unit)
Sets the length of time synchronous calls wait before checking if the caller's thread has deadlocked. Deadlocked is checked immediately if the timeout value is 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.

Throws:
IllegalArgumentException - value is less than 0.
NullPointerException - unit is null and value is neither 0 nor Long.MAX_VALUE.
See Also:
getDeadcheckTimeout()

getExecutor

Executor getExecutor()
Returns the agent's executor. This is initially the default executor.

See Also:
Agent.getDefaultExecutor()

setExecutor

void setExecutor(Executor executor)
Changes the agent's executor. The existing state of the agent is unaffected except to change the executor for starting new threads. Existing threads, for example, continue to run. The only change is that the agent will start new threads with the new 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()).

Throws:
NullPointerException - Argument is null

getUnhandledExceptionHandler

ExceptionHandler getUnhandledExceptionHandler()
Returns the agent's handler for unhandled exceptions. See setUnhandledExceptionHandler(ExceptionHandler) for details on what is considered an "unhandled" exception. The returned value is always non-null. The default handler does nothing.


setUnhandledExceptionHandler

void setUnhandledExceptionHandler(ExceptionHandler handler)
Changes the agent's handler for unhandled exceptions. An "unhandled" exception is an exception thrown by the agent's task, executor, etc., that the caller cannot receive. These are always exceptions thrown in one of the task's background threads (exceptions thrown in the caller's thread are always propagated directly to the caller, including undeclared checked exceptions wrapped in an 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.

Throws:
NullPointerException - Argument is null

getCallStateListener

CallStateListener<?> getCallStateListener()
Returns the default call state listener for this agent. Returns null if none has been assigned.

See Also:
setCallStateListener(CallStateListener)

setCallStateListener

void setCallStateListener(CallStateListener<?> listener)
Sets a default call state listener for this agent. Clears the default listener if the given listener is null. See CallStateListener for details on the relationship between an agent's default listener and other listeners.

See Also:
setCallStateListener(CallState, CallStateListener), CallSite.setCallStateListener(CallStateListener), CallSite.setCallStateListener(CallState, CallStateListener)

getCallStateListener

CallStateListener<?> getCallStateListener(CallState state)
Returns the default call listener for a specific state. Returns null if none has been assigned.

Throws:
NullPointerException - state is null
See Also:
setCallStateListener(CallState, CallStateListener)

setCallStateListener

void setCallStateListener(CallState state,
                          CallStateListener<?> listener)
Sets a default call listener for the given 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.

Throws:
NullPointerException - state is null
See Also:
setCallStateListener(CallStateListener), CallSite.setCallStateListener(CallStateListener), CallSite.setCallStateListener(CallState, CallStateListener)

getCallSite

CallSite getCallSite(String method,
                     Class<?> result,
                     Class<?>... params)
Returns metadata and configuration settings for a specific method. The given method name, return type, and parameter types must exactly match one of the methods defined in the agent's interfaces.

Parameters:
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.
Throws:
CallSiteNotFoundException - Agent does not have a method with the given name, return type, and parameters
NullPointerException - method or result is null
See Also:
Agent.newInstance(AgentLoader, Class[], AgentTasks, Class)

getData

Object getData()
Returns the data previously associated with this agent. Returns null if none.

See Also:
setData(Object)

setData

void setData(Object data)
Associates data with this agent. Any value is valid, including 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.

See Also:
getData(), CallSite.setData(Object), AgentCall.setData(Object)


Copyright 2009-2011 Tom Landon
Apache License 2.0