AuditManager


1   /**
2    * $RCSfile: AuditManager.java,v $
3    * $Revision: 1.5 $
4    * $Date: 2005/07/15 05:48:59 $
5    *
6    * Copyright (C) 2004 Jive Software. All rights reserved.
7    *
8    * This software is published under the terms of the GNU Public License (GPL),
9    * a copy of which is included in this distribution.
10   */
11  
12  package org.jivesoftware.messenger.audit;
13  
14  import java.util.Collection  ;
15  import java.util.Iterator  ;
16  
17  /**
18   * Manages and directs server message auditing behavior. Turning on
19   * all auditing options can produce copious amounts of data and
20   * significantly slow the server as it saves the data to persistent storage.<p>
21   *
22   * Auditing currently saves audit data to a raw XML file
23   * which can later be processed and mined for information.
24   *
25   * @author Iain Shigeoka
26   */
27  public interface AuditManager {
28  
29      // Presence transitions
30      public static final int PRESENCE_UNAVAILABLE_AVAILABLE = 1;
31      public static final int PRESENCE_AVAILABLE_AVAILABLE = 2;
32      public static final int PRESENCE_AVAILABLE_UNAVAILABLE = 4;
33      public static final int PRESENCE_UNAVAILABLE_UNAVAILABLE = 8;
34  
35      /**
36       * Determines if auditing is enabled at all.
37       *
38       * @return true if auditing is enabled, false indicates no auditing will occur
39       */
40      boolean isEnabled();
41  
42      /**
43       * Turns auditing off or on for the manager as a whole.
44       *
45       * @param enabled true if auditing is enabled, false indicates no auditing will occur.
46       */
47      void setEnabled(boolean enabled);
48  
49      /**
50       * Factory method for creating auditors that are configured by this
51       * audit manager.
52       *
53       * @return a new auditor that will obey the configuration of the audit manager.
54       */
55      Auditor getAuditor();
56  
57      /**
58       * Obtain the maximum size of audit log files in megabytes.
59       * Logs that exceed the max size will be rolled over to another
60       * file.
61       *
62       * @return the maximum size of an audit log in megabytes.
63       */
64      int getMaxFileSize();
65  
66      /**
67       * Set the maximum size of audit log files in megabytes.
68       *
69       * @param size the maximum audit log file size in megabytes.
70       */
71      void setMaxFileSize(int size);
72  
73      /**
74       * Obtain the maximum number of audit files to create. Audit files that
75       * exceed the maximum file size will be rolled over to new files.
76       * If there are more log files than the max file count, then the
77       * oldest log file is overwritten.
78       *
79       * @return the maximum number of audit files that will be created
80       *         or -1 for unlimited
81       */
82      int getMaxFileCount();
83  
84      /**
85       * Set the maximum number of audit files to create.
86       *
87       * @param count the maximum number of audit files that will be
88       *              created or -1 for unlimited
89       */
90      void setMaxFileCount(int count);
91  
92      /**
93       * Returns the time in milliseconds between successive executions of the task that will save
94       * the queued audited packets to a permanent store.
95       *
96       * @return the time in milliseconds between successive executions of the task that will save
97       *         the queued audited packets to a permanent store.
98       */
99      int getLogTimeout();
100 
101     /**
102      * Sets the time in milliseconds between successive executions of the task that will save
103      * the queued audited packets to a permanent store.
104      *
105      * @param logTimeout the time in milliseconds between successive executions of the task that will save
106      *        the queued audited packets to a permanent store. 
107      */
108     void setLogTimeout(int logTimeout);
109 
110     /**
111      * Returns the absolute path to the directory where the audit log files will be saved.
112      *
113      * @return the absolute path to the directory where the audit log files will be saved.
114      */
115     String   getLogDir();
116 
117     /**
118      * Sets the absolute path to the directory where the audit log files will be saved.
119      *
120      * @param logDir the absolute path to the directory where the audit log files will be saved.
121      */
122     void setLogDir(String   logDir);
123 
124     /**
125      * <p>Determines if the server will audit all message packets.</p>
126      * <p>This is a speed optimization and convenience for logging all message packets
127      * rather than using an XPath expression.</p>
128      *
129      * @return true if all messages are to be audited
130      */
131     boolean isAuditMessage();
132 
133     /**
134      * <p>Enables or disables the server auditing of all message packets.</p>
135      * <p>This is a speed optimization and convenience for logging all message packets
136      * rather than using an XPath expression.</p>
137      *
138      * @param enabled True if all messages are to be audited
139      */
140     void setAuditMessage(boolean enabled);
141 
142     /**
143      * <p>Determines if the server will audit all presence packets.</p>
144      * <p>This is a speed optimization and convenience for logging all presence packets
145      * rather than using an XPath expression.</p>
146      *
147      * @return True if all presence are to be audited
148      */
149     boolean isAuditPresence();
150 
151     /**
152      * <p>Enables or disables the server auditing of all presence packets.</p>
153      * <p>This is a speed optimization and convenience for logging all presence packets
154      * rather than using an XPath expression.</p>
155      *
156      * @param enabled True if all presence are to be audited
157      */
158     void setAuditPresence(boolean enabled);
159 
160     /**
161      * <p>Determines if the server will audit all iq packets.</p>
162      * <p>This is a speed optimization and convenience for logging all iq packets
163      * rather than using an XPath expression.</p>
164      *
165      * @return True if all iq are to be audited
166      */
167     boolean isAuditIQ();
168 
169     /**
170      * Enables or disables the server auditing of all iq packets.
171      * This is a speed optimization and convenience for logging all iq packets
172      * rather than using an XPath expression.
173      *
174      * @param enabled true if all iq are to be audited.
175      */
176     void setAuditIQ(boolean enabled);
177 
178     /**
179      * Determines if the server will audit packets using XPath expressions.
180      * XPath expressions provide a lot of power in specifying what is logged.
181      * However, it is much more compute intensive than other techniques and requires
182      * all packets be transformed into DOM objects (which can be computationally expensive).
183      *
184      * @return true if XPath expressions should be audited.
185      */
186     boolean isAuditXPath();
187 
188     /**
189      * <p>Enables/disables server auditing of packets using XPath expressions.</p>
190      * <p>XPath expressions provide a lot of power in specifying what is logged.
191      * However, it is much more compute intensive than other techniques and requires
192      * all packets be transformed into DOM objects (which can be computationally expensive).</p>
193      *
194      * @param enabled true if XPath expressions should be audited
195      */
196     void setAuditXPath(boolean enabled);
197 
198     /**
199      * Adds an XPath expression to be used for filtering packets to be audited.
200      * XPath expressions aren't evaluated or used for filtering unless isAuditXPath()
201      * returns true.
202      *
203      * @param xpathExpression the xpath expression to add to the list of auditing filters.
204      */
205     void addXPath(String   xpathExpression);
206 
207     /**
208      * <p>Removes the XPath expression from the set being used for filtering packets to be audited.</p>
209      * <p>XPath expressions aren't evaluated or used for filtering unless isAuditXPath()
210      * returns true.</p>
211      *
212      * @param xpathExpression The xpath expression to remove from the list of auditing filters
213      */
214     void removeXPath(String   xpathExpression);
215 
216     /**
217      * <p>Obtain an iterator over the XPath expressions (Strings) currently registered
218      * with the audit manager.</p>
219      * <p>XPath expressions aren't evaluated or used for filtering unless isAuditXPath()
220      * returns true.</p>
221      *
222      * @return An iterator of all XPath expressions the audit manager is using
223      */
224     Iterator   getXPathFilters();
225 
226     /**
227      * Sets the list of usernames that won't be audited. Packets sent or received by any of
228      * these users will be ignored by the auditor.
229      *
230      * @param usernames the list of usernames that won't be audited.
231      */
232     void setIgnoreList(Collection  <String  > usernames);
233 
234     /**
235      * Returns the list of usernames that won't be audited. Packets sent or received by any of
236      * these users will be ignored by the auditor.
237      *
238      * @return the list of usernames that won't be audited.
239      */
240     Collection  <String  > getIgnoreList();
241 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags