Creating UDOs

Objects and interfaces for creating UDOs

The following objects and interfaces are necessary for creating a UDO. Refer to the corresponding class or interface in the JReport Javadoc located at <install_root>\help\api.

Jet.report.JRObjectTemplate
This is an object provided by the JReport system, and is used to derive a UDO. The JRObjectTemplate contains several predefined properties of the standard JReport Object used to compose a report, including: X, Y, Height and Width. You can add more properties (supported by JReport system) to your own UDO. These properties can be viewed and modified by the Report Inspector at design time.

Note: Only JReport system properties or properties inherited from them can be added, such as JetNumber, JetColor, JetString, and JetEnumeration. See the jet.controls package.

jet.datastream.JRVisiableResult
This is another object provided by the JReport system. You will need to define an object inherited from this object, so that you can specify the methods for saving and restoring the UDO object. JRVisiableResult provides methods for saving and restoring UDOs.

jet.datastream.JRObjectResult
If the UDO you define is not used for displaying, that is, it will not appear inside the report result on the screen or on paper, then it can be inherited from the JRObjectResult object.

jet.udo.JRObjectResultCreator
This is an interface. It takes JReport system's JReport Record as input parameters and produces the UDO's JRObjectResult. A definition of the JReport Record is in the jet.connect package.

jet.udo.JRObjectRender
This is another interface. It provides a method used for painting the UDO to the report. The report can then be shown on the screen or printed on a printer.

jet.udo.JRObjectEditor
This is an optional interface. If specified, the JReport system will use it to handle interactive events (key events, mouse events, paint, and so on) at design time. If this interface is not implemented, the JReport system will use the default one.

jet.udo.JRGroupListener
This interface is used when you define a UDO with a value which is calculated based on a group of data.

Then to create a UDO manually with the objects and interfaces, follow the steps:

Inherit from the class JROblectTemplate to create a template file.

Inherit from the class JRVisiableResult or JRObjectResult to create a result file.

Implement JRObjectResultCreator to create a result creator file.

Implement interface JRObjectRender to create a result render file. If you want to display a UDO in the Design area, implement interface JRObjectEditor. If your UDO is a group level object, implement interface JRGroupListener.

Modify the file udo.ini in <install_root>\lib by adding the following:

Begin 
name=MyDbField
template=myudo.MyDbFld
resultobject=myudo.MyDbFldRst
resultcreator=myudo.MyDbFldCreator
resultviewer=myudo.MyDbFldRender
End

Compile the Java files, add the classes to the ADDCLASSPATH variable of setenv.bat in <install_root>\bin.

Note: If you want to use class files for the UDO which have been used in previous versions, you should re-compile the source files.

Example 1: Accessing a record for a UDO and registering the UDO with the report system

This example describes how to access a record for your UDO and how to register your UDO with the report system.

A UDO needs to implement at least four classes from JReport. The four classes are for template, result, creator and render files respectively.

MyDbFld.java

//Template 
package myudo;

import jet.report.*;
import jet.controls.*;

/**
 * This class extends form JRObjectTemplate, add two properties "ColumnName" and
 * "TextColor".
 */
public class MyDbFld extends JRObjectTemplate {
	/**
	 * This property is for the column name of MyDbFld.
	 */
	public JetColumnName columnName = new JetColumnName(this, "ColumnName");

	/**
	 * This property is for the background color of MyDbFld..
	 */
	public JetColor backColor = new JetColor(this, "TextColor", null, true);

	public MyDbFld() {
		super();
		columnName.setEditable(true);
		// set the default size.
		set("Width", 40); // before build575 should be width.set(40);
		set("Height", 20); // before build575 should be height.set(20);
		// add the property to group then they can displayed in ReportInspector.
		addPropertyToGroup("ColumnName", "Others");
		addPropertyToGroup("TextColor", "Color");
	}

	/**
	 * Return the instance name prefix. >
	 */
	public String getPrefix() {
		return "MyDbField";
	}
}

MyDbFldRst.java

//Result
package myudo;

import jet.connect.Record;
import jet.connect.DbValue;
import jet.util.*;
import jet.datastream.*;

public class MyDbFldRst extends JRVisiableResult {
	public MyDbFldRst() {
	}

	// retrieve value from column.
	DbValue getValue() {
		// get the column name.
		String colName = (String) getPropertyByName("ColumnName").getObject();
		// get the report record.
		Record record = getRecord();
		// return the column value.
		return record.getCell(colName);
	}

	// make the text will be displayed.
	String getText() {
		String sRet;
		DbValue value = getValue();
		if (value != null && !value.isNull()) {
			sRet = value.toString();
		} else {
			sRet = "NULL";
		}
		return sRet;
	}
}

MyDbFldCreator.java

//Creator
package myudo;

import java.awt.*;
import java.util.*;
import jet.report.*;
import jet.controls.*;
import jet.connect.*;
import jet.udo.*;
import jet.datastream.*;
import guitools.Painter;
import jet.util.*;

/**
 * Implements JRObjectResultCreator for creating JRObjectResult in JReport
 * Engine Bean.
 */
public class MyDbFldCreator implements JRObjectResultCreator {
	public MyDbFldCreator() {
	}

	public JRObjectResult createJRObjectResult(JRObjectTemplate rptobj,
			Record record) {
		MyDbFld rpt = (MyDbFld) rptobj;
		MyDbFldRst dsField = new MyDbFldRst();
		dsField.setTemplate(rpt);
		return dsField;
	}
}

MyDbFldRender.java

//Render
package myudo;

import java.awt.*;
import java.awt.event.*;
import java.util.*;
import jet.datastream.*;
import jet.connect.DbValue;
import jet.connect.Record;
import jet.udo.*;

public class MyDbFldRender extends Component implements JRObjectRender {
	String text = null;

	Color color;

	Color background;

	/**
	 * The default constructor.
	 */
	public MyDbFldRender() {
	}

	// retrieve property and data from JRObjectResult.
	public void setProperty(jet.util.PropertySetable dsPropSet) {
		text = ((MyDbFldRst) dsPropSet).getText();
		color = (Color) dsPropSet.getPropertyByName("TextColor").getObject();
		background = (Color) dsPropSet.getPropertyByName("Background")
				.getObject();
		setBounds(((MyDbFldRst) dsPropSet).getBounds());
	}

	/**
	 * Paint the text.
	 */
	public void paint(Graphics g) {
		Dimension dim = getSize();
		if (background != null) {
			g.setColor(background);
			g.fillRect(0, 0, dim.width, dim.height);
		}
		if (text != null) {
			if (color == null)
				color = Color.black;
			g.setColor(color);
			g.drawString(text, 10, 10);
		}
	}
}

Note: Since the compiling process of JReport Designer differs with that of JReport Server, when you run UDOs in these two applications, you should pay attention to some minor differences. For example, to get width and height, in JReport Designer, you should use:
w = guitools.toolkit.Unit.convertUnitToPixel(((Integer)propertySetable.getPropertyByName ("Width").getObject()).intValue()); h = guitools.toolkit.Unit.convertUnitToPixel(((Integer)propertySetable.getPropertyByName ("Height").getObject()).intValue());

While in JReport Server, you should use the following instead:
JRObjectResult obj = (JRObjectResult)propertySetable; w = guitools.toolkit.Unit.convertUnitToPixel(obj.getTemplate().getWidth(obj)); h = guitools.toolkit.Unit.convertUnitToPixel(obj.getTemplate().getHeight(obj));

Compile the Java files.

To compile these four Java files, you should add report.jar and JREngine.jar with their path into the class path (make sure that the path of the file JREngine.jar is before that of the file report.jar). For example, use the following command:

Javac -classpath "C:\JReport\Designer\lib\JRengine.jar;C:\JReport\Designer\lib\report.jar;C:\test "MyDbFld.java

Here it is assumed that JReport Designer is installed to C:\JReport\Designer. The Java files for the example are in C:\test\myudo.

Modify the udo.ini file in the <install_root>\lib directory by appending the four classes as follows:

Begin
name=MyDbField
template=myudo.MyDbFld
resultobject=myudo.MyDbFldRst
resultcreator=myudo.MyDbFldCreator
resultviewer=myudo.MyDbFldRender 
End

Edit setenv.bat in <install_root>\bin by appending the path of the four classes to the batch file's ADDCLASSPATH variable. Assume that the four classes are located in D:\test\myudo.

