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 located in:
<webapp>/WEB_INF/lib/j-semantic-layer.x.x.x.jar
| • | 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 reference valid table and column names in the data source; in particular, table names for a design based on an Oracle RDBMS must include the database 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. For a virtual data source that combines data from data sources with different JDBC drivers, SQL queries are validated against Teiid SQL; for more information, see the Teiid Reference Guide under the Documentation link on the Jaspersoft Support Portal. 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 The DomEL Syntax. |
|
|
The design of a Domain is stored internally in the repository. The XML is only a representation from which the design can be inferred, and it may have some validity errors that cannot be detected. As a result, the Domain resource and the XML may not remain totally synchronized through several cycles of exporting to XML, editing, and uploading. For example, the Domain Designer sometimes renames the result of a join (JoinTree_1), which affects the security file. However, the Domain Designer also has limitations and cannot create some valid designs. For example, in a design file, you may select the columns of a table whereas you can only select whole tables on the Tables tab. Furthermore, the Domain Designer cannot read some valid designs, in which case you must not open the uploaded design file in the Domain Designer. These rare cases are documented in the following sections. |
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.
