The following chapters describes the various things to know when migrating to version 8.x of i-net Crystal-Clear. Version 8.x included various restructuring that might lead to minor incompatibilities with older applications.
i-net Crystal-Clear and i-net DesignerXML version 8.x require at least Java 5. If your application runs with an older version of Java (version 1.4.2 or earlier), you should migrate your application to Java 5 before migrating to version 8 of i-net Crystal-Clear.
The following list includes the methods that are deprecated in version 8 and should no longer be used. Please consult the Javadoc of the individual methods for information on which newer methods to use instead.
The following methods had been deprecated for longer than 2 major versions and have now been entirely removed in version 8 of i-net Crystal-Clear.
Starting in version 8 of i-net Crystal-Clear, crystalclear.properties are no longer used. All configurations are instead stored in the operating system's preferences – where these are located depends on the operating system. In Microsoft Windows, i-net Crystal-Clear uses the Windows registry, while on Unix systems the preferences are stored in the file system (/etc/.java, or ~/.java). Because of this change, it is now possible to comfortably store and manage configurations in a central place, you no longer have to work with various crystalclear.properties files.
All existing crystalclear.properties files can be imported into a preferences scope (System, User, Temporary) with the new Configuration Manager. Note that if i-net Crystal-Clear will be started as a service, it is recommended to use the System scope since the i-net Crystal-Clear service will most likely be running as a different user.
When importing a crystalclear.properties file, its settings are completely copied into the configuration. The database driver DLL-properties, however, must first be converted into data sources in order for them to be used in version 8. An additional dialog will show the choices for converting these properties and will offer a choice of data source configuration per database driver DLL. If no database driver DLLs are to be imported, the dialog can simply be canceled, otherwise you can skip the database driver DLLs you do not need by choosing “<do not import>”. Also, for each data source Text body, an individual scope can be set (System, User, Temporary), depending on the current read and write permissions. A context menu additionally offers help for the simple choosing of drivers and scopes. Please note that after this conversion of the properties, imported configurations do not contain the database driver DLL properties any more.
If you do not want (or are not able) to use the Configuration Manager GUI for importing your crystalclear.properties files, you can do the same via the command line. The program argument -importConfig will start the import process without displaying any window.
java -jar CrystalClear.jar -importConfig <name> <file>
In the argument <name> you must specify the scope and name of the configuration that is to be created, e.g. “System/Default” or “User/myConfig”. Only scopes “System” and “User” are allowed.
The argument <file> must contain the path to a readable and valid properties file, e.g. crystalclear.properties.
Please note that the import by command line will not convert any DLL-properties to data sources. This can only be done by using the Configuration Manager.
You can store your configurations in one of three different scopes: the System scope, the User Scope, and the Temporary scope. What this means “behind the scenes” for the storage will depend on the operating system your platform uses.
The System scope is viewable by all users who have read access to system properties. On many systems, the System scope is only writable by administrators or users with system privileges. Typical uses of this scope would be for deployments on application servers which run as a different user than the normal user, and therefore could not see configurations stored in the User scope. It's also conceivable to store a system-wide scope for various different users in order to not have to create and configure multiple configurations for multiple users.
The User Scope is only visible to the user it belongs to. This means configurations stored in the User scope by user A will not be visible to user B. This scope is useful for situations where there is only one user on the system, since the user scope is almost always writable and readable by that user.
Storing configurations in this scope will cause the configuration to only work as long as the session runs. As soon as the Java VM is terminated, the configuration will be lost. These configurations are not stored in the Preferences, but are rather held in memory as Properties objects.
In order to choose which configuration you wish to use in i-net DesignerXML, select the menu point “File –> i-net Crystal-Clear Options”. Here you can create, edit, delete, copy, import, and export configurations, as well as choose the configuration you wish to use in i-net DesignerXML with “Activate”.
The i-net Crystal-Clear Listener will search for its configuration in the following order. As soon as a configuration is found, it is used until the configuration is changed in any way. In this case, the configuration is reloaded as soon as a new report is requested.
If none of the above configurations could be found, a temporary, empty configuration is created and set. Note that this configuration will only have default configuration values and no license key, so it will not be possible to display reports with a Listener running with this temporary configuration.
To change the configuration a Listener is using once it is running, you can use the API of ConfigurationManager, e.g. ConfigurationManager.setCurrent(Configuration).
The i-net Crystal-Clear servlet will search for its configuration in the following order.
If none of the above configurations could be found, a temporary, empty configuration is created and set. Note that this configuration will only have default values and no license key, so it will not be possible to display reports with a servlet running with a temporary configuration.
Starting with version 8 of i-net Crystal-Clear, it is no longer necessary to restart the Listener or application server after changing a configuration property – i-net Crystal-Clear automatically detects the change in the configuration and reloads the configuration the next time a report is requested.
There are two ways to change a configuration:
The Configuration Manager can be viewed either from within i-net DesignerXML (File –> i-net Crystal-Clear Options) or by starting it with the command “java -jar CrystalClear.jar”. From within the configuration manager it is possible to create, edit, delete, and rename configurations. Remember that unless a specific configuration is manually set as default, i-net Crystal-Clear will look for a configuration called “Default” in the user or system scope.
For information on changing properties programmatically, see the API documentation to the classes ConfigurationManager and Configuration. To get started, here is a simple code sample for setting a configuration and then changing its properties:
ConfigurationManager manager = ConfigurationManager.getInstance(); Configuration c = manager.get(Configuration.SCOPE_USER,”myconfig”); c.put("propertyXY”,”myvalue”); ... manager.setCurrent(c);
In version 8 of i-net Crystal-Clear, the mapping between driver dll name and JDBC driver properties in crystalclear.properties were completely replaced by the data sources which were introduced in version 7. A data source describes all settings for a database connection. The saving of the password is optional. Data sources are based on a similar concept to ODBC data sources.
The data sources can be edited with the Data Source Manager. This manager can be opened in i-net DesignerXML using the menu point “Database | Data Source Manager”, or with the Configuration Manager (the button on the bottom left). In the data source manager there are 3 scopes in which the data sources can be stored, just like with the configuration manager.
Old report templates (from before version 7) and Crystal Reports templates still have the old dll alias stored in the report. In order to open and run these reports, you will need pseudo data sources. These are created by the setup or when importing old crystalclear.properties. It is not possible to create reports on these pseudo data sources (such as pdssql.dll).
The URL parameters such as “dll”, “host” and “catalog” only will work for old reports. The new parameter datasource works for all templates.
If this templates are saved or opened in the designer, a temporary data source is created and is stored as a copy in the report template.
For transferring to other systems, the data sources can be exported and imported from the data source manager. This is also possible using the public API of the class com.inet.report.config.datasource.DataSourceConfigurationManager.
The older Java report viewer of version 6 and older is no longer supported. If you did not migrate to the new Java report viewer in version 7, you will have to do so now.
The i-net Crystal-Clear runtime consists of the following libraries:
Libraries of optional components:
The following libraries are required if you like to embed the i-net Crystal-Clear report engine into a Java application or Java Servlet:
If you use scheduler functionality then it is also necessary to add the files activation.jar and mail.jar to the class path.
To get these files execute the setup and install the Report Server - Runtime Library in a temporary directory.
The Chart has an entirely new API, the old one is deprecated.
The property “Compatibility Level” defines whether Charts will be converted during report loading so that they can be accessed using the new Chart API (see the class com.inet.report.Chart2).
If the value is set to “compliant to version 7.x” the old Chart-API (class Chart) can be still used for reports saved with i-net DesignerXML versions previous to version 8. You can combine also both Chart API's by using the ChartConverter class. See the following example code:
// The engine was initialized with a report with a chart in the first section of report header Section section = engine.getArea(Engine.AREA_TYPE_REPORT_HEADER).getSection(0); // Returns the old chart element Chart chart = (Chart)section.getReportElement(0); // Using the old API chart.setStyle(Chart.BAR2D_STYLE); // Converts the old chart to new, the old chart will be replaced with Chart2 ChartConverter.replaceChart(chart); // Returns the new chart element Chart2 chart2 = (Chart2)section.getReportElement(0); // Using the new API BarPlot plot = (BarPlot)chart2.getPlot(); plot.setStyle(BarStyle.BAR2D_STACKED);
In contrast, if the value is set to “compliant to version 8.0 or later” then Charts can only be accessed using the new Chart-API (class Chart2).
Starting in version 8 of i-net Crystal-Clear, crystalclear.properties are no longer used. All configurations are instead stored in the operating system's Preferences (e.g. the Registry when under Windows). To edit and manage your configurations, the easiest way is to use the Configuration Manager, by running the CrystalClear jar file (e.g. java -jar CrystalClear.jar).
See Chapter i-net Crystal-Clear Configuration in Version 8 for more information.
Most likely the configuration with your license key is not being used by your i-net Crystal-Clear installation.
See Chapter Choosing a configuration to use... for information on how to determine which configuration is to be used by your i-net Crystal-Clear installation.
The database dll properties were entirely replaced by data sources in version 8 of inet Crystal-Clear. To configure your database connections, use the Data Source Manager. See Chapter Datasources and Configuration of Driver DLL's for more information on this.
Note that importing old crystalclear.properties files will cause the dll properties to be imported into data sources. See Chapter Importing old crystalclear.properties for more information on importing crystalclear.properties files.
Version 8 of i-net Crystal-Clear supports an entirely new Chart API with many new features and an improved look to the charts. It is highly recommended to switch to the new Chart API to take advantage of these new features.
If you want to, however, you can make use of the “Compatibility Level” configuration property, and/or the ChartConverter class. See Chapter New Chart API for more information on this.