set ADDCLASSPATH=%JAVAHOME%\lib\tools.jar;D:\test;

Start JReport Designer.

Click Insert > UDO. You will now find a new UDO object named MyDbFld in the drop-down list of the Insert UDO dialog.

Example 2: Making a group based on a UDO

This example describes how to make a group based on a UDO. This sample is similar to a summary field. This example includes the implementation of four classes and shares a class with Example 1.

Create the template, result, creator and render files as follows:

MySumFld.java

//Template
package myudo;

import jet.report.*;
import jet.controls.*;

/**
 * This class extends from JRObjectTemplate, add two properties "ColumnName" and
 * "TextColor".
 */
public class MySumFld extends MyDbFld {
	public MySumFld() {
		super();
	}

	/**
	 * Return the instance name prefix.
	 */
	public String getPrefix() {
		return "MySumField";
	}

	public boolean isGroupListener() {
		return true;
	}
}

MySumFldRst.java

//Result
package myudo;

import jet.JRStopEngineException;
import jet.connect.Record;
import jet.connect.DbValue;
import jet.util.*;
import jet.datastream.*;
import java.io.*;

public class MySumFldRst extends MyDbFldRst {
	double value;

	public MySumFldRst() {
	}

	// make the text will be displayed. 
	String getText() {
		return "" + value;
	}

	/**  
	 * Read the data from DataInput. 
	 * UDO can override this method to restore its own data. 
	 * @throws JRStopEngineException 
	 * */
	protected void readProperties(DataInput in, DSDataStreamable ds)
			throws IOException, JRStopEngineException {
		super.readProperties(in, ds);
		value = in.readDouble();
	}

	/**  
	 * Write the data to DataInput. 
	 * UDO can override this method to save its own data. 
	 * */
	protected void writeProperties(DataOutput out) throws IOException {
		super.writeProperties(out);
		out.writeDouble(value);
	}
}

MySumFldCreator.java

//Creator
package myudo;

import java.awt.*;
import java.util.*;
import jet.report.*;
import jet.controls.*;
import jet.connect.*;
import jet.udo.*;
import jet.datastream.*;
import guitools.Painter;
import jet.util.*;

/**
 * * Implements JRObjectResultCreator for creating JRObjectResult in JReport *
 * Engine Bean.
 */
public class MySumFldCreator implements JRObjectResultCreator, JRGroupListener { 
	// This interface must implement by JRObjectCreator.
	MySumFld rpt;

	MySumFldRst dsField;

	double value;

	public MySumFldCreator() {
	}

	public void setTemplate(JRObjectTemplate rptobj) {
		rpt = (MySumFld) rptobj;
	}

	public JRObjectResult createJRObjectResult(JRObjectTemplate rptobj,
			Record record) {
		rpt = (MySumFld) rptobj;
		MySumFldRst dsField = new MySumFldRst();
		dsField.setTemplate(rpt);
		dsField.value = value;
		return dsField;
	}

	/** * This method will be called before the first record. */
	public void prepareFetchRecords() {
		value = 0.0;
	}

	/** * This method will be called after the last record. */
	public void finishFetchRecords() {
	}

	/** * This method will be called each record. */
	public void fetchNewRecord(Record record) {
		String colName = (String) rpt.getPropertyByName("ColumnName")
				.getObject();
		// return the column value.
		DbNumber num = (DbNumber) record.getCell(colName);
		if (!num.isNull()) {
			value += num.intValue();
		}
	}
}

MyDbFldRender.java (See Example 1 for details.)

Compile the four Java files in the same way as Example 1.

Modify udo.ini in <install_root>\lib\ by appending the four classes as follows:

Begin
name=MySumFld 
template=myudo.MySumFld 
resultobject=myudo.MySumFldRst 
resultcreator=myudo.MySumFldCreator 
resultviewer=myudo.MyDbFldRender
End

Edit setenv.bat in <install_root>\bin by appending the path of the four classes to the batch file's ADDCLASSPATH variable. Assume that the four classes are located in D:\test\myudo.

set ADDCLASSPATH=%JAVAHOME%\lib\tools.jar;D:\test;

Start JReport Designer.

Click Insert > UDO. You will now find a new UDO object named MySumFld in the drop-down list of the Insert UDO dialog.