Extending the topology editor with custom technology domains

The deployment architecture tools found in the IBM® Rational® Software Architect Versions 7.5 and 8.0 include modeling elements for a variety of technology areas, such as databases, application servers, and Java Enterprise Edition (JEE) applications. These elements are often enough to model any type of computer system or software deployment, but if you use an area of technology where specific modeling elements are not provided, you might want to create custom units and capabilities. This tutorial demonstrates how to create custom units and capabilities that you can use to model the components of any area of information technology, using the Topology Domain Generation Toolkit.

André Zwanziger (andre.zwanziger@arch-IT-ecture.com), IT Architect, IT Architecture Consulting Group, Magdeburg

author photoAndré Zwanziger is an IT architect for the IT Architecture Consulting Group in Magdeburg, Germany. He is doing his PhD dissertation at the University of Magdeburg, and his research topics include the planning and automation of software deployment.



Chad Holliday (chadh@us.ibm.com), IBM Rational Software Development Team, IBM

author photoChad Holliday is a member of IBM Rational Deployment Architecture Platform team, and is the creator of the Topology Domain Generator Toolkit. Holliday has a B.S. degree from the University of Illinois at Urbana-Champaign. Contact Chad at chadh@us.ibm.com.



Sebastian Herden (sebastian.herden@arch-it-ecture.com), IT Architect, IT Architecture Consulting Group, Magdeburg

author photoSebastian Herden is an IT architect for the IT Architecture Consulting Group in Magdeburg, Germany. He is doing his PhD dissertation at the University of Magdeburg, and his research topics include the planning and automation of software deployment.



Tim McMackin (tmcmack@us.ibm.com), Software Engineer, IBM

Photo of Tim McMackinTimothy McMackin is a technical writer for IBM's Rational software in Raleigh, NC. McMackin has a background in writing for advertising technical products and has been with IBM since 2004. Contact Tim at tmcmack@us.ibm.com.



23 August 2011 (First published 13 July 2010)

Also available in Chinese

Introduction

The Deployment Architecture Tools included in the IBM® Rational® Software Architect solution come with a set of predefined technology domains to enable the planning of application deployments. Due to the vast amount of software, middleware, and hardware domains in existence today, the need for an extension to the platform arises.

A simple way to extend the available units is to copy and rename generic units, such as Generic Software units. This approach is often sufficient if the topology editor is only to be used for deployment modeling, and no further transformations from the modeled topology need to be created. However, if the modeled topology will be the basis for additional transformations (e.g. configuration files or installation scripts), this approach is insufficient, because the resulting XML representation of the topology is too generic and the extended elements can only be identified by naming conventions, which can be ambiguous and not overly robust. To obtain strong XML types in a serialized topology, you must create a formal domain in the platform. The Topology Domain Generation Toolkit provides a straightforward way of creating custom technology domains with strong XML types in the topology file.

In this tutorial, we present a real world scenario and show an easy to use extension mechanism for the topology editor, which lets you quickly define your own technology domain with strong XML types.

There are two appendices for this article:


Extending the Deployment Architecture Platform

The overall scenario of this tutorial is to model the planning of an application deployment for a MySQL database, which is not one of the domains provided with your Rational Software Architect toolset. These domains include DB2, Derby, and generic database units, but not MySQL.

A superficial way of creating a new kind of unit is to copy an existing unit and give it a caption that suggests that it is a different type of unit. For example, you might rename a generic database unit to appear to be a MySQL database, as in Figure 1.

Figure 1. Creating new units by relabeling existing units
Picture shows a customized generic unit in a diagram.

However, this strategy creates units that merely look like MySQL database components; the units themselves retain the type and attributes of the original units from which they were created. You could make other changes to the unit to indicate its differences, such as applying a custom style or appearance to the unit, but these changes are all superficial; the unit type does not change.

A better way to model a new type of unit such as a MySQL database is to create a MySQL database system unit with the specific properties of that software component. To ease the creation of the initial domain model, and to ensure maximum reusability for the new types, you can leverage existing model constructs where they are available.

To extend the Deployment Architecture Platform with your own technology domain, the following steps are necessary:

  1. Install the Topology Domain Generation Toolkit.
  2. Create an XML Schema Definition for the new technology domain. This schema definition defines the desired metamodel of the new technology domain, including the types of units and capabilities that are available in the domain.
  3. Generate the plug-in code into a form that can be used by IBM Rational Software Architect.

Prerequisites

This tutorial assumes a basic familiarity with topologies and the deployment architecture tools. For links to introductory material on these topics, see the Resources section.

To work through these instructions, you need IBM® Rational® Software Architect Version 7.5.5 or later and the Topology Domain Generation Toolkit. The steps for installing the toolkit are slightly different for Rational Software Architect V7.5 and V8.0.

Install the Topology Domain Generation Toolkit (Rational Software Architect V7.5)

  1. Download the Topology Domain Generation Toolkit Version 7.5 from the Downloads section, and extract it to a temporary folder on your computer. This file contains a feature that you must install into your Eclipse workbench.
  2. From the menu bar of the workbench, click Help > Software Updates.
  3. At the Software Updates and Add-ons window, go to the Available Software tab, click Add Site, click Local, and browse to the directory where you extracted the SDK feature (see Figure 2).
Figure 2. Add the Topology Generation Toolkit update site
Graphic shows Add Side dialog box open.
  1. Select the Domain Generation Feature and then click Install.
  2. Complete the Installation Wizard process and restart the workbench (see Figure 3).
Figure 3. Install the domain generation feature
Diagram shows selected feature open.

Install the Topology Domain Generation Toolkit (Rational Software Architect V8.0 and later)

  1. Download the Topology Domain Generation Toolkit Version 8.0 from the Downloads section, and extract it to a temporary folder on your computer. This file contains a feature that you must install into your Eclipse workbench.
  2. From the menu bar of the workbench, click Help > Install New Software.
  3. Click Add, click Local, and select the directory where you extracted the SDK.
  4. Give the repository a name, such as Domain SDK, and click OK.
  5. Clear the Group items by category check box.
  6. Select Domain Generation Feature and click Next.
  7. Using the wizard, complete the installation process and restart the workbench.

Create the domain extension

The files that define the domain are contained in an Eclipse project. Later, this tutorial will show you how you can package this project to share it with other people who might want to use your custom domain.

  1. To get the workbench ready to create the domain extension, switch to the Plug-in Development perspective and enable the XML Developer capability. Click Window > Open Perspective > Other and double-click Plugin Development. Then click Window > Preferences; General > Capabilities, select the XML Developer check box, and click OK.
  2. Create an empty project in your IBM Rational Software Architect (File > New > Project; General > Project) and name it "org.example.mysql".
  3. Add a folder named "model" to the new project and create two additional folders under "model" named "ecore" and "schema". These will be the locations of our model constructs. Now the project looks like Figure 4.
Figure 4. Initial project structure
Figure shows Package Explorer view open.
  1. Inside the "schema" folder, create a new XML Schema Definition, which is the starting point for domain extensions and which contains the initial model elements for your technology domain extension.
  2. Right-click on the "schema" folder and select "New > Other" from the context menu.
  3. In the New window, select Example EMF Model Creation Wizards > XSD Model. (If you don't see Example EMF Model Creation Wizards, select the Show All Wizards check box at the bottom of the wizard.)
  4. Click Next and name the schema file "mysql.xsd" and click Next again. (If you had to select the Show All Wizards check box, a popup window asks if you want to enable the Eclipse Modeling Framework capability; if you see this window, click OK.)
  5. In the following dialog (see Figure 5), specify the initial settings for the XSD Model. Here, set the Target Namespace Prefix to "mysql" and the Target Namespace to http://www.example.org/deploy/mysql/1.0.0/. The target namespace defines the unique identifier for the XML schema file and its domain extension.
  6. Click Finish. The XSD file is created and the XSD editor opens in the workspace.
  7. Select the Source tab of the editor in order to edit the contents of the XSD in text mode.
Figure 5. Initial settings of the mysql.xsd file
Graphic shows XSD Model Dialog attributes.
  1. Edit the file as shown in Listing 1 by adding the namespaces for the "ecore" and "core" domain and by annotating the XSD file with ecore attributes. The ecore information is required for the transformation process and the value of the attribute ecore:nsPrefix will later be used as the namespace prefix for your own domain extension. The namespace "core" refers to basic element definitions of the topology editor and is later required to derive your own units and capabilities. In order to access the elements of the core schema, its location has to be provided in a XSD import declaration.
Listing 1. Initial XML schema file for the domain extension
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<xsd:schema xmlns:mysql="http://www.example.org/deploy/mysql/1.0.0/" 
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 targetNamespace="http://www.example.org/deploy/mysql/1.0.0/" 
 elementFormDefault="qualified" 
 
 xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore" 
 xmlns:core="http://www.ibm.com/ccl/soa/deploy/core/1.0.0/" 
 
 ecore:nsPrefix="mysql"
 ecore:name="mysql"
 ecore:package="org.example.mysql">

 <xsd:import namespace="http://www.ibm.com/ccl/soa/deploy/core/1.0.0/" 
 schemaLocation=
 "platform:/plugin/com.ibm.ccl.soa.deploy.core/models/schemas/base.xsd"/> 

 <!-- unit and capability definitions go here -->

</xsd:schema>

Adding a unit to the domain

As a next step, you will define a new topology element (in this case, a unit), which represents the MySQL database in a topology and which will appear in the palette of the topology editor. Each new topology element needs two elements in the XSD file: an xsd:element element that declares the unit type and an xsd:complexType element that defines the supertype and attributes of the unit type.

The first XSD element contains the following information:

  • The name of the new diagram element.
  • The attribute substitutionGroup, which specifies the kind of topology element for the new element, such as a unit or a capability. For units, this attribute is set to "core:unit"; for capabilities, this attribute is set to "core:capability".
  • The reference to the type definition. You can use the same type for more than one unit, but it's usually easiest to define a new type for each unit.

The unit declaration for the MySQL database system looks like the code in Listing 2:

Listing 2: Unit declaration snippet
<xsd:element name="unit.MySQLSystemUnit" 
        substitutionGroup="core:unit" type="mysql:MySQLDatabaseSystemUnit"/>

The type definition in the xsd:complexType element specifies the supertype for the unit and any additions to that supertype. For the supertype, you can refer to the general types "Unit" or "SoftwareComponent" defined in the "core" schema, or you can refer to a more specific unit in another predefined domain. In the latter case, you must import the domain specification (namespace declaration and XSD import declaration with the schema location) so that the XSD parser can resolve the referred elements.

In the case of our MySQL example, we can derive our new element from the existing unit "DatabaseSystemUnit" from the database domain, which defines the generalized concept of a database management system. The unit type definition looks like the code in Listing 3:

Listing 3: Unit type definition snippet
<xsd:complexType name="MySQLDatabaseSystemUnit">
  <xsd:complexContent>
    <xsd:extension base="database:DatabaseSystemUnit"/>
  </xsd:complexContent>
</xsd:complexType>

This type definition refers to a unit in the database domain, so you must add the namespace declaration and the import declaration for the database domain from Listing 4 to your XSD. This snippet includes a new attribute to be added to the existing xsd:schema element, and a new xsd:import element to be added as a child of that xsd:schema element.

Listing 4: Import declaration snippet for the database domain
<xsd:schema …
 xmlns:core="…" 
 xmlns:database="http://www.ibm.com/ccl/soa/deploy/database/1.0.0/" 
 …
>
…
 <xsd:import namespace="http://www.ibm.com/ccl/soa/deploy/database/1.0.0/" 
 schemaLocation=
   "platform:/plugin/com.ibm.ccl.soa.deploy.database/models/schemas/databaseDomain.xsd"/>

This import declaration refers to the namespace of the database domain and the location of the database domain schema file. See Appendix A for a list of the available domains and their namespaces and schema files.

Add these three pieces of code (the unit declaration, the unit type definition, and the import declaration) to your XSD file, making sure that the attribute "type" of the unit declaration refers to the name of the complexType definition. In the complexType definition, make sure that the reference to the database domain in the tag "extension" uses the correct name of the type from which this type is derived. The complete XSD file looks like the code in Listing 5.

Listing 5. Complete XML schema file with custom unit
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<xsd:schema …
 xmlns:core="…" 
 xmlns:database="http://www.ibm.com/ccl/soa/deploy/database/1.0.0/" 
 …
>
…
 <xsd:import namespace="http://www.ibm.com/ccl/soa/deploy/database/1.0.0/" 
 schemaLocation=
 "platform:/plugin/com.ibm.ccl.soa.deploy.database/models/schemas/databaseDomain.xsd"/>

 <xsd:element name="unit.MySQLSystemUnit" 
 substitutionGroup="core:unit" type="mysql:MySQLDatabaseSystemUnit"/> 

 <xsd:complexType name="MySQLDatabaseSystemUnit">
   <xsd:complexContent>
     <xsd:extension base="database:DatabaseSystemUnit"/>
   </xsd:complexContent>
 </xsd:complexType>

</xsd:schema>

Note: By convention, unit names have the prefix "unit" followed by a dot and an identifying string. In this case, the unit is named unit.MySQLSystemUnit.


Adding a capability to the domain

To complete the MySQL example, add a capability with three attributes (Version, Port and MaxAllowedPacket) to the XSD. The capability definition is used in the topology editor to represent the functionality that units can provide to other units.

Note: It is possible to add attributes to the unit type, but by convention, all custom attributes are placed on capabilities rather than on units.

The definition of a capability follows steps similar to the unit definition:

  1. Add a new XSD element with the attribute's name, substitutionGroup and type. The value of the attribute substitutionGroup must be set to "core:capability". By convention, the name of the capability starts with "capability."
  2. Add the type definition of the new XSD element as a complexType. In the type definition, specify the supertype of the capability and the attributes of the capability, if any.
  3. If attributes or capabilities are referenced from other domains, add the corresponding namespace and import declarations.

Listing 6 shows a snippet for a new SQL database system capability, including both the element declaration and type definition.

Listing 6: Capability snippet
<xsd:element name="capability.MySQLDatabaseSystem" 
        substitutionGroup="core:capability" type="mysql:MySQLDatabaseSystem"/>

<xsd:complexType name="MySQLDatabaseSystem">
  <xsd:complexContent>
    <xsd:extension base="database:DatabaseSystem">
      <xsd:attribute name="MySQLVersion" type="core:VersionString"/>
      <xsd:attribute name="Port" type="os:TCPPortType"/>
      <xsd:attribute name="MaxAllowedPacket" type="xsd:int"/>
    </xsd:extension>
  </xsd:complexContent>
</xsd:complexType>

Listing 7 shows all changes made to the mysql.xsd file when the capability "capability.MySQLDatabaseSystem" is added. The new capability extends the existing capability "DatabaseSystem" from the predefined database domain. In addition, the type of the attribute "Port" is taken from the domain operating system (os), which requires the additional namespace "os" and the XSD import declaration.

Add the changes to your mysql.xsd file and validate the contents by right-clicking the XSD file in the Project Explorer view and then selecting Validate. If the validation is successful, proceed with the next section of the tutorial. If the validation process shows errors, makes sure that your code matches the code in Listing 7. The complete XSD file is also provided for download in the Resources section.

Listing 7. Complete XSD file with a new unit and capability
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<xsd:schema xmlns:mysql="http://www.example.org/deploy/mysql/1.0.0/" 
            xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
            targetNamespace="http://www.example.org/deploy/mysql/1.0.0/" 
            elementFormDefault="qualified" 
            
            xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore" 
            xmlns:core="http://www.ibm.com/ccl/soa/deploy/core/1.0.0/" 
            xmlns:database="http://www.ibm.com/ccl/soa/deploy/database/1.0.0/" 
            xmlns:os="http://www.ibm.com/ccl/soa/deploy/os/1.0.0/"
            
            ecore:nsPrefix="mysql"
            ecore:name="mysql"
            ecore:package="org.example.mysql">

   <xsd:import namespace="http://www.ibm.com/ccl/soa/deploy/core/1.0.0/" 
        schemaLocation=
        "platform:/plugin/com.ibm.ccl.soa.deploy.core/models/schemas/base.xsd"/> 

   <xsd:import namespace="http://www.ibm.com/ccl/soa/deploy/database/1.0.0/" 
        schemaLocation=
   "platform:/plugin/com.ibm.ccl.soa.deploy.database/models/schemas/databaseDomain.xsd"/>
     
   <xsd:import namespace="http://www.ibm.com/ccl/soa/deploy/os/1.0.0/" 
        schemaLocation=
        "platform:/plugin/com.ibm.ccl.soa.deploy.os/models/schemas/os.xsd"/>

        
   <!-- Custom unit -->

   <xsd:element name="unit.MySQLSystemUnit" 
        substitutionGroup="core:unit" type="mysql:MySQLDatabaseSystemUnit"/> 

   <xsd:complexType name="MySQLDatabaseSystemUnit">
     <xsd:complexContent>
       <xsd:extension base="database:DatabaseSystemUnit"/>
     </xsd:complexContent>
   </xsd:complexType>

   
   <!-- Custom capability -->

   <xsd:element name="capability.MySQLDatabaseSystem" 
        substitutionGroup="core:capability" type="mysql:MySQLDatabaseSystem"/>

   <xsd:complexType name="MySQLDatabaseSystem">
     <xsd:complexContent>
       <xsd:extension base="database:DatabaseSystem">
         <xsd:attribute name="MySQLVersion" type="core:VersionString"/>
         <xsd:attribute name="Port" type="os:TCPPortType"/>
         <xsd:attribute name="MaxAllowedPacket" type="xsd:int"/>
       </xsd:extension>
     </xsd:complexContent>
   </xsd:complexType>

</xsd:schema>

You may add as many unit and capability types to the XSD file as you wish to include in the domain. When you are done adding new topology elements, it's time to convert the XSD file into a domain extension that the topology editor can use.


Generate the domain extension

In this section, you generate an Ecore Model and an EMF Model (also called a genmodel) from the XML schema definition. From the genmodel, you can create the plug-in code for the domain extension.

  1. Right-click the mysql.xsd file in the Package Explorer view and choose New > Other so that the New Wizard" opens.
  2. In Rational Software Architect 7.5, select Eclipse Modeling Framework > EMF Model and then click Next. In Version 8.0, select Eclipse Modeling Framework > EMF Generator Model and then click Next.
  3. In the following dialog window, titled either "New EMF Model" (see Figure 6) or "New EMF Generator Model," select the ecore folder and make sure that the file name of the genmodel is set to mysql.genmodel.
  4. Then click Next.
Figure 6. Edit name and location for the genmodel
Graphic shows the EMF Model Creation Wizard.
  1. Select the XML Schema model importer and click Next.
  2. The mysql.xsd file should automatically appear in the text field "Model URIs". If it is not, select Browse Workspace and select your mysql.xsd file.
  3. Click Load to start the import of the XSD file.
  4. If the XSD file contains no errors, the Next button is activated; click this button to continue.
  5. In the next dialog, select the root package and the packages that have to be imported: In the upper table of the dialog box, select the "org.example.mysql" package. In the lower box, check all referenced packages (see Figure 7).
Figure 7. Completed Package Selection
Picture shows EMF Model Package Selection tab.
  1. Then click Finish. A mysql.ecore file and a mysql.genmodel file are created in the "ecore" folder of your project.
  2. Double-click the "mysql.genmodel" to open the file in the genmodel editor and select the top root node of the model.
  3. Edit the properties of the genmodel file and specify the following attributes, as shown in Figure 8:
    1. Set "Compliance Level" to "1.4"
    2. Set "Non-NLS Markers" to "true"
    3. Delete the ".edit" from the path entry "Edit Directory"; the new value for this field is "/org.example.mysql/src".
    4. Save the changes to the genmodel file (Ctrl+s).
Figure 8. Edit the genmodel properties
Figure depicts the properties of the MySQL root element.
  1. In the genmodel editor, right click on the top node labeled "Mysql" and generate the Model Code (see Figure 9), the Edit Code (see Figure 10), and finally the Topology Edit Code (see Figure 11).

In the Project Explorer view you will see the generated artifacts of each generation step. The "Model Code" generation produces the EMF code for the domain artifacts and the domain validators. The "Edit Code" generator creates the plug-in infrastructure to edit the model that is the plug-in.xml, META-INF directory, and provider classes as the ItemProvider and the EditPlugin. These files allow you to create instances of the units and capabilities in topologies. You don't need to edit these files directly.

The domain generator creates a new folder named "templates", where the topology templates for the concrete and the conceptual MySQL unit are stored. Additionally, the generator creates a new project called "org.example.mysql.ui" which contains the plug-in code for the diagram extension.

Figure 9. Generate Model Code
Picture shows the Generate Model Code screen.
Figure 10. Generate Edit Code
Figure depicts the Root element context menu.
Figure 11. Generate Topology Code
Picture shows the Generate Topology Edit Code.

Test the new technology domain in the runtime

To test the newly created technology domain, run the generated plug-in in a runtime instance of the workbench.

Open the "plugin.xml" file from "org.example.mysql" project and click Launch an Eclipse application as shown in Figure 12.

Figure 12. plugin.xml of the org.example.mysql project
Screenshot shows the plugin.xml Overview Tab.

The runtime instance of the workbench is initialized in a new window.

  1. Add a new project in the runtime instance (File > New > Project | General > Project) and name it "org.example.mysql.topology".
  2. In the Project Explorer, right click the newly created project and select New > Topology.
  3. In the dialog box, give the topology a name such as "MySQLExample" and click Finish.
  4. By default, palette entries from a generated domain are located in the Middleware palette drawer. Open this drawer, click the MySQLDatabaseSystemUnit entry, and place it onto the topology diagram (see Figure 13).

Note: You could also use the quick palette to select the new unit. Click on the topology diagram and press Ctrl+t and a popup window with available units opens. You can now browse through the units or, more quickly, enter the first letters of the unit's name.

Figure 13. Select a MySQLDatabaseUnit from the palette
Screenshot shows Runtime Instance and MySQL Unit.
  1. After placing the unit on the diagram, check for the presence of the MySQLDatabaseSystem capability and its attributes in the Properties view of the unit.

Note:
You can also access capabilities and requirements directly by double-clicking the unit and going to the Capabilities page (see Figure 14).

Figure 14. MySQLDatabaseUnit and its capability
Picture shows the MySQL unit and capabilities window.

To review the created topology code with strong XML types, save the diagram (Ctrl+s) and open the topology file in a text editor (Right click MySQLExample.topology and then click Open With > Text Editor). The source of the topology file should look like Figure 15.

Figure 15. Source Code of the .topology file with strong xml types for the mysql extension
Screenshot shows resulting .topology file in XML.

This source code shows that the MySQL units are distinct types and not merely copies of other units in the editor. Publishers and other extensions to the topology editor can now distinguish these units from other database units.

Close the runtime instance (Ctrl+F4) and proceed with the next section of this tutorial.


Configure the palette of the topology editor

The generation process creates topology templates, which are entries in the palette that contain one or more units for you to add to topologies. In this case, the generation process created two new templates for each new unit type that you defined, one containing a conceptual version of the unit and the other containing a concrete version of the unit. These templates are placed in the "Middleware" drawer of the palette by default.

The locations of the templates are specified in the plugin.xml files of the UI and domain project. In the UI project, drawers (top-level categories) and stacks (groups of related templates) are defined, which serve as containers for topology templates. Each drawer can contain individual template entries, as well as stacks of related templates. Each drawer, stack, and template must have a unique identifier on the same hierarchy level so that each path definition is unique. In the domain project, templates are provided with a UI binding which includes a palette path attribute that links the template to one or more drawers or stacks. If the path definition is invalid or missing, the template will not be shown in the palette.

In the MySQL example, a new drawer will be created that contains all elements of the example.org domain. Within that drawer, the existing MySQL stack (which has been created by the Domain Generation Toolkit) will be included.

  1. Open the plug-in editor of the UI project (double-click the plugin.xml) and go to the Extensions tab.
  2. Expand org.eclipse.gmf.runtime.diagram.ui.paletteProviders > com.ibm.ccl.soa.deploy.core.ui.providers.DefaultPaletteProvider > com.ibm.ccl.soa.deploy.core.ui.providers.DeployCorePaletteFactory. As shown in Figure 16, the Topology Domain Generator Toolkit has created a default palette entry for the MySQL database in a stack named mysqlStack in the path /serverSoftwareDrawer (representing the "middleware" drawer).
Figure 16. Generated Palette Entry for the MySQL Domain
Picture shows plugin.xml editor stack extension.
  1. To extend the palette with a custom drawer, right click the contribution entry com.ibm.ccl.soa.deploy.core.ui.providers.DeployCorePaletteFactory and select New > entry as shown in Figure 17.
Figure 17. Add a new palette entry
Graphic shows adding an entry to the plugin.xml file.

On the right side of the screen, you can edit the details of the new extension entry.

  1. In the kind field, select drawer and enter the id "ExampleOrgExtensions". The drawer is placed as a top level element in the palette, which is indicated by a ‘/' in the path field.
  2. In the label field, specify "example.org Extensions" for the label of the new drawer. In the case that an attribute's value remains empty, a default value is set. Optionally, you can also set a description and icons for the new drawer.
  3. After you have entered the data, select the entry example.org Extensions and click on the Up button in the dialog (see Figure 18). Moving the drawer definition above the stack definition ensures that the new drawer is created before the mysqlStack is inserted.
Figure 18. Check that the new drawer is placed above the stack entry (left side) and the details of the new drawer (right side)
Picture shows Extensions Tab open.
  1. The next step is to link the mysqlStack entry to the newly created drawer entry. To do this, open the Mysql Stack entry and set its path attribute to "/ExampleOrgExtensions".
  2. Save the UI plugin.xml (Ctrl+s).

Next, update the paths of the templates to point to the new drawer and stack.

  1. Open the plugin.xml file of the domain project (not the UI project) and go to the Extensions tab. Expand the extension point com.ibm.ccl.soa.deploy.core.domains. Each template in the domain extension is defined as a resourceType (which contains general information about the resource) and a resourceTypeUIBinding (which includes the UI definition of the resource, including its location in the Palette and its labels and icons). In the resourceTypeUIBinding, the attribute "path" defines the palette path.
  2. For both templates, set the value of the path attribute to /ExampleOrgExtensions/mysqlStack/ as shown in Figure 19 and save the changes.
Figure 19. Extensions dialog of the plugin.xml file of the domain project with adapted value for the attribute "path"
Screenshot shows the domain extension.
  1. Test the new configuration in the runtime environment by clicking Launch an Eclipse application on the Overview tab. You can see the new drawer and stack in the Palette as in Figure 20.
Figure 20. The new Palette drawer
Picture depicts the Palette in Runtime instance.

You can add as many new Palette drawers, stacks, and templates as you want. By default, each template contains only one unit, but you can create templates with as many units and capabilites as you want by creating a topology with those units and capabilities, saving that topology to the "templates" folder of the domain project, and creating resourceType and resourceTypeUIBinding elements as shown in the previous example.

You can also add Palette entries to the existing drawers; the IDs of these default drawers are listed in Appendix B.


Export and install the new domain extension plug-ins

To exchange the created plug-ins and templates easily, all plug-ins can be assembled into one update site project that may be accessed by all users of the extension. An update site consists of a collection of features and each feature itself consists of a collection of plug-ins which are installed together. For the MySQL example, the update site will provide one feature that includes the domain and UI plug-in.

Before creating the update site, make sure that the templates folder of the domain plug-in is included in the plug-in archive:

  1. Open the plugin.xml file of the domain plug-in in the plug-in editor and go to the Build tab.
  2. In the Binary Build section, make sure that the check box next to the "templates" folder is selected.
  3. Save the changes (Ctrl+s) and close the editor (Ctrl+F4).

Create a new feature to contain the domain and UI plug-ins:

  1. Create a new Feature Project (File > New | Plugin Development > Feature Project).
  2. In the dialog shown in Figure 21, enter a name for the project such as "org.example.mysql.feature" and a Feature Name such as "MySQL Feature" and then click Next.
  3. In the next dialog, select the plug-ins to include in the feature (see Figure 22). In this case, select the checkboxes of the two mysql plug-ins (org.example.mysql and org.example.mysql.ui) and click Finish.

The new project is created and the feature.xml editor opens in the workspace.

Figure 21. Create a new feature project
Graphic shows Feature Properties creation wizard.
Figure 22. Selecting plug-ins
Feature Creation wizard showing plug-in selection
  1. In the editor, go to the Plug-ins tab and check that both plug-ins are added properly. By default, the version numbers of the plug-ins is set to "0.0.0", which is a placeholder that refers to the latest version configured in the plug-in project.
  2. On the Information tab, you can change the overall information of the feature (such as the feature description, the copyright, the license agreement and additional websites to visit). This information is displayed in the "Software Update" dialog ahead when someone installs the feature.

Next, create the update site to allow other people to install the domain extension:

  1. Return to the Overview tab and in the Publishing section, click Create an Update Site Project (see Figure 23).
Figure 23. Overview page of the feature.xml editor
Picture shows the feature.xml Overview Tab open.
  1. In the New Update Site dialog, enter a project name (e.g. org.example.mysql.updatesite) and click Finish. The Update Site editor opens automatically to the Site Map tab, from which you can add new categories and features to include in the update site.
  2. Click New Category and enter "MySQL Extension" as value for the Name and Label fields.
  3. Then select the category "MySQL Extension" and click Add Feature. A selection dialog opens where you can add the mysql feature (org.example.mysql.feature).
  4. Click Build All to build the plug-ins, the feature, and the Update Site (see Figure 24).
  5. Finally, delete the generated files "content.xml" and "artifacts.xml" from the update site project to avoid an error message during the installation of the new plug-ins.
Figure 24. Complete configuration of the site.xml for the mysql example
Screenshot shows Update Site Project.

Now you can share the update site with other people who might want to use the domain extension. The update site project contains all of the necessary plug-ins and features in the "features" and "plugins" folders, so you do not need to include the other projects when you distribute the update site. Follow these instructions to install the domain extension from the update site:

  1. Open the Software Installation Dialog (Help > Software Updates) and select the Available Software tab.
  2. Click Add Site and select the folder that contains your update site project. In the Software Update dialog, the new MySQL Extension with the MySQL Feature is displayed as shown in Figure 25.
  3. Select the feature's checkbox and click Install.
  4. Restart the workbench.
  5. To verify that the domain extension is installed, test the domain by creating a new project with a topology and adding the units in the domain to the topology.
Figure 25. Software Update Dialog with the MySQL Feature
Picture shows Software Updates with MySQL selected.

Summary

This tutorial showed how validation mechanisms can greatly enhance your technology domain extensions at different levels of abstraction. You can add validators on attributes, units, capabilities, and domains, and you can report the status to the model user as an informational message, warning, or error message. Custom validators can contain detailed logic to examine the elements of a topology through the API, such as the static methods of the ValidatorUtils class. In most cases, it will be sufficient for you to edit and override the existing validate(…) methods. For more complex validations, you can also use the API provided with the deployment planning tools in Rational Software Architect to add your own validator project with its own set of rules.

Having validators in a technology domain extension increases the value of that domain to modelers. The next step to enhance your custom domains might be to add resolution mechanisms to resolve to the problems discovered by the validators in your custom domain. For information on adding validators to custom domains, see the tutorial titled "Use the topology editor in Rational Software Architect to add a custom validator" (see Resources)


Downloads

DescriptionNameSize
Topology Generation Toolkit for V7.5Zephyr-SDK-75x.zip151KB
Topology Generation Toolkit for V8.0Zephyr-SDK-80x.zip151KB

Resources

Learn

Get products and technologies

Discuss

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=499526
ArticleTitle=Extending the topology editor with custom technology domains
publish-date=08232011