001    /*
002     * CDDL HEADER START
003     *
004     * The contents of this file are subject to the terms of the
005     * Common Development and Distribution License, Version 1.0 only
006     * (the "License").  You may not use this file except in compliance
007     * with the License.
008     *
009     * You can obtain a copy of the license at
010     * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011     * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012     * See the License for the specific language governing permissions
013     * and limitations under the License.
014     *
015     * When distributing Covered Code, include this CDDL HEADER in each
016     * file and include the License file at
017     * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
018     * add the following below this CDDL HEADER, with the fields enclosed
019     * by brackets "[]" replaced with your own identifying information:
020     *      Portions Copyright [yyyy] [name of copyright owner]
021     *
022     * CDDL HEADER END
023     *
024     *
025     *      Copyright 2008 Sun Microsystems, Inc.
026     */
027    package org.opends.server.api;
028    
029    
030    
031    import java.util.List;
032    
033    import org.opends.server.admin.std.server.AccessLogPublisherCfg;
034    import org.opends.server.config.ConfigException;
035    import org.opends.server.core.*;
036    import org.opends.server.types.*;
037    import org.opends.messages.Message;
038    
039    
040    /**
041     * This class defines the set of methods and structures that must be
042     * implemented for a Directory Server access log publisher.
043     *
044     * @param  <T>  The type of access log publisher configuration handled
045     *              by this log publisher implementation.
046     */
047    @org.opends.server.types.PublicAPI(
048         stability=org.opends.server.types.StabilityLevel.VOLATILE,
049         mayInstantiate=false,
050         mayExtend=true,
051         mayInvoke=false)
052    public abstract class AccessLogPublisher
053           <T extends AccessLogPublisherCfg>
054    {
055      /**
056       * Initializes this access publisher provider based on the
057       * information in the provided debug publisher configuration.
058       *
059       * @param  config  The access publisher configuration that contains
060       *                 the information to use to initialize this access
061       *                 publisher.
062       *
063       * @throws  ConfigException  If an unrecoverable problem arises in
064       *                           the process of performing the
065       *                           initialization as a result of the
066       *                           server configuration.
067       *
068       * @throws  InitializationException  If a problem occurs during
069       *                                   initialization that is not
070       *                                   related to the server
071       *                                   configuration.
072       */
073      public abstract void initializeAccessLogPublisher(T config)
074             throws ConfigException, InitializationException;
075    
076    
077    
078      /**
079       * Indicates whether the provided configuration is acceptable for
080       * this access log publisher.  It should be possible to call this
081       * method on an uninitialized access log publisher instance in
082       * order to determine whether the access log publisher would be able
083       * to use the provided configuration.
084       * <BR><BR>
085       * Note that implementations which use a subclass of the provided
086       * configuration class will likely need to cast the configuration
087       * to the appropriate subclass type.
088       *
089       * @param  configuration        The access log publisher
090       *                              configuration for which to make the
091       *                              determination.
092       * @param  unacceptableReasons  A list that may be used to hold the
093       *                              reasons that the provided
094       *                              configuration is not acceptable.
095       *
096       * @return  {@code true} if the provided configuration is acceptable
097       *          for this access log publisher, or {@code false} if not.
098       */
099      public boolean isConfigurationAcceptable(
100                          AccessLogPublisherCfg configuration,
101                          List<Message> unacceptableReasons)
102      {
103        // This default implementation does not perform any special
104        // validation.  It should be overridden by access log publisher
105        // implementations that wish to perform more detailed validation.
106        return true;
107      }
108    
109    
110    
111      /**
112       * Close this publisher.
113       */
114      public abstract void close();
115    
116    
117    
118      /**
119       * Writes a message to the access logger with information about a
120       * new client connection that has been established, regardless of
121       * whether it will be immediately terminated.
122       *
123       * @param  clientConnection  The client connection that has been
124       *                           established.
125       */
126      public abstract void logConnect(ClientConnection clientConnection);
127    
128    
129    
130      /**
131       * Writes a message to the access logger with information about the
132       * termination of an existing client connection.
133       *
134       * @param  clientConnection  The client connection that has been
135       *                           terminated.
136       * @param  disconnectReason  A generic disconnect reason for the
137       *                           connection termination.
138       * @param  message           A human-readable message that can
139       *                           provide additional information about
140       *                           the disconnect.
141       */
142      public abstract void logDisconnect(
143                                ClientConnection clientConnection,
144                                DisconnectReason disconnectReason,
145                                Message message);
146    
147    
148    
149      /**
150       * Writes a message to the access logger with information about the
151       * abandon request associated with the provided abandon operation.
152       *
153       * @param  abandonOperation  The abandon operation containing the
154       *                           information to use to log the abandon
155       *                           request.
156       */
157      public abstract void logAbandonRequest(
158                                AbandonOperation abandonOperation);
159    
160    
161    
162      /**
163       * Writes a message to the access logger with information about the
164       * result of the provided abandon operation.
165       *
166       * @param  abandonOperation  The abandon operation containing the
167       *                           information to use to log the abandon
168       *                           request.
169       */
170      public abstract void logAbandonResult(
171                                AbandonOperation abandonOperation);
172    
173    
174    
175      /**
176       * Writes a message to the access logger with information about the
177       * add request associated with the provided add operation.
178       *
179       * @param  addOperation  The add operation containing the
180       *                       information to use to log the add request.
181       */
182      public abstract void logAddRequest(AddOperation addOperation);
183    
184    
185    
186      /**
187       * Writes a message to the access logger with information about the
188       * add response associated with the provided add operation.
189       *
190       * @param  addOperation  The add operation containing the
191       *                       information to use to log the add response.
192       */
193      public abstract void logAddResponse(AddOperation addOperation);
194    
195    
196    
197      /**
198       * Writes a message to the access logger with information about the
199       * bind request associated with the provided bind operation.
200       *
201       * @param  bindOperation  The bind operation containing the
202       *                        information to use to log the bind
203       *                        request.
204       */
205      public abstract void logBindRequest(BindOperation bindOperation);
206    
207    
208    
209      /**
210       * Writes a message to the access logger with information about the
211       * bind response associated with the provided bind operation.
212       *
213       * @param  bindOperation  The bind operation containing the
214       *                        information to use to log the bind
215       *                        response.
216       */
217      public abstract void logBindResponse(BindOperation bindOperation);
218    
219    
220    
221      /**
222       * Writes a message to the access logger with information about the
223       * compare request associated with the provided compare operation.
224       *
225       * @param  compareOperation  The compare operation containing the
226       *                           information to use to log the compare
227       *                           request.
228       */
229      public abstract void logCompareRequest(
230                                CompareOperation compareOperation);
231    
232    
233    
234      /**
235       * Writes a message to the access logger with information about the
236       * compare response associated with the provided compare operation.
237       *
238       * @param  compareOperation  The compare operation containing the
239       *                           information to use to log the compare
240       *                           response.
241       */
242      public abstract void logCompareResponse(
243                                CompareOperation compareOperation);
244    
245    
246    
247      /**
248       * Writes a message to the access logger with information about the
249       * delete request associated with the provided delete operation.
250       *
251       * @param  deleteOperation  The delete operation containing the
252       *                          information to use to log the delete
253       *                          request.
254       */
255      public abstract void logDeleteRequest(
256                                DeleteOperation deleteOperation);
257    
258    
259    
260      /**
261       * Writes a message to the access logger with information about the
262       * delete response associated with the provided delete operation.
263       *
264       * @param  deleteOperation  The delete operation containing the
265       *                          information to use to log the delete
266       *                          response.
267       */
268      public abstract void logDeleteResponse(
269                                DeleteOperation deleteOperation);
270    
271    
272    
273      /**
274       * Writes a message to the access logger with information about the
275       * extended request associated with the provided extended operation.
276       *
277       * @param  extendedOperation  The extended operation containing the
278       *                            information to use to log the extended
279       *                            request.
280       */
281      public abstract void logExtendedRequest(
282                                ExtendedOperation extendedOperation);
283    
284    
285    
286      /**
287       * Writes a message to the access logger with information about the
288       * extended response associated with the provided extended
289       * operation.
290       *
291       * @param  extendedOperation  The extended operation containing the
292       *                            information to use to log the extended
293       *                            response.
294       */
295      public abstract void logExtendedResponse(
296                                ExtendedOperation extendedOperation);
297    
298    
299    
300      /**
301       * Writes a message to the access logger with information about the
302       * modify request associated with the provided modify operation.
303       *
304       * @param  modifyOperation  The modify operation containing the
305       *                          information to use to log the modify
306       *                          request.
307       */
308      public abstract void logModifyRequest(
309                                ModifyOperation modifyOperation);
310    
311    
312    
313      /**
314       * Writes a message to the access logger with information about the
315       * modify response associated with the provided modify operation.
316       *
317       * @param  modifyOperation  The modify operation containing the
318       *                          information to use to log the modify
319       *                          response.
320       */
321      public abstract void logModifyResponse(
322                                ModifyOperation modifyOperation);
323    
324    
325    
326      /**
327       * Writes a message to the access logger with information about the
328       * modify DN request associated with the provided modify DN
329       * operation.
330       *
331       * @param  modifyDNOperation  The modify DN operation containing the
332       *                            information to use to log the modify
333       *                            DN request.
334       */
335      public abstract void logModifyDNRequest(
336                                ModifyDNOperation modifyDNOperation);
337    
338    
339    
340      /**
341       * Writes a message to the access logger with information about the
342       * modify DN response associated with the provided modify DN
343       * operation.
344       *
345       * @param  modifyDNOperation  The modify DN operation containing the
346       *                            information to use to log the modify
347       *                            DN response.
348       */
349      public abstract void logModifyDNResponse(
350                                ModifyDNOperation modifyDNOperation);
351    
352    
353    
354      /**
355       * Writes a message to the access logger with information about the
356       * search request associated with the provided search operation.
357       *
358       * @param  searchOperation  The search operation containing the
359       *                          information to use to log the search
360       *                          request.
361       */
362      public abstract void logSearchRequest(
363                                SearchOperation searchOperation);
364    
365    
366    
367      /**
368       * Writes a message to the access logger with information about the
369       * search result entry that matches the criteria associated with the
370       * provided search operation.
371       *
372       * @param  searchOperation  The search operation with which the
373       *                          search result entry is associated.
374       * @param  searchEntry      The search result entry to be logged.
375       */
376      public abstract void logSearchResultEntry(
377                                SearchOperation searchOperation,
378                                SearchResultEntry searchEntry);
379    
380    
381    
382      /**
383       * Writes a message to the access logger with information about the
384       * search result reference returned while processing the associated
385       * search operation.
386       *
387       * @param  searchOperation  The search operation with which the
388       *                          search result reference is associated.
389       * @param  searchReference  The search result reference to be
390       *                          logged.
391       */
392      public abstract void logSearchResultReference(
393                                SearchOperation searchOperation,
394                                SearchResultReference searchReference);
395    
396    
397    
398      /**
399       * Writes a message to the access logger with information about the
400       * completion of the provided search operation.
401       *
402       * @param  searchOperation  The search operation containing the
403       *                          information to use to log the search
404       *                          result done message.
405       */
406      public abstract void logSearchResultDone(
407                                SearchOperation searchOperation);
408    
409    
410    
411      /**
412       * Writes a message to the access logger with information about the
413       * unbind request associated with the provided unbind operation.
414       *
415       * @param  unbindOperation  The unbind operation containing the
416       *                          information to use to log the unbind
417       *                          request.
418       */
419      public abstract void logUnbind(UnbindOperation unbindOperation);
420    
421      /**
422       * Gets the DN of the configuration entry for this access log
423       * publisher.
424       *
425       * @return The configuration entry DN.
426       */
427      public abstract DN getDN();
428    
429    }
430