com.sun.enterprise.admin.monitor.callflow.Agent Maven / Gradle / Ivy
/*
* Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
/*
* Agent.java
* $Id: Agent.java,v 1.19 2006/11/08 20:55:16 harpreet Exp $
* $Date: 2006/11/08 20:55:16 $
* $Revision: 1.19 $
*/
package com.sun.enterprise.admin.monitor.callflow;
import java.util.List;
import java.util.Map;
/**
* 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
* @date March 21, 2005
*/
public interface Agent {
/**
* Call flow trap points.
*/
/**
* 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.
*
* @param requestType Type of the request.
*/
public void requestStart(RequestType requestType);
/**
* 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.
*/
public void addRequestInfo(RequestInfo requestInfo, String value);
/**
* This method is called by a request processor thread, after completion
* of request processing. Upon being called, this method releases the
* thread local state.
*/
public void requestEnd();
/**
* 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.
*
* @param type Describes the type of the container or application.
*/
public void startTime(ContainerTypeOrApplicationType type);
/**
* 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.
*/
public void endTime();
// Method trap points
/**
* 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.
*
* @param info This object encapsulates information such as method name,
* component type, application name, module name, component name,
* transaction id, and security id.
*/
public void ejbMethodStart(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.
*
* @param info This object encapsulates information about the outcome of
* the invocation such as exception, if any.
*/
public void ejbMethodEnd(CallFlowInfo info);
/**
* 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.
*/
public void webMethodStart(
String methodName, String applicationName, String moduleName,
String componentName, ComponentType componentType,
String callerPrincipal);
/**
* 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.
*/
public void webMethodEnd(Throwable exception);
/**
* This method is called the persistence container on a request processor
* thread, before invoking a method on the
* @see javax.persistence.EntityManager EntityManager interface
*/
public void entityManagerMethodStart (EntityManagerMethod entityManagerMethod);
/**
* This method is called the persistence container on a request processor
* thread, after invoking a method on the
* @see javax.persistence.EntityManager EntityManager interface
*/
public void entityManagerMethodEnd ();
/**
* This method is called the persistence container on a request processor
* thread, before invoking a method on the
* @see javax.persistence.Query Query interface
*/
public void entityManagerQueryStart (EntityManagerQueryMethod queryMethod);
/**
* This method is called the persistence container on a request processor
* thread, after invoking a method on the
* @see javax.persistence.Query Query interface
*/
public void entityManagerQueryEnd ();
/**
* Data accessors.
*/
/**
* @return Callflow thread local data.
*/
public ThreadLocalData getThreadLocalData();
/**
* Support for notifications.
*/
/**
* Register a listener.
*
* Registered listeners are notified during the following call trap points:
* { requestStart, requestEnd, methodStart, methodEnd }.
*/
public void registerListener(Listener listener);
/**
* Unregister a listener.
*/
public void unregisterListener(Listener listener);
/**
* API to support AMX MBean calls.
*/
// Enablement APIs
/**
* Enable or disable call flow. This is typically called from AMX MBean.
*
* @param enable true, to turn on call flow.
*/
public void setEnable(boolean enable);
/**
* 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.
*
* @return true if persistent logging is enabled, false otherwise.
*/
public boolean isEnabled();
// Filters
/**
* 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.
*/
public void setCallerIPFilter(String ipAddress);
/**
* Gets the IP address of the client, only for which, call flow
* information would be collected.
*/
public String getCallerIPFilter ();
/**
* 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.
*/
public void setCallerPrincipalFilter(String callerPrincipal);
/**
* Gets the caller principal, only for which, call flow information
* would be collected.
*/
public String getCallerPrincipalFilter();
/**
* Clear all accumulated data collected in the previous CallFlow runs
* from the database. This is only called from AMX APIs.
*/
public void clearData ();
/**
* Delete request ids from the database
*/
public boolean deleteRequestIds (String[] requestIds);
/**
* @return 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.
*/
public List> getRequestInformation();
/**
* @return 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.
*/
public List> getCallStackForRequest(String requestId);
/**
* @return 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.
*/
public Map getPieInformation(String requestID);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy