offapi/com/sun/star/logging/XLogger.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21 module com { module sun { module star { module logging {
  22
  23 interface XLogHandler;
  24
  25
  26 /** implemented by a component which is able to log events.
  27
  28     <p>This interface is roughly designed after the
  29     <a href="http://java.sun.com/javase/6/docs/api/java/util/logging/package-summary.html">Java
  30     Logging API</a>. However, there are some differences, the major ones being:
  31     <ul><li>There's no support (yet) for filtering log events.</li>
  32         <li>There ain't no convenience methods for logging.</li>
  33         <li>There's no localization support.</li>
  34         <li>Logger instances do not form a hierarchy.</li>
  35     </ul></p>
  36
  37     @since OOo 2.3
  38  */
  39 interface XLogger
  40 {
  41     /** denotes the name of the logger.
  42     */
  43     [attribute, readonly]   string  Name;
  44
  45     /** specifies which log events are logged or ignored.
  46
  47         @see LogLevel
  48     */
  49     [attribute]   long Level;
  50
  51     /** adds the given handler to the list of handlers.
  52
  53         <p>When an event is logged, the logger will create a LogRecord
  54         for this event, and pass this record to all registered handlers. Single handlers
  55         might or might not log those records at their own discretion, and depending on
  56         additional restrictions such as filters specified at handler level.</p>
  57
  58         <p>Note: The log level of the given handler (XLogHandler::Level) will
  59         not be touched. In particular, it will not be set to the logger's log level. It's
  60         the responsibility of the component which knits a logger with one or more
  61         log handlers to ensure that all loggers have appropriate levels set.</p>
  62
  63         @param LogHandler
  64             the handler to add to the list of handlers. The call is ignored if this
  65             parameter is `NULL`.
  66     */
  67     void    addLogHandler( [in] XLogHandler LogHandler );
  68
  69     /** removes the given handler from the list of handlers.
  70
  71         @param LogHandler
  72             the handler to remove from the list of handlers. The call is ignored if this
  73             parameter is `NULL`, or if the handler has not previously been added.
  74     */
  75     void    removeLogHandler( [in] XLogHandler LogHandler );
  76
  77     /** determines whether logger instance would produce any output for the given level.
  78
  79         <p>The method can be used to optimize performance as maybe complex parameter evaluation
  80         in the <code>log</code> calls can be omitted if <code>isLoggable</code> evaluates to false.</p>
  81
  82         @param Level
  83             level to be checked against
  84
  85         @returns
  86             `TRUE` if there would be some output for this XLogger for the given level, `FALSE`
  87             otherwise. Note that a return value of `FALSE` could also indicate that the logger
  88             does not have any log handlers associated with it.
  89
  90         @see addLogHandler
  91         @see removeLogHandler
  92     */
  93     boolean isLoggable( [in] long Level );
  94
  95     /** logs a given message
  96
  97         @param Level
  98             the log level of this message. If this level is smaller than the logger's #Level
  99             attribute, then the call will be ignored.
 100
 101         @param Message
 102             the message to log
 103     */
 104     void    log( [in] long Level, [in] string Message );
 105
 106     /** logs a given message, detailing the source class and method at which the logged
 107         event occurred.
 108
 109         @param Level
 110             the log level of this message. If this level is smaller than the logger's #Level
 111             attribute, then the call will be ignored.
 112
 113         @param SourceClass
 114             the source class at which the logged event occurred.
 115
 116         @param SourceMethod
 117             the source class at which the logged event occurred.
 118
 119         @param Message
 120             the message to log
 121     */
 122     void    logp( [in] long Level, [in] string SourceClass, [in] string SourceMethod, [in] string Message );
 123 };
 124
 125
 126 }; }; }; };
 127
 128
 129 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */