Nirmal’s blog

Recently, I had a task of a converting a UML model in Enterprise Architect to a EMF UML2 model. Googling with the keywords took me straightaway to Ueli Brawand and his tool EA_UML2Exporter. It is a wonderful little tool that works with openArchitectureWare and gets the task done in no time. However, setting it up does consume some time. I thought of summarizing the steps I did, incase it helps others.

1. Downloading Enterprise Architect

• If you don’t have Enterprise Architect, download a 30-day trial from here: http://www.sparxsystems.com/products/ea/trial.html.
  Please note that Enterprise Architect runs only on Microsoft Windows. If you are using other environments, please use a virtual Windows environment to install Enterprise Architect.

2. Downloading openArchitectureWare

• Download openArchitectureWare 4.3.1 (”oAW IDE from itemis”) from http://www.openarchitectureware.org/staticpages/index.php/download?menu=Download.
  Please note that EA_UML2Exporter doesn’t work with openArchitectureWare 5 (Eclipse MWE).

3. Downloading EA_UML2Exporter

• Download EA_UML2Exporter from http://sourceforge.net/projects/components4oaw/files/ and extract the libraries to any folder.
  The libraries are simples JARs and not Eclipse plugins. Hence they shouldn’t be copied to the Eclipse plugins/dropins folder.

4. Setting up a new openArchitectureWare Project

• Start the downloaded Eclipse distribution with oAW and create a new openArchitectureWare Project.
• The EA_UML2Exporter libraries needs to be added to the project. Select Project Properties from context menu and add the EA_UML2Exporter JARs using Java Build Path -> Libraries ->  Add External JARs….
  
• The EA Java API library now needs to be added to the project in the same way. Browse to the Java API folder within Enterprise Architect Installation folder and add eaapi.jar to the project in the same way as above.
• SSJavaCOM.dll within the Enterprise Architect Java API folder needs to be in the system path. Easiest would be to add this to the root of the newly created project.
• Open MANIFEST.MF and add the following plugin dependencies:

org.eclipse.uml2

org.eclipse.uml2.uml

org.eclipse.uml2.uml.ecore.exporter

org.eclipse.uml2.uml.ecore.importer

org.eclipse.uml2.uml.resources

org.openarchitectureware.uml2.adapter

• Copy the to be converted Enterprise Architect EAP file to the src folder.
• Create an empty file called model.uml within the src folder.
  This would be your converted UML2 model after the workflow is run.
• Within this src folder create a workflow file (workflow.oaw) with the following content:

<?xml version=”1.0″ encoding=”UTF-8″?>

<workflow>

<property file=“workflow.properties”/>

<bean class=“oaw.uml2.Setup” standardUML2Setup=“true” />

<!– Metamodel-Definition –>

<bean id=“EmfMM” class=“oaw.type.emf.EmfMetaModel”>

<metaModelPackage value=“org.eclipse.emf.ecore.EcorePackage”/>

</bean>

<bean id=“UmlMM” class=“oaw.uml2.UML2MetaModel”/>

<component class=“oaw.uml2.toolsupport.ea.EA_Xmi2Exporter” >

<EapFile value=“${project_root}${ea_file}” />

<ModelFile value=“${model_file}” />

<PackageName value=“${model_pkg}” />

<Cleanup value=“true”/>

</component>

</workflow>

• Within this src folder create a workflow properties file (workflow.properties) with the following content:

project_root =

# EA filename

ea_file =

#Output UML2 filename

model_file =

#Package within EA Model

model_pkg =

• Fill in the missing values in the properties file.
  project_root: You could leave this empty
  ea_file: EAP file to be converted
  model_file: UML2 model to be created
  model_pkg: Package within EAP file to be converted (this could be the root package, if you want the whole file to be converted)

  The properties file might look, for example, as below:

project_root =

# EA filename

ea_file = src/2006-10-04 RiF-Meta-Modell_v1.1_PUBLIC.EAP

#Output UML2 filename

model_file = src/model.uml

#Package within EA Model

model_pkg = RIF/ExchangeFile

• If the project is setup correctly, it would look like this:
  

5. Running the openArchitectureWare workflow

• Run the workflow by selecting the workflow file (workflow.oaw) and choosing Run As -> oAW Worlflow from context menu.
• Enterprise Architect would now be started in the background.
• If the conversion is successful you would get a console output similiar to below:

0    INFO  WorkflowRunner     – ————————————————————————————–

0    INFO  WorkflowRunner     – openArchitectureWare 4.3.1, Build 20090107-2000PRD

0    INFO  WorkflowRunner     – (c) 2005-2008 openarchitectureware.org and contributors

0    INFO  WorkflowRunner     – ————————————————————————————–

0    INFO  WorkflowRunner     – running workflow: workflow.oaw

0    INFO  WorkflowRunner     -

1281 INFO  CompositeComponent – EA_Xmi2Exporter

1281 INFO  EA_Xmi2ExportBase  – UML2Exporter for EA (1.7.0-SNAPSHOT)

1281 INFO  EA_Xmi2ExportBase  –   EAP-File   : src\2006-10-04 RiF-Meta-Modell_v1.1_PUBLIC.EAP

1281 INFO  EA_Xmi2ExportBase  –   Package    : RIF/ExchangeFile

1281 INFO  EA_Xmi2ExportBase  –   OutputFile : src\model.uml

70266 INFO  EA_Xmi2ExportBase  – Start XML2.0-output …

86891 INFO  EA_Xmi2ExportBase  – XML2.0-Export done.

86891 INFO  WorkflowRunner     – workflow completed in 85610ms!

• model.uml file would now be the converted UML2 file.

If you are a Microsoft Windows user and want to install OSEE (Open System Engineering Environment), you are plain lucky. The “platform independent” OSEE at the moment seems highly tuned to run on Windows. Follow the pointers here and you could get OSEE installed on Windows in no time. Coming back to the discriminated Mac OS X users, the hard truth is – the current version of OSEE (0.7.0) will NOT run on a Mac. But you could trick OSEE and make it run on a Mac with the steps below (but some features still does not work).

I wouldn’t advise to do this on a live/production environment. Try to get a Windows box and install OSEE or if you have only a Mac, install OSEE using a virtual machine like VirtualBox.

Why can’t OSEE run on Mac OS X?

One of the major reasons for this is that the current version of OSEE (0.7.0) requires Java 1.6 to run. Though Apple delivered 1.6.0 for Leopard, they delivered only a 64 bit version of it (and has no plans as of now to deliver a 32 bit version). Eclipse (more precisely SWT) cannot make use of 64bit unless you are using Eclipse Galileo Cocoa 64 bit. Unfortunately, OSEE client doesn’t run on Galileo Cocoa 64 bit, due to missing plugin dependencies. This leaves us with no option but use OSEE client with Eclipse Ganymede (3.4.2) as prescribed, by cheating it a bit.

Preparation

You need the following to make OSEE database, server and client run on a Mac.

1. PostgreSQL 8.4.0 (Download)

2. OSEE Application Server 0.7.0 (Download)

3. Eclipse (3.4.2) Ganyemde IDE for Java and Report Developers (Download)

4. OSEE Client 0.7.0 (Download)

5. OSEE Addons 0.7.0 (Download)

The above are the basic items you would need to run OSEE on any platform (unless you decide to use a database other than PostgresSQL). To run OSEE on Mac you additionally need:

6. SoyLatte Java 6 Port 1.0.2 (Download - Use username: “jrl” and password: “I am a Licensee in good standing”. Please note that SoyLatte 1.0.3 would not work)

7. WebKit Build for Safari 3.2.1 (Download – If you have Safari 4.0+ installed, YOU NEED this)

8. A bunch of shell scripts I made to make things easy (Download)

You can download these separately and configure it yourself or download the configured All-in-one bundle I made from here. Download and extract it to any folder, for example, $HOME/OSEE. The PostgresSQL installer is however not included in the bundle. You need to download and install it as per the steps below.

Installing PostGresSql

1. Run the PostgresSQL installer and follow the wizard, leaving the defaults as it is (unless you know what you are doing).
2. In the Password form enter password as “postgres” and confirm it. This is the password to be used for the superuser account (postgres) in the database cluster.

3. In the last step, UNCHECK “Launch Stack Builder at exit?”

Setting up PostGresSql for OSEE

PostGresSql installation creates a new service user account in your OS (this is different from the “postgres” super account in the database, the password for which you already provided in the wizard during installation). This is a standard OS user who could start/stop/administer the database. You need to set a password for this user to enable you to do database operations in the future.

1. Start Terminal and execute the following

sudo passwd postgres

Enter the new password as “postgres” and confirm.

Don’t be surprised if you see a new user called PostGresSQL the next time you log in to your OS.

2. Launch “pgAdmin III” from Applications.

3. Double Click on PostgreSQL Database Server (listed under Servers on the left hand side). If you are prompted for a password, type the password “postgres” selected during installation (user should be postgres by default)

4. OSEE needs a special database account named “osee”.To create it, right-click on Login Roles (at the bottom of the tree on the left hand side) and select “New Login Role…”. Enter the following in the dialog.

Please forgive me for the German text in screenshots

5. OSEE also needs a special database named “OSEE”. To create it, right-click on Databases and select “New Database…”. Enter the following in the dialog.

6. Click on OSEE and expand it and expand Schemas. Create a ”osee” schema by right-clicking on Schemas and selecting “New Schema…”. Enter the following in the dialog.

Starting PostGresSql

The installer starts up the database after it is finished. Also you could start/stop the database manually as follows:

1. Start Terminal and navigate to the “scripts” folder of the All-in-one bundle.

2. Execute the following:

./pg.sh start

3. Enter the password as “postgres”. This is the password for the service user account PostGresSQL created.

4. You could stop the database later by the following

./pg.sh stop

Initializing PostGresSql for OSEE

Before OSEE can start using the database, you need to initialize it with the initialization steps below:

1. Start Terminal and navigate to the “scripts” folder of the All-in-one bundle.

2. Assuming that the database is already running with the step above, you need to start the application server by executing the following:

./startserver.sh

3. Start database initialization by

./initdb.sh

Starting OSEE client

Now you are ready to startup and use the OSEE client.

1. Start Terminal and navigate to the “scripts” folder of the All-in-one bundle.

2. Execute the following

./osee.sh

What doesn’t work yet

1. The XWidgets included in OSEE doesn’t seem to work properly on Mac. Hence you see an error while opening forms which has these widgets.

OSGi debugging can turn out to be a nightmare at times, especially when using OSGi declarative services. The steps below might provide some solace.

1. Using diag OSGi command

The OSGi console is automatically enabled if you launch your bundle from eclipse launch configuration as a “OSGi Framework”. Else you could add the argument -console to your launch configuration. This will enable the OSGi console upon run.

There are lot of OSGi commands that can be used from the console. You could get the list by simply typing help at the console.

To diagnose a particular bundle, type ss at the console to see its status. This would give you a list like, for example:

osgi> ss

Framework is launched.

id State Bundle
0 ACTIVE org.eclipse.osgi_3.4.0.v20080605-1900
1 ACTIVE org.eclipse.osgi.services_3.1.200.v20071203
2 ACTIVE org.eclipse.equinox.ds_1.0.0.v20080427-0830
3 ACTIVE org.my.bundle._1.0.0
4 ACTIVE org.his.bundle_1.0.0
5 ACTIVE org.her.bundle_1.0.0
6 ACTIVE org.eclipse.equinox.util_1.0.0.v20080414

Use the command diag to diagnose a particular bundle.

For instance,

osgi> diag 3

initial@reference:file:plugins/org.my.bundle._1.0.0.jar/ [1]
Direct constraints which are unresolved:
Missing imported package org.someones.bundle_0.0.0.

3 is the id of the bundle org.my.bundle._1.0.0 above

2. Using -Dequinox.ds.print=true

Using VM argument -Dequinox.ds.print=true in your Launch configuration will echo all error messages to your console.

3. Using OSGi logging service

Start the OSGI bundle org.eclipse.equinox.log. With this bundle enabled, you could use the command log in your OSGi console.

For example,

osgi> log

>Info [2] Log created; Log Size=100; Log Threshold=4 initial@reference:file:plugins/org.eclipse.equinox.log_1.1.0.v20080414.jar/
>Info [2] ServiceEvent REGISTERED {service.id=23}
>Info [2] ServiceEvent REGISTERED {service.id=24}
>Info [2] ServiceEvent REGISTERED {service.id=25}