You can also manage the debugging settings of XINS by changing the xins.properties file. Here are the main logging settings that can be changed:

The log levels are DEBUG < INFO < NOTICE < WARN < ERROR < FATAL. This means that if you set the log level to ERROR, only the ERROR and FATAL messages will be logged.

For more information on the possible characters in the conversion pattern, visit the log4j website.

The nested diagnostic context (NDC - %x) is set to the value of the _context parameter of the query. If no _context parameter is passed a default context is created as apiName@localHost:yyyyMMdd-HHmmssNNN:random where:

For more information on the possible logging properties and values, visit log4j documentation page.

It's sometimes useful to log events that may happen in your function. To do so, you need to create what is called a logdoc (log documentation).

To create a new logdoc execute xins create-logdoc.

The command will ask you for the name of your api. The script will then create a new log.xml file in the directory apis\<api name>\impl with the content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log PUBLIC "-//XINS//DTD XINS Logdoc 2.2//EN"
          "http://www.xins.org/dtd/log_2_2.dtd">

<log>

  <translation-bundle locale="en_US" />

  <group id="exampleid" name="Example">
    <entry id="10000" level="DEBUG">
      <description>Example of logdoc with some parameters.</description>
      <param name="parameter" />
      <param name="number" nullable="false" type="int32" />
    </entry>
    <entry id="10001" level="ERROR" exception="true">
      <description>Example with an exception.</description>
    </entry>
  </group>
</log>

The group id is used for the creation of the log key (e.g. com.mycompany.myproject.api.exampleid.10001) and the group name is used for the description of the group.

It also creates a default translation file translation-bundle-en_US.xml with the content:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE translation-bundle PUBLIC "-//XINS//DTD XINS Translation Bundle 2.2//EN"
          "http://www.xins.org/dtd/translation-bundle_2_2.dtd">

<translation-bundle>
  <translation entry="10000">Example of logdoc with the parameter <value-of-param name="parameter" format="quoted" /> and <value-of-param name="number" />.</translation>
  <translation entry="10001">Example of an exception.</translation>
</translation-bundle>

You can now use the logdoc in your function implementation by calling the method Log.log_10000(myParam, 36);

The command will also add the element <logdoc /> to the impl element of the impl.xml file. If you want to use the logs in packages other than the default one add the attribute accesslevel="public" to the logdoc element.

The Logdoc consist of a main log.xml file which defines the possible locale for the logs of this API and the groups of entries. Each entry has an id that is by convension a number higher than 10000 as numbers between 1000 and 9999 are reserved for XINS. Ids don't have to be consecutive numbers. It's even advisable to have numbers gaps between groups.

If the entry has the attribute exception with the value true, then the exception should be the first parameter when invoking the method. For example the id 10001 should be invoked with Log.log_10001(myException);.

The possible types for a parameter are boolean, int8, int16, in32, int64, text and object.

By default for a parameter the nullable attribute is set to true and the type attribute is set to text.

These types match respectively in Java the types boolean, byte, short, int, long, String and Object.

If you use logdoc in your API, the list and the description of the defined log entries will be available in the specification documentation.

In the log.xml the warning level is set with level="WARNING" but the level is translated as the WARN log4j level.

Note that when the specification documentation (specdocs) is generated the HTML pages describing the logging message is also generated. You can see the XINS logdoc at http://xins.sourceforge.net/logdoc.html.

Sometimes too much log information is printed and you would like to remove some of the messages printed by the log.

There are several ways to do this. The best ways is to hide the logging messages you don't want.

The following example will hide the HTTPClient DEBUG logs:

log4j.logger.org.apache.commons.httpclient=INFO
log4j.logger.httpclient=INFO

The following example will hide all XINS messages which are not at least at the WARN level:

log4j.logger.org.xins=WARN

The following example will hide the specific logging message because the message is at DEBUG level:

log4j.logger.org.xins.server.lifespan.init.3402=INFO

The locale can also be specified in the XINS properties file:

# Locale used for logging
org.xins.server.log.locale=en_US

The logdoc with the locale en_US and fr_FR are provided in XINS.

An example of a XINS properties file with a customized logging system can be found in the demo directory.