001    /**
002     * Copyright 2007-2008 Arthur Blake
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *    http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package net.sf.log4jdbc;
017    
018    /**
019     * Delegates Spy events to a logger.
020     * This interface is used for all logging activity used by log4jdbc and hides the specific implementation
021     * of any given logging system from log4jdbc.
022     *
023     * @author Arthur Blake
024     */
025    public interface SpyLogDelegator
026    {
027    
028      /**
029       * Determine if any of the jdbc or sql loggers are turned on.
030       *
031       * @return true if any of the jdbc or sql loggers are enabled at error level or higher.
032       */
033      public boolean isJdbcLoggingEnabled();
034    
035      /**
036       * Called when a spied upon method throws an Exception.
037       *
038       * @param spy        the Spy wrapping the class that threw an Exception.
039       * @param methodCall a description of the name and call parameters of the method generated the Exception.
040       * @param e          the Exception that was thrown.
041       * @param sql        optional sql that occured just before the exception occured.
042       * @param execTime   optional amount of time that passed before an exception was thrown when sql was being executed.
043       *                   caller should pass -1 if not used
044       */
045      public void exceptionOccured(Spy spy, String methodCall, Exception e, String sql, long execTime);
046    
047      /**
048       * Called when spied upon method call returns.
049       *
050       * @param spy        the Spy wrapping the class that called the method that returned.
051       * @param methodCall a description of the name and call parameters of the method that returned.
052       * @param returnMsg  return value converted to a String for integral types, or String representation for Object
053       *                   return types this will be null for void return types.
054       */
055      public void methodReturned(Spy spy, String methodCall, String returnMsg);
056    
057    
058      /**
059       * Called when a spied upon object is constructed.
060       *
061       * @param spy              the Spy wrapping the class that called the method that returned.
062       * @param constructionInfo information about the object construction
063       */
064      public void constructorReturned(Spy spy, String constructionInfo);
065    
066      /**
067       * Special call that is called only for JDBC method calls that contain SQL.
068       *
069       * @param spy        the Spy wrapping the class where the SQL occured.
070       * @param methodCall a description of the name and call parameters of the method that generated the SQL.
071       * @param sql        sql that occured.
072       */
073      public void sqlOccured(Spy spy, String methodCall, String sql);
074    
075      /**
076       * Similar to sqlOccured, but reported after SQL executes and used to report timing stats on the SQL
077       *
078       * @param spy the    Spy wrapping the class where the SQL occured.
079       * @param execTime   how long it took the sql to run, in msec.
080       * @param methodCall a description of the name and call parameters of the method that generated the SQL.
081       * @param sql        sql that occured.
082       */
083      public void sqlTimingOccured(Spy spy, long execTime, String methodCall, String sql);
084    
085      /**
086       * Log a Setup and/or administrative log message for log4jdbc.
087       *
088       * @param msg message to log.
089       */
090      public void debug(String msg);
091    
092    }