| /* |
| * 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 |
| * <code>startTime</code> 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 jakarta.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 jakarta.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 jakarta.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 jakarta.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<Map<String, String>> 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<Map<String, String>> 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<String, String> getPieInformation(String requestID); |
| } |