Calling the PEERNET Reports Runtime Engine
Contents
Calling the PEERNET Reports Embedded Engine requires only the implementation of one Java interface (com.peernet.report.engine.RuntimeInterface). You can then open any project (PNJ file) created in PEERNET Reports using the PEERNET Reports Object Model API. Optionally, you can implement com.peernet.report.engine.StatusInterface to obtain status feedback.
Included in the installation folder of PEERNET Reports is a folder named javaexamples that contains PEERNETReportsSampleViewer. This Java application can be built using JBuilder by opening the JBX file included with this sample.
PeernetReportViewerFrame implements the RuntimeInterface and shows you how to implement your own version of this interface for your desktop application. You can open the file named PeernetReportViewerFrame.java in an appropriate editor. Note that this interface can be implemented in a variety of ways; shown below is a console-based implementation for an application that has no user interface:
// PeernetRuntimeInterface : starts
protected Hashtable m_propertyHash = new Hashtable() ;
/**
* Reports an exception with the specified cause
* contained in the input throwable.
*
* @param e the cause of the exception to report
*/
public void reportException(Throwable e) {
System.err.println("A Program Application Error has occurred");
System.err.println("");
System.err.println(
"please provide the following information to [email protected].");
System.err.println("");
e.printStackTrace();
}
/**
* Reports an exception with the specified detail
* message and cause.
*
* @param msg the detail message
* @param e the cause of the exception to report
*/
public void reportException( String msg, Throwable e ) {
System.err.println("A Program Application Error has occurred");
System.err.println("");
System.err.println(
"please provide the following information to [email protected].");
System.err.println("");
System.err.println(msg);
System.err.println("");
e.printStackTrace();
}
/**
* Reports an error with the specified cause contained
* in the input throwable.
*
* @param e the cause of the error to report
*/
public void reportError( Throwable e ) {
e.printStackTrace() ;
}
/**
* Reports an error with the specified detail message
* and cause.
*
* @param msg the detail message
* @param e the cause of the error to report
*/
public void reportError( String msg, Throwable e ) {
System.err.println( msg ) ;
e.printStackTrace() ;
}
/**
* Reports an error with the specified detail message.
*
* @param msg the detail message
*/
public void reportError( String msg ) {
System.err.println( msg ) ;
}
/**
* Reports a message with the specified detail message.
*
* @param msg the detail message
*/
public void reportMessage( String msg ) {
System.err.println( msg ) ;
}
/**
* Returns this desktop object.
*
* @return this desktop object
*/
public java.awt.Component getDesktop() {
return null ;
}
/**
* Sets a property with the specified key and value.
*
* @param key the specified key of the property
* @param value the specified value of the key
*/
public void putProperty( Object key, Object value ) {
if ( value == null )
m_propertyHash.remove( key ) ;
else
m_propertyHash.put( key, value ) ;
}
/**
* Gets a property with the specified key.
*
* @param key the specified key of the property
* @return the property with the specified key
*/
public Object getProperty( Object key ) {
return m_propertyHash.get( key ) ;
}
/**
* Checks whether or not a property with the
* specified key exists.
*
* @param key the specified key of the property
* @return true if the property with the specified
* key exists; <code>false</code> otherwise
*/
public boolean containsProperty( Object key ) {
return m_propertyHash.containsKey( key ) ;
}
// PeernetRuntimeInterface : ends
The PeernetReportViewerFrame class also contains a process method that demonstrates how to open a project. To open a project (PNJ file), you first must set the properties in the RuntimeInterface to provide a context for the Embedded Engine. The table below provides you with the key name, value type, default value, and description of the properties you should set up in the RuntimeInterface:
Key Name |
Value Type |
Default Value |
Description |
Application.license. serialNumber |
java.lang.String |
Null |
Distribution serial number provided by PEERNET Inc. for licensed Java solutions using PEERNET Reports runtime engine. |
Application.license.dir |
java.lang.String |
{Folder containing PEERNETReportsEngine3.jar} |
Not applicable when a distribution serial number is specified. |
Application.dir |
java.lang.String |
{Folder containing PEERNETReportsEngine3.jar} /../projects |
Folder containing the PNJ file(s); used when the PNJ file is not fully qualified. |
Application.fonts |
java.lang.String |
{Application.dir}/fonts |
Folder containing the distributed TrueType font file(s). |
Application.lib |
java.lang.String |
{Application.dir}/lib |
Folder containing the Java libraries referenced by all projects. This is an alternative to using the classpath object of a project. |
You can set a property using the setProperty method of the RuntimeInterface as follows:
runtime.putProperty( "Application.license.serialNumber", "My Serial Number" ) ;
By default, no properties must be set other than Application.license.serialNumber, and this property only needs to be set once PEERNET Reports Embedded Engine has been licensed for distribution. For evaluation purposes, this property must not be set.
Shown below is the process method in the PEERNETReportsSampleViewerFrame class:
public void process( String args[] ) {
String projectFile = "<Path to your pnj file>" ;
String reportOrLabelOrRequestName = "<Your Report, Label or Request Name>" ;
String serialNumber = null ;
// Load from command line if arguments have been specified
if ( args.length > 0 ) {
projectFile = args[ 0 ] ;
}
if ( args.length > 1 ) {
reportOrLabelOrRequestName = args[ 1 ] ;
}
if ( args.length > 2 ) {
serialNumber = args[ 2 ] ;
}
File in = new File( projectFile ) ;
java.net.URL url = null ;
try {
url = in.toURL();
} catch ( java.io.IOException ex ) {
reportError( ex ) ;
return ;
} catch ( Throwable tr ) {
reportException( tr ) ;
return ;
}
if ( serialNumber != null && serialNumber.trim().length() > 0 ) {
// This will be your distribution serial number provided from PEERNET
this.putProperty( "Application.license.serialNumber", serialNumber.trim() ) ;
}
try {
Project project = ProjectManager.open( this, this, url ) ;
if ( project != null ) {
String name ;
Request request = null ;
Report report = null ;
com.peernet.report.engine.Label label = null ;
name = reportOrLabelOrRequestName.trim() ;
String test = reportOrLabelOrRequestName.toLowerCase() ;
if ( test.startsWith( "request:" ) ) {
name = name.substring( "request:".length(), name.length() ) ;
request = project.getRequest( name ) ;
if ( request == null ) {
reportError( "Request '" + name + "' does not exist in this project." ) ;
}
} else if ( test.startsWith( "report:")) {
name = name.substring( "report:".length(), name.length() ) ;
report = project.getReport( name ) ;
if ( report == null ) {
reportError( "Report '" + name + "' does not exist in this project." ) ;
}
} else if ( test.startsWith( "label:" )) {
name = name.substring( "label:".length(), name.length() ) ;
label = project.getLabel( name ) ;
if ( label == null ) {
reportError( "Label '" + name + "' does not exist in this project." ) ;
}
} else {
int count = 0 ;
request = project.getRequest( name ) ;
if ( request != null )
count++ ;
report = project.getReport( name ) ;
if ( report != null )
count++ ;
label = project.getLabel( name ) ;
if ( label != null )
count++ ;
if ( count == 0 ) {
reportError( "'" + name + "' is not a request, report or label in this project." ) ;
} else if ( count > 1 ) {
reportError( "'" + name + "' needs a prefix of Request:, Report: or Label:. Name is ambiguous." ) ;
}
}
if ( report != null ) {
java.util.Hashtable parameters = new java.util.Hashtable() ;
DocumentInterface doc = report.format(this, null, null, parameters, null);
if (doc != null) {
PeernetReportPreviewDialog d = new PeernetReportPreviewDialog(this);
d.show(doc);
}
if ( doc != null ) {
// Release the formatted document as we are now finished with it
doc.dispose() ;
doc = null ;
}
} else if ( label != null ) {
java.util.Hashtable parameters = new java.util.Hashtable() ;
DocumentInterface doc = label.format(this, null, null, parameters, null);
if (doc != null) {
PeernetReportPreviewDialog d = new PeernetReportPreviewDialog(this);
d.show(doc);
}
if ( doc != null ) {
// Release the formatted document as we are now finished with it
doc.dispose() ;
doc = null ;
}
} else if ( request != null ) {
ByteArrayOutputStream bos = new ByteArrayOutputStream() ;
java.util.Hashtable parameters = new java.util.Hashtable() ;
request.run( this, // RuntimeInterface
null, // StatusInterface
null, // Reserved for future use
parameters, // Parameters values to be used by this
bos ) ; // OutputStream to receive results of this request
bos.close();
if ( bos.size() > 0 ) {
// save results to disk
// TODO : Implement where you want results to be saved
}
}
}
} catch ( java.io.IOException ex ) {
reportError( ex ) ;
} catch ( Throwable ex ) {
reportException( ex ) ;
}
}
This method shows how to load a project using com.peernet.report.engine.ProjectManager. It then shows how to find a report, label, or request using the project interface. For a report or label, it goes further to format the report or label for previewing using the report or label interface. For a request, it shows how to use the run method of the request interface.
There are many other tasks you can perform using the PEERNET Reports Object Model (refer to the PEERNET Reports Object Model documentation for complete information). It provides access to all objects in a project, provides interfaces at the object level to alter or retrieve object information, and provides format, print, and run methods.
One of the most important features is the passing of parameters to a report, label, or request. This is one way in which your application can provide information to an underlying report, label or request. A parameter can be any Java object type, even one of your own creation. All that is required is that, when you design the report, label, or request, you set the parameter’s data type to the desired class, or use object to mean any type.
In order to specify an object type of your own creation, you must add a classpath object that specifies from where the class is loaded, or copy your library (JAR or ZIP) to the lib folder of PEERNET Reports. Then, type your class name into the data type field of the parameter (without getting a ‘class not found’ error). You can then reference the parameter from within reports, labels, or requests just as you would in your own Java code.
Another important feature is Java Object tables. Java Object tables provide a way to use Java collections to create tables that can be used by PEERNET Reports. For example, at design time you might be using a static Java Object table for design purposes, but at runtime you might need to change the contents of the table dynamically. You can do this by locating the Java Table (by name, using the project interface’s method findTable("MyJavaTable")), then using the table interface’s method setSource(YourDesiredContents) before formatting, printing, or running the report, label, or request. The setSource method overrides the default table contents, and makes the table contents the ones you specify in the setSource method.