Developing and deploying Aspects in a Model-Driven Development environment: Part 1: How to package an Aspect for MDD

How to develop and deploy a simple AspectJ-based architectural mechanism for use with IBM Rational Software Architect

This tutorial discusses the details involved in creating an AspectJ-based library that can be introduced into an IBM Rational Software Architect Model-Driven Development project. This tutorial does not introduce AspectJ programming, but rather describes in detail how an existing AspectJ library can be packaged, deployed and used in Rational Software Architect. It also discusses configuration options that can be used to provide additional customization at the model element level. Finally this tutorial discusses localization and categorization options as well as introduce user documentation options such as the online help and cheat sheets.


Eoin Lane, Senior Solution Engineer, IBM

Dr. Eoin Lane, Senior Solution Engineer, is the lead for harvesting and developing of application pattern from key IBM SOA engagements and driving those patterns through IBM pattern governance process to accelerate adoption. Eoin also specializes in Model Driven Development (MDD), asset based development and Reusable Asset Specification (RAS) to facilitate SOA development.

Jim Conallen (, Senior Software Engineer, IBM

Jim ConallenJim Conallen is a software engineer in IBM Software Group's Rational Model-Driven Development Strategy team, where he is actively involved in applying the Object Management Group's (OMG) Model-Driven Architecture (MDA) initiative to IBM's Rational model tooling. Jim is a frequent conference speaker and article writer. His areas of expertise include Web application development, where he developed the Web Application Extension for UML (WAE), an extension to the UML that lets developers model web-centric architectures with UML at appropriate levels of abstraction and detail. This work served as the basis for IBM Rational Rose and IBM Rational XDE Web Modeling functionality.

13 June 2006

Also available in Chinese

Before you start

This tutorial describes how to package AspectJ-based assets for delivery in an Model-Driven Development (MDD) based software development process using IBM® Rational® Software Architect (hereafter, Software Architect). It is assumed that you are already familiar with the fundamentals of AspectJ, UML, and Software Architect.

Aspects can be an intimidating technology for developers, who are struggling with even the most basic set of new APIs and frameworks (Enterprise JavaBeans™ or EJB™, JavaServer Faces™ or JSF, Portal, and so on). Most do not have the time to learn a new language and technology, and as a result Aspects are often under utilized. The Aspects for MDD framework provides an opportunity for local experts in AspectJ technologies to package and deploy their work to large teams of developers, who can introduce them -- via the models they produce -- without having to understand AspectJ at all.

The advantage of this approach is that when it has been determined that the use of AspectJ is appropriate for a particular project, the architecture team can produce (or reuse) an aspect library, package it up, and deploy it to an entire team of developers who will use Software Architect and UML models to apply them. The developers need only understand when and to what to apply the aspects. The code in the aspect -- and the Aspect for MDD framework -- takes care of all the rest. Behind the scenes, the framework takes the responsibility of producing the actual AspectJ files that extend and reference the aspect library. While these files are available for the developer to modify and debug if necessary, they are in general fully functional and should not be touched

About this series

This series of two tutorials describes in detail how to package AspectJ-based assets for use with Software Architect. In the first part the basics are discussed. A basic logging example is chosen for its simplicity. In the second part a more interesting example is demonstrated, one which shows how to construct customized dialogs that enable an aspect's application to be parameterized.

About this tutorial

This tutorial is meant for architects -- familiar with AspectJ and UML Modeling -- who want to package and deliver architectural mechanisms to their development teams so that they can leverage the power of Aspects without requiring a detailed knowledge of the underlying technology. This tutorial focuses on how to package and deploy aspects in an MDD environment with Software Architect and AspectJ. It does not discuss in any detail how to design and create AspectJ-based architectural mechanisms. This is because it is assumed that the architect reading this already has some existing AspectJ-based assets -- or is considering creating some specific ones -- and is mostly concerned with how to package and deploy them in a controlled way to development teams in an MDD environment.

The overall outline of steps that you will perform is:

  1. Create an abstract AspectJ class that will be used and extended in some target project.
  2. Package and deploy the aspect in a form that can be downloaded and managed by the Aspects for MDD framework.
  3. Create a simple test model and project to test the aspect.
  4. Review the details of the generated configuration files, and offer some deployment suggestions.


In this tutorial you will learn how to create an Eclipse plugin that extends a defined extension point of the Aspects for MDD framework. This plugin is then packaged and deployed as a standard Eclipse feature or RAS (Reusable Asset Specification) asset that can easily be deployed to development teams. The plugin includes the definition of a new UML profile that is used to mark up a UML model. This tutorial discusses how to package up, test, and deploy the asset.


Before you can follow along with the steps in this tutorial, you must first have both the AspectJ Eclipse feature and the Aspects for MDD framework core and wizard plugins (full feature) installed in Software Architect. The former can be found on the website, and the latter can be downloaded and installed as a RAS asset using the link at the bottom of this tutorial. This tutorial assumes that you have some experience in the development of AspectJ code, and that you know how to create a project, compile a class, and deploy it as a library.

System requirements

To follow along with this tutorial you will need a machine that can comfortably run Software Architect and a simultaneous Software Architect runtime development configuration. Typically this is a machine with about 1GB of working RAM.

Developing the aspect

Before you begin packaging an AspectJ-based asset, you need to create it first. For the purposes of this tutorial we will begin with a very simple logging aspect, one that does nothing more than write a string to the console. In the real world this aspect could do anything (for example, manage security tokens, provide caching, or audit messages). For this tutorial, however, the focus is not on the aspect itself, but rather how you can package it so that it can easily be deployed to teams and used in the context of an MDD effort.

Create a new AspectJ project, and create a new aspect called ConsoleLogger. The source for this aspect is given below. This aspect does nothing more than write a single line out to the console just before and after invoking a method. The keyword thisJoinPointStaticPart is a special AspectJ object that contains type and signature information about the actual method for which this aspect is being invoked.

Listing 1. Simple logging aspect

public abstract aspect ConsoleLogger { protected abstract pointcut log ();

	before() : log() { 
		System.out.println("Entering " + thisJoinPointStaticPart ); 
	after() : log() {
		System.out.println("Exiting " + thisJoinPointStaticPart ); 

With the aspect created, deploy the code as a simple JAR (Java™ Archive) file. This is done by setting the name of the JAR file in the project's preferences.

Figure 1. Configuring an AspectJ project to build a JAR file
AspectJ project to build to a JAR file

Packaging an aspect for the Aspects for MDD framework

Aspect libraries that can be managed by the Aspects for MDD framework, like all new functionality for Software Architect, must be packaged as an Eclipse plugin. Plugins are the primary mechanism to add functionality to Software Architect and Eclipse, so it is only natural to use this mechanism to package aspects. Fortunately, there is a new plugin wizard that will help create this plugin and do most of the work of configuring it for deployment.

Before you create this project, you will need to know the following information. The first page of information is associated with the entire library, while the second page is just concerned with the first aspect to be packaged in this library.

Table 1. Information associated with the entire library scope
Aspect Library Name This is a human-readable name for your entire library of aspects. These aspects, of which the console logger is one, are packaged and deployed together.
Profile The name of a UML Profile that will be created, and that will own the UML Stereotypes to associate with each application of an aspect in the model.
Table 2. Information associated with a single aspect's scope.
Aspect Name The name of the first (and maybe only) aspect to be packaged in this deployment. This name will appear in the popup menu from which the modeler can select it.
Aspect Type The fully-qualified name of the aspect class that is to be applied. In this case it is
Suffix A short suffix to place at the end of each generated aspect class. This suffix is necessary to ensure that no namespace collisions will occur in the generated code.
Aspect JAR The JAR filename that contains the compiled aspect code. This JAR file will be automatically imported as a library in any project that uses the aspect. This JAR file should be considered a runtime artifact for the target project.
Stereotype A short name of a stereotype that will be created and applied to all modeling elements that the modeler wishes to associate with the aspect. In order to comply with the UML 2 API, this name should be a valid Java type identifier (that is, no spaces or special characters). Additionally, since the default behavior is for Software Architect to show stereotypes in all diagrams, keeping this name short will help enable other stereotypes to be applied without cluttering up the diagram too much.
Pointcut The name of the abstract pointcut to create in the aspect in order to make a concrete instance of the aspect. This pointcut must be defined in the aspect, and will get generated in a separate concrete aspect each time the aspect is applied to a model element.
Apply to Package, Class, Operation Indicate whether this aspect can be applied to these respective types of elements. For instance, if you want to restrict this particular aspect to only apply to operations, clear the Apply to Package and Apply to Class checkboxes.

To create a new Aspect Library Plugin Project, create a new Software Architect project and select the Plug-in Project Wizard (Figure 2).

Figure 2. Invoking the new Plug-in Project Wizard
New Plug-in Project Wizard

If you have not previously enabled the Plug-in Development Environment (PDE) functionality, you will be prompted to enable it at this point (Figure 3).

Figure 3. Enabling Plug-in Development Environment functionality
Plug-in Development Environment dialog

Enter an appropriate project name. The typical Eclipse convention is to use a Java package name (Figure 4).

Figure 4. Specifying the name of the new plug-in project
name of the new plug-in project

Specify plug-in project properties. You can accept all the defaults (Figure 4). Note the name of the Runtime Library JAR file. This is the name of the JAR file in which this deployment unit is packaged. This is a different JAR file than the one that contains the aspect itself. That JAR file will eventually get deployed with the runtime product, and should therefore contain only the aspect code, not any modeling framework code (such as this project).

Figure 5. Setting the plug-in properties
plug-in properties

Select the Aspect for MDD Library template (Figure 6). This template will ensure that the project structure and all necessary files will get created and initialized.

Figure 6. Selecting the Aspects for MDD New Plug-in Template
Aspects for MDD New Plug-in Template

Specify the aspect library name, the name of the JAR file that contains the aspect code, and give a name for the UML profile that will contain the stereotypes applied to the model (Figure 7).

Figure 7. Defining the aspect library information
aspect library information

Specify the information for the first aspect to be packaged. This information is for one aspect of potentially many that are packaged and deployed with the plugin project you are creating. Each aspect in this project will have the following:

  • A name
  • A fully qualified aspect type
  • A suffix with which to name concrete instances of the aspect
  • A stereotype name
  • A pointcut specification
  • Indicators as to what types of modeling elements can be tagged with this aspect

This example specifies for an aspect type the simple console logging aspect described in the previous section. The pointcut name is also defined in the aspect. The stereotype should be a short name that will help indicate which aspect is being applied. In this example we will only allow operations to be tagged with this aspect (Figure 8).

Figure 8. Defining the first aspect's information.
aspect information.

If this is the first time you have created a plug-in, you may get prompted to switch to the PDE perspective (Figure 9).

Figure 9. Enabling the PDE perspective
PDE perspective

Most of the work of packaging the aspect has already been done when the new plug-in project got created. It already has the required extension points defined -- and the required configuration files completed -- for the one aspect that was specified during the new project wizard. The only thing left to do now is to place a copy of the runtime aspect JAR file into the plug-in project's lib folder so that it will be packaged and deployed with the plug-in (Figure 10). This file will be added as an imported library to every project that uses this aspect.

Figure 10. Copying the Aspect JAR file into the plug-in project.
Aspect JAR file copied into the plug-in project.

For this simple example, this is all you need to do to test the aspect with the Aspect for MDD framework.

Testing a packaged aspect

To test the aspect (and its packaging) you will need to create a new Runtime Workbench debug configuration. This is the only way to test and debug eclipse plug-ins. A runtime configuration is essentially a new instance of the Eclipse (Software Architect) shell, one that is run in debug mode. To create a new debug configuration select Run > Debug from the main menu (Figure 11).

Figure 11. Selecting the debug configuration menu item
debug configuration menu item

Select the Runtime Workbench Configuration type and press the New button to create a new instance of this configuration type. Specify a name (for example, Runtime Workbench). You can optionally set the VM arguments and Program arguments as shown in Figure 12 to improve the debugging performance. Press the Debug button to begin debugging.

Figure 12. A runtime workbench debug configuration
runtime workbench debug configuration

If this runtime workbench is a new one, you will get the welcome screen for new workspaces (Figure 13). Configure this workspace as you like, and create a new test Java project (for example, SimpleJava) with which to test your plug-in. In this new project, create a new UML model (for instance, SimpleDesign), and then create a new UML Package in it. Inside that package, create a new class. This class can specify a standard static main method (to use in the test), and other methods to apply and not apply our aspects to. Figure 14 shows a class diagram in this model (with signatures shown in the diagram).

Figure 13. A new Software Architect workspace
Software Architect workspace
Figure 14. A simple test model
test model

To apply an aspect to a specific operation, select that operation in the diagram or in the model explorer, right-click it and select Aspect Lib (Figure 15).

Figure 15. Invoking the Aspect Lib Popup Menu
Aspect Lib Popup Menu

In the dialog box, expand the only category of aspects there and select the Console Aspect by checking it. Pressing the OK button will mark the model with a special stereotype. Figure 17 shows how the operation appears in the diagram.

Figure 16. Selecting the Aspect
aspect selected
Figure 17. Tagged Operation
A tagged operation.

The next step is to use the standard UML to Java Transformation to generate the code for the TestMain class. Since an aspect has been applied it will also generate an Aspect .aj file that contains the code for the concrete instance of the selected aspect.

Figure 18. Invoking the UML to Java Transformation
UML to Java Transformation

Use the Run Transformation dialog to select the same project as the default to generate code into (Figure 19).

Figure 19. Transformation Configuration dialog
Transformation Configuration

The UML to Java code generation creates two new files; and TestMainMyLogAspect.aj (Figure 20).

Figure 20. Update Test Project
Test Project

The UML to Java code generation creates two new files, but the TestMain class has no method bodies defined for it yet. To provide a suitable test scenario use the code in Listing 2.

Listing 2. Updated TestMain class
public static void main(String[] args) { 
	TestMain main = new TestMain();
	System.out.println( main.sayHello() ); 
	System.out.println( main.sayGoodbye() ); 
	System.out.println( "Finishing" ); 
public String sayHello() { return "Hello World"; }
public String sayGoodbye() { return "Goodbye World"; }

The aspect file that gets generated (Listing 3) simply matches the selected operation(s) with the precompiled library aspect. This code is designed not to be touched by the developer.

Listing 3. Generated aspect file

public aspect TestMainMyLogAspect extends {

	protected pointcut log () : call( * );


You can test the class by selecting it. Note, that you only need to run it as AspectJ/Java Application if the main method is in an aspect or if you're using the aspect path. So in this case it can be run either as a Java Application or as an aspect application.

Figure 21. Running the test project
test project

In the sample output of Figure 22, it is important to note that the call to the sayHello() method happens without console output (excluding the logging of course), and that you should expect to see all of the method sayHello() to complete in order to see the message "Hello World" display in the console. A proper test scenario would of course include a number of variants. You can use the JUnit test framework to help manage unit tests of the aspects being developed.

Figure 22. The test output.
test output.

Customizing the packaged aspect

There are a few customizable options that you can manually adjust. These are mostly to aid in the localization of developed aspects. The new plug-in wizard template creates a standard Eclipse plugin.xml file and a separate configuration file called aspect-library.xml, which aspect specific configuration information. First we'll examine the plug-in configuration.

Listing 4 shows the contents of the generated plugin.xml. In it you will find the required plug-in information and three extension definitions. The first defined extension is for the Aspects for MDD framework. It simply defines the extension and points to another XML (extensible markup language) file for the framework to process. We will discuss this file in detail later.

The other two extensions are for managing the generated UML Profile. The UML Profile is what is used to create stereotypes and stereotype properties (tagged values) that are added to the model when it is marked up and associated with the selected aspects. A UML Profile in Software Architect must be referenced with a defined path map, which in this case points to a folder relative to where this plug-in gets installed. The second profile-related extension specification identifies the profile, its file (using the defined pathmap), and some other interesting properties. The name attribute is how the profile appears in the drop-down list for those who want to apply this profile to a model explicitly. The required attribute -- if set to TRUE -- will tell Software Architect to apply this profile automatically to all opened models. Finally, the visible attribute indicates whether the profile can be seen by modelers. Invisible profiles are useful for attaching and marking models with information that is inappropriate or too confusing to users of the model. Normally you'll leave all of the generated options the way they are.

Listing 4. Generated plug-in.xml file.
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
   name="My Aspect Library"

      <library name="mylib.JAR">
         <export name="*"/>

      <import plugin="org.eclipse.ui"/>
      <import plugin="org.eclipse.core.runtime"/>
      <import plugin=""/>
      <import plugin=""/>
      <import plugin="org.eclipse.ui.cheatsheets"/>

            name="My Aspect Library Profile"


Most of the configuration information required to implement an Aspects for MDD framework extension is found in the aspect-library.xml file. The generated file contains a completed entry for just a single aspect. It is possible to include several aspects in the same plug-in. They are included by adding other <aspect> elements to the configuration file. You can also specify additional categories in this file with new <category> elements.

Listing 5 shows the contents of the generated aspect-library.xml file.

Listing 5. Generated aspect-library.xml file.
<?xml version="1.0" encoding="UTF-8"?>

	<category name="My Category of Aspects" id="">
		Enter a description for this category of aspects.

	<aspect name="Console Logger" 
	  profile="My Aspect Library Profile"
			<required-JAR name="lib/consolelogger.JAR"/>
			This is the description of my simple library aspect.


Each aspect definition must identify the aspect that can be applied and supply some specific information (Table 3). Each aspect should have a dependency on at least one supplied runtime JAR file. Aspects may require multiple JAR files. If so, they should be included in the <required-jars> section. Finally, a paragraph-length description is specified for each aspect, and is used in the popup dialog box.

Table 3. Aspect library attribute definitions.
id A unique identifier of the aspect. Using Eclipse conventions, this is usually the fully-qualified class name of the implementation with an .id extension appended to it.
category A reference to the id of a category that is defined in this configuration file, or possibly in another configuration file that is known to also be installed in the active IDE configuration.
type The fully-qualified name of the abstract AspectJ class that provides the target implementation. This is the main class of the actual aspect, which has an abstract pointcut definition.
aspectClassSuffix A simple suffix that is applied to the concrete AspectJ classes when code is generated. This suffix is necessary to distinguish AspectJ classes that are generated for the same target Java class. If more than one aspect is applied to a Java class, there is the potential for AspectJ class clashes. The suffix provides a simple mechanism for distinguishing which aspects are in which generated class.
pointcut The name of the abstract pointcut defined in the main AspectJ class.
applyToPackage A Boolean (true/false) attribute indicating whether this aspect can be applied to an entire package at once or not.
applyToClass A Boolean (true/false) attribute indicating whether this aspect can be applied to an entire class at once or not.
applyToOperation A Boolean (true/false) attribute indicating whether this aspect can be applied to a single operation or not.
profilePathmap The defined pathmap to the model used by the UML Profile.
profile The name of the profile to apply when this aspect is applied to an element in the model.
customize-class The fully-qualified class name of the class that implements BaseLibraryAspect. This class is responsible for handling framework requests. This includes the customizations to the code generation process, and prompting the user for additional information during the marking of the model.

Adding online Help

One often-neglected part of developing developer automation is supplying appropriate online Help and guidance. The Eclipse environment has an excellent and easy way to contribute online help (in the form of HTML files). It is highly recommended that you add a few Help pages to the online content that explain how and when to use the aspect in the normal course of development.

Another useful mechanism for providing prescriptive guidance with Eclipse is the Cheat Sheet mechanism. Cheat sheets are short, discrete prescriptive steps to accomplish specific tasks in the development environment. They appear in a checklist form in a fast view window (so they remain in view as you are doing the tasks). To learn more about how to create cheat sheets, examine the Eclipse Platform Plugin Development Guide > Programmer's guide > Advanced workbench concepts > Guiding the user through tasks > Cheat sheet topic.


Deploying a packaged Aspect for the Aspects for MDD framework involves nothing more than what is required to package and deploy any Eclipse automation. First an Eclipse Feature project is created that combines all the required plugins in one deployable package. This allows you not only to include your custom Aspect library, but also the Aspects for MDD runtime as well. This means that a new user can install just the one feature to get everything running, instead of requiring the Aspects for MDD runtime to be installed explicitly. The Eclipse feature and plug-in import mechanisms are smart enough to deal with duplicate plug-ins that may be found across features, and with different plug-in versions.

An alternate form of deployment unit can be a RAS asset. This format is based on the OMG standard for asset management. Software Architect can export and import RAS files. A RAS file can also include installable binary plugins/features. It is best to package all installable plug-ins as features first, then package the feature as a RAS asset, as this enables the Eclipse configuration manager to more easily uninstall the aspect in the future.

After creating the feature project, you can export the aspect as a RAS asset by selecting File > Export from the main menu. Then select RAS from the list (Figure 23).

Figure 23. Selecting RAS for export
Selecting RAS export

You will need to either specify an installed RAS repository server, or specify a filename to which to export the asset. In Figure 24 we simply specify a filename on the local machine.

Figure 24. Specifying a RAS filename
Specifying RAS filename

Each RAS asset includes meta information about the asset. The Export Wizard only prompts for the most common and required information. Figure 25 shows some of this information filled out.

Figure 25. Specifying RAS classification information
RAS classification information

Finally, the feature needs to be exported as a deployable feature. Otherwise, the asset will just contain the project source, leaving the developer to compile and install it manually on the local machine. Figure 26 shows how to mark the feature as deployable.

Figure 26. Specifying the feature for binary install
feature for binary install

When the Export Wizard completes, the result is a .ras file that can be shared and installed onto Software Architect workstations.


This tutorial described how to take a simple AspectJ-based architectural mechanism and package it in a way that enables it to be delivered to a development team and used in a model driven development process. This tutorial focuses on the basic steps needed to package and deploy such an aspect for use with the Aspects for MDD framework. Part 2 of this tutorial series will show how to create customized dialogs to prompt for additional information on each aspect application, and how to customize the generated aspect code.


Eclipse RSA project sourcesAspectsForMDD_ProjectSources_Part1.zip9KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=Developing and deploying Aspects in a Model-Driven Development environment: Part 1: How to package an Aspect for MDD