Configuring Domains

Advanced uses of Domains may consider these configurations:

When you use Domains with certain database constructs, you may need to configure JasperReports Server:

Disabling the Domain Validation Check

By default, JasperReports Server validates a Domain against its data source to ensure that the Domain design maps properly to the underlying tables. This validation occurs when a Domain design file is uploaded to the server. If your data source is very large and complex, this validation can take time. If the validation takes too long, you can disable it. In this case, JasperReports Server assumes the Domain design is valid, and simply uploads it without the check.

Setting the Level of Referential Integrity

Referential integrity is the verification process that occurs when opening an Ad Hoc view or a report that is based on a Domain. The server checks that all fields and measures referenced by the view or the report match those defined in the Domain. This ensures that out-of-date views or reports cannot be run if they rely on items in the Domain that were modified or removed.

In practice, when you modify a Domain to remove fields or measures, you must also modify all Ad Hoc views that depend on those fields and measures, and you must regenerate any reports based on those views. In case you don't, referential integrity will give an error so that the user knows why the report did not run, instead of failing at runtime or showing empty data. When opening an Ad Hoc view that has similar referential integrity errors, the server displays a list of missing fields and measures and prompts you to removes the items so the view is coherent when it opens.

However, in cases where Domain security makes a field unavailable to a user, this will also be detected as a referential integrity error upon opening a view or running a report. Some views and their corresponding reports may be designed for multiple users with different security access to data, and you intend to display the report with blank or zero in place of certain data. In such cases, you should change the default setting for referential integrity so that users can open views and run reports without causing an error.

Optimizing Snowflake Schema Joins

When creating a Domain on top of a snowflake schema, the default joins generated when using the Domain in the Ad Hoc Editor may take a long time and include dimensions not used in the report. For example, a schema with over a hundred dimension tables mostly connected to a subset of 5-10 fact tables may cause such behavior. The following setting can be enabled to optimize the joins generated for such a snowflake database schema. The default setting has better performance in the more common cases with fewer tables.

Enabling Oracle Synonyms

By default, Domains can't access synonyms in an Oracle database. Settings to enable them vary depending on your application server. The settings shown here apply to Apache Tomcat. Your application server may require different values. Set the following property to enable Oracle synonyms on Tomcat. If you access your Oracle database through JNDI, you also need to configure the JNDI connection.

Be aware that the Oracle metadata service is significantly slower when synonyms are in scope.

Enabling CLOB Fields

Support for CLOB (Character Large Object) fields is dependent on your database and must be enabled manually. If you want to access CLOB fields in JasperReports Server, set the following options according to your database.

The Oracle JDBC driver implementation uses the CLOB JDBC type for CLOB fields.

<!--entry key="CLOB" value=""/-->

<entry key="CLOB" value="java.lang.String"/>

The MySQL JDBC driver implementation uses either the CLOB JDBC type, the LONGVARBINARY JDBC type, or both to represent CLOB fields, depending on their length.

<!--entry key="CLOB" value=""/-->
<!--entry key="LONGVARBINARY" value=""/-->

<entry key="CLOB" value="java.lang.String"/>
<entry key="LONGVARBINARY" value="java.lang.String"/>

Enabling Proprietary Types

JasperReports Server provides a JDBC-to-Java type mapping for all standard JDBC column types for use in Domains. However, some databases have proprietary types that you may need to map to a Java type with a special configuration. Some proprietary types, such as NVARCHAR2 for Oracle, are already mapped by default.

As a prerequisite, the proprietary type must be logically equivalent to one of following Java classes:

There are two ways to create a mapping for a proprietary type, as shown in the following table:

<entry key="NUMERIC" value="java.math.BigDecimal"/>

<entry key="OTHER">
    <map>
        <entry key="NVARCHAR2" value="java.lang.String"/>
    </map>
</entry>

Extending JDBC Type Mapping

Some database types are not even mapped to a JDBC type. In particular, Oracle uses TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE that must be mapped in order to appear in JasperReports Server. If there are other types in your database, you can override or extend the JDBC type mapping with the following configuration:

<entry key="-101" value="TIMESTAMP"/>
<entry key="-102" value="TIMESTAMP"/>

Accessing Materialized Views

Domains access tables and views by default, but some databases support other structures such as materialized views. These alternate table structures don't show up by default, but you can often configure Domains to display and access them.

If the JDBC driver for your database assigns a standard table type identifier to the materialized view, you can access it in Domains, Ad Hoc views, and reports. To find the table type, use a JDBC client such as the SQuirreL tool to view your database schema. In SQuirreL, use the “Objects” tab to browse the tables and views organized by table type. Look for your materialized view and note its table type.

The table type values are defined in the DatabaseMetaData.html.getTables() documentation. When you know the string corresponding to your table type, add it to the following configuration value:

Modifying Domain Calculated Field Variable Behavior

The property resolveDomainCalcFieldVariableInAdvance included in WEB-INF/applicationContext-adhoc-dataStrategy.xml for bean id="commonDomainDataStrategy" allows you to calculate a domain calculated field in two ways. The default value is set to false, and the behavior overrides the lookupExpression(Variable var) in ColumnCalculation.

For example, if you have a domain calculated field expression such as “coverage / allowance”, it will translate to sum(coverage) / sum(allowance) instead of sum(coverage / allowance).

You can change the default domain calculated field variable behavior to use a sum aggregation (the original behavior prior to JasperReports Server 7.8) with the following configuration: