xref: /trunk/main/offapi/com/sun/star/logging/XLogger.idl (revision a893be29)
1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#ifndef __com_sun_star_logging_XLogger_idl__
25#define __com_sun_star_logging_XLogger_idl__
26
27#ifndef __com_sun_star_uno_XInterface_idl__
28#include <com/sun/star/uno/XInterface.idl>
29#endif
30
31//=============================================================================
32
33module com { module sun { module star { module logging {
34
35published interface XLogHandler;
36
37//=============================================================================
38
39/** implemented by a component which is able to log events.
40
41    <p>This interface is roughly designed after the
42    <a href="http://java.sun.com/javase/6/docs/api/java/util/logging/package-summary.html">Java
43    Logging API</a>. However, there are some differences, the major ones being:
44    <ul><li>There's no support (yet) for filtering log events.</li>
45        <li>There ain't no convenience menthods for logging.</li>
46        <li>There's no localization support.</li>
47        <li>Logger instances do not form a hierarchy.</li>
48    </ul></p>
49
50    @since OpenOffice 2.3
51 */
52published interface XLogger
53{
54    /** denotes the name of the logger.
55    */
56    [attribute, readonly]   string  Name;
57
58    /** specifies which log events are logged or ignored.
59
60        @see LogLevel
61    */
62    [attribute]   long Level;
63
64    /** adds the given handler to the list of handlers.
65
66        <p>When an event is logged, the logger will create a <type>LogRecord</type>
67        for this event, and pass this record to all registered handlers. Single handlers
68        might or might not log those records at their own discretion, and depending on
69        additional restrictions such as filters specified at handler level.</p>
70
71        <p>Note: The log level of the given handler (<member>XLogHandler::Level</member>) will
72        not be touched. In particular, it will not be set to the logger's log level. It's
73        the responsibility of the component which knits a logger with one or more
74        log handlers to ensure that all loggers have appropriate levels set.</p>
75
76        @param LogHandler
77            the handler to add to the list of handlers. The call is ignored if this
78            parameter is <NULL/>.
79    */
80    void    addLogHandler( [in] XLogHandler LogHandler );
81
82    /** removes the given handler from the list of handlers.
83
84        @param LogHandler
85            the handler to remove from the list of handlers. The call is ignored if this
86            parameter is <NULL/>, or if the handler has not previously beed added.
87    */
88    void    removeLogHandler( [in] XLogHandler LogHandler );
89
90    /** determines whether logger instance would produce any output for the given level.
91
92        <p>The method can be used to optimize performance as maybe complex parameter evaluation
93        in the <code>log</code> calls can be omitted if <code>isLoggable</code> evaluates to false.</p>
94
95        @param Level
96            level to be checked against
97
98        @returns
99            <TRUE/> if there would be some output for this XLogger for the given level, <FALSE/>
100            otherwise. Note that a return value of <FALSE/> could also indicate that the logger
101            does not have any log handlers associated with it.
102
103        @see addLogHandler
104        @see removeLogHandler
105    */
106    boolean isLoggable( [in] long Level );
107
108    /** logs a given message
109
110        @param Level
111            the log level of this message. If this level is smaller than the logger's <member>Level</member>
112            attribute, then the call will be ignored.
113
114        @param Message
115            the message to log
116    */
117    void    log( [in] long Level, [in] string Message );
118
119    /** logs a given message, detailing the source class and method at which the logged
120        event occurred.
121
122        @param Level
123            the log level of this message. If this level is smaller than the logger's <member>Level</member>
124            attribute, then the call will be ignored.
125
126        @param SourceClass
127            the source class at which the logged event occurred.
128
129        @param SourceMethod
130            the source class at which the logged event occurred.
131
132        @param Message
133            the message to log
134    */
135    void    logp( [in] long Level, [in] string SourceClassName, [in] string SourceMethodName, [in] string Message );
136};
137
138//=============================================================================
139
140}; }; }; };
141
142//=============================================================================
143
144#endif
145