Writing a JAVA Class

In this section:

When you write a JAVA class to be invoked by the Reporting Server, you use the class with the CALLJAVA interface, as much as you would use a 3GL program with the CALLPGM interface. The CALLJAVA interface defines two methods, execute and fetch.

Note: The CALLJAVA interface is also used internally, and, as such, requires an additional execute method as a signature returning a null to exist in user application so the two uses can co-exist. The additional method is:

public ibianswr
     execute(String username, String password, Object obj, String[] parms)
             throws Exception { return null; }

Tip: This signature is already included in the sample application, so if the sample is just cloned as a template for another application, the signature will already properly placed.

For applications built prior to 7.6.3 to work with 7.6.3 (or higher) servers, the signature must be added and the application rebuilt. The current sample can be used to determine where to place the signature in older applications (current sample JAVA CALLPGM code is shown in Compiling and Running a JAVA Program).

Please note that while you must include this code, you may neither modify nor use it.


Top of page

x
The Java Logging API

In this section:

A logging api is provided to assist in transaction logging, tracing and debugging. The api follows the industry practices followed by many providers. If you have experience working with other widely accepted Java logging packages (for example, java.logging, org.apache.commons.logging, log4j, slf4j), then you will be familiar with these methods.

Note: This API replaces the deprecated ibtrace methods in earlier releases.



x
Basic Logging API

Assume you need to add logging capabilities to the following class:

public class Foo 
{
   public static String concatenate(String s1, String s2) 
   {
      return s1 + s2;
   }
}

Add static member of type ibi.trace.ILogger (commonly named “log”) to the class, then use it to log actions within the code:

import ibi.trace.ILogger;
import ibi.trace.IBILogFactory;
 
public class Foo 
{
   private static final ILogger log = IBILogFactory.getLogger(Foo.class);
   public static String concatenate(String s1, String s2) 
   {
      log.debug("About to concatenate ''{0}'' and ''{1}''", s1, s2);
      return s1 + s2;
   }
}


x
Logging Levels

The logging API supports the following levels:

Each level allows formatted output and exception logging. For example, at warn level:

   log.warn("About to sleep 100 millis");
   try 
   {
      Thread.sleep(100);
   }
   catch(InterruptedException ex) 
   {
      log.warn("Warning: interrupted", ex);
   }


x
Java Logging and Server Tracing

When the server is started with the -traceon option, java logging is enabled at the debug level (this level automatically includes all other levels).

The special logger name edaprint.log can be used to duplicate logging messages to the edaprint.log file of the server. Only error, warn, and info levels can go to edaprint.log. Also, edaprint.log logger is always enabled, regardless of whether server was started with traces on or off.

The use edaprint.log method should be done sparingly - only important and critical events should be put to edaprint.

The following code illustrates the edaprint.log logging functionality:

public class Foo
{
   private static final log      = IBILogFactory.getLogger(Foo.class);
   private static final edaprint = IBILogFactory.getLogger("edaprint.log");
   public static void concatenateAndWrite(Writer writer, String s1, String
s2) 
   {
      log.debug("About to concatenate {0} and {1}", s1, s2);
      String s = s1 + s2;
      log.debug("Result is: {0}", s);
      try
      {
          writer.write(s);
      }
      catch(IOException ex)
      {
          // this sends error report to the server's edaprint.log 
          // regardless of server tracing setting.
          // Additionally, if traces are on, the error report
          // will be sent to the standard trace facility
          edaprint.error("Failed to write", ex);
      }
   }
}


x
Logging Reference Guide

The following sections describe different logging levels.



x
Debug Level
public boolean isDebugEnabled();

Returns true if logging is enabled at the Debug level. Useful to avoid time-consuming computations that are needed only for logging purposes.

public void debug(String message);

Sends message string to the logging destination, but only if logging is enabled at the debug level.

public void debug(String messageFormat, Object arg1);
public void debug(String messageFormat, Object arg1, Object arg2);
public void debug(String messageFormat, Object arg1, Object arg2, Object arg3);

Formats message and sends the result to the logging destination, but only if logging is enabled at the debug level.

public void debug(String messageFormat, Throwable th);

Prints message and exception trace to the logging destination, but only if logging is enabled at the debug level.



x
Info Level
public boolean isInfoEnabled();

Returns true if logging is enabled at the Info level. Useful to avoid time-consuming computations that are needed only for logging purposes.

public void info(String message);

Sends message string to the logging destination, but only if logging is enabled at info or higher level.

public void info(String messageFormat, Object arg1);
public void info(String messageFormat, Object arg1, Object arg2);
public void info(String messageFormat, Object arg1, Object arg2, Object arg3);

Formats message and sends the result to the logging destination, but only if logging is enabled at info or higher level.

public void info(String messageFormat, Throwable th);

Prints message and exception trace to the logging destination, but only if logging is enabled at info or higher level.



x
Warn Level
public boolean isWarnEnabled();

Returns true if logging is enabled at the Warn level. Useful to avoid time-consuming computations that are needed only for logging purposes.

public void warn(String message);

Sends message string to the logging destination, but only if logging is enabled at warn or higher level.

public void warn(String messageFormat, Object arg1);
public void warn(String messageFormat, Object arg1, Object arg2);
public void warn(String messageFormat, Object arg1, Object arg2, Object arg3);

Formats message and sends the result to the logging destination, but only if logging is enabled at warn or higher level.

public void warn(String messageFormat, Throwable th);

Prints message and exception trace to the logging destination, but only if logging is enabled at warn or higher level.



x
Error Level
public boolean isErrorEnabled();

Returns true if logging is enabled at the Error level. Useful to avoid time-consuming computations that are needed only for logging purposes.

public void error(String message);

Sends message string to the logging destination, but only if logging is enabled at error or higher level.

public void error(String messageFormat, Object arg1);
public void error(String messageFormat, Object arg1, Object arg2);
public void error(String messageFormat, Object arg1, Object arg2, Object arg3);

Formats message and sends the result to the logging destination, but only if logging is enabled at error or higher level.

public void error(String messageFormat, Throwable th);

Prints message and exception trace to the logging destination, but only if logging is enabled at error or higher level.


Top of page

x
The Java ibtrace Tracing Interface (Deprecated)

Reference:

The ibi.trace methods described here are considered deprecated as of Version 7 Release 7, but remain (with one exception) for backward compatibility purposes. The normal edastart -traceon facility captures the trace interactions between the user (TSCOM3) process, the CALLJAVA API and any ibtrace.println() statements that may be in the application. The user process interactions are stored in the normal TS###### trace files and the Java traces are stored in the JS###### trace files of the Java service, both in the EDATEMP directory.

The numbering of the JS###### files is based on the current JAVA execution number. As a reference, in the EDATEMP directory, you will also find JSCOM3 and JSCOM3_J trace files related to the start up of the Java service.

The API also includes ibtrace class methods for the Java application to more precisely control trace activities in which the main traces can be off, yet specific events using ibtrace.println() can be tracked, much like an activity log.

Tracing is typically used when an exception is thrown and a user wants to send special information to the process trace (which may or may not be active) before taking the next step, possibly performing some remediative action.

} catch (Exception e)
  {
    ibtrace.println(ClassName + ": Parm One Not Integer: " + e + "\n");
    Rows = 1; /* Reset to 1 if not numeric */
  }


x
Reference: Trace Methods and Uses

The following chart lists a complete set of trace methods and typical uses.

Method

Typical Use

closeTrace( )

Closes an open trace file. This is required before the first initTrace() call in order to close the internal default file. If not supplied, the initTrace() is ineffective and the prior trace file remains active.

initTrace(String fname)

Is used after closeTrace() to initialize and provide an alternate trace file name. If a previously used file is provided, it is opened as new and the contents are over-written.

initTrace(String fname, append flag)

Is used after closeTrace() to initialize and provide an alternate trace file name with a boolean flag (true/false) to indicate appending to an existing file. An append flag of false is effectively the same as initTrace(String fname).

println(String msg)

Prints a text message into a trace file.

println(Exception e + String id)

Prints an exception into a trace file with a string ID.

traceOn( )

Enables Write operations for trace file. This is the default if the server was start with tracing.

traceOff( )

Disables Write operations for trace file. This is the default if the server was started without tracing.

isTraceOn( )

Checks for tracing on/off status to control logic flow. The reply response is "true" or "false."

Note: Prior releases supported a method of printIn(exception e), however, it was necessary to remove the method and not just deprecate it. It is easily replaced by concatenating with a string (for example, +”\n”).



x
The ibiAnswerSet Interface
package ibi.callpgm;
 
public interface ibiAnswerSet {
 
public static final int IBI_ALPHA
public static final int IBI_INTEGER
public static final int IBI_FLOAT
public static final int IBI_DOUBLE
public static final int IBI_TIME
public static final int IBI_DATE
public static final int IBI_TIMESTAMP
public static final int IBI_SMALLINT
public static final int IBI_BIGINT
public static final int IBI_DECIMAL
public static final String IBI_MISSING
 
public int getColsNumb();
public void setColName(int colIndex, String name);
public void setColType(int colIndex, int type);
public void setColSize(int colIndex, int size);
public void setColValue(int colIndex, String value);
}

See Compiling and Running a JAVA CALLPGM Program for an illustration of how setColName, setColType, setColSize, and setColValue are used.


Top of page

x
The callpgm Interface
package ibi.callpgm;
 
public interface callpgm {
/**
* executes the request and returns answer set description
* @param username - the user name or null
* @param password - the user password or null
* @param parms - array of parameters or null
* @param ibianswr - the IBI Answer Set object
* @return ibianswr populated with the meta information
*/
public ibianswr
       execute(String username, String password, String[] parms)
               throws Exception;
/**
* returns one row of the answer
* @param - none. IBI Answer Set object instantiated in "execute" 
*          is used to return data
* @return End-Of-Data indicator
*/
public Integer fetch() throws Exception;
 
public static final Integer IBI_EOD = null;
public static final Integer IBI_DATA = new Integer(1);
} 

iWay Software