Agent


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  /*
25   * Agent.java
26   * $Id: Agent.java,v 1.18 2005/12/25 04:10:35 tcfujii Exp $
27   * $Date: 2005/12/25 04:10:35 $
28   * $Revision: 1.18 $
29   */
30  
31  package com.sun.enterprise.admin.monitor.callflow;
32  
33  import java.util.List  ;
34  import java.util.Map  ;
35  
36  /**
37   * This interface exposes the call flow agent API.
38   * 
39   * This is intended to be called by various container trap points. An
40   * implementation of the call flow agent would collect the data supplied, and
41   * persist it, for later querying and analysis.
42   *
43   * Further, it is possible to set filters, based on client side attributes
44   * such as caller IP address and caller security principal (USER).
45   *
46   * The trap point call sequence has a specific order:
47   * 
48   *      {
49   *        requestStart, addRequestInfo*, requestInfoComplete,
50   *        (startTime, (webMethodStart|ejbMethodStart))*,
51   *        ((ejbMethodEnd|webMethodEnd), endTime)*,
52   *        requestEnd
53   *      }
54   *
55   * Data schema: Tables
56   *
57   * RequestStart: { RequestId, Timestamp, CallerIPAddress, RemoteUser }
58   * RequestEnd  : { RequestId, Timestamp }
59   * StartTime : { RequestId, TimeStamp, ContainerTypeOrApplicationType }
60   * EndTime : { RequestId, TimeStamp, ContainerTypeOrApplicationType }
61   * MethodStart : { MethodName, RequestId, Timestamp, ComponentType, ThreadId,
62   *                 AppId, ModuleId, ComponentId, TransactionId, SecurityId }
63   * MethodEnd   : { RequestId, Timestamp, Exception }
64   *
65   * @author Ram Jeyaraman, Harpreet Singh, Nazrul Islam, Siraj Ghaffar
66   * @date March 21, 2005
67   */
68  public interface Agent {
69      
70      /**
71       * Call flow trap points.
72       */
73      
74      /**
75       * This method is called by a request processor thread, dispatched by the
76       * container to process a new request on behalf of a client, before any
77       * request processing activity begins.
78       *
79       * Allowed request types are:
80       * 
81       * 1. Remote HTTP Web request.
82       * 2. Remote EJB request.
83       * 3. MDB request.
84       * 4. Timer EJB.
85       *
86       * Upon being called, this method allocates a unique request id, and
87       * associates it with the thread local state.
88       *
89       * @param requestType Type of the request.
90       */      
91      public void requestStart(RequestType requestType);
92      
93      /**
94       * This method may be called by the container during request dispatch,
95       * to add request information such as caller IP address, and remote
96       * user name. This method is not required to be called by the container.
97       *
98       * This method may be called many times by the container, but only before
99       * <code>startTime</code> is called.
100      */
101     public void addRequestInfo(RequestInfo requestInfo, String   value);
102     
103     /**
104      * This method is called by a request processor thread, after completion
105      * of request processing. Upon being called, this method releases the
106      * thread local state.
107      */
108     public void requestEnd();
109     
110     /**
111      * This method is called by a request processor thread, when the thread
112      * of execution transitions into the container code. That is,
113      * this method is called from a method preInvoke point, before the
114      * container begins method call setup activity.
115      *
116      * @param type Describes the type of the container or application.
117      */    
118     public void startTime(ContainerTypeOrApplicationType type);
119     
120     /**
121      * This method is called by a request processor thread, when the thread
122      * of execution transitions out of the container code. That is,
123      * this method is called from a method postInvoke point, after the
124      * container has completed all method call related cleanup activity.
125      */
126     public void endTime();
127     
128     // Method trap points    
129 
130     /**
131      * This method is called by a request processor thread, before invoking a
132      * business method on a target EJB. This trap point must be called after
133      * the transaction and security context for the invocation has been
134      * established.
135      * 
136      * This trap point collects information about the target EJB invocation.
137      *
138      * @param info This object encapsulates information such as method name,
139      * component type, application name, module name, component name,
140      * transaction id, and security id.
141      */
142     public void ejbMethodStart(CallFlowInfo info);
143     
144     /**
145      * This method is called by a request processor thread, after invoking a
146      * business method on a target EJB. This trap point gathers information
147      * about the outcome of the invocation such as exception, if any.
148      *
149      * @param info This object encapsulates information about the outcome of
150      * the invocation such as exception, if any.
151      */
152     public void ejbMethodEnd(CallFlowInfo info);
153 
154     /**
155      * This method is called by a request processor thread, before invoking a
156      * target method on a filter or servlet. This trap point must be called
157      * after the invocation context for the invocation is established.
158      * 
159      * This trap point collects information such as method name, component
160      * name, component type, application name, module name, callerPrincipal.
161      */
162     public void webMethodStart(
163             String   methodName, String   applicationName, String   moduleName,
164             String   componentName, ComponentType componentType,
165             String   callerPrincipal);
166     
167     /**
168      * This method is called by a request processor thread, after invoking a
169      * target method on a filter or servlet. This trap point gathers information
170      * on the outcome of the invocation such as exception, if any.
171      */    
172     public void webMethodEnd(Throwable   exception);
173     
174     /**
175      * Data accessors.
176      */
177     
178     /**
179      * @return Callflow thread local data.
180      */
181     public ThreadLocalData getThreadLocalData();
182         
183     /**
184      * Support for notifications.
185      */
186     
187     /**
188      * Register a listener.
189      * 
190      * Registered listeners are notified during the following call trap points:
191      * { requestStart, requestEnd, methodStart, methodEnd }.
192      */
193     public void registerListener(Listener listener);
194     
195     /**
196      * Unregister a listener.
197      */
198     public void unregisterListener(Listener listener);
199     
200     /**
201      * API to support AMX MBean calls.
202      */
203         
204     // Enablement APIs
205     
206     /**
207      * Enable or disable call flow. This is typically called from AMX MBean.
208      *
209      * @param enable true, to turn on call flow.
210      */
211     public void setEnable(boolean enable);
212     
213     /**
214      * Get enabled information of call flow's persistent logging. Only user of
215      * this API is Web Services Managament. Please check with author before
216      * using this API.
217      *
218      * @return true if persistent logging is enabled, false otherwise.
219      */
220     public boolean isEnabled();
221     
222     // Filters
223     
224     /**
225      * Specifies the IP address of the client, only for which, call flow 
226      * information would be collected. That is, call flow information is
227      * gathered, only for calls originating from the client IP address.
228      * Others calls are ignored.
229      *
230      * Note, there may be other filters that may be further applied to narrow
231      * the scope of call flow data collection.
232      */
233     public void setCallerIPFilter(String   ipAddress);
234     
235     /**
236      * Gets the IP address of the client, only for which, call flow 
237      * information would be collected.
238      */
239     public String   getCallerIPFilter ();
240     
241     /**
242      * Specifies the caller principal, only for which, call flow information
243      * would be collected. That is, call flow information is gathered, only for
244      * calls originating from the caller principal. Others calls are ignored.
245      *
246      * Note, there may be other filters that may be further applied to narrow
247      * the scope of call flow data collection.
248      */
249     public void setCallerPrincipalFilter(String   callerPrincipal);
250     
251     /**
252      * Gets the caller principal, only for which, call flow information
253      * would be collected.
254      */
255     public String   getCallerPrincipalFilter();
256     
257     /**
258      * Clear all accumulated data collected in the previous CallFlow runs
259      * from the database. This is only called from AMX APIs.
260      */
261     public void clearData ();
262     
263     /**
264      * Delete request ids from the database
265      */
266     public boolean deleteRequestIds (String  [] requestIds);
267     /**
268      * @return a list of Map objects. Each entry in the list contains
269      * information pertaining to a unique request. Refer to AMX MBean API
270      * com.sun.appserv.management.monitor.CallFlowMonitor for more details.
271      */
272     public List  <Map  <String  , String  >> getRequestInformation();
273     
274     /**
275      * @return a list of Map objects. The list contains the ordered call stack
276      * flow stack information. Refer to AMX MBean API
277      * com.sun.appserv.management.monitor.CallFlowMonitor for more details.
278      */
279     public List  <Map  <String  , String  >> getCallStackForRequest(String   requestId);
280 
281     /**
282      * @return a Map object containing time information for a request,
283      * showing the time distribution across application code and container code.
284      * Refer to AMX MBean API com.sun.appserv.management.monitor.CallFlowMonitor
285      * for more details.
286      */
287     public Map  <String  , String  > getPieInformation(String   requestID);
288 }
289
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags