The XML schema file

ReportWeaver uses Java's reflection to analyze the classes for reporting. It uses the schema file for directions which classes must be analyzed.

The minimal information the XML configuration file must specify are the entry points into your data. From these entry points ReportWeaver deducts attributes and methods that can appear in a report.

However the number of classes and attributes found may be very large. To many users this is confusing, because there are many more classes/attributes than needed. To reduce the set of classes/attributes the schema generation process can be controlled by the XML configuration file. In this case the configuration file can specify views for the classes, which hide or rename members. Because the physical class can be hidden completely this layer is called the curtain definition.

This is a minimal schema definition file:

<?xml version = '1.0'?>
<com.qintsoft.joria.datasources.curtainschema
	  name="TestSamples"
	  dataAccessTrigger="com.qintsoft.joria.examples.curtainschema.SampleDataGenerator"
	  listVisibleJavaClasses="false">
	<root 
   name="Products" 
   view="java.util.List" 
   eltype="com.qintsoft.joria.examples.beansapi.Product"/>
</com.qintsoft.joria.datasources.curtainschema>

The first two lines specify it as an xml file that contains a curtain definition. The top level element is com.qintsoft.joria.datasources.curtainschema It specifies a number of configuration parameters, which are explained in the reference section. It contains at least one or more root elements which declare the entry points into your data.

Schema File Basics

There are a some basics required when you want to write a schema file:

Element/Attribute Reference

Root element com.qintsoft.joria.datasources.curtainschema

Top level element of a curtain defnition. It contains the root declaration and view definition elements.

Attributes:

name
Required. Names the schema. Choose a name for your schema. It will be used to identify the schema.
version
Optional (Default: empty). The version of your schema. It is not used by ReportWeaver. For your documentation purposes.
dataAccessTrigger
Required. This class implements the triggers, that supply reporting data to ReportWeaver. It must implement the interface com.qintsoft.joria.runtimeapi.DataAccessTrigger. The named class is instantiated when ReportWeaver is started. For most cases it is fine to use the default (com.qintsoft.joria.datasources.jaxb.JaxBDataAccessTrigger)). If you need special functions, then you can override this class with your own implementation. See the javadoc for details.
listVisibleJavaClasses
Optional (Default: true). If there is no view for a class that appears in the curtain definition (e.g. as an element type or as the type of a field or method), then ReportWeaver uses the Java class definition. However this may not be desired. Therefore ReportWeaver can be instructed to list all classes that is uses in the absence of a view for the class. In the above example this is set to false, to allow ReportWeaver to use the class Order and all its referenced classes implicitly. Note that listing the classes does not prevent the classes from being used. They will only be listed, so that you can correct them.
dataAccessTrigger
The class that does data serialisation/deserialisation. For most cases it is fine to use the default (com.qintsoft.joria.datasources.jaxb.JaxBDeserializerFactory). It will deserialize a XML file. This file must be preceeeded by the string "0|s". If you need special functions, then you can override this class with your own implementation.

Contained Elements:

Top Level Element initargs

Attributes:

database
Required. Names the primary database to open. The name must be in Versant format, i.e. databasename for local databases or databasename@hostname for databases residing on a network server. To find your local databases use the Versant command dblist.
options="512"
Optional. The open mode. The value of 512 opens the database readonly.
lockmode="0"
Optional. The value of 0 opens the database without locks.

You can add any option from Versant to configure your database connection. These will be passed to Versant when the database is opened.

Contained Elements:

secondarydatabase
Optional, repetitive. Specifies a secondary database to open. There may be any number of secondary databases.

Attributes:

bootfile
Required. Specifies the federated database to open. The name must refer to a federated database configuration file.

Contained Elements:none.

Top Level Element initargs

Attributes:

database
Required. Names the database to open. The name must refer to a file or to a network database in the form: server:filename.

Contained Elements:none.

Attributes:

database
Required. Names the database to open. The name must be in the format of a fastobjects database url.

Contained Elements:none.

Attributes:

url
Optional. Names the database to open. The name must be in the format of a cache JDBC database url. If not specified the Sample namespace will be opened.
username
Optional. The database user name. Default is "_SYSTEM".
password
Optional. The database user password. Default is "sys".

Contained Elements:none.

The attributes of the initarg tag are passed to the DataAccessTrigger as a property map.
package
The common package prefix of the generated jaxb wrapper classes. This prefix will be omitted when the classes are displayed in the template studio.

Top Level Element classpath

Contains a list of classpath extensions. Each element is wrapped in a <entry> tag.

Top Level Element root

This defines a data entry point. The name of the root will appear in the data tab of ReportWeaver were it can be used to design report templates. The view specifies the data fields you can use in your report template.

Attributes:

name
Required. Names the root. This name will be used as the display name that appears in the data tab of the ReportWeaver explorer
view
Required. The type of the root. It can either be a view specified elsewhere in the curtain definition file or a java class.
eltype
For a collection root (Collection,Iterator/Enumeration) you can directly specify the actual element type. This can either be a view or a physical class.

Attributes for XML with Jaxb

package
the package of the class defined in the view attribute.
file
A file, that is read as a default during testing in the template studio.

Attributes for Versant/Java (JVI)

database
Specify a secondary database to read the root from.

Attributes for Objectivity/Java

A root in objy is specified using a combination of attributes, namely:

The following combinations are possible:

