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.

XML is not the native format of the Domain design. The XML file is only a representation from which the design can be inferred. A design has additional constraints that are not mapped in the XML format.

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.