AuditManager.java 9.54 KB
Newer Older
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision: 1632 $
 * $Date: 2005-07-15 02:49:00 -0300 (Fri, 15 Jul 2005) $
 *
6
 * Copyright (C) 2004-2008 Jive Software. All rights reserved.
7
 *
8 9 10 11 12 13 14 15 16 17 18
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
19 20
 */

21
package org.jivesoftware.openfire.audit;
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

import java.util.Collection;
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();

66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
    /**
     * Returns the maximum size in megabytes that all audit log files may have. When the
     * limit is reached oldest audit log files will be removed until total size is under
     * the limit.
     *
     * @return the maximum size of all audit logs in megabytes.
     */
    int getMaxTotalSize();

    /**
     * Sets the maximum size in megabytes that all audit log files may have. When the
     * limit is reached oldest audit log files will be removed until total size is under
     * the limit.
     *
     * @param size the maximum size of all audit logs in megabytes.
     */
    void setMaxTotalSize(int size);

84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
    /**
     * 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);

    /**
101 102 103
     * Returns the maximum number of days to keep audit information. Once the limit
     * has been reached audit files that contain information that exceed the limit
     * will be deleted.
104
     *
105
     * @return the maximum number of days to keep audit information
106 107
     *         or -1 for unlimited
     */
108
    int getMaxDays();
109 110

    /**
111
     * Set the the maximum number of days to keep audit information.
112
     *
113 114
     * @param count the maximum number of days to keep audit information
     *        or -1 for unlimited
115
     */
116
    void setMaxDays(int count);
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 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267

    /**
     * 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);

    /**
     * Returns the absolute path to the directory where the audit log files will be saved.
     *
     * @return the absolute path to the directory where the audit log files will be saved.
     */
    String getLogDir();

    /**
     * Sets the absolute path to the directory where the audit log files will be saved.
     *
     * @param logDir the absolute path to the directory where the audit log files will be saved.
     */
    void setLogDir(String logDir);

    /**
     * <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();

    /**
     * Sets the list of usernames that won't be audited. Packets sent or received by any of
     * these users will be ignored by the auditor.
     *
     * @param usernames the list of usernames that won't be audited.
     */
    void setIgnoreList(Collection<String> usernames);

    /**
     * Returns the list of usernames that won't be audited. Packets sent or received by any of
     * these users will be ignored by the auditor.
     *
     * @return the list of usernames that won't be audited.
     */
    Collection<String> getIgnoreList();
}