com.sun.enterprise.admin.monitor.callflow

Interface Agent

All Known Implementing Classes:

AgentAdapter

public interface Agent

This interface exposes the call flow agent API. This is intended to be called by various container trap points. An implementation of the call flow agent would collect the data supplied, and persist it, for later querying and analysis. Further, it is possible to set filters, based on client side attributes such as caller IP address and caller security principal (USER). The trap point call sequence has a specific order: { requestStart, addRequestInfo*, requestInfoComplete, (startTime, (webMethodStart|ejbMethodStart))*, ((ejbMethodEnd|webMethodEnd), endTime)*, requestEnd } Data schema: Tables RequestStart: { RequestId, Timestamp, CallerIPAddress, RemoteUser } RequestEnd : { RequestId, Timestamp } StartTime : { RequestId, TimeStamp, ContainerTypeOrApplicationType } EndTime : { RequestId, TimeStamp, ContainerTypeOrApplicationType } MethodStart : { MethodName, RequestId, Timestamp, ComponentType, ThreadId, AppId, ModuleId, ComponentId, TransactionId, SecurityId } MethodEnd : { RequestId, Timestamp, Exception }

Author:

Ram Jeyaraman, Harpreet Singh, Nazrul Islam, Siraj Ghaffar

Method Summary

Modifier and Type	Method and Description
void	addRequestInfo(RequestInfo requestInfo, String value) This method may be called by the container during request dispatch, to add request information such as caller IP address, and remote user name.
void	clearData() Clear all accumulated data collected in the previous CallFlow runs from the database.
boolean	deleteRequestIds(String[] requestIds) Delete request ids from the database
void	ejbMethodEnd(CallFlowInfo info) This method is called by a request processor thread, after invoking a business method on a target EJB.
void	ejbMethodStart(CallFlowInfo info) This method is called by a request processor thread, before invoking a business method on a target EJB.
void	endTime() This method is called by a request processor thread, when the thread of execution transitions out of the container code.
void	entityManagerMethodEnd() This method is called the persistence container on a request processor thread, after invoking a method on the
void	entityManagerMethodStart(EntityManagerMethod entityManagerMethod) This method is called the persistence container on a request processor thread, before invoking a method on the
void	entityManagerQueryEnd() This method is called the persistence container on a request processor thread, after invoking a method on the
void	entityManagerQueryStart(EntityManagerQueryMethod queryMethod) This method is called the persistence container on a request processor thread, before invoking a method on the
String	getCallerIPFilter() Gets the IP address of the client, only for which, call flow information would be collected.
String	getCallerPrincipalFilter() Gets the caller principal, only for which, call flow information would be collected.
List<Map<String,String>>	getCallStackForRequest(String requestId)
Map<String,String>	getPieInformation(String requestID)
List<Map<String,String>>	getRequestInformation()
ThreadLocalData	getThreadLocalData()
boolean	isEnabled() Get enabled information of call flow's persistent logging.
void	registerListener(Listener listener) Register a listener.
void	requestEnd() This method is called by a request processor thread, after completion of request processing.
void	requestStart(RequestType requestType) This method is called by a request processor thread, dispatched by the container to process a new request on behalf of a client, before any request processing activity begins.
void	setCallerIPFilter(String ipAddress) Specifies the IP address of the client, only for which, call flow information would be collected.
void	setCallerPrincipalFilter(String callerPrincipal) Specifies the caller principal, only for which, call flow information would be collected.
void	setEnable(boolean enable) Enable or disable call flow.
void	startTime(ContainerTypeOrApplicationType type) This method is called by a request processor thread, when the thread of execution transitions into the container code.
void	unregisterListener(Listener listener) Unregister a listener.
void	webMethodEnd(Throwable exception) This method is called by a request processor thread, after invoking a target method on a filter or servlet.
void	webMethodStart(String methodName, String applicationName, String moduleName, String componentName, ComponentType componentType, String callerPrincipal) This method is called by a request processor thread, before invoking a target method on a filter or servlet.

Method Detail

requestStart

void requestStart(RequestType requestType)

This method is called by a request processor thread, dispatched by the container to process a new request on behalf of a client, before any request processing activity begins. Allowed request types are: 1. Remote HTTP Web request. 2. Remote EJB request. 3. MDB request. 4. Timer EJB. Upon being called, this method allocates a unique request id, and associates it with the thread local state.

Parameters:

requestType - Type of the request.

addRequestInfo

void addRequestInfo(RequestInfo requestInfo,
                    String value)

This method may be called by the container during request dispatch, to add request information such as caller IP address, and remote user name. This method is not required to be called by the container. This method may be called many times by the container, but only before startTime is called.

requestEnd

void requestEnd()

This method is called by a request processor thread, after completion of request processing. Upon being called, this method releases the thread local state.

startTime

void startTime(ContainerTypeOrApplicationType type)

