001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: Logger.java,v 1.3 2008/06/25 05:47:28 qcheng Exp $
026 *
027 */
028
029package com.sun.identity.plugin.log;
030
031import java.util.Map;
032import java.util.logging.Level;
033
034/**
035 * This interface defines methods which will be invoked by the
036 * the Federation Framework to write federation related
037 * events and errors to the access and error log files.
038 *
039 * @supported.all.api
040 */
041
042public interface Logger {
043    
044    /**
045     * Initializes the logging for the component.
046     *
047     * @param componentName the component name.
048     * @exception LogException if there is an error
049     *    during initialization.
050     */
051    public void init(String componentName) throws LogException;
052    
053    /**
054     * Logs message to the access logs. 
055     *
056     * @param level the log level , these are based on those
057     *          defined in java.util.logging.Level, the values for
058     *          level can be any one of the following : <br>
059     *          <ul>
060     *          <li>SEVERE (highest value) <br>
061     *          <li>WARNING <br>
062     *          <li>INFO <br>
063     *          <li>CONFIG <br>
064     *          <li>FINE <br>
065     *          <li>FINER <br>
066     *          <li>FINEST (lowest value) <br>
067     *          </ul>
068     * @param messageID the message or a message identifier.
069     * @param data string array of dynamic data to be replaced in the message.
070     * @param session the User's session object
071     * @exception LogException if there is an error.
072     */
073    
074    public void access(Level level,
075                       String messageID,
076                       String data[],
077                       Object session) throws LogException;
078    
079    
080    /**
081     * Writes access to a component into a log.
082     * @param level indicating log level
083     * @param msgid Message id
084     * @param data string array of dynamic data only known during run time
085     * @param session Session object (it could be null)
086     * @param props representing log record columns
087     * @exception LogException if there is an error.
088     */
089    public abstract void access(
090        Level level,
091        String msgid,
092        String data[],
093        Object session,
094        Map props) throws LogException;
095 
096
097    /**
098     * Logs error messages to the error logs.
099     *
100     * @param level the log level , these are based on those
101     *          defined in java.util.logging.Level, the values for
102     *          level can be any one of the following : <br>
103     *          <ul>
104     *          <li>SEVERE (highest value) <br>
105     *          <li>WARNING <br>
106     *          <li>INFO <br>
107     *          <li>CONFIG <br>
108     *          <li>FINE <br>
109     *          <li>FINER <br>
110     *          <li>FINEST (lowest value) <br>
111     *          </ul>
112     * @param messageId the message or a message identifier.
113     * @param data string array of dynamic data to be replaced in the message.
114     * @param session the User's Session object.
115     * @exception LogException if there is an error.
116     */
117    public void error(Level level,String messageId,String data[],
118                      Object session) throws LogException;
119    
120    /**
121     * Writes error occurred in a component into a log.
122     * @param level indicating log level
123     * @param msgid Message id
124     * @param data string array of dynamic data only known during run time
125     * @param session Session object (it could be null)
126     * @param props log record columns
127     * @exception LogException if there is an error.
128     */
129    public abstract void error(
130      Level level,
131      String msgid,
132      String data[],
133      Object session,
134      Map props) throws LogException;
135
136    /**
137     * Checks if the logging is enabled.
138     *
139     * @return true if logging is enabled.
140     */
141    public boolean isLogEnabled() ;
142    
143    /**
144     * Checks if an access message of the given level would actually be logged
145     * by this logger. This check is based on the Logger's effective level.
146     *
147     * @param level a message logging level defined in java.util.logging.Level.
148     * @return true if the given message level is currently being logged.
149     */
150    public boolean isAccessLoggable(Level level);
151    
152    /**
153     * Checks if an error message of the given level would actually be logged
154     * by this logger. This check is based on the Logger's effective level.
155     *
156     * @param level a message logging level defined in java.util.logging.Level.
157     * @return true if the given message level is currently being logged.
158     */
159    public boolean isErrorLoggable(Level level);
160}
161