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

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

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