AuditManager.java 7.23 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
 * Copyright (C) 2004 Jive Software. All rights reserved.
 *
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
 */

package org.jivesoftware.messenger.audit;

import java.util.Iterator;

/**
 * Manages and directs server message auditing behavior. Turning on
 * all auditing options can produce copious amounts of data and
 * significantly slow the server as it saves the data to persistent storage.<p>
 *
 * Auditing currently saves audit data to a raw XML file
 * which can later be processed and mined for information.
 *
 * @author Iain Shigeoka
 */
public interface AuditManager {

    // Presence transitions
    public static final int PRESENCE_UNAVAILABLE_AVAILABLE = 1;
    public static final int PRESENCE_AVAILABLE_AVAILABLE = 2;
    public static final int PRESENCE_AVAILABLE_UNAVAILABLE = 4;
    public static final int PRESENCE_UNAVAILABLE_UNAVAILABLE = 8;

    /**
     * Determines if auditing is enabled at all.
     *
     * @return true if auditing is enabled, false indicates no auditing will occur
     */
    boolean isEnabled();

    /**
     * Turns auditing off or on for the manager as a whole.
     *
     * @param enabled true if auditing is enabled, false indicates no auditing will occur.
     */
    void setEnabled(boolean enabled);

    /**
     * Factory method for creating auditors that are configured by this
     * audit manager.
     *
     * @return a new auditor that will obey the configuration of the audit manager.
     */
    Auditor getAuditor();

    /**
     * Obtain the maximum size of audit log files in megabytes.
     * Logs that exceed the max size will be rolled over to another
     * file.
     *
     * @return the maximum size of an audit log in megabytes.
     */
    int getMaxFileSize();

    /**
     * Set the maximum size of audit log files in megabytes.
     *
     * @param size the maximum audit log file size in megabytes.
     */
    void setMaxFileSize(int size);

    /**
     * Obtain the maximum number of audit files to create. Audit files that
     * exceed the maximum file size will be rolled over to new files.
     * If there are more log files than the max file count, then the
     * oldest log file is overwritten.
     *
     * @return the maximum number of audit files that will be created
     *         or -1 for unlimited
     */
    int getMaxFileCount();

    /**
     * Set the maximum number of audit files to create.
     *
     * @param count the maximum number of audit files that will be
     *              created or -1 for unlimited
     */
    void setMaxFileCount(int count);

91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
    /**
     * Returns the time in milliseconds between successive executions of the task that will save
     * the queued audited packets to a permanent store.
     *
     * @return the time in milliseconds between successive executions of the task that will save
     *         the queued audited packets to a permanent store.
     */
    int getLogTimeout();

    /**
     * Sets the time in milliseconds between successive executions of the task that will save
     * the queued audited packets to a permanent store.
     *
     * @param logTimeout the time in milliseconds between successive executions of the task that will save
     *        the queued audited packets to a permanent store. 
     */
    void setLogTimeout(int logTimeout);

Matt Tucker's avatar
Matt Tucker committed
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
    /**
     * <p>Determines if the server will audit all message packets.</p>
     * <p>This is a speed optimization and convenience for logging all message packets
     * rather than using an XPath expression.</p>
     *
     * @return true if all messages are to be audited
     */
    boolean isAuditMessage();

    /**
     * <p>Enables or disables the server auditing of all message packets.</p>
     * <p>This is a speed optimization and convenience for logging all message packets
     * rather than using an XPath expression.</p>
     *
     * @param enabled True if all messages are to be audited
     */
    void setAuditMessage(boolean enabled);

    /**
     * <p>Determines if the server will audit all presence packets.</p>
     * <p>This is a speed optimization and convenience for logging all presence packets
     * rather than using an XPath expression.</p>
     *
     * @return True if all presence are to be audited
     */
    boolean isAuditPresence();

    /**
     * <p>Enables or disables the server auditing of all presence packets.</p>
     * <p>This is a speed optimization and convenience for logging all presence packets
     * rather than using an XPath expression.</p>
     *
     * @param enabled True if all presence are to be audited
     */
    void setAuditPresence(boolean enabled);

    /**
     * <p>Determines if the server will audit all iq packets.</p>
     * <p>This is a speed optimization and convenience for logging all iq packets
     * rather than using an XPath expression.</p>
     *
     * @return True if all iq are to be audited
     */
    boolean isAuditIQ();

    /**
     * Enables or disables the server auditing of all iq packets.
     * This is a speed optimization and convenience for logging all iq packets
     * rather than using an XPath expression.
     *
     * @param enabled true if all iq are to be audited.
     */
    void setAuditIQ(boolean enabled);

    /**
     * Determines if the server will audit packets using XPath expressions.
     * XPath expressions provide a lot of power in specifying what is logged.
     * However, it is much more compute intensive than other techniques and requires
     * all packets be transformed into DOM objects (which can be computationally expensive).
     *
     * @return true if XPath expressions should be audited.
     */
    boolean isAuditXPath();

    /**
     * <p>Enables/disables server auditing of packets using XPath expressions.</p>
     * <p>XPath expressions provide a lot of power in specifying what is logged.
     * However, it is much more compute intensive than other techniques and requires
     * all packets be transformed into DOM objects (which can be computationally expensive).</p>
     *
     * @param enabled true if XPath expressions should be audited
     */
    void setAuditXPath(boolean enabled);

    /**
     * Adds an XPath expression to be used for filtering packets to be audited.
     * XPath expressions aren't evaluated or used for filtering unless isAuditXPath()
     * returns true.
     *
     * @param xpathExpression the xpath expression to add to the list of auditing filters.
     */
    void addXPath(String xpathExpression);

    /**
     * <p>Removes the XPath expression from the set being used for filtering packets to be audited.</p>
     * <p>XPath expressions aren't evaluated or used for filtering unless isAuditXPath()
     * returns true.</p>
     *
     * @param xpathExpression The xpath expression to remove from the list of auditing filters
     */
    void removeXPath(String xpathExpression);

    /**
     * <p>Obtain an iterator over the XPath expressions (Strings) currently registered
     * with the audit manager.</p>
     * <p>XPath expressions aren't evaluated or used for filtering unless isAuditXPath()
     * returns true.</p>
     *
     * @return An iterator of all XPath expressions the audit manager is using
     */
    Iterator getXPathFilters();
    
}