- * TODO comment + * The log manager handles different {@link HtmlMonitorOutputWriter}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 HtmlMonitorMessageListener} mechanism provided by the + * {@link HtmlMonitorServer} is used. *
* * @author Patrick Harms */ -public class HtmlMonitorLogManager implements HtmlMonitorComponent, HtmlMonitorMessageListener { +class HtmlMonitorLogManager implements HtmlMonitorComponent, HtmlMonitorMessageListener { /** - * + * the timeout after which a writer of an inactive client is closed */ private static final int SESSION_TIMEOUT = 100000; /** - * + * the directory into which the log files shall be written */ private String logFileBaseDir; /** - * + * the mapping of client ids to the respective writers. */ private Map- * TODO: comment + * initializes the log manager with the directory into which the log files shall be stored *
* - * @param logFileBaseDir + * @param logFileBaseDir the directory into which the log files shall be stored */ HtmlMonitorLogManager(String logFileBaseDir) { @@ -93,5 +98,5 @@ /* (non-Javadoc) - * @see de.ugoe.cs.autoquest.htmlmonitor.HtmlMonitoringListener#handleEvents(de.ugoe.cs.quest.htmlmonitor.HtmlClientInfos, de.ugoe.cs.quest.htmlmonitor.HtmlEvent[]) + * @see HtmlMonitoringListener#handleEvents(HtmlClientInfos, HtmlEvent[]) */ @Override @@ -139,5 +144,5 @@ /** *- * TODO comment + * internal timer task used for detecting session timeouts of clients *
* Index: trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorMessageListener.java =================================================================== --- trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorMessageListener.java (revision 870) +++ trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorMessageListener.java (revision 871) @@ -3,5 +3,6 @@ /** *- * TODO comment + * a message listener to be registered with the {@link HtmlMonitorServer} for being called for + * new messages send by clients. *
* @@ -12,9 +13,10 @@ /** *
- * TODO: comment
+ * called for new messages received from a client. The client is described through the
+ * clientInfos. The events are several events that were recorded at client side.
*
- * comment + * dumps messages to a log file belonging to a specific client id. In the provided base log + * directory, it creates a subdirectory with the client id. In this directory it creates + * appropriate log files. The name of each finished log file starts with the "htmlmonitor_" + * followed by the client id and an index of the log file. An unfinished log file has no index yet. + * A log file is finished if + *
+ * initializes the writer with the log file base directory and the id of the client for which + * this writer logs the messages. + *
* - */ - private static final int MAXIMUM_LOG_FILE_SIZE = 10000000; - - /** - * - */ - private static final String DEFAULT_LOG_FILE_BASE_DIR = "logs"; - - /** - * - */ - private File logFileBaseDir; - - /** - * - */ - private String clientId; - - /** - * - */ - private File logFile; - - /** - *- * Writer for logging events. - *
- */ - private PrintWriter outputWriter; - - /** - * - */ - private long lastUpdate; - - /** - *- * - *
- * - * @param outputWriter - * writer for the logged information + * @param logFileBaseDir the log file base directory, or null if the default directory shall + * be taken + * @param clientId the ID of the client, for which this writer logs */ public HtmlMonitorOutputWriter(String logFileBaseDir, String clientId) { @@ -117,9 +127,11 @@ /** *- * TODO: comment + * used to calculate a log file name. If the provided index is smaller 0, then no index + * is added to the file name. A filename is e.g. "htmlmonitor_12345_001.log". *
* - * @param logFileIndex2 - * @return + * @param index the index of the log file or -1 one, if no index shall be added + * + * @return the file name as described */ private String getLogFileName(int index) { @@ -144,5 +156,5 @@ /* (non-Javadoc) - * @see de.ugoe.cs.autoquest.htmlmonitor.HtmlMonitorMessageListener#handleMessage(de.ugoe.cs.quest.htmlmonitor.HtmlClientInfos, de.ugoe.cs.quest.htmlmonitor.HtmlEvent[]) + * @see HtmlMonitorMessageListener#handleMessage(HtmlClientInfos, HtmlEvent[]) */ @Override @@ -170,8 +182,9 @@ /** *- * TODO: comment + * formats a received event and writes it to the log file. One event results in one line + * in the log file containing all infos of the event. *
* - * @param event + * @param event to be written to the log file */ private void dumpEvent(HtmlEvent event) { @@ -219,5 +232,6 @@ /** *- * TODO: comment + * convenience method to dump a string with trailing and leading " as well as replaced + * backslashes, ", and newlines *
* @@ -226,5 +240,6 @@ private void dumpString(String str) { outputWriter.print('"'); - outputWriter.print(str.replaceAll("\\\\", "\\\\").replaceAll("\\\"", "\\\"")); + outputWriter.print + (str.replaceAll("\\\\", "\\\\").replaceAll("\\\"", "\\\"").replaceAll("\n", " ")); outputWriter.print('"'); } @@ -232,7 +247,8 @@ /** *- * TODO: comment - *
- * + * checks, if the log file exeeded the {@link #MAXIMUM_LOG_FILE_SIZE}. If so, the current + * log file is closed, the next log file name is determined and this new file is opend for + * writing. + * */ private synchronized void considerLogRotate() throws IOException { @@ -246,7 +262,7 @@ /** *- * TODO: comment - *
- * + * renames the current log file to a new log file with the next available index. It further + * sets the current log file to the default name, i.e. without index. + * */ private void rotateLogFile() { @@ -269,7 +285,6 @@ /** *- * TODO: comment - *
- * + * instantiates a writer to be used for writing messages into the log file. + * */ private void createLogWriter() throws IOException { @@ -280,7 +295,6 @@ /** *- * TODO: comment - *
- * + * closed the current writer if it is open. + * */ private void closeLogWriter() { @@ -305,8 +319,8 @@ /** *- * TODO: comment + * return the time stamp of the last activity that happened on this writer. *
* - * @return + * @return as described */ public long getLastUpdate() { Index: trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServer.java =================================================================== --- trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServer.java (revision 870) +++ trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServer.java (revision 871) @@ -8,5 +8,10 @@ /** - * TODO: comment + *+ * this is the web server, that receives the client messages. It is initialized with a port on + * which it shall listen, as well as a message listener to forward the received messages to. + * Internally it starts a jetty web server with a single {@link HtmlMonitorServlet} to receive + * the messages. + *
* * @author Patrick Harms @@ -15,15 +20,15 @@ /** - * + * the port to listen on */ private int port; /** - * + * the jetty web server used for receiving messages */ private Server server; /** - * + * the message listener to forward the messages to */ private HtmlMonitorMessageListener messageListener; @@ -31,7 +36,10 @@ /** *- * TODO: comment + * initializes the server with the port to listen on and the message listener to forward + * the messages to. *
* + * @param port the port to listen on + * @param messageListener the message listener to forward the messages to */ HtmlMonitorServer(int port, HtmlMonitorMessageListener messageListener) { Index: trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServlet.java =================================================================== --- trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServlet.java (revision 870) +++ trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServlet.java (revision 871) @@ -24,10 +24,13 @@ /** *- * TODO comment + * the servlet deployed in the web server that receives all client messages. 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. *
* * @author Patrick Harms */ -public class HtmlMonitorServlet extends DefaultServlet { +class HtmlMonitorServlet extends DefaultServlet { /** */ @@ -35,5 +38,5 @@ /** - * + * the message listener to forward received messages to. */ private HtmlMonitorMessageListener messageListener; @@ -41,8 +44,8 @@ /** *- * TODO: comment - *
- * - * @param htmlMonitoringListener + * initializes the servlet with the message listener to which all events shall be forwarded + * + * + * @param messageListener the message listener that shall receive all client events */ HtmlMonitorServlet(HtmlMonitorMessageListener messageListener) { @@ -76,8 +79,9 @@ /** *- * TODO: comment - *
- * - * @param object + * processes a received JSON object and validates it. If the message is ok, it is forwarded + * to the message listener + * + * + * @param object the JSON object that contains a client message */ private void handleJSONObject(JSONObject object) { @@ -111,9 +115,12 @@ /** *- * TODO: comment - *
- * - * @param object - * @return + * tries to extract the client infos out of the received JSON object. If this is not fully + * possible, an appropriate message is dumped and the whole message is discarded (the method + * return null). + * + * + * @param message the message to parse the client infos from + * + * @return the client infos, if the message is valid in this respect, or null if not */ private HtmlClientInfos extractClientInfos(JSONObject message) { @@ -150,10 +157,13 @@ /** *- * TODO: comment - *
- * - * @param object - * @param clientInfos - * @return + * tries to extract the events out of the received JSON object. If this is not fully + * possible, an appropriate message is dumped and the errorprone event is discarded. If no + * valid event is found, the whole message is discarded. + * + * + * @param object the message to parse the events from + * @param clientInfos the infos about the client that send the events + * + * @return the valid events stored in the message, or null if there are none */ private HtmlEvent[] extractHtmlEvents(JSONObject object, HtmlClientInfos clientInfos) { @@ -218,12 +228,15 @@ /** *- * TODO: comment - *
- * - * @param eventType - * @param coordinates - * @param key - * @param scrollPosition - * @return + * validates if for the given event type the parameter combination of coordinates, key, and + * scroll position is valid. As an example, an onclick event should usually not have an + * associated scroll position. + * + * + * @param eventType the type of the event + * @param coordinates the coordinates of the event + * @param key the key of the event + * @param scrollPosition the scroll position of the event + * + * @return true, if the combination of the parameters is valid, false else */ private boolean checkEventParameterCombinations(String eventType, @@ -279,11 +292,15 @@ /** *- * TODO: comment - *
- * - * @param object - * @param string - * @param class1 - * @return + * converts a value in the provided object matching the provided key to the provided type. If + * there is no value with the key or if the value can not be transformed to the provided type, + * the method returns null. + * + * + * @param object the object to read the value from + * @param key the key of the value + * @param clazz the type to which the value should be transformed + * + * @return the value or null if either the value does not exist or if it can not be transformed + * to the expected type */ @SuppressWarnings("unchecked") @@ -381,8 +398,10 @@ /** *- * TODO: comment - *
- * - * @param object + * convenience method for dumping an object to std out. If the object is a JSON object, it is + * deeply analyzed and its internal structure is dumped as well. + * + * + * @param object the object to dump + * @param indent the indentation to be used. */ private void dumpJSONObject(Object object, String indent) { Index: trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/Runner.java =================================================================== --- trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/Runner.java (revision 870) +++ trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/Runner.java (revision 871) @@ -6,5 +6,5 @@ /** *- * TODO comment + * implements the main method to start the {@link HtmlMonitor}. *
* @@ -19,6 +19,5 @@ * * - * @param args - * TODO comment + * @param args command line arguments */ public static void main(String[] args) { Index: trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/ShutdownHook.java =================================================================== --- trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/ShutdownHook.java (revision 870) +++ trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/ShutdownHook.java (revision 871) @@ -3,5 +3,6 @@ /** *- * TODO comment + * used to be able to shut down any {@link HtmlMonitorComponent} that must be stopped if the + * application stops. *
* @@ -10,10 +11,13 @@ public class ShutdownHook implements Runnable { - /** */ + /** + * the components to be stopped on shutdown + */ private HtmlMonitorComponent[] components; /** *- * TODO: comment + * initializes the shutdown hook with the components to be shut down on shutdown of the whole + * application *
*