Many organizations are realizing the prime importance of design and modeling in application development. These design models serve as a shared vision of an application for both the business and development teams. The design models are also amenable to code generation of all boiler plate code, thus allowing rapid development.
Although these models accurately capture aspects of the design, they lack descriptions that are found in typical design artifact work products. To help make these work products comprehensive, designers must manually prepare them by copying from design tools and adding explanations. This is effort intensive and also any change in design forces the designers to manually author the work product again.
In this tutorial, we will show you how to dynamically generate design artifacts from IBM® Rational ® Software Architect models by using BIRT reports. Business Intelligence and Reporting Tools (BIRT) is an Eclipse-based open source reporting system for web applications, especially those based on Java and Java Enterprise Edition (Java EE). Rational Software Architect includes BIRT, which offers capabilities to help you produce a report that includes selected contents of UML models.
By using reports to dynamically generate design documents, you can keep the model and design artifacts in synch without any extra effort.
- Rational Software Architect 7.5.5
- A good understanding of UML models and BIRT
- Knowledge of XML or XPath
The sample project, model and report are for illustrative purposes and to aid comprehension of BIRT reports generation from Rational Software Architect. The sample project and model are not technically accurate.
The tutorial covers only the important concepts of BIRT reports and how you can use them for UML models.
The sample project describes a fictional website akin to IBM developerWorks, which is a professional network and technical resource center where authors can submit articles. The articles are reviewed for technical accuracy and content standards of the site. The articles are tagged under different topics by authors and reviewers. The website subscribers can view the articles and filter them by topics.
To view the project dwSubscriptions, import the archive to Rational Software Architect. Figure 1 represents the sample project model:
Figure 1. Design model for the project
The sample project model contains the following parts:
- Activity diagram
- A diagram that describes the flow of events of a use case and what needs to be done by the system to provide value to an actor. It consists of a sequence of tasks that together produce something for the actor. The flow of events consists of a basic flow, and one or several alternative flows.
- Component diagram
- This diagram describes usage relationships that exist between the various deployment units. Its purpose is to show the dependencies that the software has on the other software components in the system, such as software libraries.
- Domain model
- This model describes various entities, their attributes and relationships. It also describes the constraints that govern the integrity of the model elements that comprise the problem domain.
- Interaction diagram
- This diagram represents the internal behavior of the system. It shows how objects collaborate by sending messages and returning responses to each other.
- State chart diagram
- This diagram represents the behavior or life cycle of a single class. It is a projection of all interaction diagrams for a single class. It describes the following behaviors:
- States that might be attained.
- External stimuli (events, messages, responses) that cause a change in state.
Sample design output
The file SampleDesignArtifact.pdf in the archive is a sample of the output that we want. By using this output, we will demonstrate how BIRT report can be generated from UML models. Please go through this sample along with the design models to understand the requirements from the BIRT report.
- Static model for text content
- The artifact consists of design elements from the Rational Software Architect model and static text content that describes the model.
To easily manage the static text, we created the dwStaticModel project and included it in the tutorial archive. The project mirrors the requirements for the static content.
Figure 2. Design model for static content
Review the project, especially the documentation for each package.
Figure 3. Documentation section of the package
This documentation is used to generate the static content for the report.
Prepare the report
The first thing we do is create a report project named developerWorks and a new report named dwReport.rptdesign
Creating a BIRT report consists of the following steps:
- Define the connection to the data sources.
- Define the queries that will generate the data sets for the report.
- Define the layout of the data elements.
Defining data sources
The report data is in two separate projects: dwSubscriptions and dwStaticModel; therefore we must create the data sources for each project.
- Open the Data Explorer view.
- Right-click Data Sources, and select New Data Source.
Figure 4. Creating a new data source
- Choose UML Data Source, and enter the data source name as
StaticDataSourcein the Data Source Name text box
- Click Next.
The New UML Data Source is displayed.
Figure 5. Specifying the UML meta model for the report
- Specify the data source by doing the following steps:
- Choose Instance Models-> Add
- Select Browse Workspace…->dwStaticModel -> dwStaticModel.emx
- Confirm the choice by Ok -> Ok -> Finish
- The default meta model for the data source is UML 2.1.0 and the notation is 1.0.1.
UML 2.1.0 helps to develop data sets for classes, packages and property level. Notation helps to create data sets for component, interaction, activity and state diagrams
Use these steps again to add another data source DynamicDataSource, and point it to the dwSubscriptions.emx file.
Defining data sets
The next step is to create queries to be used in the reports. First we will create a report from the static text.
Data sets for the static model
We will create data sets for each package under the static model. We begin by creating a data set for Activity Diagrams Packages.
Figure 6. Creating a new data set
- In the Data Explorer view, select Data Set > New Data Set
- Select Static Data Source, and enter
ActivityStaticDataSetfor the data set name.
- Click Next. The Row Mapping screen is displayed.
The purpose of this step is to extract the documentation that we wrote for the Activity Diagrams package. We know that the model file is in an XML file. Rational Software Architect has a wizard that helps you create queries that can be used with this XML.
Figure 7. Extracting information from a model
- In the Browse section, choose the UML model. Then select the package and click the button next to Row Query Expression. Enter
- Edit the row query to be
The XPath expression means "Get me all packages whose name is Activity Diagrams."
If you want to learn more about UML models, see the Resources section of this article for documentation and the org.eclipse.uml2.uml package.
- Click Next. The Column Mapping screen is displayed.
Now we must get the required attributes for the rows that we captured in the previous step. By default, it will display the first level attribute of the selected type (package in this scenario).
- Map the following columns from UML model:
- Name with @name
- Documentation with ownedComment/@body
Figure 8. Mapping columns
- Click Finish.
- To see if the data set is correct, select Preview Results. You should get results like those displayed in Figure 9.
Figure 9. Query results
Repeat these steps again for the following packages that remain in the static model:
- Domain Model
- Component Relationship
Ensure that the package name is correct in the Row Mapping screen by referring to the package name that is specified in the Static Model project dwStaticModel.
Important: The Introduction package under static contents has sub packages. What will be the Row Query for the sub sections like Description, Identification etc? We leave this as an exercise for the readers. You can also refer to the attached sample report for the answer to this query.
Make sure that you complete all the data sets for the static content. In the next sub section, we will create the data set for the design models.
Data sets for design models
To create a new report parameter, select Outline view ->Report Parameters -> New Parameter. We will pass the package name as a parameter to the report.
Figure 10. Creating report parameters
Now we will create a new data set named
DomainModelClassDataSet and use it to get all the classes associated with the package name that is being passed as a parameter to the report.
- In the first screen of the Query Parameters wizard add a new parameter named packageName.
- Click Next.
Figure 11. Specifying parameters for the data set
The query parameter helps to externalize the query. This helps to generate custom reports, based on the input parameters passed to the report.
- In the Row Mapping screen, Browse 'UML Model' and select Package as expression
Figure 12. Extracting information from the model
- Change the row query expression to support the following query parameter //Package[@name=$packageName]/Class; and then select Class as the type.
Figure 13. Providing expression for the query
- Provide the following column mapping
Figure 14. Column mapping for a dynamic class set
Figure 15. Creating parameters for the query
To link the report parameter to this data set, select Linked To Report Parameter and assign the packageName parameter.
Figure 16. Linking the report and query parameters
Now we are finished creating the data set using UML model. In the next section, we will create another data set by using the UML notation model.
Data set for interaction diagrams
To create a data set for interaction diagrams, choose the notation model in the Row Mapping tab.
Figure 17. Choosing the notation model for row mapping
- In the Row Query Expression text box, enter
Note: This expression means "Get me all the diagrams from all the Collaborations whose name is ArticleInteractions. Also the diagrams are below the Interaction."
With the notation model, you can easily query for the images by using the getDiagrams function. This row query gets us the interaction diagrams. We are interested the information that is displayed in Figure 18.
Figure 18. Column mapping for notation
Use the previous steps in this section to complete the wizard.
The notation model can be used in other cases where we need diagrams. See the report in the sample archive to see how we to create the rest of the datasets.
Now that we have the data set and data source ready, we can create the report, which involves creating the layout, putting the report elements on the report and setting the data sources.
Create the report layout
We have not described the report layout in detail because it is out of scope for this article. See the attached report for the layout details.
For this sample, we used the data sets that we created in this article and basic knowledge of BIRT to create the report. Other report layout considerations like header and footer, different main page, images, indexes can be used to make the report look polished.
Running the report
In this section, we describe how we can run the report and verify that the output report matches to our requirements.
Figure 19. Running the report
Create a new configuration, and choose the following options to generate PDF report.
Figure 20. Creating report configurations
Set the parameters for the report.
Figure 21. Setting the runtime parameters for the report
We generated design artifacts from the Rational Software Architect models by using the BIRT reports. In addition to the discussion on UML and Notation models, we also practiced the steps for creating data sources and data sets.
|File for article||PI_0612.zip||37KB|
|Sample output design artifact work products||SampleDesignArtifact.pdf||360KB|
- To learn more about Rational Software Architect, start at the developerWorks page. Also explore the product overview and the information center, where you'll find installation and use instructions.
- Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the "Getting Started" ones are free.
- UML documentation from Eclipse.org. For more details about UML:Package, choose package org.eclipse.uml2.uml, and then select the interface Package.
- Article: UML basics: An introduction to the Unified Modeling Language
- Tutorial: BIRT reports in Eclipse
Get products and technologies
- Download either or both versions for a trial:
- Evaluate IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
- Join the discussion in the Rational Development Tools forum.
- Rate or review Rational software. It's quick and easy. Really.
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.
- Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.