/*

 * Licensed to the Apache Software Foundation (ASF) under one or more

 * contributor license agreements.  See the NOTICE file distributed with

 * this work for additional information regarding copyright ownership.

 * The ASF licenses this file to You under the Apache License, Version 2.0

 * (the "License"); you may not use this file except in compliance with

 * the License.  You may obtain a copy of the License at

 *

 *      http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

#ifndef _LOG4CXX_DB_ODBC_APPENDER_H

#define _LOG4CXX_DB_ODBC_APPENDER_H

#include <log4cxx/log4cxx.h>

#include <log4cxx/helpers/exception.h>

#include <log4cxx/appenderskeleton.h>

#include <log4cxx/spi/loggingevent.h>

#if LOG4CXX_EVENTS_AT_EXIT

#include <log4cxx/private/atexitregistry.h>

#endif

#include <list>

#include <memory>

namespace LOG4CXX_NS

{

namespace db

{

class LOG4CXX_EXPORT SQLException : public LOG4CXX_NS::helpers::Exception

{

  public:

    SQLException(short fHandleType,

      void* hInput, const char* prolog,

      LOG4CXX_NS::helpers::Pool& p);

    SQLException(const char* msg);

    SQLException(const SQLException& src);

  private:

    const char* formatMessage(short fHandleType,

      void* hInput, const char* prolog,

      LOG4CXX_NS::helpers::Pool& p);

};

/**

The ODBCAppender sends log events to a database.

<p>Each append call adds the spi::LoggingEvent to a buffer.

When the buffer is full, values are extracted from each spi::LoggingEvent

and the sql insert statement executed.

The SQL insert statement pattern must be provided

either in the Log4cxx configuration file

using the <b>sql</b> parameter element

or programatically by calling the <code>setSql(String sql)</code> method.

The following <b>param</b> elements are optional:

- one of <b>DSN</b>, <b>URL</b>, <b>ConnectionString</b> -

  The <b>serverName</b> parameter value in the <a href="https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlconnect-function">SQLConnect</a> call.

- <b>User</b> -

  The <b>UserName</b> parameter value in the <a href="https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlconnect-function">SQLConnect</a> call.

- <b>Password</b> -

  The <b>Authentication</b> parameter value in the <a href="https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqlconnect-function">SQLConnect</a> call.

- <b>BufferSize</b> -

  Delay executing the sql until this many logging events are available.

  One by default, meaning an sql statement is executed

  whenever a logging event is appended.

- <b>ColumnMapping</b> -

  One element for each "?" in the <b>sql</b> statement

  in a sequence corresponding to the columns in the insert statement.

  The following values are supported:

  - <b>logger</b> - the name of the logger that generated the logging event

  - <b>level</b> - the level of the logging event

  - <b>thread</b> - the thread number as a hex string that generated the logging event

  - <b>threadname</b> - the name assigned to the thread that generated the logging event

  - <b>time</b> - a datetime or datetime2 SQL field type at which the event was generated

  - <b>shortfilename</b> - the basename of the file containing the logging statement

  - <b>fullfilename</b> - the path of the file containing the logging statement

  - <b>line</b> - the position in the file at which the logging event was generated

  - <b>class</b> - the class from which the logging event was generated (\ref usingMacros "1")

  - <b>method</b> - the function in which the logging event was generated (\ref usingMacros "1")

  - <b>message</b> - the data sent by the logging statement

  - <b>mdc</b> - A JSON format string of all entries in the logging thread's mapped diagnostic context

  - <b>mdc{key}</b> - the value associated with the <b>key</b> entry in the logging thread's mapped diagnostic context

  - <b>ndc</b> - the last entry the logging thread's nested diagnostic context

\anchor usingMacros (1) Only available when the LOG4CXX_* macros are used to issue the logging request.

<p>For use as a base class:

<ul>

<li>Override getConnection() to pass any connection

you want.  Typically this is used to enable application wide

connection pooling.

<li>Override closeConnection -- if

you override getConnection make sure to implement

<code>closeConnection</code> to handle the connection you

generated.  Typically this would return the connection to the

pool it came from.

</ul>

An example configuration that writes to the data source named "LoggingDSN" is:

~~~{.xml}

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">

<appender name="PreparedAppender" class="ODBCAppender">

 <param name="DSN" value="LoggingDSN"/>

 <param name="sql" value="INSERT INTO [SomeDatabaseName].[SomeUserName].[SomeTableName] ([Thread],[LogName],[LogTime],[LogLevel],[FileName],[FileLine],[Message],[MappedContext]) VALUES (?,?,?,?,?,?,?,?)" />

 <param name="ColumnMapping" value="thread"/>

 <param name="ColumnMapping" value="logger"/>

 <param name="ColumnMapping" value="time"/>

 <param name="ColumnMapping" value="level"/>

 <param name="ColumnMapping" value="shortfilename"/>

 <param name="ColumnMapping" value="line"/>

 <param name="ColumnMapping" value="message"/>

 <param name="ColumnMapping" value="mdc"/>

</appender>

<appender name="ASYNC" class="AsyncAppender">

  <param name="BufferSize" value="1000"/>

  <param name="Blocking" value="false"/>

  <appender-ref ref="PreparedAppender"/>

</appender>

<root>

  <priority value ="INFO" />

  <appender-ref ref="ASYNC" />

</root>

</log4j:configuration>

~~~

You may also want to consider the DBAppender class, which uses APR in order to support logging to databases apart from ODBC.

*/

class LOG4CXX_EXPORT ODBCAppender : public AppenderSkeleton

{

  public:

    DECLARE_LOG4CXX_OBJECT(ODBCAppender)

    BEGIN_LOG4CXX_CAST_MAP()

    LOG4CXX_CAST_ENTRY(ODBCAppender)

    LOG4CXX_CAST_ENTRY_CHAIN(AppenderSkeleton)

    END_LOG4CXX_CAST_MAP()

    typedef void* SQLHDBC;

    typedef void* SQLHENV;

    typedef void* SQLHANDLE;

    typedef short SQLSMALLINT;

    ODBCAppender();

    virtual ~ODBCAppender();

    /**

    \copybrief AppenderSkeleton::setOption()

    Supported options | Supported values | Default value |

    :-------------- | :----------------: | :---------------: |

    BufferSize | {int} | 1 |

    ConnectionString | {any} | - |

    URL | {any} | - |

    DSN | {any} | - |

    User | {any} | - |

    Password | {any} | - |

    SQL | {any} | -

    ColumnMapping | (\ref colName "^") | -

    \anchor colName (^) One value for each '?' character in the SQL value.

    \sa AppenderSkeleton::setOption()

    */

    void setOption(const LogString& option, const LogString& value) override;

    /**

    Activate the specified options.

    */

    void activateOptions(helpers::Pool& p) override;

    /**

    * Adds the event to the buffer.  When full the buffer is flushed.

    */

    void append(const spi::LoggingEventPtr& event, helpers::Pool&) override;

  protected:

    /**

    * To be removed.

    */

    LogString getLogStatement(const spi::LoggingEventPtr& event,

      helpers::Pool& p) const;

    /**

    *

    * To be removed.

    * */

    virtual void execute(const LogString& sql,

      LOG4CXX_NS::helpers::Pool& p) /*throw(SQLException)*/;

    /**

    * Override this to return the connection to a pool, or to clean up the

    * resource.

    *

    * The default behavior holds a single connection open until the appender

    * is closed (typically when garbage collected).

    */

    virtual void closeConnection(SQLHDBC con);

    /**

    * Override this to link with your connection pooling system.

    *

    * By default this creates a single connection which is held open

    * until the object is garbage collected.

    */

    virtual SQLHDBC getConnection(LOG4CXX_NS::helpers::Pool& p) /*throw(SQLException)*/;

    /**

    * Closes the appender, flushing the buffer first then closing the default

    * connection if it is open.

    */

  public:

    void close() override;

    /**

    * loops through the buffer of LoggingEvents, gets a

    * sql string from getLogStatement() and sends it to execute().

    * Errors are sent to the errorHandler.

    *

    * If a statement fails the LoggingEvent stays in the buffer!

    */

    virtual void flushBuffer(LOG4CXX_NS::helpers::Pool& p);

    /**

    * Does this appender require a layout?

    * */

    bool requiresLayout() const override;

    /**

    * Set pre-formated statement eg: insert into LogTable (msg) values ("%m")

    */

    void setSql(const LogString& s);

    /**

    * Returns pre-formated statement eg: insert into LogTable (msg) values ("%m")

    */

    const LogString& getSql() const;

    void setUser(const LogString& user);

    void setURL(const LogString& url);

    void setPassword(const LogString& password);

    void setBufferSize(size_t newBufferSize);

    const LogString& getUser() const;

    const LogString& getURL() const;

    const LogString& getPassword() const;

    size_t getBufferSize() const;

  private:

    ODBCAppender(const ODBCAppender&);

    ODBCAppender& operator=(const ODBCAppender&);

#if LOG4CXX_WCHAR_T_API || LOG4CXX_LOGCHAR_IS_WCHAR_T || defined(WIN32) || defined(_WIN32)

    static void encode(wchar_t** dest, const LogString& src,

      LOG4CXX_NS::helpers::Pool& p);

#endif

    static void encode(unsigned short** dest, const LogString& src,

      LOG4CXX_NS::helpers::Pool& p);

  protected:

    struct ODBCAppenderPriv;

}; // class ODBCAppender

LOG4CXX_PTR_DEF(ODBCAppender);

} // namespace db

} // namespace log4cxx

#endif // _LOG4CXX_DB_ODBC_APPENDER_H