Ignore:
Timestamp:
10/12/12 15:08:45 (12 years ago)
Author:
pharms
Message:
  • added some comments
Location:
trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor
Files:
10 edited

Legend:

Unmodified
Added
Removed

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlClientInfos.java

    r870 r871  
    1010 * @author Patrick Harms 
    1111 */ 
    12 public class HtmlClientInfos { 
     12class HtmlClientInfos { 
    1313 
    1414    /** 

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorComponent.java

    r870 r871  
    1010 * @author Patrick Harms 
    1111 */ 
    12 public interface HtmlMonitorComponent { 
     12interface HtmlMonitorComponent { 
    1313 
    1414    /** 

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorException.java

    r870 r871  
    99 * @author Patrick Harms 
    1010 */ 
    11 public class HtmlMonitorException extends Exception { 
     11class HtmlMonitorException extends Exception { 
    1212 
    1313    /**  */ 
    … …  
    2121     * @param message the message of the exception 
    2222     */ 
    23     public HtmlMonitorException(String message) { 
     23    HtmlMonitorException(String message) { 
    2424        super(message); 
    2525    } 
    … …  
    3333     * @param cause   the root cause of the exception 
    3434     */ 
    35     public HtmlMonitorException(String message, Throwable cause) { 
     35    HtmlMonitorException(String message, Throwable cause) { 
    3636        super(message, cause); 
    3737    } 

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorLogManager.java

    r857 r871  
    1212/** 
    1313 * <p> 
    14  * TODO comment 
     14 * The log manager handles different {@link HtmlMonitorOutputWriter}s to perform the logging 
     15 * of recorded messages. It initializes a new writer if the first message for a specific 
     16 * client is received and it closes a writer if for a specific period of time no further message 
     17 * of the same client was received. The writers themselves consider log rotation. For handling 
     18 * messages, the {@link HtmlMonitorMessageListener} mechanism provided by the 
     19 * {@link HtmlMonitorServer} is used. 
    1520 * </p> 
    1621 *  
    1722 * @author Patrick Harms 
    1823 */ 
    19 public class HtmlMonitorLogManager implements HtmlMonitorComponent, HtmlMonitorMessageListener { 
     24class HtmlMonitorLogManager implements HtmlMonitorComponent, HtmlMonitorMessageListener { 
    2025     
    2126    /** 
    22      *  
     27     * the timeout after which a writer of an inactive client is closed 
    2328     */ 
    2429    private static final int SESSION_TIMEOUT = 100000; 
    2530     
    2631    /** 
    27      *  
     32     * the directory into which the log files shall be written 
    2833     */ 
    2934    private String logFileBaseDir; 
    3035 
    3136    /** 
    32      *  
     37     * the mapping of client ids to the respective writers. 
    3338     */ 
    3439    private Map<String, HtmlMonitorOutputWriter> writers; 
    3540 
    3641    /** 
    37      *  
     42     * a timer used to detect client timouts 
    3843     */ 
    3944    private Timer logFileMonitorTimer; 
    … …  
    4146    /** 
    4247     * <p> 
    43      * TODO: comment 
     48     * initializes the log manager with the directory into which the log files shall be stored 
    4449     * </p> 
    4550     * 
    46      * @param logFileBaseDir 
     51     * @param logFileBaseDir the directory into which the log files shall be stored 
    4752     */ 
    4853    HtmlMonitorLogManager(String logFileBaseDir) { 
    … …  
    9398 
    9499    /* (non-Javadoc) 
    95      * @see de.ugoe.cs.autoquest.htmlmonitor.HtmlMonitoringListener#handleEvents(de.ugoe.cs.quest.htmlmonitor.HtmlClientInfos, de.ugoe.cs.quest.htmlmonitor.HtmlEvent[]) 
     100     * @see HtmlMonitoringListener#handleEvents(HtmlClientInfos, HtmlEvent[]) 
    96101     */ 
    97102    @Override 
    … …  
    139144    /** 
    140145     * <p> 
    141      * TODO comment 
     146     * internal timer task used for detecting session timeouts of clients 
    142147     * </p> 
    143148     *  

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorMessageListener.java

    r857 r871  
    33/** 
    44 * <p> 
    5  * TODO comment 
     5 * a message listener to be registered with the {@link HtmlMonitorServer} for being called for 
     6 * new messages send by clients. 
    67 * </p> 
    78 *  
    … …  
    1213    /** 
    1314     * <p> 
    14      * TODO: comment 
     15     * called for new messages received from a client. The client is described through the 
     16     * <code>clientInfos</code>. The events are several events that were recorded at client side. 
    1517     * </p> 
    1618     * 
    17      * @param clientInfos 
    18      * @param events 
     19     * @param clientInfos infos about the client that send the events 
     20     * @param events      the received events 
    1921     */ 
    2022    void handleMessage(HtmlClientInfos clientInfos, HtmlEvent[] events); 

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorOutputWriter.java

    r857 r871  
    1111/** 
    1212 * <p> 
    13  * comment 
     13 * dumps messages to a log file belonging to a specific client id. In the provided base log 
     14 * directory, it creates a subdirectory with the client id. In this directory it creates 
     15 * appropriate log files. The name of each finished log file starts with the "htmlmonitor_" 
     16 * followed by the client id and an index of the log file. An unfinished log file has no index yet. 
     17 * A log file is finished if 
     18 * <ul> 
     19 *   <li>the client session is closed by a timeout</li> 
     20 *   <li>the HTML monitor is normally shut down</li> 
     21 *   <li>on startup an unfinished log file is detected.</li> 
     22 *   <li>the {@link #MAXIMUM_LOG_FILE_SIZE} is reached</li> 
     23 * </ul> 
    1424 * </p> 
    1525 *  
    … …  
    2131     
    2232    /** 
     33     * the maximum size of an individual log file 
     34     */ 
     35    private static final int MAXIMUM_LOG_FILE_SIZE = 10000000; 
     36 
     37    /** 
     38     * the default log base directory if none is provided through the constructor  
     39     */ 
     40    private static final String DEFAULT_LOG_FILE_BASE_DIR = "logs"; 
     41 
     42    /** 
     43     * the currently used log file base directory 
     44     */ 
     45    private File logFileBaseDir; 
     46 
     47    /** 
     48     * the is of the client of which all messages are logged through this writer 
     49     */ 
     50    private String clientId; 
     51 
     52    /** 
     53     * the log file into which all messages are currently written 
     54     */ 
     55    private File logFile; 
     56 
     57    /** 
     58     * an output writer to be used for writing into the log file 
     59     */ 
     60    private PrintWriter outputWriter; 
     61 
     62    /** 
     63     * the time stamp of the last action taken on this writer (such as logging a message) 
     64     */ 
     65    private long lastUpdate; 
     66 
     67    /** 
     68     * <p> 
     69     * initializes the writer with the log file base directory and the id of the client for which 
     70     * this writer logs the messages. 
     71     * </p> 
    2372     *  
    24      */ 
    25     private static final int MAXIMUM_LOG_FILE_SIZE = 10000000; 
    26  
    27     /** 
    28      *  
    29      */ 
    30     private static final String DEFAULT_LOG_FILE_BASE_DIR = "logs"; 
    31  
    32     /** 
    33      *  
    34      */ 
    35     private File logFileBaseDir; 
    36  
    37     /** 
    38      * 
    39      */ 
    40     private String clientId; 
    41  
    42     /** 
    43      * 
    44      */ 
    45     private File logFile; 
    46  
    47     /** 
    48      * <p> 
    49      * Writer for logging events. 
    50      * </p> 
    51      */ 
    52     private PrintWriter outputWriter; 
    53  
    54     /** 
    55      *  
    56      */ 
    57     private long lastUpdate; 
    58  
    59     /** 
    60      * <p> 
    61      *  
    62      * </p> 
    63      *  
    64      * @param outputWriter 
    65      *            writer for the logged information 
     73     * @param logFileBaseDir the log file base directory, or null if the default directory shall 
     74     *                       be taken 
     75     * @param clientId       the ID of the client, for which this writer logs 
    6676     */ 
    6777    public HtmlMonitorOutputWriter(String logFileBaseDir, String clientId) { 
    … …  
    117127    /** 
    118128     * <p> 
    119      * TODO: comment 
     129     * used to calculate a log file name. If the provided index is smaller 0, then no index 
     130     * is added to the file name. A filename is e.g. "htmlmonitor_12345_001.log".  
    120131     * </p> 
    121132     * 
    122      * @param logFileIndex2 
    123      * @return 
     133     * @param index the index of the log file or -1 one, if no index shall be added 
     134     *  
     135     * @return the file name as described 
    124136     */ 
    125137    private String getLogFileName(int index) { 
    … …  
    144156 
    145157    /* (non-Javadoc) 
    146      * @see de.ugoe.cs.autoquest.htmlmonitor.HtmlMonitorMessageListener#handleMessage(de.ugoe.cs.quest.htmlmonitor.HtmlClientInfos, de.ugoe.cs.quest.htmlmonitor.HtmlEvent[]) 
     158     * @see HtmlMonitorMessageListener#handleMessage(HtmlClientInfos, HtmlEvent[]) 
    147159     */ 
    148160    @Override 
    … …  
    170182    /** 
    171183     * <p> 
    172      * TODO: comment 
     184     * formats a received event and writes it to the log file. One event results in one line 
     185     * in the log file containing all infos of the event. 
    173186     * </p> 
    174187     * 
    175      * @param event 
     188     * @param event to be written to the log file 
    176189     */ 
    177190    private void dumpEvent(HtmlEvent event) { 
    … …  
    219232    /** 
    220233     * <p> 
    221      * TODO: comment 
     234     * convenience method to dump a string with trailing and leading " as well as replaced 
     235     * backslashes, ", and newlines 
    222236     * </p> 
    223237     * 
    … …  
    226240    private void dumpString(String str) { 
    227241        outputWriter.print('"'); 
    228         outputWriter.print(str.replaceAll("\\\\", "\\\\").replaceAll("\\\"", "\\\"")); 
     242        outputWriter.print 
     243            (str.replaceAll("\\\\", "\\\\").replaceAll("\\\"", "\\\"").replaceAll("\n", " ")); 
    229244        outputWriter.print('"'); 
    230245    } 
    … …  
    232247    /** 
    233248     * <p> 
    234      * TODO: comment 
    235      * </p> 
    236      * 
     249     * checks, if the log file exeeded the {@link #MAXIMUM_LOG_FILE_SIZE}. If so, the current 
     250     * log file is closed, the next log file name is determined and this new file is opend for 
     251     * writing.  
     252     * </p> 
    237253     */ 
    238254    private synchronized void considerLogRotate() throws IOException { 
    … …  
    246262    /** 
    247263     * <p> 
    248      * TODO: comment 
    249      * </p> 
    250      * 
     264     * renames the current log file to a new log file with the next available index. It further 
     265     * sets the current log file to the default name, i.e. without index. 
     266     * </p> 
    251267     */ 
    252268    private void rotateLogFile() { 
    … …  
    269285    /** 
    270286     * <p> 
    271      * TODO: comment 
    272      * </p> 
    273      * 
     287     * instantiates a writer to be used for writing messages into the log file. 
     288     * </p> 
    274289     */ 
    275290    private void createLogWriter() throws IOException { 
    … …  
    280295    /** 
    281296     * <p> 
    282      * TODO: comment 
    283      * </p> 
    284      * 
     297     * closed the current writer if it is open. 
     298     * </p> 
    285299     */ 
    286300    private void closeLogWriter() { 
    … …  
    305319    /** 
    306320     * <p> 
    307      * TODO: comment 
     321     * return the time stamp of the last activity that happened on this writer. 
    308322     * </p> 
    309323     * 
    310      * @return 
     324     * @return as described 
    311325     */ 
    312326    public long getLastUpdate() { 

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServer.java

    r857 r871  
    88 
    99/** 
    10  * TODO: comment 
     10 * <p> 
     11 * this is the web server, that receives the client messages. It is initialized with a port on 
     12 * which it shall listen, as well as a message listener to forward the received messages to. 
     13 * Internally it starts a jetty web server with a single {@link HtmlMonitorServlet} to receive 
     14 * the messages. 
     15 * </p> 
    1116 *  
    1217 * @author Patrick Harms 
    … …  
    1520     
    1621    /** 
    17      *  
     22     * the port to listen on 
    1823     */ 
    1924    private int port; 
    2025 
    2126    /** 
    22      *  
     27     * the jetty web server used for receiving messages 
    2328     */ 
    2429    private Server server; 
    2530 
    2631    /** 
    27      *  
     32     * the message listener to forward the messages to 
    2833     */ 
    2934    private HtmlMonitorMessageListener messageListener; 
    … …  
    3136    /** 
    3237     * <p> 
    33      * TODO: comment 
     38     * initializes the server with the port to listen on and the message listener to forward 
     39     * the messages to. 
    3440     * </p> 
    3541     * 
     42     * @param port            the port to listen on 
     43     * @param messageListener the message listener to forward the messages to 
    3644     */ 
    3745    HtmlMonitorServer(int port, HtmlMonitorMessageListener messageListener) { 

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/HtmlMonitorServlet.java

    r857 r871  
    2424/** 
    2525 * <p> 
    26  * TODO comment 
     26 * the servlet deployed in the web server that receives all client messages. The messages are 
     27 * parsed, validated, and forwarded to the provided message listener. If a message is not valid, 
     28 * it is discarded. If an event in a message is not valid, it is discarded. Messages are only 
     29 * received via the POST HTTP method. 
    2730 * </p> 
    2831 *  
    2932 * @author Patrick Harms 
    3033 */ 
    31 public class HtmlMonitorServlet extends DefaultServlet { 
     34class HtmlMonitorServlet extends DefaultServlet { 
    3235 
    3336    /**  */ 
    … …  
    3538     
    3639    /** 
    37      *  
     40     * the message listener to forward received messages to. 
    3841     */ 
    3942    private HtmlMonitorMessageListener messageListener; 
    … …  
    4144    /** 
    4245     * <p> 
    43      * TODO: comment 
    44      * </p> 
    45      * 
    46      * @param htmlMonitoringListener 
     46     * initializes the servlet with the message listener to which all events shall be forwarded 
     47     * </p> 
     48     * 
     49     * @param messageListener the message listener that shall receive all client events 
    4750     */ 
    4851    HtmlMonitorServlet(HtmlMonitorMessageListener messageListener) { 
    … …  
    7679    /** 
    7780     * <p> 
    78      * TODO: comment 
    79      * </p> 
    80      * 
    81      * @param object 
     81     * processes a received JSON object and validates it. If the message is ok, it is forwarded 
     82     * to the message listener 
     83     * </p> 
     84     * 
     85     * @param object the JSON object that contains a client message 
    8286     */ 
    8387    private void handleJSONObject(JSONObject object) { 
    … …  
    111115    /** 
    112116     * <p> 
    113      * TODO: comment 
    114      * </p> 
    115      * 
    116      * @param object 
    117      * @return 
     117     * tries to extract the client infos out of the received JSON object. If this is not fully 
     118     * possible, an appropriate message is dumped and the whole message is discarded (the method 
     119     * return null). 
     120     * </p> 
     121     * 
     122     * @param message the message to parse the client infos from 
     123     *  
     124     * @return the client infos, if the message is valid in this respect, or null if not 
    118125     */ 
    119126    private HtmlClientInfos extractClientInfos(JSONObject message) { 
    … …  
    150157    /** 
    151158     * <p> 
    152      * TODO: comment 
    153      * </p> 
    154      * 
    155      * @param object 
    156      * @param clientInfos 
    157      * @return 
     159     * tries to extract the events out of the received JSON object. If this is not fully 
     160     * possible, an appropriate message is dumped and the errorprone event is discarded. If no 
     161     * valid event is found, the whole message is discarded. 
     162     * </p> 
     163     * 
     164     * @param object      the message to parse the events from 
     165     * @param clientInfos the infos about the client that send the events 
     166     *   
     167     * @return the valid events stored in the message, or null if there are none 
    158168     */ 
    159169    private HtmlEvent[] extractHtmlEvents(JSONObject object, HtmlClientInfos clientInfos) { 
    … …  
    218228    /** 
    219229     * <p> 
    220      * TODO: comment 
    221      * </p> 
    222      * 
    223      * @param eventType 
    224      * @param coordinates 
    225      * @param key 
    226      * @param scrollPosition 
    227      * @return 
     230     * validates if for the given event type the parameter combination of coordinates, key, and 
     231     * scroll position is valid. As an example, an onclick event should usually not have an 
     232     * associated scroll position. 
     233     * </p> 
     234     * 
     235     * @param eventType      the type of the event 
     236     * @param coordinates    the coordinates of the event 
     237     * @param key            the key of the event 
     238     * @param scrollPosition the scroll position of the event 
     239     *  
     240     * @return true, if the combination of the parameters is valid, false else 
    228241     */ 
    229242    private boolean checkEventParameterCombinations(String    eventType, 
    … …  
    279292    /** 
    280293     * <p> 
    281      * TODO: comment 
    282      * </p> 
    283      * 
    284      * @param object 
    285      * @param string 
    286      * @param class1 
    287      * @return 
     294     * converts a value in the provided object matching the provided key to the provided type. If 
     295     * there is no value with the key or if the value can not be transformed to the provided type, 
     296     * the method returns null.  
     297     * </p> 
     298     * 
     299     * @param object the object to read the value from 
     300     * @param key    the key of the value 
     301     * @param clazz  the type to which the value should be transformed 
     302     *  
     303     * @return the value or null if either the value does not exist or if it can not be transformed 
     304     *         to the expected type 
    288305     */ 
    289306    @SuppressWarnings("unchecked") 
    … …  
    381398    /** 
    382399     * <p> 
    383      * TODO: comment 
    384      * </p> 
    385      * 
    386      * @param object 
     400     * convenience method for dumping an object to std out. If the object is a JSON object, it is 
     401     * deeply analyzed and its internal structure is dumped as well. 
     402     * </p> 
     403     * 
     404     * @param object the object to dump 
     405     * @param indent the indentation to be used. 
    387406     */ 
    388407    private void dumpJSONObject(Object object, String indent) { 

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/Runner.java

    r857 r871  
    66/** 
    77 * <p> 
    8  * TODO comment 
     8 * implements the main method to start the {@link HtmlMonitor}. 
    99 * </p> 
    1010 *  
    … …  
    1919     * </p> 
    2020     *  
    21      * @param args 
    22      *            TODO comment 
     21     * @param args command line arguments 
    2322     */ 
    2423    public static void main(String[] args) { 

  • trunk/autoquest-htmlmonitor/src/main/java/de/ugoe/cs/autoquest/htmlmonitor/ShutdownHook.java

    r857 r871  
    33/** 
    44 * <p> 
    5  * TODO comment 
     5 * used to be able to shut down any {@link HtmlMonitorComponent} that must be stopped if the 
     6 * application stops. 
    67 * </p> 
    78 *  
    … …  
    1011public class ShutdownHook implements Runnable { 
    1112 
    12     /** */ 
     13    /** 
     14     * the components to be stopped on shutdown 
     15     */ 
    1316    private HtmlMonitorComponent[] components; 
    1417     
    1518    /** 
    1619     * <p> 
    17      * TODO: comment 
     20     * initializes the shutdown hook with the components to be shut down on shutdown of the whole 
     21     * application 
    1822     * </p> 
    1923     * 
Note: See TracChangeset for help on using the changeset viewer.