This method is called by a request processor thread, when the thread of execution transitions into the container code. That is, this method is called from a method preInvoke point, before the container begins method call setup activity.

Parameters:

type - Describes the type of the container or application.

endTime

void endTime()

This method is called by a request processor thread, when the thread of execution transitions out of the container code. That is, this method is called from a method postInvoke point, after the container has completed all method call related cleanup activity.

ejbMethodStart

void ejbMethodStart(CallFlowInfo info)

This method is called by a request processor thread, before invoking a business method on a target EJB. This trap point must be called after the transaction and security context for the invocation has been established. This trap point collects information about the target EJB invocation.

Parameters:

info - This object encapsulates information such as method name, component type, application name, module name, component name, transaction id, and security id.

ejbMethodEnd

void ejbMethodEnd(CallFlowInfo info)

This method is called by a request processor thread, after invoking a business method on a target EJB. This trap point gathers information about the outcome of the invocation such as exception, if any.

Parameters:

info - This object encapsulates information about the outcome of the invocation such as exception, if any.

webMethodStart

void webMethodStart(String methodName,
                    String applicationName,
                    String moduleName,
                    String componentName,
                    ComponentType componentType,
                    String callerPrincipal)

This method is called by a request processor thread, before invoking a target method on a filter or servlet. This trap point must be called after the invocation context for the invocation is established. This trap point collects information such as method name, component name, component type, application name, module name, callerPrincipal.

webMethodEnd

void webMethodEnd(Throwable exception)

This method is called by a request processor thread, after invoking a target method on a filter or servlet. This trap point gathers information on the outcome of the invocation such as exception, if any.

entityManagerMethodStart

void entityManagerMethodStart(EntityManagerMethod entityManagerMethod)

This method is called the persistence container on a request processor thread, before invoking a method on the

See Also:

EntityManager interface

entityManagerMethodEnd

void entityManagerMethodEnd()

This method is called the persistence container on a request processor thread, after invoking a method on the

See Also:

EntityManager interface

entityManagerQueryStart

void entityManagerQueryStart(EntityManagerQueryMethod queryMethod)

This method is called the persistence container on a request processor thread, before invoking a method on the

See Also:

Query interface

entityManagerQueryEnd

void entityManagerQueryEnd()

This method is called the persistence container on a request processor thread, after invoking a method on the

See Also:

Query interface

getThreadLocalData

ThreadLocalData getThreadLocalData()

Returns:

Callflow thread local data.

registerListener

void registerListener(Listener listener)

Register a listener. Registered listeners are notified during the following call trap points: { requestStart, requestEnd, methodStart, methodEnd }.

unregisterListener

void unregisterListener(Listener listener)

Unregister a listener.

setEnable

void setEnable(boolean enable)

Enable or disable call flow. This is typically called from AMX MBean.

Parameters:

enable - true, to turn on call flow.

isEnabled

boolean isEnabled()

Get enabled information of call flow's persistent logging. Only user of this API is Web Services Managament. Please check with author before using this API.

Returns:

true if persistent logging is enabled, false otherwise.

setCallerIPFilter

void setCallerIPFilter(String ipAddress)

Specifies the IP address of the client, only for which, call flow information would be collected. That is, call flow information is gathered, only for calls originating from the client IP address. Others calls are ignored. Note, there may be other filters that may be further applied to narrow the scope of call flow data collection.

getCallerIPFilter

String getCallerIPFilter()

Gets the IP address of the client, only for which, call flow information would be collected.

setCallerPrincipalFilter

void setCallerPrincipalFilter(String callerPrincipal)

Specifies the caller principal, only for which, call flow information would be collected. That is, call flow information is gathered, only for calls originating from the caller principal. Others calls are ignored. Note, there may be other filters that may be further applied to narrow the scope of call flow data collection.

getCallerPrincipalFilter

String getCallerPrincipalFilter()

Gets the caller principal, only for which, call flow information would be collected.

clearData

void clearData()

Clear all accumulated data collected in the previous CallFlow runs from the database. This is only called from AMX APIs.

deleteRequestIds

boolean deleteRequestIds(String[] requestIds)

Delete request ids from the database

getRequestInformation

List<Map<String,String>> getRequestInformation()

Returns:

a list of Map objects. Each entry in the list contains information pertaining to a unique request. Refer to AMX MBean API com.sun.appserv.management.monitor.CallFlowMonitor for more details.

getCallStackForRequest

List<Map<String,String>> getCallStackForRequest(String requestId)

Returns:

a list of Map objects. The list contains the ordered call stack flow stack information. Refer to AMX MBean API com.sun.appserv.management.monitor.CallFlowMonitor for more details.

getPieInformation

Map<String,String> getPieInformation(String requestID)

Returns:

a Map object containing time information for a request, showing the time distribution across application code and container code. Refer to AMX MBean API com.sun.appserv.management.monitor.CallFlowMonitor for more details.