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 #ifndef __com_sun_star_logging_XLogger_idl__
  21 #define __com_sun_star_logging_XLogger_idl__
  22
  23 #include <com/sun/star/uno/XInterface.idl>
  24
  25
  26 module com { module sun { module star { module logging {
  27
  28 interface XLogHandler;
  29
  30
  31 /** implemented by a component which is able to log events.
  32
  33     <p>This interface is roughly designed after the
  34     <a href="http://java.sun.com/javase/6/docs/api/java/util/logging/package-summary.html">Java
  35     Logging API</a>. However, there are some differences, the major ones being:
  36     <ul><li>There's no support (yet) for filtering log events.</li>
  37         <li>There ain't no convenience methods for logging.</li>
  38         <li>There's no localization support.</li>
  39         <li>Logger instances do not form a hierarchy.</li>
  40     </ul></p>
  41
  42     @since OOo 2.3
  43  */
  44 interface XLogger
  45 {
  46     /** denotes the name of the logger.
  47     */
  48     [attribute, readonly]   string  Name;
  49
  50     /** specifies which log events are logged or ignored.
  51
  52         @see LogLevel
  53     */
  54     [attribute]   long Level;
  55
  56     /** adds the given handler to the list of handlers.
  57
  58         <p>When an event is logged, the logger will create a LogRecord
  59         for this event, and pass this record to all registered handlers. Single handlers
  60         might or might not log those records at their own discretion, and depending on
  61         additional restrictions such as filters specified at handler level.</p>
  62
  63         <p>Note: The log level of the given handler (XLogHandler::Level) will
  64         not be touched. In particular, it will not be set to the logger's log level. It's
  65         the responsibility of the component which knits a logger with one or more
  66         log handlers to ensure that all loggers have appropriate levels set.</p>
  67
  68         @param LogHandler
  69             the handler to add to the list of handlers. The call is ignored if this
  70             parameter is `NULL`.
  71     */
  72     void    addLogHandler( [in] XLogHandler LogHandler );
  73
  74     /** removes the given handler from the list of handlers.
  75
  76         @param LogHandler
  77             the handler to remove from the list of handlers. The call is ignored if this
  78             parameter is `NULL`, or if the handler has not previously been added.
  79     */
  80     void    removeLogHandler( [in] XLogHandler LogHandler );
  81
  82     /** determines whether logger instance would produce any output for the given level.
  83
  84         <p>The method can be used to optimize performance as maybe complex parameter evaluation
  85         in the <code>log</code> calls can be omitted if <code>isLoggable</code> evaluates to false.</p>
  86
  87         @param Level
  88             level to be checked against
  89
  90         @returns
  91             `TRUE` if there would be some output for this XLogger for the given level, `FALSE`
  92             otherwise. Note that a return value of `FALSE` could also indicate that the logger
  93             does not have any log handlers associated with it.
  94
  95         @see addLogHandler
  96         @see removeLogHandler
  97     */
  98     boolean isLoggable( [in] long Level );
  99
 100     /** logs a given message
 101
 102         @param Level
 103             the log level of this message. If this level is smaller than the logger's #Level
 104             attribute, then the call will be ignored.
 105
 106         @param Message
 107             the message to log
 108     */
 109     void    log( [in] long Level, [in] string Message );
 110
 111     /** logs a given message, detailing the source class and method at which the logged
 112         event occurred.
 113
 114         @param Level
 115             the log level of this message. If this level is smaller than the logger's #Level
 116             attribute, then the call will be ignored.
 117
 118         @param SourceClass
 119             the source class at which the logged event occurred.
 120
 121         @param SourceMethod
 122             the source class at which the logged event occurred.
 123
 124         @param Message
 125             the message to log
 126     */
 127     void    logp( [in] long Level, [in] string SourceClass, [in] string SourceMethod, [in] string Message );
 128 };
 129
 130
 131 }; }; }; };
 132
 133
 134 #endif
 135
 136 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */