28
© 2010 IBM Corporation Session 2 : Specification Authoring 2nd Biannual Symposium On Eclipse Open Source Software & OMG Open Specifications June 22, 2010 Generating Specification Documents from Models using BIRT Maged Elaasar Senior Software Engineer IBM Rational Modeling Tools

Generating Specification Documents from Models using BIRTmagedelaasar.com/wp-content/uploads/2012/11/Generating... · Designing a specification document template using BIRT Define

Embed Size (px)

Citation preview

© 2010 IBM Corporation

Session 2 : Specification Authoring

2nd Biannual Symposium On Eclipse Open Source Software & OMG Open Specifications

June 22, 2010

Generating Specification Documentsfrom Models using BIRT

Maged ElaasarSenior Software Engineer

IBM Rational Modeling Tools

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

2Session 2: Specification Authoring

Outline

� The need to generate specification documents from models

� Introduction to BIRT and its integration in RSM modeling tool

� Designing a specification document template using BIRT

� Limitations of using BIRT for document generation

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

3Session 2: Specification Authoring

The need for generating specification documents

� The current process of producing specification documents:

� Specification documents are maintained in a word processing tool (e.g. Frame Maker).

� Metamodels are maintained as UML models using a UML tool (e.g. RSM)

� Changes are applied separately to both artifacts leading to inconsistencies (~30% of issues)

� Hard to do global changes to document structure or style

� Hard to keep repeated information consistent throughout the spec document

� Hard to producing alternative document design or content

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

4Session 2: Specification Authoring

Characteristics of a Desired Solution

� Link documentation to metamodels

� Documentation can either be embedded in metamodels (Comments) or in external files

� Documentation can be done in a textual markup language (e.g. HTML/RTF)

� Define a profile with stereotypes to organize documentation

� Can be applied to the metamodel itself

� Can be applied by separate document model with references to metamodels

� Define a document template that extracts and layouts content form metamodels

� Define the structure, layout and style of the document sections

� Define queries to extract information from metamodels

� Link the document sections from the corresponding model queries

� A candidate tool for template authoring and generation is BIRT.

� Used to generate the Diagram Definition specification

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

5Session 2: Specification Authoring

What is BIRT?

� BIRT - Business Intelligence and Reporting Toolswww.eclipse.org/birt

� Provides visual report authoring experience

� Supports a variety of report content (text, tables, charts…etc)

� Creates various output formats (HTML, PDF, DOC, …etc)

� Natively works with data in tabular format, but…

� Provides Open Data Access (ODA) interface to map other data to native format:

� RSM tool implements ODA to define:�A mapping from EMF-based models

�An extension to handle UML profiles

�An extension to handle GMF diagrams

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

6Session 2: Specification Authoring

Report Data

BIRT Report Template

Data Sources

Data Sets

Report Parameters

Report Layout/Style

DataThe ‘raw’ data being reported on

Subsets of the data sources fetched using

queries and mapped to a tabular format

Points of variability of the report

Text

Image

Table

Values

Chart

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

7Session 2: Specification Authoring

BIRT Report Editor

Report Data

Report Widgets

Report Layout / Style

Report Properties

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

8Session 2: Specification Authoring

Report Parameters

� Report parameters allow authors to capture variability in a report

� Report parameters can be configured with various styles and presented with various widgets

Text Box

Static Combo BoxDynamic Combo Box

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

9Session 2: Specification Authoring

Data Sources� Specify how to access data (models) and meta data (metamodels / profiles)

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

10Session 2: Specification Authoring

Data Sets

� Data sets define queries against data sources and put the result into a tabular format (with rows and columns)

� Data sets can be defined with parameters

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

11Session 2: Specification Authoring

Data Sets� Row mapping : specifies a query to collect model elements representing the rows of a table

� Expression : an XPath query that collects elements

� Type: the type of elements being collected

� Stereotypes : the stereotypes applied to row elements being collected

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

12Session 2: Specification Authoring

Data Sets

� Column mapping : define columns representing data extracted from row elements

� name : user specified name for the column

� query : expression to extract primitive data from each row element

� type : the primitive type of the query result

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

13Session 2: Specification Authoring

XPath Functions� Prepackaged EMF-Generic Functions

� getURI( xpath ) gets the URI of a given element

� resolveURI( uri ) resolves the given URI to its element

� instanceOf( xpath, type ) checks if a given element conforms to a given type

� getXMIID( xpath ) gets the unique GUID of an element

� getXMIType( xpath ) gets the type of an element

� oclQuery( xpath, OCL statement ) gets a subset of given elements that satisfy given OCL condition

� oclEvaluate( xpath, OCL statement ) evaluates the given OCL expression on the given element

� Prepackaged GMF-Specific Functions� getDiagramImage( xpath, maxWidth, maxHeight ) renders given diagram subject to given maximum resolution

� getDiagramHTMLImage( xpath, path, tileWidth, tileHe ight ) renders the given diagram as HTML tile grid

� Prepackaged UML-Specific Functions� getDiagrams( xpath ) gets the diagram of the given UML namespace element

� getElementsWithStereotype( xpath, stereotype ) gets a subset of given elements with given stereotype

� getStereotypePropertyValue( xpath, stereotype attri bute ) gets value of a given stereotype attribute

� Custom Functions� Implement org.eclipse.jet.xpath.XPathFunction interface with one method Object evaluate(List args)� Package implementation in a PDE plugin and register it with the org.eclipse.jet.xpathFunctions extension point

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

14Session 2: Specification Authoring

Row Query Examples

getElementsWithStereotype(//Class, “Profile1::Stereotype1”)All classes with a given stereotype

oclEvaluate(//Class, “self.ownedAttributes”)All attributes owned by classes

instanceOf(//*, “uml:Class”)All kinds of classes

Model/nestedPackagesAll first level packages

resolveURI($classURI)/ownedAttributeAll attributes of a class parameter

getDiagrams(//*)[upper-case(substring(@name,1,2))='ST']All diagrams whose name starts with the “st”

Query expressionTo get

//Interface[owner/@name=$owner_name]All interfaces whose owner’s name is specified

getDiagrams(//Package)[@type = “Class”]All class diagrams contained by any package

//InterfaceAll interfaces

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

15Session 2: Specification Authoring

Column Query Examples

getStereotypePropertyValue(., “Profile1::Stereotype1::property1”)A value of a stereotype attribute

oclEvaluete(., “self.getQualifiedName()”)A value derived using an OCL expression

getXMIID(.)The URI (unique id) of the element

getXMIType(.)The type of the element

count(/.ownedAttribute)The count of attributes of a class

getDiagramHTMLImage(., /temp, $tileWidth, $tileHeight)The diagram’s image as an HTML grid of tiles

Query expressionTo get

getDiagramImage(., $maxWidth, $maxHeight)The diagram’s image blob up to a maximum resolution

@isAttribute = ‘true’The isAbstract attribute of a class

@nameThe name of the element

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

16Session 2: Specification Authoring

Report Design

� Use the palette view to insert various widgets in your reports

Static text

HTML Text

Computed Text (Static / HTML) e.g. for model doc

Image : embedded, from URL, from expression, e.g. for diagrams

Table with rows / columns

Chats of various kinds

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

17Session 2: Specification Authoring

Report Design� Link the report widgets to data in your data sets

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

18Session 2: Specification Authoring

Report Generation

� BIRT supports 2-phase generation of reports:�Generation Phase : generates an intermediate output-independent document

�Presentation Phase : renders the intermediate document to specific output (e.g. PDF)

� BIRT elements can be scripted (in Java Script) at various generation events�Define reusable code snippets in global java script functions in report

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

19Session 2: Specification Authoring

Other BIRT Features

� Report Libraries: report parts can be defined in report libraries imported by report

� Master Pages: several can be defined and linked to report sections

� Report Themes: themes can be defined in CSS style sheets and applied to report

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

20Session 2: Specification Authoring

Designing a specification document template using BIRT

� Analyze the current specification document template components:� Cover Page

� Legal Statements

� Issues Page

� Preface

� Table of Contents

� Submission material (Section 0)

� Front Matter

� Metamodels

� Annexes

� Index

Editable directly

Fixed by OMG

Post Processing

Generated from Model

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

21Session 2: Specification Authoring

Designing a specification document template using BIRT

� Create report library with a separate page (Grid) for each component�This way each component can be manipulated separately

� Create report design whose body integrates the components in order �Editing occurs in the library and report picks changes automatically

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

22Session 2: Specification Authoring

Designing a specification document template using BIRT

� Define one or more master pages and link each Grid to one of them�This way each grid can have different headers, footers, page number style…etc.

� Define a theme using a CSS style sheet�Styles are either pre-defined (apply automatically) or user-defined (apply manually)

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

23Session 2: Specification Authoring

Designing a specification document template using BIRT

� Define one UML data source for each set of related metamodels

� Define data sets from the data source�Define a unique key column (use URI for EMF elements)

�Define data set parameters (use URI to identify elements)

� Define the content of the grid with nested tables bound to data sets

Packages

Classes

Attributes

Associations

Operations

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

24Session 2: Specification Authoring

Designing a specification document template using BIRT

� Use the following widgets:�Use Text widget for static text content (regular or markup)

� Ex: “This <b>State</b> class can do this….”

�Use Dynamic Text widget for dynamic text content (calculated with script)

�Use Shared Image widget for adding figures from files

�Use Dynamic Image widget for adding diagrams (from models)

� Create a separate widget for �content that need to be bookmarked

�content that need to be in TOC

� Use scripts to automatically numbers sections, figures and tables

� Apply appropriate styles from theme to text elements

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

25Session 2: Specification Authoring

Designing a specification document template using BIRT

� Implement cross-referencing:�Add bookmarks:

� Use naming conventions for naming bookmarks of numbered items:

– Sections: “Section_<name>” (e.g. Section_UML::Kernel::Class)

– Figures: “Figure_<name>” (e.g. Figure_Kernel Package)

– Tables: “Table_<name>” (e.g. Table_Classifier Notations)

� Write a script to build bookmark names to numbers map

�Add cross-references:

� Insert “[[bookmark_name]]” to specify a cross-reference in the textEx. “…as can be found in Section [[Section_UML::Kernel::Classifier]].”

� Write a script to substitute them with cross-reference linksEx. “…as can be found in Figure 7.3.5.”

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

26Session 2: Specification Authoring

Limitations of using BIRT

� No support for embedded TOC or Index in the template itself�Workaround: do post processing to add these in the output format

� TOC nesting in PDF output is based only on table nesting�Workaround: batched BIRT to base it on used TOC styles (TOC1, TOC2…etc)

� No support for “resize image proportionally to fit container” in PDF output�Only supported are original size, exact size or % of container size

�Workaround: use original size but ensure diagrams are small enough to fit

� Master pages do not support �alternating page number placement

�page number restarts

�Roman numbers

� BIRT is an active project and could fix these issues in the future

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

27Session 2: Specification Authoring

2nd Biannual Symposium On Eclipse Open Source Softw are & OMG Open Specifications

28Session 2: Specification Authoring

© Copyright IBM Corporation 2009. All rights reserv ed. The information contained in these materials is provided for informational purposes only, and is provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, these materials. Nothing contained in these materials is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in these materials to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in these materials may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. IBM, the IBM logo, Rational, the Rational logo, Telelogic, the Telelogic logo, and other IBM products and services are trademarks of the International Business Machines Corporation, in the United States, other countries or both. Other company, product, or service names may be trademarks or service marks of others.