5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * The contents of this file are subject to the terms
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * of the Common Development and Distribution License
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * (the License). You may not use this file except in
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * compliance with the License.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * You can obtain a copy of the License at
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * https://opensso.dev.java.net/public/CDDLv1.0.html or
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * See the License for the specific language governing
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * permission and limitations under the License.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * When distributing Covered Code, include this CDDL
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Header Notice in each file and include the License file
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * If applicable, add the following below the CDDL Header,
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * with the fields enclosed by brackets [] replaced by
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * your own identifying information:
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * "Portions Copyrighted [year] [name of copyright owner]"
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * $Id: Debug.java,v 1.6 2009/08/19 05:41:17 veiming Exp $
63fa802de4c94f52abaa048ec9a450f25fab607cJaco Jooste * Portions Copyrighted 2013-2016 ForgeRock AS.
18c03cd4bf115326b28f25585025a01870123275James Phillpottsimport com.sun.identity.shared.configuration.SystemPropertiesManager;
18c03cd4bf115326b28f25585025a01870123275James Phillpottsimport com.sun.identity.shared.debug.file.impl.StdDebugFile;
18c03cd4bf115326b28f25585025a01870123275James Phillpottsimport com.sun.identity.shared.debug.impl.DebugProviderImpl;
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster// NOTE: Since JVM specs guarantee atomic access/updates to int variables
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster// (actually all variables except double and long), the design consciously
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster// avoids synchronized methods, particularly for message(). This is done to
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster// reduce the performance overhead of synchronized message() when debugging
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster// is disabled. This does not have serious side-effects other than an occasional
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster// invocation of message() missing concurrent update of 'debugLevel'.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * ****************************************************************************
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Allows a uniform interface to file debug and exception information in a
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * uniform format. <code>Debug</code> supports different levels/states of
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * filing debug information (in the ascending order): <code>OFF</code>,
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>ERROR</code>, <code>WARNING</code>, <code>MESSAGE</code> and
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>ON</code>. A given debug level/state is enabled if the debug
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * state/level is set to at least that state/level. For example, if the debug
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * state is <code>ERROR</code>, only errors will be filed. If the debug state
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * is <code>WARNING</code>, only errors and warnings will be filed. If the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * debug state is <code>MESSAGE</code>, everything will be filed.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>MESSAGE</code> and <code>ON</code> are of the same levels; the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * difference between them being <code>MESSAGE</code> writes to a file,
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * whereas <code>ON</code> writes to System.out.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Debug service uses the property file, <code>AMConfig.properties</code>, to
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * set the default debug level and the output directory where the debug files
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * will be placed. The properties file is located (using
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * {@link java.util.ResourceBundle} semantics) from one of the directories in
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * the CLASSPATH.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * The following keys are used to configure the Debug service. Possible values
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * for the key 'com.iplanet.services.debug.level' are: off | error | warning |
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * message. The key 'com.iplanet.services.debug.directory' specifies the output
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * directory where the debug files will be created. Optionally, the key
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * 'com.sun.identity.util.debug.provider' may be used to plugin a non-default
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * implementation of the debug service where necessary.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <blockquote>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * com.iplanet.services.debug.level
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * com.iplanet.services.debug.directory
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * com.sun.identity.util.debug.provider
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * </blockquote>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * If there is an error reading or loading the properties, Debug service will
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * redirect all debug information to <code>System.out</code>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * If these properties are changed, the server must be restarted for the changes
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to take effect.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <b>NOTE:</b> Debugging is an IO intensive operation and may hurt application
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * performance when abused. Particularly, note that Java evaluates the arguments
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to <code>message()</code> and <code>warning()</code> even when debugging
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * is turned off. It is recommended that the debug state be checked before
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * invoking any <code>message()</code> or <code>warning()</code> methods to
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * avoid unnecessary argument evaluation and to maximize application
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * performance.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @supported.all.api
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster /* Static fields and methods */
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * flags the disabled debug state.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * flags the state where error debugging is enabled. When debugging is set
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to less than <code>ERROR</code>, error debugging is also disabled.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * flags the state where warning debugging is enabled, but message debugging
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * is disabled. When debugging is set to less than <code>WARNING</code>,
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * warning debugging is also disabled.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * This state enables debugging of messages, warnings and errors.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * flags the enabled debug state for warnings, errors and messages. Printing
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to a file is disabled. All printing is done on System.out.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * flags the disabled debug state.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * flags the state where error debugging is enabled. When debugging is set
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to less than <code>ERROR</code>, error debugging is also disabled.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster public static final String STR_ERROR = "error";
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * flags the state where warning debugging is enabled, but message debugging
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * is disabled. When debugging is set to less than <code>WARNING</code>,
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * warning debugging is also disabled.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster public static final String STR_WARNING = "warning";
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * This state enables debugging of messages, warnings and errors.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster public static final String STR_MESSAGE = "message";
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * flags the enables debug state for warnings, errors and messages. Printing
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to a file is disabled. All printing is done on System.out.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * debugMap is a container of all active Debug objects. Log file name is the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * key and Debug is the value of this map.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * serviceInitialized indicates if the service is already initialized.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster private static boolean serviceInitialized = false;
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * the provider instance that will be used for Debug service.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Gets an existing instance of Debug for the specified debug name or a new
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * one if no such instance already exists. If a Debug object has to be
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * created, its level is set to the level defined in the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>AMConfig.properties</code> file. The level can be changed later
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * by using {@link #setDebug(int)} or {@link #setDebug(String)} methods.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param debugName name of the debug instances to be created
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return a Debug instance corresponding to the specified debug name.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster public static synchronized Debug getInstance(String debugName) {
63fa802de4c94f52abaa048ec9a450f25fab607cJaco Jooste IDebug iDebug = getDebugProvider().getInstance(debugName);
63fa802de4c94f52abaa048ec9a450f25fab607cJaco Jooste Debug debug = (Debug) getDebugMap().get(iDebug.getName());
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Returns a collection of all Debug instances that exist in the system at
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * the current instance. This is a live collection that will be updated as
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * and when new Debug instances are created. Note that if an iterator is
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * used, it could potentially cause a
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>ConcurrentModificationException</code> if during the process of
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * iteration, the collection is modified by the system.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return a collection of all Debug instances in the system.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Gets the <code>Map</code> of all Debug instances being used in the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * system currently.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return the <code>Map</code> of all Debug instances
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Sets the provider instance to be used by Debug service.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param provider the <code>IDebugProvider</code> instance that is used by the
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * Debug service.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster private static void setDebugProvider(IDebugProvider provider) {
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Gets the configured debug provider being used by the Debug service.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return the configured debug provider.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Initializes the Debug Service by locating the SPI implementations and
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * instantiating the appropriate classes.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster private static synchronized void initialize() {
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL String providerName = SystemPropertiesManager.get(DebugConstants.CONFIG_DEBUG_PROVIDER);
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster boolean providerLoadFailed = false;
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster if (providerName != null && providerName.trim().length() > 0) {
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL provider = (IDebugProvider) Class.forName(providerName).newInstance();
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL ResourceBundle bundle = com.sun.identity.shared.locale.Locale.getInstallResourceBundle
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL ("amUtilMsgs");
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL StdDebugFile.printError(Debug.class.getSimpleName(), bundle.getString("com.iplanet" + ".services" +
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL ".debug.invalidprovider"), exceptionCatched);
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster /* Instance fields and methods */
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * The instance of the actual debug service class as obtained from the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * configured provider.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Convinience method to query the name being used for this Debug instance.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * The return value of this method is a string exactly equal to the name
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * that was used while creating this instance.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return the name of this Debug instance
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Checks if message debugging is enabled.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <b>NOTE:</b> Debugging is an IO intensive operation and may hurt
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * application performance when abused. Particularly, note that Java
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * evaluates arguments to <code>message()</code> even when debugging is
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * turned off. It is recommended that <code>messageEnabled()</code> be
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * called to check the debug state before invoking any
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>message()</code> methods to avoid unnecessary argument evaluation
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * and maximize application performance.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return <code>true</code> if message debugging is enabled
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <code>false</code> if message debugging is disabled
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster return getDebugServiceInstance().messageEnabled();
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Checks if warning debugging is enabled.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <b>NOTE:</b> Debugging is an IO intensive operation and may hurt
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * application performance when abused. Particularly, note that Java
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * evaluates arguments to <code>warning()</code> even when warning
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * debugging is turned off. It is recommended that
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>warningEnabled()</code> be called to check the debug state before
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * invoking any <code>warning()</code> methods to avoid unnecessary
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * argument evaluation and maximize application performance.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return <code>true</code> if warning debugging is enabled
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <code>false</code> if warning debugging is disabled
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster return getDebugServiceInstance().warningEnabled();
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Checks if error debugging is enabled.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <b>NOTE:</b> Debugging is an IO intensive operation and may hurt
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * application performance when abused. Particularly, note that Java
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * evaluates arguments to <code>error()</code> even when error debugging
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * is turned off. It is recommended that <code>errorEnabled()</code> be
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * called to check the debug state before invoking any <code>error()</code>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * methods to avoid unnecessary argument evaluation and maximize application
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * performance.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return <code>true</code> if error debugging is enabled
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <code>false</code> if error debugging is disabled
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster return getDebugServiceInstance().errorEnabled();
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Returns one of the five possible values:
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <li>Debug.OFF
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <li>Debug.ERROR
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <li>Debug.WARNING
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <li>Debug.MESSAGE
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <li>Debug.ON
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return the debug level
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Prints messages only when the debug state is either Debug.MESSAGE or
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <b>NOTE:</b> Debugging is an IO intensive operation and may hurt
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * application performance when abused. Particularly, note that Java
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * evaluates arguments to <code>message()</code> even when debugging is
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * turned off. So when the argument to this method involves the String
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * concatenation operator '+' or any other method invocation,
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>messageEnabled</code> <b>MUST</b> be used. It is recommended
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * that the debug state be checked by invoking <code>messageEnabled()</code>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * before invoking any <code>message()</code> methods to avoid unnecessary
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * argument evaluation and maximize application performance.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param msg debug message.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @see Debug#message(String, Throwable)
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Prints debug and exception messages only when the debug state is either
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Debug.MESSAGE or Debug.ON. If the debug file is not accessible and
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * debugging is enabled, the message along with a time stamp and thread info
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * will be printed on <code>System.out</code>.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * This method creates the debug file if does not exist; otherwise it starts
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * appending to the existing debug file. When invoked for the first time on
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * this object, the method writes a line delimiter of '*'s.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Note that the debug file will remain open until <code>destroy()</code>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * is invoked. To conserve file resources, you should invoke
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>destroy()</code> explicitly rather than wait for the garbage
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * collector to clean up.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <b>NOTE:</b> Debugging is an IO intensive operation and may hurt
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * application performance when abused. Particularly, note that Java
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * evaluates arguments to <code>message()</code> even when debugging is
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * turned off. It is recommended that the debug state be checked by invoking
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>messageEnabled()</code> before invoking any
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>message()</code> methods to avoid unnecessary argument evaluation
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * and to maximize application performance.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param msg message to be printed. A newline will be appended to the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * message before printing either to <code>System.out</code> or
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to the debug file. If <code>msg</code> is null, it is
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param t <code>Throwable</code>, on which
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>printStackTrace</code> will be invoked to print the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * stack trace. If <code>t</code> is null, it is ignored.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @see Debug#error(String, Throwable)
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * A convenience method for message debug statements. The message will only be formatted
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * if the debug level is greater than {@link #WARNING}, and then it will be formatted using
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * the {@link org.slf4j.helpers.MessageFormatter} class. The relevant {@code message} method is then
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * called depending on whether the last parameter is an instance of {@code Throwable}.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * This method is convenient way of issuing warning level debug statements without having
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * to guard the call with a check to {@link #messageEnabled()}, as that check is done
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * before evaluating the method parameters.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * For this optimisation to work properly, this method should not be called using string
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * concatenation. If concatenation is required, it can be achieved using format patterns.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * In this way, the only cost to execution is the assembly of the varargs parameter.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * @param msg The debug message format, using {@link MessageFormatter} style format patterns.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * @param params The parameters to the message, optionally with a {@code Throwable} as
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * the last parameter.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts public void message(String msg, Object... params) {
18c03cd4bf115326b28f25585025a01870123275James Phillpotts String message = MessageFormatter.arrayFormat(msg, params).getMessage();
305fa812bf6619cb3436c8b1984210fd7f82fca7Jaco Jooste if (params.length > 0 && params[params.length - 1] instanceof Throwable) {
18c03cd4bf115326b28f25585025a01870123275James Phillpotts debug.message(message, (Throwable) params[params.length - 1]);
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Prints warning messages only when debug level is greater than
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Debug.ERROR.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <b>NOTE:</b> Debugging is an IO intensive operation and may hurt
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * application performance when abused. Particularly, note that Java
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * evaluates arguments to <code>warning()</code> even when debugging is
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * turned off. So when the argument to this method involves the String
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * concatenation operator '+' or any other method invocation,
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>warningEnabled</code> <b>MUST</b> be used. It is recommended
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * that the debug state be checked by invoking <code>warningEnabled()</code>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * before invoking any <code>warning()</code> methods to avoid unnecessary
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * argument evaluation and to maximize application performance.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param msg message to be printed. A newline will be appended to the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * message before printing either to <code>System.out</code> or
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to the debug file. If <code>msg</code> is null, it is
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @see Debug#warning(String, Throwable)
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Prints warning messages only when debug level is greater than
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Debug.ERROR.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <b>NOTE:</b> Debugging is an IO intensive operation and may hurt
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * application performance when abused. Particularly, note that Java
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * evaluates arguments to <code>warning()</code> even when debugging is
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * turned off. It is recommended that the debug state be checked by invoking
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>warningEnabled()</code> before invoking any
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>warning()</code> methods to avoid unnecessary argument evaluation
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * and to maximize application performance.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * If the debug file is not accessible and debugging is enabled, the message
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * along with a time stamp and thread info will be printed on
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>System.out</code>.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * This method creates the debug file if does not exist; otherwise it starts
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * appending to the existing debug file. When invoked for the first time on
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * this object, the method writes a line delimiter of '*'s.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Note that the debug file will remain open until <code>destroy()</code>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * is invoked. To conserve file resources, you should invoke
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>destroy()</code> explicitly rather than wait for the garbage
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * collector to clean up.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param msg message to be printed. A newline will be appended to the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * message before printing either to <code>System.out</code> or
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to the debug file. If <code>msg</code> is null, it is
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param t <code>Throwable</code>, on which
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>printStackTrace()</code> will be invoked to print the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * stack trace. If <code>t</code> is null, it is ignored.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * A convenience method for warning debug statements. The message will only be formatted
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * if the debug level is greater than {@link #ERROR}, and then it will be formatted using
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * the {@link org.slf4j.helpers.MessageFormatter} class. The relevant {@code warning} method is then
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * called depending on whether the last parameter is an instance of {@code Throwable}.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * This method is convenient way of issuing warning level debug statements without having
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * to guard the call with a check to {@link #warningEnabled()}, as that check is done
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * before evaluating the method parameters.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * For this optimisation to work properly, this method should not be called using string
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * concatenation. If concatenation is required, it can be achieved using format patterns.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * In this way, the only cost to execution is the assembly of the varargs parameter.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * @param msg The debug message format, using {@link MessageFormatter} style format patterns.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * @param params The parameters to the message, optionally with a {@code Throwable} as
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * the last parameter.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts public void warning(String msg, Object... params) {
18c03cd4bf115326b28f25585025a01870123275James Phillpotts String message = MessageFormatter.arrayFormat(msg, params).getMessage();
305fa812bf6619cb3436c8b1984210fd7f82fca7Jaco Jooste if (params.length > 0 && params[params.length - 1] instanceof Throwable) {
18c03cd4bf115326b28f25585025a01870123275James Phillpotts debug.warning(message, (Throwable) params[params.length - 1]);
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Prints error messages only when debug level is greater than DEBUG.OFF.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param msg message to be printed. A newline will be appended to the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * message before printing either to <code>System.out</code> or
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to the debug file. If <code>msg</code> is null, it is
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @see Debug#error(String, Throwable)
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Prints error messages only if debug state is greater than Debug.OFF. If
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * the debug file is not accessible and debugging is enabled, the message
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * along with a time stamp and thread info will be printed on
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>System.out</code>.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * This method creates the debug file if does not exist; otherwise it starts
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * appending to the existing debug file. When invoked for the first time on
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * this object, the method writes a line delimiter of '*'s.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Note that the debug file will remain open until <code>destroy()</code>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * is invoked. To conserve file resources, you should invoke
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>destroy()</code> explicitly rather than wait for the garbage
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * collector to clean up.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param msg message to be printed. A newline will be appended to the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * message before printing either to <code>System.out</code> or
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * to the debug file. If <code>msg</code> is null, it is
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param t <code>Throwable</code>, on which
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>printStackTrace()</code> will be invoked to print the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * stack trace. If <code>t</code> is null, it is ignored.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * A convenience method for error debug statements. The message will only be formatted
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * if the debug level is greater than {@link #OFF}, and then it will be formatted using
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * the {@link org.slf4j.helpers.MessageFormatter} class. The relevant {@code error} method is then
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * called depending on whether the last parameter is an instance of {@code Throwable}.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * This method is convenient way of issuing warning level debug statements without having
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * to guard the call with a check to {@link #errorEnabled()}, as that check is done
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * before evaluating the method parameters.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * For this optimisation to work properly, this method should not be called using string
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * concatenation. If concatenation is required, it can be achieved using format patterns.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * In this way, the only cost to execution is the assembly of the varargs parameter.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * @param msg The debug message format, using {@link MessageFormatter} style format patterns.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * @param params The parameters to the message, optionally with a {@code Throwable} as
18c03cd4bf115326b28f25585025a01870123275James Phillpotts * the last parameter.
18c03cd4bf115326b28f25585025a01870123275James Phillpotts public void error(String msg, Object... params) {
18c03cd4bf115326b28f25585025a01870123275James Phillpotts String message = MessageFormatter.arrayFormat(msg, params).getMessage();
305fa812bf6619cb3436c8b1984210fd7f82fca7Jaco Jooste if (params.length > 0 && params[params.length - 1] instanceof Throwable) {
18c03cd4bf115326b28f25585025a01870123275James Phillpotts debug.error(message, (Throwable) params[params.length - 1]);
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Sets the debug capabilities based on the values of the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>debugType</code> argument.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param debugType is any one of five possible values:
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.OFF</code>
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.ERROR</code>
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.WARNING</code>
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.MESSAGE</code>
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.ON</code>
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * Allows runtime modification of the backend used by this instance.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * by resetting the debug instance to reinitialize itself.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @param mf merge flag - on for creating a single debug file.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Sets the debug capabilities based on the values of the
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>debugType</code> argument.
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * @param debugType is any one of the following possible values:
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.STR_OFF</code>
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.STR_ERROR</code>
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.STR_WARNING</code>
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.STR_MESSAGE</code>
5e89746cb5bec21d15a044ce89cfcdbf99d3d49dQuentin CASTEL * <li><code>Debug.STR_ON</code>
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Destroys the debug object, closes the debug file and releases any system
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * resources. Note that the debug file will remain open until
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * <code>destroy()</code> is invoked. To conserve file resources, you
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * should invoke <code>destroy()</code> explicitly rather than wait for
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * the garbage collector to clean up.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * If this object is accessed after <code>destroy()</code> has been
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * invoked, the results are undefined.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster // No handling required
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Setter for setting the actual debug service class which is obtained from
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * the configured provider.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster private void setDebugServiceInstance(IDebug debugServiceInstance) {
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster this.debugServiceInstance = debugServiceInstance;
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * Returns the actual debug service class.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * @return The underlying debug service class.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * The sole constructor of the Debug instances. This constructor is declared
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * private to ensure the use of the factory method provided in this class
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster * called {@link #getInstance(String)}.
5c099afa7c9361afc2f4477fec0e3018588d7840Allan Foster /* Static Initializer */