Generating Diagrams in Design Studio Reports December 2015
Copyright 2015, Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
Contents 1. Introduction... 3 1.1 Prerequisites... 3 1.2 About Graphviz... 3 1.3 About the SVG Image File Format... 3 2. Installing the Report Diagram Processor Example... 4 2.1 About the Report Diagram Processor Example... 7 3. Downloading Graphviz... 8 3.1 Creating a System Variable for Graphviz... 8 4. Designing the Report... 9 4.1 Creating the Report Processor... 9 4.1.1. Declaring Extension Points... 9 4.1.2. About the ReportDiagramProcessor Class... 10 4.2 Generating a Diagram in SVG Format...11 4.2.1. About Graph Description Language... 11 4.2.2. About the ImageFileFactory Class... 13 4.2.3. About the createimagefile() Method... 13 4.2.4. About the createdotfile() method... 13 4.2.5. The creatediagramusingcommandline() Method... 14 4.3 Configuring Report Designs...15 4.3.1. Creating a Report Parameter in a Report Design... 16 4.3.2. Adding Images to a Report... 17 4.3.3. Adding a Script to the Image Report Item... 17 5. Testing Report Designs... 20
1. Introduction This white paper describes how to include diagrams in Design Studio reports. It describes how to: 1.1 Prerequisites Install the Design Studio Report Diagram Processor example and locate the sample code Use Graphviz to generate an SVG image file Configure a report design to include an SVG image file in a report Test report designs that include diagrams This white paper assumes that you are familiar with Design Studio reporting features and that you have reviewed the reporting information in: 1.2 About Graphviz Design Studio Developer s Guide: http://docs.oracle.com/cd/e57034_01/doc.73/e57039/toc.htm Design Studio Reporting Course, available at Oracle University The instructions in this white paper include how to use Graphviz to create diagrams in Design Studio reports. Graphviz is an open-source diagramming tool that converts textual diagram definitions into diagrams. For information about Graphviz, including the product documentation, see the Graphviz product web site: http://www.graphviz.org/ 1.3 About the SVG Image File Format The instructions in this white paper include how to use the Scalable Vector Graphics (SVG) image file format when generating diagrams in Design Studio reports. An SVG image is a vector-based graphic in XML format, which enables you to scale images to any size without sacrificing quality or reducing the image resolution.
2. Installing the Report Diagram Processor Example Design Studio includes the Report Diagram Processor example, design.studio.example.report.diagram.processor, that you install into your workspace. You can use this example as a starting point for your own custom reports. To install the design.studio.example.report.diagram.processor into your workspace: 1. In Design Studio, from the File menu, select New and then select Example. The New Example wizard appears:
2. Expand the Design Studio Examples folder, and then select Design Studio Report Processor Examples: 3. Click Next. The Example Projects page appears: 4. Click Finish. Design Studio creates two new projects: the design.studio.example.report.processor project
and the design.studio.example.report.diagram.processor project. You can view these projects in the Package Explorer view: 5. Expand the design.studio.example.report.diagram.processor project, and then expand the src folder. The src folder displays the Java files included in the example:
2.1 About the Report Diagram Processor Example The Report Diagram Processor example contains: The Java code for implementing the report diagram processor: o o o o o o o o o AbstractProcessor.java, which includes boilerplate code for implementing the required IReportProcessor interface. ReportDiagramProcessor.java, which is the class that provides the logic for the report diagram processor. ReportDiagramProcessorLogger.java, which is the class that provides functions for logging to the Eclipse error log. See section 4.1.2, About the ReportDiagramProcessor Class for more information. ReportDiagramProcessorMessage.java, which is the class that contains static variables for logging defined message to the Eclipse error log. ReportDiagramProcessorPlugin.java, which is an implementation of a BundleActivator interface required for Eclipse plug-ins, and which includes useful utility methods. ReportDiagramProcessorMessage.properties, which contains the error message properties for each static variable defined in ReportDiagramProcessorMessage.java. ImageFileFactory.java, which is the class that provides functions for generating the image file. See section 4.2.2, About the ImageFileFactory Class for more information. ProjectDependenciesHandler.java, which is the class that provides functions to gather the project and the project dependencies information. ProjectNode.java, which is the class that provides the logic for storing the project and the project dependencies information. The ProjectSummaryWithDiagram.rptdesign file, which is a report design file that defines the layout of report. The plugin.xml file, which contains extension point declarations for the report diagram processor. See section 4.1.1, Declaring Extension Points for more information.
3. Downloading Graphviz The instructions in this white paper include how to use Graphviz to create diagrams in Design Studio reports. Graphviz is an open-source diagramming tool that converts textual diagram definitions into diagrams. Graphviz can be downloaded from: http://www.graphviz.org/download.php 3.1 Creating a System Variable for Graphviz To use Graphviz with the Design Studio Report Diagram Processor example, you must create the system variable DS_SVG_DIAGRAM_PROGRAM with a value set to the path of the Graphviz dot.exe file. To create the system variable for Graphviz: 1. Navigate to the directory in which you installed Graphviz. 2. Click the bin directory. 3. Copy the location of the dot.exe file. 4. Create a new Windows system variable. a. In the Variable name field, enter DS_SVG_DIAGRAM_PROGRAM. b. In the Variable value field, enter the pathname of the dot.exe file. For example:
4. Designing the Report This section describes how to: Create a report processor Generate a diagram in SVG format Configure the report design 4.1 Creating the Report Processor To create a report processor, you can use the Design Studio Report Diagram Processor example as a reference or as a starting point for your own project. The Design Studio Report Diagram Processor example is an advanced example project that demonstrates how to extend the processing logic of the Design Studio report generation framework. See the Design Studio Developer s Guide for more information about the examples included in Design Studio and for more information about extending Design Studio using a report processor. 4.1.1. Declaring Extension Points When creating report processors, you must add a Report Generator extension and a Report Type extension to the plugin.xml file. The Report Diagram Processor example includes the following Report Generator extension and Report Type extension definitions:
In the Report Generator extension, ensure that processorclass attribute is set to the correct processor Java class (in the example, processorclass is set to ReportDiagramProcessor). Also, ensure that the reporttypeid attribute is set to the correct reporttypeid defined in the Report Type extension in the plugin.xml file (in the example, reporttypeid is set to design.studio.example.report.diagram.projectsummarywithsummaryreport). 4.1.2. About the ReportDiagramProcessor Class The ReportDiagramProcessor class performs the following tasks: Obtains the SVG image file, which is created by calling createimagefile() in ImageFileFactory class. See section 4.2, Generating a Diagram in SVG Format for more information about the implementation of the ImageFileFactory class. Maps the location of the created SVG image file to the svgimagefile parameter, which is located in the report descriptor. See section 4.3, Configuring Report Designs for more information about how report designs use this parameter.
4.2 Generating a Diagram in SVG Format This white paper describes a process that uses Graphviz to generate a diagram in an SVG format. Graphviz creates an SVG image based on a file that contains Graph Description Language (DOT). 4.2.1. About Graph Description Language When using Graph Description Language (DOT), you define the following: The node shape: The node content: The relationship between nodes: The following is an example of a text file that uses DOT:
The following is the sample diagram of DOT: See the Graphviz Documentation page and the DOT Guide for more information about DOT language, node shapes, arrow shapes, and so forth:
http://www.graphviz.org/documentation.php http://www.graphviz.org/documentation/dotguide.pdf 4.2.2. About the ImageFileFactory Class The ImageFileFactory class is designed and implemented to generate the text file with DOT and to execute dot.exe with the created text file to generate an SVG image file. The following key methods are implemented in the ImageFileFactory class: createimagefile() createdotfile() creatediagramusingcommandline() For the complete implementation of the ImageFileFactory class, see ImageFileFactory.java in the Design Studio Report Diagram Processor example. 4.2.3. About the createimagefile() Method You use the createimagefile() method to call the createdotfile() method, which generates a text file with DOT. Subsequently, you can call the creatediagramusingcommandline() method with the created DOT file to generate the SVG image file. 4.2.4. About the createdotfile() method The createdotfile() method is implemented to generate the data based on the syntax of DOT and to output the result to text file. See the Design Studio Report Diagram Processor example for a similar example. The text file is saved to the default temporary-file directory:
4.2.5. The creatediagramusingcommandline() Method You implement the creatediagramusingcommandline() method to create an SVG image file based on a given DOT file. Use ProcessBuilder to execute the following command line for dot.exe to generate the SVG image file: dot.exe Tsvg O < pathname of DOT file> The generated SVG image file is saved to the default temporary-file directory:
4.3 Configuring Report Designs The location of the SVG image file is saved to the svgimagefile report parameter in the report descriptor. You must create a report parameter in your report design with the same name as the image to ensure that the report can obtain the image file information. The Design Studio Report Diagram Processor example includes the ProjectSummaryWithDiagram.rptDesign report design file. From the Report Design perspective, you can open the Data Explorer to see the svgimagefile report parameter: If you open the ProjectSummaryWithDiagram.rptdesign report design, you can see that the report design also includes an image report item: The following sections describe how to create the report parameter and how to add an image report item to a report design.
4.3.1. Creating a Report Parameter in a Report Design To create a report parameter in a report design: 1. From the Report Design perspective, click the Data Explorer tab, then right-click Report Parameters, and then select New Parameter: The New Parameter page appears. 2. In the Name field, enter svgimagefile and click OK. Design Studio creates a report parameter named svgimagefile.
4.3.2. Adding Images to a Report To add an image to a report: 1. From the Report Design perspective, in the Resource Explorer view, expand the reports folder and double-click an.rptdesign file to open a report design. The report design opens in the Report Design editor. 2. Click the Palette tab, and then select Image: 3. Drag the Image item to the desired location in the report design. 4.3.3. Adding a Script to the Image Report Item You must add a script to an image item to ensure that the SVG image file is included in the final report. The script acquires the value of the svgimagefile report parameter, which defines the location of the SVG image file. Load the data from the file and output the data to the image report item: To add this script to image report item: 1. In the Report Design editor, click the image item that you added to the report design, and then click Script tab. 2. In the Script field, select oncreate:
3. Copy the following script: importpackage(packages.java.io); importpackage(packages.java.lang); var file = new File(reportContext.getParameterValue("svgImageFile")); var ist = new FileInputStream(file); var lengthi = file.length(); bytesa = new ByteArrayOutputStream( lengthi); var c; while((c=ist.read())!= -1){ bytesa.write(c); } ist.close(); this.data = bytesa.tobytearray(); 4. Paste the script into the Script tab:
5. Click Save.
5. Testing Report Designs The following instructions use the Report Diagram Processor example project to demonstrate how to test a report design. You develop custom report designs in Eclipse plug-in projects and plug-in projects are associated with feature projects. An Eclipse plug-in project can include any number of custom report designs. For example, you will likely include all of your custom report designs in a single plug-in project. You can test report designs by launching the associated plugin.xml file in a separate Eclipse application. To test a report design: 1. From the Design Studio Package Explorer view, expand your custom report design project, and then double-click the plugin.xml file. The Manifest editor opens. 2. Click the Overview tab: 3. In the Testing area, select an option to launch a separate Eclipse application: The project opens in a separate instance of Eclipse.
4. From the Studio menu, select Generate Report. The Generate Report wizard appears. 5. Select Select a report design from the list, and expand the Design Studio with Diagram Reports option. 6. Select Project Summary, and then navigate through the wizard to generate a project report. The following example shows the report output in PDF format: