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 Session 2 : Specification Authoring 2010 IBM Corporation
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 2
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 3
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 4
What is BIRT? BIRT - Business Intelligence and Reporting Tools www.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 5
BIRT Report Template Values Data Report Data Report Parameters Points of variability of the report Data Sources The raw data being reported on Data Sets Subsets of the data sources fetched using queries and mapped to a tabular format Report Layout/Style Text Image Table Chart 6
BIRT Report Editor Report Data Report Layout / Style Report Widgets Report Properties 7
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 Dynamic Combo Box Static Combo Box 8
Data Sources Specify how to access data (models) and meta data (metamodels / profiles) 9
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 10
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 11
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 12
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, tileheight ) 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 attribute ) 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 13
Row Query Examples To get All interfaces All kinds of classes All first level packages All class diagrams contained by any package All attributes of a class parameter All interfaces whose owner s name is specified All diagrams whose name starts with the st All attributes owned by classes All classes with a given stereotype Query expression //Interface instanceof(//*, uml:class ) Model/nestedPackages getdiagrams(//package)[@type = Class ] resolveuri($classuri)/ownedattribute //Interface[owner/@name=$owner_name] getdiagrams(//*)[upper-case(substring(@name,1,2))='st'] oclevaluate(//class, self.ownedattributes ) getelementswithstereotype(//class, Profile1::Stereotype1 ) 14
Column Query Examples To get The name of the element The URI (unique id) of the element The type of the element The isabstract attribute of a class The count of attributes of a class The diagram s image blob up to a maximum resolution The diagram s image as an HTML grid of tiles A value derived using an OCL expression A value of a stereotype attribute Query expression @name getxmiid(.) getxmitype(.) @isattribute = true count(/.ownedattribute) getdiagramimage(., $maxwidth, $maxheight) getdiagramhtmlimage(., /temp, $tilewidth, $tileheight) oclevaluete(., self.getqualifiedname() ) getstereotypepropertyvalue(., Profile1::Stereotype1::property1 ) 15
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 16
Report Design Link the report widgets to data in your data sets 17
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 18
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 19
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 Generated from Model Post Processing 20
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 21
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) 22
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 23
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 24
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 text Ex. as can be found in Section [[Section_UML::Kernel::Classifier]]. Write a script to substitute them with cross-reference links Ex. as can be found in Figure 7.3.5. 25
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 26
27
Copyright IBM Corporation 2009. All rights reserved. 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. 28