Configuring Domains

For advanced uses of Domains, there are some configurations you may consider:

Disabling the Domain Validation Check
Optimizing Snowflake Schema Joins
Configuring Domain Dependency Behavior

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

Enabling Oracle Synonyms
Enabling CLOB Fields
Enabling Proprietary Types
Extending JDBC Type Mapping
Accessing Materialized Views

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 be time consuming. 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. You can disable the validation by editing the following configuration file:

Configuring Domain Validation Check

Configuration File

.../WEB-INF/applicationContext-semanticLayer.xml

Property

Bean

Description

skipDomainDatabase
Validation

slConfig

By default, this property is set to FALSE; in this case, JasperReports Server validates Domain designs against their data sources. Set it to TRUE to disable this validation check.

If the tables and fields referenced in the Domain design don’t exist in the data source when skipDomainDatabaseValidation is set to TRUE, the Domain wizard won’t detect the problem, but the Choose Data wizard returns errors when your end users work use the Domain.

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 that are 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 less tables.

Configuring Domain Join Optimization

Configuration File

.../WEB-INF/applicationContext-semanticLayer.xml

Property

Bean

Description

specialOptimizationOn

graph
Operations

The default setting of false handles typical cases of Domains based on 10-100 tables. For snowflake schemas that typically have 100 or more tables, or for database topologies that cause slow join performance in Ad Hoc views, set this property to true to optimize the joins in the Ad Hoc editor.

Configuring Domain Dependency Behavior

When modifying a Domain that is already in use by Ad Hoc views, JasperReports Server checks to see if any of these dependent views are affected. For example, if an Ad Hoc view uses a field, it should not be deleted from the Domain. However, if that field is not in use by any dependent view, it can be removed from the Domain, and from the list of fields in every view.

For dependency purposes, a field is "in use" by an Ad Hoc view if that field appears in the display manager (in any row, column, or group), if it is used in any filter, or if it is used in any calculated field formula, whether the calculated field is in use or not.

When modifying fields in a Domain, JasperReports Server always checks all views that depend on the Domain and always notifies the user of any fields in use. There are two settings to configure the Domain dependency behavior after the check:

defaultDomainDependentsBlockAndUpdate - This setting turns on or off the behavior that ensures Ad Hoc views remain consistent with their Domains. When on, it ensure consistency by either blocking Domain changes that affect fields in use by any dependencies, or by updating the dependencies when there are no fields in use. When updating a dependency, it removes the field from the list of available fields (left-hand panel in the Ad Hoc editor). When off, it allows changes to Domains that will cause errors in any dependent view. If a field is in use by a view, and this setting is off and allows the Domain to delete that field, the view will cause an exception when opened. If a field is not in use by a view, and this setting is off, the field is not removed from the list of available fields. If a deleted field appears in the list of available fields, the view can still be opened, but any action on that field will cause an error.

The only scenario for turning off this setting is when a field is deleted from the data source, and the Domain cannot be modified because the field is being used by some dependencies. You then need to manually edit the dependencies so they do not cause errors.

defaultAddToDomainDependents - This setting determines whether a field being added to a Domain is automatically added to each dependent Ad Hoc view. When on, any new field added to a Domain is added to the list of available fields in every dependent view. When this setting or the pervious setting is off, dependent views are not updated with new Domain fields.

Turning Domain Dependency Checks On or Off

Configuration File

.../WEB-INF/applicationContext.xml

Property

Bean

Description

defaultDomainDependents
BlockAndUpdate

configuration
Bean

The default setting of true means that Domain modification will be blocked if any Ad Hoc view uses the modified fields. If no Ad Hoc view uses the modified fields, the Domain modification proceeds, and all Ad Hoc views are updated with the change.

When set to false, Domain modifications are not be blocked when the field is in use, and dependent views are not updated when fields are not in use. Any Ad Hoc view may become unusable if it references a field that is deleted from a Domain while this setting is false.

 

Configuring Domain Dependency Additions

Configuration File

.../WEB-INF/applicationContext.xml

Property

Bean

Description

default
AddToDomainDependents

configuration
Bean

When defaultDomainDependents
BlockAndUpdate
is set to true AND this setting is true (the default), any field being added to a Domain is added to each dependent Ad Hoc view. It might not be possible to add a field to an Ad Hoc view if the field being added does not belong to the data island being used in the Ad Hoc view.

When defaultDomainDependents
BlockAndUpdate
is set to false OR this setting is false, dependent Ad Hoc views are not updated with fields that are added to a Domain. The new fields will not be available when a user opens a dependent Ad Hoc view.

Enabling Oracle Synonyms

By default, Domains cannot access synonyms in an Oracle database. Set the following property to enable them. If you access your Oracle database through JNDI, you also need to configure the JNDI connection.

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

Enabling Oracle Synonyms

Configuration File

.../WEB-INF/applicationContext-semanticLayer.xml

Property

Bean

Description

includeSynonyms
ForOracle

jdbcMeta
Configuration

Set the value to true:

<value>true</value>

Configuration File

...\META-INF\context.xml

Property

Bean

Description

accessToUnderlying
ConnectionAllowed

<Resourcename=
"jdbc/oracle"...

If you use JNDI, add the following property:

accessToUnderlying
ConnectionAllowed="true"

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, you must set the following options according to your database.

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

CLOB Support for Oracle

Configuration File

.../WEB-INF/applicationContext-semanticLayer.xml

Property

Bean

Description

jdbc2JavaType
Mapping

jdbcMeta
Configuration

This property contains a map of database field types to Java types. Find the line for CLOB that is commented out:

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

Modify it as follows:

<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.

CLOB Support for MySQL

Configuration File

.../WEB-INF/applicationContext-semanticLayer.xml

Property

Bean

Description

jdbc2JavaType
Mapping

jdbcMeta
Configuration

This property contains a map of database field types to Java types. Find the following lines:

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

And modify them as follows:

<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, such as NVARCHAR2 in Oracle. You can map these types with a special configuration.

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

java.lang.Boolean

java.lang.Byte

java.lang.Character

java.lang.Double

java.lang.Float

java.lang.Integer

java.lang.Long

java.lang.Short

java.lang.String

java.math.BigDecimal

java.sql.Date

java.sql.Time

java.sql.Timestamp

java.util.Date

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

Modify the generic mapping for NUMERIC types. By default, any numeric type that doesn’t match one of the other types is mapped to BigDecimal.
Create a secondary mapping under the special OTHER key, where the secondary key can be your custom type name.

Proprietary Database Type Mapping

Configuration File

.../WEB-INF/applicationContext-semanticLayer.xml

Properties

Bean

Description

jdbc2Java
TypeMapping

jdbcMeta
Configuration

To modify the generic mapping, edit this line:
<entry key="NUMERIC" value="java.math.BigDecimal"/>
Add any secondary key to the OTHER key, following this example:
<entry key="OTHER">
    <map>
        <entry key="NVARCHAR2" value="java.lang.String"/>
    </map>
</entry>
Java 1.6 supports java.sql.Types.NVARCHAR, therefore you should add it as a generic mapping, not under OTHER:
<entry key="NVARCHAR" value="java.lang.String"/>

Extending JDBC Type Mapping

Some database types are not even mapped to a JDBC type. In particular, Oracle uses the 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:

Extending JDBC Type Mapping

Configuration File

.../WEB-INF/applicationContext-semanticLayer.xml

Property

Bean

Description

codeToJdbcType
Mapping

jdbcMeta
Configuration

This property contains a map of database type codes to JDBC types. By default the codes for Oracle TIMESTAMP types are mapped:

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

Add or replace these entries to map additional types from your database.

Accessing Materialized Views

Domains access tables and views by default, but some databases support other structures such as materialized views. These alternate table structures do not 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 it's 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:

Accessing Materialized Views

Configuration File

.../WEB-INF/applicationContext-semanticLayer.xml

Property

Bean

Description

tableTypes

jdbcMeta
Configuration

Uncomment the JDBC table type corresponding to the materialized view or other table structure in your databases, for example:

<value>LOCAL TEMPORARY</value>

Version: 
Feedback