When you open an existing Domain with the Domain Designer, the Domain Designer reads the current state of the database and uploads it to the design. The Domain Designer does not detect changes to the database schemas, tables, and columns in real-time, but it will detect them the next time you open the Domain in the Domain Designer. The data source or structure can change for any of the following reasons:
| • | You manually change the JasperReports Server data source by selecting Replace Data from the menu. |
| • | The selected data source or a schema uses an attribute and the attribute changes or you log in with a different attribute value. |
| • | The structure of the underlying database or other data source has changed. For example, if a table or column is added to or deleted from the database, it is detected the next time you open the Domain Designer. |
Missing schemas, tables, or columns in the new or updated data source are automatically deleted from the design along with any elements, such as calculated fields, joins, or sets, that depend on them.
Because the Domain design relies extensively on the data source, changing the data source makes sense only in certain cases. Examples include:
| • | Switching to a data source with a different schema but with the same tables, for example, when moving from staging to production. |
| • | Switching from a regular data source to a virtual data source that contains the original data source. In this case, JasperReports Server attempts to locate the original data source inside the virtual data source and create the correct prefix. Derived tables and calculated fields are not preserved. |
| • | Switching from a virtual data source to one of the underlying data sources. In this case, any resources that are not in the selected data source are deleted along with any dependent information, such as derived tables, joins, calculated fields, or labels that depend on the deleted resources. |
Before you select a new data source manually or use attributes to specify data sources and/or schemas, do your best to ensure that the schema structures are identical. You should also export your Domain design before changing the data source manually.
Selecting a New Data Source
| If you have modified your database tables, fields, or schema, use Replace Data and select your current database to upload the changes. |
To select a new data source:
| 1. | Select Replace Data… from the |
| 2. | Select the data source you want in the Choose Data dialog, and click OK. |
The Select Schemas to Map dialog appears. This dialog shows the schemas used by your Domain on the left, and the schemas available in the data source on the right.
Selecting schemas to map |
|
| If you are switching between a schemaless data source (such as MySQL) and a schema-based data source (such as Oracle), the dialog is different, as follows: | • | If the original data source is schemaless and the new data source supports schemas, the Current Schemas list is omitted. Select a new schema from the available schemas. | | • | If the original data source has schemas and the new data source is schemaless, the New Data Source Schemas list is omitted. Select one of the schemas in your Domain to use for the new data source. In addition, if your Domain has only one schema and you are selecting a schemaless data source, the schema is mapped automatically and you do not see this dialog. | |
| 3. | To associate an existing schema in your Domain with a schema in the data source: |
| a. | Select the schema in the Domain in the Current Schemas list. |
| b. | Select the schema you want to replace it with in the New Data Source Schemas list. |
| c. | Click |
The schemas are associated. A number is added after the schema name to make it easier to manage multiple schemas.
| 4. | Repeat the previous step for each schema you want to map. If you want to unlink two schemas, click |
| 5. | Click Confirm to map the schemas. |
JasperReports Server retrieves the data structure from the data source and validates the Domain. If all the tables and columns in your Domain are found, the Domain Designer opens at the Data Management tab.
| 6. | If there are missing tables or columns, a warning dialog lists the affected components of your design. Click Delete Items to continue and delete all the items listed, or click Cancel to keep the original data source. |
Warning dialog for changing data source |
|
If you click Delete Items, JasperReports Server deletes all the displayed items. There may still be some errors you need to resolve before the Domain is valid.
Changes Due to Attributes
If you use attributes to define a database schema, a calculated field, or another Domain element, you may see the following when you log in as a different user:
| • | If a schema is missing, the Select Schemas to Map dialog appears. See Selecting a New Data Source for more information. This can happen because the attribute is no longer defined or because the attribute is defined but resolves to a non-existent schema. |
| • | If you use an attribute for the schema name and you later select a different schema in the Select Schemas to Map dialog, the design will always use that schema; the schema will no longer be attribute-based. |
| • | If any tables or fields are missing in the new data source or schema, JasperReports Server displays a warning dialog. Clicking Delete Items deletes the missing tables and columns and any Domain design elements that depend on them. |
| • | If an attribute is not defined or does not resolve to a usable value, JasperReports Server displays a warning dialog. Clicking Delete Items deletes any Domain design elements that depend on the undefined or invalid attribute(s). |
| If you use an attribute in your data source definition, you may see similar problems. Data source attributes are defined outside the Domain Designer. See the section on defining attributes in the JasperReports Server Administrator Guide for more information. |
Updating an Existing Data Source
To update a Domain after changes to the underlying data structure, do one of the following:
| • | Close the Domain Designer then open the Domain for editing again. |
| • | Select Replace Data… from the |
Keep the following points in mind regarding data source updates:
| • | You will be prompted to remap any schemas no longer found in the database. |
| • | If your design uses tables and columns that are no longer found in the data source, JasperReports Server displays a warning dialog. Clicking Delete Items deletes the missing tables and columns and any Domain design elements that depend on them. |
| • | New schemas, tables, and columns appear in the Data Structure panel on the Data Management tab. JasperReports Server has no way to automatically map schemas, tables, or columns that have been added since the last time you edited the Domain. |
| • | To add a new column to the Domain, move its table to Selected Tables. If the table is already selected, the column is automatically available. Table selection works only with entire tables. |
Recommended Comments
There are no comments to display.