Advanced uses of Domains may consider these configurations:
| • | Disabling the Domain Validation Check |
| • | Optimizing Snowflake Schema Joins |
| • | Configuring Domain Dependency Behavior |
When you use Domains with certain 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 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.
To disable the validation edit the following configuration file:
| Configuring Domain Validation Check | ||
| Configuration File | ||
| .../WEB-INF/applicationContext-semanticLayer.xml | ||
| Property | Bean | Description |
| skipDomainDatabase | slConfig | Set this property to TRUE to disable the 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 uses 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 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.
| Configuring Domain Join Optimization | ||
| Configuration File | ||
| .../WEB-INF/applicationContext-semanticLayer.xml | ||
| Property | Bean | Description |
| specialOptimizationOn | graph | 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's 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's used in any filter, or if it's 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 ensures 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-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. |
You should turn this setting off only when a field is deleted from the data source, and the Domain can't be modified because the field is being used by some dependencies. You then need to manually edit the dependencies so they don't 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 previous 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 | configuration | 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 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's deleted from a Domain while this setting is false. |
| Configuring Domain Dependency Additions | ||
| Configuration File | ||
| .../WEB-INF/applicationContext.xml | ||
| Property | Bean | Description |
| default | configuration | When this setting is true(the default), AND defaultDomainDependents When this setting is set to false OR defaultDomainDependents |
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 Oracle Synonyms | ||
| Configuration File | ||
| .../WEB-INF/applicationContext-semanticLayer.xml | ||
| Property | Bean | Description |
| includeSynonyms | jdbcMeta | Set the value to true: <value>true</value> |
| Configuration File | ||
| .../META-INF/context.xml | ||
| Property | Bean | Description |
| accessToUnderlying | <Resourcename= | If you use JNDI, add the following property: accessToUnderlying |
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.
| CLOB Support for Oracle | ||
| Configuration File | ||
| .../WEB-INF/applicationContext-semanticLayer.xml | ||
| Property | Bean | Description |
| jdbc2JavaType | jdbcMeta | This property contains a map of database field types to Java types. Find the line for CLOB that is commented out: Modify it as follows: |
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 | jdbcMeta | This property contains a map of database field types to Java types. Find the following lines: And modify them as follows: |
| | Due to a limitation, CLOB and NTEXT fields cannot be sorted or compared in a query. For example, trying to add a CLOB field as a crosstab column with domain query optimization enabled will result in an error message. |
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:
| 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 | jdbcMeta | If your proprietary type is not already defined in this file, you can add it:
<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:
| Extending JDBC Type Mapping | ||
| Configuration File | ||
| .../WEB-INF/applicationContext-semanticLayer.xml | ||
| Property | Bean | Description |
| codeToJdbcType | jdbcMeta | 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"/>[/code] 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 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:
| Accessing Materialized Views | ||
| Configuration File | ||
| .../WEB-INF/applicationContext-semanticLayer.xml | ||
| Property | Bean | Description |
| tableTypes | jdbcMeta | Uncomment the JDBC table type corresponding to the materialized view or other table structure in your databases, for example: <value>LOCAL TEMPORARY</value> |
Recommended Comments
There are no comments to display.