- * TODO comment + * recording an exchange can not be done in one step. This is due to the fact, that the proxy + * servlet notifies different processing states for requests and response. An exchange listener + * records all these event. On the occurrence of the final event, it compiles an + * {@link HttpExchange} and forwards it to the exchange handler. *
* @@ -52,35 +55,51 @@ /** - * + *+ * the exchange handler to forward compiles exchanges to + *
*/ private HttpMonitorExchangeHandler exchangeHandler; /** - * + *+ * the request of compiled exchange + *
*/ private HttpServletRequest request; /** - * + *+ * the content of the request of compiled exchange + *
*/ private List+ * the response of compiled exchange + *
*/ private HttpServletResponse response; /** - * + *+ * the content of the response of compiled exchange + *
*/ private List+ * the last time an event for the exchange was received (used for supporting timeouts) + *
*/ private long lastUpdate = System.currentTimeMillis(); /** - * + *+ * initialized the exchange listener with the exchange handler to forward compiled exchanges to + *
+ * + * @param exchangeHandler the exchange handler to forward compiled exchanges to */ ExchangeListener(HttpMonitorExchangeHandler exchangeHandler) { @@ -89,5 +108,9 @@ /** - * + *+ * called, when the request was received by the proxy + *
+ * + * @param request the request of the exchange */ public void onRequest(HttpServletRequest request) throws IllegalStateException { @@ -103,5 +126,9 @@ /** - * + *+ * called, when some content of the request was processed by the proxy + *
+ * + * @param data the processed content of the request of the exchange */ public void onRequestContent(ByteBuffer data) { @@ -117,5 +144,9 @@ /** - * + *+ * called, when the response is to be returned by the proxy + *
+ * + * @param response the response of the exchange */ public void onResponse(HttpServletResponse response) { @@ -131,5 +162,9 @@ /** - * + *+ * called, when some content of the response was processed by the proxy + *
+ * + * @param data the processed content of the response of the exchange */ public void onResponseContent(ByteBuffer data) { @@ -145,5 +180,9 @@ /** - * + *+ * called, when proxy finished proxying a request + *
+ * + * @param status the status of the proxying after finalization */ public void onFinish(Status status) { @@ -159,5 +198,5 @@ /** - * @return the request + * @return the request of the exchange */ HttpServletRequest getRequest() { @@ -166,5 +205,5 @@ /** - * + * @return the last time this listener received an event */ long getLastUpdate() { @@ -173,5 +212,10 @@ /** - * + *+ * convenience method to compile an {@link HttpExchange} and send it to the exchange handler + * after finalization of the exchange. + *
+ * + * @param status the status of the proxying after finalization */ private void sendToExchangeHandler(Status status) { @@ -202,5 +246,7 @@ /** - * + *+ * convenience method to map an {@link HttpServletRequest} to an {@link HttpRequest} + *
*/ private HttpRequest map(HttpServletRequest request, ObjectFactory eventObjectFactory) { @@ -261,5 +307,7 @@ /** - * + *+ * convenience method to map an {@link HttpServletResponse} to an {@link HttpResponse} + *
*/ private HttpResponse map(HttpServletResponse response, ObjectFactory eventObjectFactory) { @@ -297,5 +345,7 @@ /** - * + *+ * convenience method to create a string out of recorded request or response content + *
*/ private String createString(List- * TODO update comment - * The log manager handles different {@link HttpMonitorOutputWriter}s to perform the logging - * of recorded messages. It initializes a new writer if the first message for a specific - * client is received and it closes a writer if for a specific period of time no further message - * of the same client was received. The writers themselves consider log rotation. For handling - * messages, the {@link HttpMonitorExchangeHandler} mechanism provided by the - * {@link HttpMonitorServer} is used. + * {@link ExchangeListener}s need to be managed, as there is one instantiated for each proxied + * request/response. They need to be timed out, if for a longer time, no update is received. All + * this is done by the ExchangeListenerManager. *
* @@ -52,26 +48,38 @@ /** + ** the timeout after which a writer of an inactive client is closed + *
*/ private static final int SESSION_TIMEOUT = 10 * 60 * 1000; /** - * + *+ * the exchange handler forwarded to the exchange listeners + *
*/ private HttpMonitorExchangeHandler exchangeHandler; /** - * the mapping of client ids to the respective writers. + *+ * the mapping of requests handled by the proxy to the respective exchange listeners + *
*/ private Map+ * a timer used to detect exchange listener timeouts + *
*/ private Timer listenerTimer; /** - * - * + *+ * creates the exchange listener manager with the exchange handler to be forwarded to the + * exchange listeners + *
+ * + * @param exchangeHandler the exchange handler to be forwarded to the exchange listeners */ ExchangeListenerManager(HttpMonitorExchangeHandler exchangeHandler) { @@ -130,5 +138,10 @@ /** - * + *+ * called, when the request was received by the proxy. Calls the appropriate method on + * the exchange listener. + *
+ * + * @param request the request of the exchange */ public void onRequest(HttpServletRequest request) throws IllegalStateException { @@ -137,5 +150,11 @@ /** - * + *+ * called, when some content of the request was processed by the proxy. Calls the appropriate + * method on the exchange listener. + *
+ * + * @param request the request of the exchange + * @param data the processed content of the request of the exchange */ public void onRequestContent(HttpServletRequest request, ByteBuffer data) @@ -146,5 +165,11 @@ /** - * + *+ * called, when the response is to be returned by the proxy. Calls the appropriate + * method on the exchange listener. + *
+ * + * @param request the request of the exchange + * @param response the response of the exchange */ public void onResponse(HttpServletRequest request, HttpServletResponse response) @@ -155,5 +180,11 @@ /** - * + *+ * called, when some content of the response was processed by the proxy. Calls the appropriate + * method on the exchange listener. + *
+ * + * @param request the request of the exchange + * @param data the processed content of the response of the exchange */ public void onResponseContent(HttpServletRequest request, ByteBuffer data) @@ -164,5 +195,11 @@ /** - * + *+ * called, when proxy finished proxying a request. Calls the appropriate method on the + * exchange listener and afterwards cleans up the listener. + *
+ * + * @param request the request of the exchange + * @param status the status of the proxying after finalization */ public void onFinish(HttpServletRequest request, Status status) throws IllegalStateException { @@ -173,5 +210,7 @@ /** - * + *+ * convenience method to ensure a listener for a specific HTTP servlet request to be handled. + *
*/ private ExchangeListener ensureListener(HttpServletRequest request) { @@ -194,5 +233,5 @@ /** *- * internal timer task used for detecting session timeouts of clients + * internal timer task used for detecting exchange timeouts *
* Index: trunk/autoquest-httpmonitor/src/main/java/de/ugoe/cs/autoquest/httpmonitor/proxy/HttpMonitorRemoteExchangeHandler.java =================================================================== --- trunk/autoquest-httpmonitor/src/main/java/de/ugoe/cs/autoquest/httpmonitor/proxy/HttpMonitorRemoteExchangeHandler.java (revision 1381) +++ trunk/autoquest-httpmonitor/src/main/java/de/ugoe/cs/autoquest/httpmonitor/proxy/HttpMonitorRemoteExchangeHandler.java (revision 1382) @@ -34,4 +34,5 @@ import org.eclipse.jetty.util.thread.QueuedThreadPool; +import de.ugoe.cs.autoquest.httpmonitor.HttpMonitor; import de.ugoe.cs.autoquest.httpmonitor.HttpMonitorComponent; import de.ugoe.cs.autoquest.httpmonitor.HttpMonitorException; @@ -43,5 +44,9 @@ /** *- * TODO comment + * If the exchanges recorded by the proxy are to be transmitted to a central {@link HttpMonitor}, + * this exchanges handler is used. It is called by the exchange listener on completion of a proxied + * request/response. It then creates an HTTP request to the central monitor and sends it there. + * It is initialized with the name of the server and the port on which the central monitor runs. + * If the exchanges can not be forwarded to the central server, they are discarded. *
* @@ -55,23 +60,39 @@ private static final long serialVersionUID = 1L; - /** */ + /** + *+ * the HTTP client used internally to send data to the central server + *
+ */ private HttpClient httpClient; - /** */ + /** + *+ * the host name of the central server + *
+ */ private String httpMonitorServer; - /** */ + /** + *+ * the port of the central server + *
+ */ private int httpMonitorPort; - /** */ + /** + *+ * a set of requests send to the central server for which the response was not received yet + *
+ */ private Set- * TODO: comment + * initializes the exchange handler with the host and port of the central server *
* - * @param httpMonitorServer2 - * @param httpMonitorPort2 + * @param httpMonitorServer the host name of the central server + * @param httpMonitorPort the port of the central server */ public HttpMonitorRemoteExchangeHandler(String httpMonitorServer, int httpMonitorPort) { @@ -187,5 +208,7 @@ /** - * + *+ * convenience method to create an initialize the utilized HTTP client + *
*/ private HttpClient createHttpClient() { Index: trunk/autoquest-httpmonitor/src/main/java/de/ugoe/cs/autoquest/httpmonitor/proxy/HttpMonitoringProxy.java =================================================================== --- trunk/autoquest-httpmonitor/src/main/java/de/ugoe/cs/autoquest/httpmonitor/proxy/HttpMonitoringProxy.java (revision 1381) +++ trunk/autoquest-httpmonitor/src/main/java/de/ugoe/cs/autoquest/httpmonitor/proxy/HttpMonitoringProxy.java (revision 1382) @@ -28,9 +28,10 @@ /** *- * TODO comment - * The HTML monitor starts a web server ({@link HttpMonitorServer}) that receives log messages - * of the HTML monitor java script. These messages are logged using the - * {@link ExchangeListenerManager}. The class assures that on shutdown e.g. caused by CTRL-C the - * server and the log manager are stopped correctly. + * The HTTP monitory proxy monitor starts a web server ({@link HttpMonitorServer}) that receives + * proxies HTTP messages and response. Each exchange of a request and a response is forwarded to + * an exchange handler. The exchange handler is either a local log manager + * ({@link HttpMonitorLogManager}) or a connection to an external and central HTTP monitor via + * an {@link HttpMonitorRemoteExchangeHandler}. The class ensures that on shutdown e.g. caused + * by CTRL-C the server and all other requied components are stopped correctly. *
* @@ -48,15 +49,15 @@ /** - * the web server receiving the log messages + * the web server receiving the HTTP requests to be proxied */ private HttpMonitorServer server; /** - * the web server receiving the log messages + * the manager for all currently recorded exchanges */ private ExchangeListenerManager exchangeListenerManager; /** - * + * the exchange handler to handle are request/response combinations, i.e., exchanges */ private HttpMonitorExchangeHandler exchangeHandler; @@ -72,20 +73,31 @@ private Thread shutdownHook; - /** */ + /** + * the name of the proxied server + */ private String proxiedServer; - /** */ + /** + * the port of the proxied server + */ private int proxiedPort; - /** */ + /** + * the name of the server where the HTTP monitor runs if the exchanges are not logged locally + */ private String httpMonitorServer; - /** */ + /** + * the port of the server where the HTTP monitor runs if the exchanges are not logged locally + */ private int httpMonitorPort; /** *- * initializes the monitor with the command line arguments. Those may be the log directory - * as first argument and the port to listen on as second + * initializes the proxy with the command line arguments. Those are the log directory + * as first argument, the port to listen to as second argument, the proxied server and port + * as third argument, and either the server and port of the HTTP monitor or the term local as + * fourth argument. If the term local is provided as fourth argument, logging of exchanges + * takes place locally. *
* Index: trunk/autoquest-httpmonitor/src/main/java/de/ugoe/cs/autoquest/httpmonitor/proxy/HttpMonitoringProxyServlet.java =================================================================== --- trunk/autoquest-httpmonitor/src/main/java/de/ugoe/cs/autoquest/httpmonitor/proxy/HttpMonitoringProxyServlet.java (revision 1381) +++ trunk/autoquest-httpmonitor/src/main/java/de/ugoe/cs/autoquest/httpmonitor/proxy/HttpMonitoringProxyServlet.java (revision 1382) @@ -34,10 +34,10 @@ /** *- * TODO document - * the servlet deployed in the web server that receives all client messages and returns the client - * java script. The messages are parsed, validated, and forwarded to the provided message listener. - * If a message is not valid, it is discarded. If an event in a message is not valid, it is - * discarded. Messages are only received via the POST HTTP method. The GET HTTP method is only - * implemented for returning the client java script. + * the servlet deployed in the web server of the proxy that proxies all incoming messages and + * forwards a copy of recorded exchanges to the exchange listener manager. It is based on the + * proxy servlet provided by jetty. It extends the servlet and implements all hooks required to + * get access to the exchanged requests and responses. Each hook forwards the tracked data to the + * exchange listener. On exchange completion, the exchange listener ensures a logging of the + * recorded exchange. *
* @@ -49,19 +49,28 @@ private static final long serialVersionUID = 1L; - /** */ + /** + * the proxied server + */ private String proxiedServer; - /** */ + /** + * the port of the proxied server + */ private int proxiedPort; - /** */ + /** + * the exchange listener to handle the different events happening when an exchange is proxied + */ private ExchangeListenerManager exchangeListenerManager; /** *- * initializes the servlet with the message listener to which all events shall be forwarded + * initializes the servlet with the proxied server and the exchange listener *
* - * @param messageListener the message listener that shall receive all client events + * @param proxiedServer the proxied server + * @param proxiedPort the port of the proxied server + * @param exchangeListenerManager the exchange listener to handle the different events + * happening when an exchange is proxied */ HttpMonitoringProxyServlet(String proxiedServer, @@ -75,5 +84,5 @@ /* (non-Javadoc) - * @see org.eclipse.jetty.proxy.ProxyServlet#rewriteURI(javax.servlet.http.HttpServletRequest) + * @see org.eclipse.jetty.proxy.ProxyServlet#rewriteURI(HttpServletRequest) */ @Override @@ -91,5 +100,5 @@ /* (non-Javadoc) - * @see org.eclipse.jetty.proxy.ProxyServlet#customizeProxyRequest(org.eclipse.jetty.client.api.Request, javax.servlet.http.HttpServletRequest) + * @see org.eclipse.jetty.proxy.ProxyServlet#customizeProxyRequest(Request, HttpServletRequest) */ @Override @@ -102,5 +111,5 @@ /* (non-Javadoc) - * @see org.eclipse.jetty.proxy.ProxyServlet#onResponseContent(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, org.eclipse.jetty.client.api.Response, byte[], int, int) + * @see ProxyServlet#onResponseContent(HttpServletRequest, HttpServletResponse, Response, byte[], int, int) */ @Override @@ -119,5 +128,5 @@ /* (non-Javadoc) - * @see org.eclipse.jetty.proxy.ProxyServlet#onResponseSuccess(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, org.eclipse.jetty.client.api.Response) + * @see ProxyServlet#onResponseSuccess(HttpServletRequest, HttpServletResponse, Response) */ @Override @@ -133,5 +142,5 @@ /* (non-Javadoc) - * @see org.eclipse.jetty.proxy.ProxyServlet#onResponseFailure(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, org.eclipse.jetty.client.api.Response, java.lang.Throwable) + * @see ProxyServlet#onResponseFailure(HttpServletRequest, HttpServletResponse, Response, Throwable) */ @Override @@ -148,16 +157,22 @@ /** - * + * This content provided is required to copy the content of a proxied request. It uses + * delegation to wrap the original content provided but to also copy the data and forward + * it to the exchange listener manager. */ private class DubbingContentProvider implements ContentProvider { - /** */ + /** + * the dubbed request + */ private HttpServletRequest request; - /** */ + /** + * the original content provider of which the data is copied + */ private ContentProvider delegate; /** - * + * initializes this content provider with the copied request and the delegate. */ public DubbingContentProvider(HttpServletRequest request, ContentProvider delegate) { @@ -185,16 +200,22 @@ /** - * + * This iterator is used to implement the {@link DubbingContentProvider}. It works in the + * same manner and uses delegation for wrapping the original iterator and forwards all copied + * data to the exchange listener manager. */ public class DubbingByteBufferIterator implements Iterator