The Domain Design File

The design of a Domain specifies the selection of tables in the data source, any derived tables, joins, calculated fields, and filters, as well as how those elements appear to users. In JasperReports Server, the Domain design can be created interactively through the Domain Designer, however there is also an XML file format for exporting and uploading the settings. The text file containing a Domain design represented in XML is called a design file.

The XML in a design file is a hierarchy of elements and attributes on those elements that specifies all the settings in the Domain. The elements and attributes are defined by an XML schema provided in an XSD file. In addition, there are constraints on a Domain design that are not expressed in the XML schema. A design file can be modified or written from scratch in an editor and uploaded to the server, as long as it conforms to the XML schema and the design constraints.

There are several common use cases for working with design files:

•    Completing the elements of a new design. Use the Domain Designer to define as much of the design as possible, then export the design file and add your handwritten code to the exported file. For example, you can enter the SQL query for a derived table or complex expressions for a calculated field.

•    Working with very large Domains. The Domain Designer makes it easy to select all tables and columns and expose them as sets and items, but editing the labels and descriptions of dozens of items is faster when they appear in a single design file.

•    Making repetitive changes to an existing Domain design. If the database changes or you want to move a design file to a different system, you may need to edit each table or item in the design in the same way. Using search-and-replace on an external editor does this quickly.

•    Creating locale bundles and security files as described in the other sections of this chapter. These optional files refer to elements of the Domain design, and it is often more convenient to copy-paste them between external files.

•    Creating a Domain design from scratch. It is possible to write a valid XML file that meets the constraints of JasperReports Server and defines a Domain design. However, due to the complexity of creating a valid design file, it is much easier to begin with a basic design file exported from the Domain Designer or to modify an existing design file.

After editing, a design file can be uploaded, validated, and used to define the design of a new or existing Domain. When you open the design in the Domain Designer again, the modifications appear and are editable in the Designer. For example, a description you added in the XML design file appears in the Properties table of the Display Tab, and you are be able to edit it again the Designer. Other elements of the XML file appear on some or all of the Designer tabs.

Exporting the Design File from a Domain

The design file of a Domain can be exported from the Domain Designer dialog and saved as an XML file. The file contains the current state of the Domain in the Domain Designer.

To export a Domain’s design file:

Choose View > Search Results.

The Edit Domain page of the Domain Designer appears.

The Domain Designer opens to the Tables tab. The tabs of the designer show the design settings for this Domain that you can export to XML.

The server validates the design before exporting the XML file. If errors are found, you can cancel the export. For more information, see section 6.4.10, “Domain Validation,” on page 156.

Working With a Design File

The relationship between item definitions, column definitions, and actual database columns is the essence of the Domain itself and must be maintained when editing the design file. In order to be usable when uploaded to a Domain, a design file must meet the following conditions:

•    It must be well-formed XML.

This means that all syntax, spelling, and punctuation is correct so that the file contains a hierarchy of elements, attributes, and content.

•    It must be valid with regards to the XML schema.

The XML schema defines element and attribute names that are allowed and how they are nested to create a hierarchical structure. This ensures that the elements and attributes are the same ones with the same meaning used by JasperReports Server. The XML schema of a Domain design is given in the XSD file is located in:

<install-dir>/samples/domain-xsd/schema_1_0.xsd

•    The design file must be internally consistent and define all the necessary elements of a Domain design.

These are constraints that cannot be expressed in the XSD file because they are outside the scope of an XML schema.

•    The tables and columns in the design must be consistent with their external definition in the data source of the Domain.

The design must references valid table and column names in the data source; in particular, table names for a design based on an Oracle RDBMS must include the schema name. The data source also defines the datatype of a column, and the design must use that column accordingly. As a result, a design file is specific to a given data source and most likely fails when used in a Domain with a different data source.

In addition, the more complex elements of a design file have further constraints:

•    SQL queries for a derived table must be valid with respect to the JDBC driver for the data source. Also, the tables and columns in the query must exist in the data source, and the columns in the results must match those declared in the design.

•    Expressions for filters and calculated fields must be valid programmatic expressions in a local format called Domain Expression Language (DomEL). This format is documented in section The DomEL Syntax.

As with any XML file, a design file is plain text and can be edited in any text editor. The server exports well-formatted XML, and if you want to make only a few changes or simple additions, a text editor is sufficient. For editing the content of the design file, a specialized XML editor ensures that the design file is well-formed, so you don’t introduce other errors. If you want to make structural changes or write a design file from scratch, use an XML editor that understands the XML schema in the schema_1_0.xsd file. By loading both the XML and XSD files, this type of XML editor lets you insert elements and attributes only in the places they are allowed to ensure that the design file is valid.

However, no editor can enforce the internal and external constraints on a design file. The following section explains all of the possible elements and attributes of an XML design file and the various constraints you must maintain on each of them.

Structure of the Design File

This section explains each of the XML elements and attributes in a design file and how they relate to the settings in the Domain Designer. The sample XML code is taken from the example Domain created in 6.2, “Example of Creating a Domain,” on page 138, although some elements have been added to show structures that did not appear in the example.

The top-level container elements of a design file are:

•    schema

•    itemGroups

•    items

•    resources

The following schema representation shows the top-level structure of the design file:

•    schema – The outer-most container element of a design file.

When exported from the Domain Designer, the schema element includes the xmlns and version attributes.

•     The xmlns attribute specifies an XML namespace for all element names.

This string must be unique to Jaspersoft, but it does not correspond to a valid URL. For more information, see http://www.w3.org/TR/REC-xml-names.

•     The version attribute gives the version of the XSD used to create this design file.

•     The schemaLocation attribute is often added by XML editors to locate the XSD file.

•    itemGroups – Contains all the sets and items within sets in the Domain.

Along with items, this element corresponds to all the sets and items defined on the Display tab of the Domain Designer. Therefore, itemGroups and items define what users see when they create a report based on this Domain. The sets and items defined under itemGroups and items must be internally consistent with the tables and columns under resources.

•    items – Contains all the items that are not within sets.

These correspond to the items at the root level of the Display tab. When all items are contained in sets, this element is absent.

•    resources – Contains all the definitions in the design:

•     columns

•     tables

•     derived tables

•     joins

•     calculated fields

•     filters

Five definitions in the design correspond to definitions on tabs of the Domain Designer:

Because the elements under resources refer to database objects, they must be externally consistent with the data source intended for this Domain.

Even though the itemGroups appear first in the design file, this section documents the resources first so that design elements are presented in the same order as the tabs of the Domain Designer.

The resources element contains the jdbcTable and jdbcQuery elements to represent database tables and derived tables, respectively. Join trees are represented as a jdbcTable element with additional contents to define the joins.

Representing Tables in XML

In the Domain Designer, you can select only entire tables, not individual columns. In the XML design file, however, you can specify any subset of columns that you need.

•    jdbcTable – Represents a table or a copy of a table in the data source. A Domain design must reference all the tables that it needs to access. The jdbcTable element is also used to describe join trees. All three attributes of jdbcTable are required:

•     datasourceId – Alias that identifies the data source. When created in the Domain Designer, this is the data source alias defined in section 6.4.3, “Derived Tables Tab,” on page 148. When creating a design file, this alias may be any name you choose, but it must be identical for all tables and derived tables. When uploading the file, the datasourceId automatically becomes the alias associated with the data source defined for the Domain.

•     tableName – Literal name of the table in the data source. For a Oracle RDBMS, the table name includes the schema name in the form schema_name.table_name.

•     id – Table ID that is used to reference the table in the Domain design. If you copy a table in order to join it multiple times, each has the same datasourceId and tableName but must be given a different id.

•    fieldList – A container for field elements. Required on jdbcTable elements because it would not make sense to have a table without columns in the Domain design. You must reference all the columns that you use in the Domain.

•    field – Represents a column of a table in the data source. All the columns that you want to reference in the Domain defined with this element. Both attributes of field are required:

•     id – Literal name of the column in the data source. As in the JDBC model that the data source is based on, the id must be unique within the jdbcTable, but not necessarily within the Domain.

•     type – The Java type of the column, as determined from the data source by the JDBC driver. The type is one of the following:

Unless you know the name and type of every column in the data source, it is often easier to select and export tables from the Domain Designer. The Domain Designer accesses the data source to find the names of all tables and columns, as well as their types. You may then export the XML design file with this information and refine your design.

Representing Derived Tables in XML

Derived tables are similar in structure to tables, but they use the jdbcQuery element which contains the query element:

•    jdbcQuery – Represents a derived table that is the result of an SQL query.

Both attributes of jdbcQuery are required:

•     datasourceId – Alias that identifies the data source for the Domain. The alias designates the data source to be queried. In the design file, this alias must be identical for all tables and derived tables.

•     id – Table ID that is used to reference the derived table in the Domain design. Any reference to the id of a jdbcTable may also reference the id of a derived table.

•    fieldList – A required container for the field elements.

When the derived table is created in the Domain Designer, the set of columns corresponds to the selection of columns in the query result on the Derived Tables tab.

•    field – Represents a column in the results of the query.

Only the columns represented by a field element are available for reference by other elements. The columns of a derived table must be among those returned by the query.

•     id – Literal name of the column in the query result. If the query gives an alias to the column in a SELECT AS statement, the id is the same as the alias. The id must be unique within the query results, but not necessarily within the Domain.

•     type – The Java type of the column, as determined from the data source by the JDBC driver.

•    query – The SQL query sent to the database server.

Any valid SQL can be used, as long as the columns in the result match the id and type of all field elements of the derived table given in the fieldList. If you add a derived table in the Domain Designer, it runs the query and generates columns based on the result set. You could then export the design file containing the generated column list. The syntax for a valid SQL query does not include a closing semi-colon (;).

The following sample query selects some columns, including a field calculated in the SQL, from the result of a join with sorted results. In this case, only exp_date, store_id, amount, currency, conv, and as_dollars can be exposed as columns of this derived table.

A derived table provides an alternative way to create joins and calculated fields. Here are some things to keep in mind when deciding how to implement the Domain:

•    Unlike joins defined in the Domain, joins within a derived table are not restricted to equality comparisons when uploaded to the Domain Designer. For more information, see section Representing Joins in XML.

•    Unlike calculated fields in DomEL, calculated fields within derived tables may use any function call recognized by the RDBMS. See section The DomEL Syntax for restrictions on function calls in calculated fields.

•    The Domain mechanism applies filters, aggregation, and joins to derived tables by wrapping the SQL in a nested query, which may be less efficient on some databases than the equivalent query generated for a non-derived table.

Representing Joins in XML

A join is represented in the design file as a special jdbcTable element. It contains the joinInfo and joinedDataSetList elements to define the actual joins. It also contains a list of columns that are exposed through the Domain, each with a prefix on the field id attribute to identify its originating table. The Domain Designer automatically exposes all columns of all tables in a join, but in the design file you only need to specify those you want to reference elsewhere in the Domain.

•    jdbcTable – Represents the results of one or more joins between tables. If not all tables are joined together, there is one jdbcTable representing each join tree and containing only the join expressions for that tree. To define the join, the attributes and elements have a different meaning than for a regular table.

•     datasourceId – Alias that identifies the data source for the Domain. The alias designates the data source where the join is performed. In the design file, this alias must be identical to that for all tables and derived tables.

•     id – ID that is used to reference the join results in the Domain design. In the Domain Designer, each join tree is automatically given the ID JoinTree_n, where n is a sequential number. In the design file, you can give the join any name, as long as it is unique among all other tables and derived tables.

•     tableName – Literal name of the first table in the join. This table name is combined with those in the joinInfo and joinedDataSetList to define the join expressions. For an Oracle RDBMS, the table name includes the schema name in the form schema_name.table_name.

•    fieldList – A required container for the field elements in the join tree.

•    field – Represents a column in the join tree. The table of each column is identified by a prefix on the id attribute. When created in the Domain Designer, the design file includes every column in every table of the join. When you create your own design file, only the columns you want to reference are needed. Both attributes of field are required:

•     id – Field ID composed of the ID of the table in the design and the literal name of the column in the data source. The syntax is table_ID.field_name.

•     type – The Java type of the column, identical to the type in its table definition.

•    joinInfo – Gives the table ID and alias for the table given by the tablename attribute. The table ID and alias are used as the first table in the join definition. This element and its two attributes are required even if they are identical.

•     alias – Alternative name within the join expression for the table identified in referenceId. By default, the alias is the same as the referenceID, but you may supply a true alias in handwritten design files. If you use a distinct alias, you must be careful to use the alias throughout the joinString element that defines the join.

•     referenceId – Table id of the table within the design whose data source name is given in tableName.

•    joinedDataSetList – Container for the list of join statements.

•    joinedDataSetRef – Container for the join statement.

•    joinString – A string expressing an SQL join statement in the following format:

join_type join table_ID table_alias on join_expression

Where:

•     join_type – One of right outer, left outer, or full outer. Inner join is the default if no join type is specified.

•     table_ID – The ID of a table within the design.

•     table_alias – Alternative name to use for the table_ID within the join expression. By default, the alias is the same as the table_ID, but you may supply a true alias in handwritten design files.

•     join_expression – Expression that compares the columns on which the join is made, in the form

left_table_alias.field_name == right_table_alias.field_name

The order of joinedDataSetRef elements is important. The first one must contain a join expression between the table_alias it defines and the alias in the joinInfo element. The subsequent ones may only reference the table_alias they define and ones that appear in joinString elements before them.

Representing Calculated Fields in XML

Calculated fields are defined as regular columns in a field element with an additional attribute. Calculated fields that rely only on columns of the same table appear in jdbcTable for that table, as well as in the join tree. Calculated fields that rely on columns from different tables that are joined appear only in the join tree.

The following example shows the XML for a calculated expression in the accounts table. Because it references only the columns of accounts, it appears in that table and in the join tree.

The attributes of the field element have a different meaning when defining a calculated field:

•    dataSetExpression – Expression which calculates a value based on other columns. The syntax for the expression, including how to reference columns, is documented in section The DomEL Syntax.

•    id – User-defined name of the calculated field. The format of the id is dependent on how the calculated field appears in the design file:

The field appears in the table and the id is a simple column name.

•    type – The Java type of the value calculated by the expression, for example java.lang.String. This type must be compatible with the result of the DomEL expression and among the JDBC-compatible types listed on See "type – The Java type of the column, as determined from the data source by the JDBC driver. ".

A special case of a calculated field occurs when the expression does not reference any column names. The calculated field always has the same value and is said to be a constant. In the Domain Designer, constant fields are automatically grouped in a table named Constant and may be used in other calculated fields, filters, or even as an item. Because constant fields are not dependent on any column values, they may be used in any join tree and exposed to the user along with the items from any join tree. When editing a design file, you must treat constant calculated fields in the same way.

Representing Filters in XML

Filters are defined as optional filterString elements inside of jdbcTable and jdbcQuery elements. They impose a condition on any results that are returned for that table, query, or join tree, thereby limiting the number of rows returned when accessing the data source. Whereas other settings mainly determine which columns are available for use in a report. A filter determines which rows are available when running the report.

•    filterString – Expression which evaluates to true or false when applied to each row of values in the data source. The expression refers to columns using their id attribute. Thus, a filter on a table or derived table refers to the simple column name, but a filter on a join tree refers to the table_ID.field_name. The full syntax for the expression is documented in section The DomEL Syntax.

For example, the following filters are defined in the example Domain on page 143:

Representing Sets and Items in XML

Now that all the table and field IDs have been defined, look at the definitions of sets and items that are exposed through itemGroups and items elements at the top of the Domain design file. The itemGroups and items elements are equivalent to the selection of sets and items on the Display tab of the Domain Designer. They create a hierarchy of sets, subsets and items and hold attributes that define all the properties available on sets and items. For a description of each possible property, see section 6.4.8, “The Properties Panel,” on page 153. The following example shows two levels of sets, with items inside each level as well as at the root, outside of any set.

•    itemGroups – A container for itemGroup elements.

•    itemGroup – Represents a set. The itemGroup element may contain an itemGroups element, an items element, or both, representing its subsets and items, respectively. The attributes of itemGroup are the properties of the set it represents:

•     id – The unique identifier of the set among all set and item IDs. This attribute is required.

•     label – The set’s name, visible to users of the Domain. If the label is missing, the Ad Hoc Editor displays the id.

•     description – The optional description of the set, visible to users as a tooltip on the set name in the Ad Hoc Editor.

•     labelId – The internationalization key for the label in the Domain’s locale bundles.

•     descriptionId – The internationalization key for the description in the Domain’s locale bundles.

•     resourceId – A reference to the table on which the set is based. This attribute is required, but it has no meaning on a set and is not significant in the design.

When an internationalization key is defined for the label or description, the label or description is replaced with the value given by the key in the local bundle corresponding to the user’s locale. For more information, see section Locale Bundles.

•    items – A container for item elements.

•    item – Represents an item. The attributes of item are the properties of the item it represents:

•     id – The unique identifier of the item among all set and item IDs. This attribute is required.

•     label – The item’s name, visible to users. If the label is missing, the Ad Hoc Editor displays the id.

•     description – The optional description of the item, visible as a tooltip on the item name in the Ad Hoc Editor.

•     labelId – The internationalization key for the label in the Domain’s locale bundles.

•     descriptionId – The internationalization key for the description in the Domain’s locale bundles.

•     resourceId – A reference to the column on which the item is based. This attribute is required because it defines the connection between what the user sees and the corresponding data in the data source. The resourceId has the form table_ID.field_ID. When the item refers to a column in a join tree, the resourceID corresponds to jointree_ID.table_ID.field_name because the field ID in a join tree includes the table ID.

•     defaultMask – A representation of the default data format to use when this item is included in a report. The possible values for the defaultMask depend on the type attribute of the column referenced by the resourceId. See the table below.

•     defaultAgg – The name of the default summary function (also called aggregation) to use when this item is included in a report. The possible values for the defaultAgg depend on the type attribute of the column referenced by the resourceId. The following table gives the possible data formats and summary functions based on the column type. The appearance columns show the equivalent setting in the properties table of the Display tab:

The following example shows the use of the itemGroup and item elements to represent the sets and items from section 6.2, “Example of Creating a Domain,” on page 138. The design file was exported from the Domain Designer.

Labels and descriptions may contain any characters, but the ID property value of both itemGroup and item elements must be alphanumeric and not start with a digit.

Uploading a Design File to a Domain

After you have modified an XML design file, you can upload it through the Add New Domain page. Alternatively, you can create a new Domain based on a modified file or even on a design file created from scratch.

To upload an XML design file:

Choose View > Search Results.

To create a new Domain, select Create > Domain from the main menu.

The Domain appears in the Data and Design page of the Edit Domain or Add New Domain dialog. If you are creating a new Domain, you must select a data source before you can proceed.

The server validates the uploaded XML file. If there are syntax or semantic errors, the current design is not replaced. You can make changes to the XML file and upload it again until there are no errors.

After the design appears correctly in the Domain Designer, you may make further modifications on any of the tabs.