Upload
doannhan
View
220
Download
0
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.