generating diagrams in design studio reports - oracle cloud · generating diagrams in design studio...
TRANSCRIPT
Generating Diagrams in Design
Studio Reports
December 2015
Generating Diagrams in Design Studio Reports
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.
Generating Diagrams in Design Studio Reports
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
Generating Diagrams in Design Studio Reports
1. Introduction
This white paper describes how to include diagrams in Design Studio reports. It describes how to:
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
1.1 Prerequisites
This white paper assumes that you are familiar with Design Studio reporting features and that you
have reviewed the reporting information in:
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
1.2 About 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. 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.
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
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
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
2.1 About the Report Diagram Processor Example
The Report Diagram Processor example contains:
The Java code for implementing the report diagram processor:
o AbstractProcessor.java, which includes boilerplate code for implementing the
required IReportProcessor interface.
o ReportDiagramProcessor.java, which is the class that provides the logic for the
report diagram processor.
o 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.
o ReportDiagramProcessorMessage.java, which is the class that contains static
variables for logging defined message to the Eclipse error log.
o ReportDiagramProcessorPlugin.java, which is an implementation of a
BundleActivator interface required for Eclipse plug-ins, and which includes useful
utility methods.
o ReportDiagramProcessorMessage.properties, which contains the error message
properties for each static variable defined in
ReportDiagramProcessorMessage.java.
o 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.
o ProjectDependenciesHandler.java, which is the class that provides functions to
gather the project and the project dependencies information.
o 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.
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
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.
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
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.
Generating Diagrams in Design Studio Reports
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.
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
5. Click Save.
Generating Diagrams in Design Studio Reports
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.
Generating Diagrams in Design Studio Reports
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:
Generating Diagrams in Design Studio Reports
Generating Diagrams in Design Studio Reports