include/axis/Axis.hpp

/*
 *   Copyright 2003-2004 The Apache Software Foundation.
// (c) Copyright IBM Corp. 2004, 2005 All Rights Reserved
 *
 *   Licensed 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.
 *
 *
 * @author Samisa Abeysinghe (sabeysinghe@virtusa.com)
 *
 */
 
/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
/* NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE   */
/* ----------------------------------------------------------------   */
/* CHANGES TO hpp HEADER FILE MAY NEED TO BE PROPAGATED TO THE        */
/* C-EQUIVALENT HEADER FILE IN SUPPORT OF THE C-BINDING INTERFACES.   */
/* ----------------------------------------------------------------   */
/* NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE   */
/* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
 
#ifdef WIN32
#pragma warning (disable : 4786)
#endif

#if !defined(__AXIS_H_OF_AXIS_INCLUDED__)
#define __AXIS_H_OF_AXIS_INCLUDED__

#include <axis/TypeMapping.hpp>

/**
 * @file Axis.hpp
 */

AXIS_CPP_NAMESPACE_START

/**
 * @class Axis
 *
 * Contains methods to initialize and terminate the Axis runtime. Creating a stub also initializes
 * the Axis runtime and deleting the stub terminates it. So simple applications that only ever
 * use one stub at a time do not need to call these methods. More complicated applications that 
 * initialize multiple stubs, use them and delete them later, should initialize Axis at the start
 * of their application using Axis::initialize and terminate Axis at the very end of their 
 * application with Axis::terminate. Applications that use Axis in multiple threads should also 
 * call Axis:: initialize and terminate.
 */
class STORAGE_CLASS_INFO Axis
{
  public:
	  /**
	   * @enum AXIS_TRACE_TYPE
	   * Trace types 
	   */
	  typedef enum 
	  { 
		  AXIS_TRACE_TYPE_ENTRY=0,
		  
		  AXIS_TRACE_TYPE_EXIT=1,
		  
		  AXIS_TRACE_TYPE_EXCEPTION=2,
		  
		  AXIS_TRACE_TYPE_DEBUG=3
		  
	  }  AXIS_TRACE_TYPE;
	  
    /**
     * Initializes the Axis runtime.
     * @param bIsServer should be set to false for client applications.
     */
    static void initialize(bool bIsServer);

    /**
     * Terminates the Axis runtime.
     */
    static void terminate();
    
    /**
     * Deletes storage allocated by the Axis engine, that is no longer required
     * by the customer application.
     * 
     * @param pValue
     * @param type The XSDTYPE of the storage item to be deleted.
     */
    static void AxisDelete(void* pValue, XSDTYPE type);
    
    /**
     * Indicates if the Axis engine is running.
     * This will return true after the first invocation of Axis::initialize()before
     * the last invocation of Axis::terminate().
     * 
     * @return Indicate if Axis engine is still running.
     */
     static bool isRunning();
     
    /**
     * Stop Axis engine. 
     */
     static void stopAxis();
     
     /**
      * Start Axis logging. This must be done prior to any activiy in order to propagate 
      * logging attributes to parser and transport.  If there are active transports and 
      * parsers, you will not get trace records other than those associated with the  
      * the engine and newly instantiated transports and parsers.
      * 
      * @param logFilePath  Path to where trace records are written to.
      * @param filter       Trace filter.  The string filter is a semicolon delimited string
	  *                     of possible filters.  Possible filters include:
	  * 
	  *                     stub         - show trace records generated by stubs
	  *                     engine       - show trace records generated by engine
	  *                     parser       - show trace records generated by parser
	  *                     transport    - show trace records generated by transport
	  *                     noEntryExit  - do not show entry/exit trace records
	  *                     
	  *                     The default filter is "stub;engine;parser;transport".
	  *                     Specifying a NULL pointer or NULL string is equivalent to 
	  *                     requesting the defailt filter.
	  */
     static int startTrace(const char* logFilePath, const char *logFilter=NULL);
  
     /**
      * Stop Axis logging. This should be done as the last step when everything has been cleaned
      * up. Otherwise, active transports and parsers will continue to trace.
      */
     static void stopTrace();
     
     /**
      * Log trace. 
      * 
      * @param  type          - trace type 
      * @param  functionName  - class method or function for which trace record is being written.
      * @param  fmt           - format as defined in printf and related functions.
      * @param  ...           - variable nuumber of parameters.
      */
     static void writeTrace(AXIS_TRACE_TYPE type, const char* functionName, const char * fmt, ...);
};

AXIS_CPP_NAMESPACE_END

#endif // !defined(__AXIS_H_OF_AXIS_INCLUDED__)