objectname
Specify a named object to look up.
database
Specify a database to use.
container
Specify a container to use.
scan
Specify a class to the instances of which will be returned.
predicate
Specify a predicate (Objectivity format not OQL) for a scan to filter the instances.

Attributes for Caché with Java projections (not Jalapeno)

extent
Required. The extent to load from the database.

Contained Elements: none

Top Level Element view

A view defines a data type that can be used in reports. Views can be defined for either classes or collections. A view is a class view if it contains member elements. A view is a collection view if it has a eltype attribute.

Class View

A class view defines which members of a class shall be visible to the report developer. A view is based on a java class from where it takes its members or on another view. It contains a number of member elements, which are described below.

Attributes:

name
Required. Names the class view. This name will be used as the display name that appears in the type tab of the ReportWeaver explorer
class
Required. Specifies the class that this view is based on. This is usually a java class, but it can also be a class view defined elsewhere in the curtain definition file. Format: A fully qualified class name.
extclass
Optional (Default: empty). Specific access code that is not in the viewed class, can be added by specifying a class which provides extensions. See element extmethod on how extensions are used.

Contained Elements:

Collection View

A collection view controls access to a collection type. Its main purpose is to provide a name that is easy to understand and to declare the element type of the collection. For ReportWeaver collections are a very general and important concept. Collections allow you to create tables of object data. The term collection is used for anything that can supply a number of elements of a common type. (Relational tables are mapped to collection in ReportWeaver) First and foremost these are the collection classes from the package java.util. However ReportWeaver also allows you to create tables from arrays and iterators (java.util.Iterator and java.util.Enumeration) Consequently in ReportWeaver arrays or iterators are also simply called collections. In addition ReportWeaver provides direct support for the collection classes defined by the Object Data Management Group (package org.odmg).

Java collections except arrays do not have a specific element type. They are just defined as containing objects of type java.lang.Object. However ReportWeaver needs the element type to display the fields that become the columns of a table in the report. Therefore the true element type must be specified in the collection view element. This type is used to determine which fields are available as columns in a table, and it is also used to filter the collection according to this type. This means, that a collection view which is declared as containing Persons may contain elements which are not Persons, but the elements which are not Persons will be skipped.

Attributes:

name
Required. Names the class view. This name will be used as the display name that appears in the type tab of the ReportWeaver explorer
class
Required. Specifies the collection class that implements the collection. Format: A fully qualified class name. This can be:
  • Any class that derives from java.util.Collection
  • Any class that derives from java.util.Iterator
    Iterators are the preferred class from a performance type of view.
  • Any class that derives from java.util.Enumeration
  • Any collection class defined by the database system if you are using a direct database connector.
  • Any Array.
    Arrays must be written as elementtype[]. For arrays the eltype attribute is only required if you whish to narrow the element type to one of its subclasses. Arrays of literal types (including String) are not possible.
large
Optional (Default: false)
If this attribute appears and has the value true then ReportWeaver will not cache the collection to reduce memory. Use of this option is recommended only for collections whose size is expected to be beyound 10 000 elements.
eltype
The type of the elements. This can be either a java class or a class view defined elsewhere in the curtain definition file.

Contained Elements: none

Subelement member of a class view

Specifies a data field that appears in the view. A view member comes from a member of the source class or from a navigation path. One of its purposes is to provide an alias name that is easy to understand. A member element must contain at least one srcfield or srcmethod element. If it contains several srcfield or srcmethod elements then this does specify a navigation path. A navigation path is the equivalent of a java navigation expression hat uses the dot notation. If during runtime one of the steps in a navigation path evaluates to null, then the whole path evaluates to null.

Attributes:

name
The alias name for the member. This is the name that will appear in the fields tab of ReportWeaver when you design a template.
eltype
For a collection member (Collection,Iterator/Enumeration) you can directly specify the actual element type. This can either be a view or a physical class.

Subelement src of a member

Selects a field from the source class that supplies the data for the member. If a method of the same name exists the field is used. To use the method write the name with "()"

Attributes:

name
The name of the source field, which is used to retrieve the data. This must name one of the fields in the source class. The field can also be private or protected.

Subelement srcmethod of a member

Selects a method from the source class that supplies the data for the member. If a field of the same name exists the field is used. To use the method write the name with "()"

Attributes:

name
The name of the source method, which is used to retrieve the data. This must name a parameterless method in the source class. The method can also be private or protected.

Subelement extmethod of member

Selects a method from the extension class that supplies the data for the member. The name of the extension class must appear as the extclass attribute in the class view element. The extclass must be a public static method in the extclass that takes exactly one parameter of the viewed class. seeA sample of extclass usage.

Attributes:

name
The name of the source method, which is used to retrieve the data. This must name a parameterless method in the source class. The method must be public

Implementing the Data Access Trigger Class

The data access trigger class is defined by an interface in the package com.qintsoft.joria.runtimeapi. It is used at runtime to access the data. You only have to implement a function that returns the value for the roots declared in the curtain definition file. All other data is accessed from this root using java reflection. As a consequence all data that is required for the report must be accessible via reflection. (This means it mus be either loaded in advance, or you must use a mechnism like JDO that dynamically loads data from the database.) If your data is in memory anyway or if you use an object database like Poet, Versant, Objectivity or ObjectStore then this is trivial. The data access trigger interface also contains methods which are triggered when a transaction must be started and when a report is closed. For your convenience there is the class com.qintsoft.joria.runtimeapi.AbstractDataAccessTrigger which implements most methods.

Details of the classes and interfaces can be found in the java documentation for the classes.