Login | Register
My pages Projects Community openCollabNet

argouml
Wiki: Extending ArgoUML

Edit this page | Links to this page | Page information | Attachments | Refresh page

 

This section explains some general concepts which come in handy, when developing additions to ArgoUML.

How do I ...?

...get the corresponding UML element for a given Fig''XXX'' object?

Each Fig''XXX'' implements the method getOwner() which returns the appropriate owner element which is responsible for this Fig element.

...get the corresponding Fig element for a given ModelElement?

for this one needs to iterate through all Fig objects and invoke getOwner. Compare the result with the given ModelElement. Be aware that there might be more than one Fig object for a given ModelElement if it appears in multiple diagrams or there may be none if it has no diagrams.

Modules

The ArgoUML tool provides a basis for UML design and potentially an executable architecture environment for more specialized applications. This is solved by a clear interfaces between the ArgoUML core and the extensions. Extensions are called modules.

Modules

Modules

A module is a collection of classes and resource files that can be enabled and disabled in ArgoUML. Currently this is decided by the module's availability when ArgoUML starts but in the future it could be made possible to enable modules from within a running ArgoUML.

This module system is the extension capability to the ArgoUML tool. It gives developers of ArgoUML and developers of applications running within the ArgoUML architecture the ability to add functionality to the ArgoUML environment without modifying the basic ArgoUML tool. This flexibility is designed to encourage additional open source and/or commercial involvement with the open source UML tool.

The module extensions load when ArgoUML starts. When the modules are loaded they have the capability of attaching to internal ArgoUML architectural elements. Once the plugins are attached, the plugins will receive calls at the right moment and can perform the correct action at that point.

Modules can be internal and external. The only difference is that the internal modules are part of the argouml.jar and the external are delivered as separate jar-files.

This is essentially and implementation of the Dynamic Linkage pattern as described in Patterns in Java Volume 1 by Mark Grand ISBN 0-471-25839-3. The whole of ArgoUML Core is the Environment, the classes inheriting Pluggable are the AbstractLoadableClass.

Modules

Module Architecture

The controlling class for the implementation is org.argouml.moduleloader.ModuleLoader2. It is a singleton created when first used. It is first used in the main initialization routine.

When created it searches through all available modules and creates a list of their main objects (implementing ModuleInterface). Currently (September 2004) this also means that the found modules are by default selected i.e. they are marked to be enabled.

At the end of the main initialization routine the selected modules are enabled. (The original idea was to do this several times during the main routine to allow for modules to add command line arguments, add languages, and make functions available for batch command, but the example used for testing loaded the ?ProjectBrowser "too early" and the result wasn't so good. I (Linus) hope this can be eventually fixed.)

The {{{ModuleInterface}}} interface

Each class used by the ModuleLoader2 must implement the ModuleInterface interface.

This interface has methods for enabling, disabling and identifying the module.

When a module is enabled it is expected to register some class wherever it affects ArgoUML using the interfaces provided there. Since the same interfaces and registration mechanism is used internally within ArgoUML there is a small likelyhood that there already is an interface and a possibility to register. If there isn't, ArgoUML cannot currently be extended at that point. If you still need ArgoUML to be extended at that point you will have to work in getting this interface or registration mechanism implemented within ArgoUML. (This could also be another module that has to be amended.)

Classes administered by the module that registers to whatever place of ArgoUML they are interested in, does not need to have any connection to the module loader. They are written exactly as if they would have been if they were part of the core ArgoUML.

Using Modules

When modules are used they can't be distinguished from the rest of the ArgoUML environment.

How do I ...?

...tell when a module is enabled?

The method isEnabled in ModuleLoader2 returns true if the module with that name is enabled and false otherwise.

Tip for creating new modules (from Florent de Lamotte)

/!\ CategoryFix: This description is for the old moduleloader.

Florent wrote a small tutorial for creating modules. It can be found on the ArgoPNO website.

How are modules organized in the Java code?

The previous section describes how modules and plug-ins are organized at the Java level independent of how they are actually packaged.

Within the ArgoUML project some parts of the code are developed and packaged separately from the main ArgoUML source code. This section describes how they are organized and how you create such source-code modules.

Requirements on modules

An external module requires:

The module main class implements org.argouml.moduleloader.ModuleInterface

Archive the main class into a jar, with an entry "Name" in MANIFEST.MF specifying the name of the main class. For example, Name:

Name: your/own/domain/your/package/your.class

The class in question must implement org.argouml.moduleloader.ModuleInterface.

Put the jar file into a directory called ext under the home directory of ArgoUML

Run ArgoUML and check if the module appears in Edit -> Settings -> Modules

New modules that are added to ArgoUML shall reside in whole new packages. Either you put your module classes in your.own.domain .your.package.name or if you want to emphasize the connection to ArgoUML you can use org.argouml.your.package.name where your.package.name is the name of your addition.

How do I ...?

...create a new source-code module.

Suggestion, copy from the menutest module as described here.

Make a copy of argouml/modules/menutest into argouml/modules/your name.

Add any jar you need to argouml/modules/your name /lib and add references to each of the jars in argouml/modules/your name/build.xml.

Edit argouml/modules/your name /module.properties

Edit argouml/modules/your name/src/org/manifest.mf.

Reorganize the source files as necessary. Remove the directory argouml/modules/your name /src/org/argouml/ui and create your own classes like org.argouml.your package name in argouml/modules/your name /src/org/argouml/your package name.

...get Argo to use a plug-in?

/!\ CategoryFix: This description is for the old module loader.

Once you've created a jar file with a plug-in in it, you need to make sure that Argo can find the jar to be able to execute it.

If you are using a "standard" ArgoUML source structure, then you should be able to execute build install or ant install in the source directory of the plug-in. This will copy the jar file to the proper directory in the main ArgoUML build target. You can test your plug-in by running build run in the src_new directory.

If you need to install the jar "the hard way", try the following steps.

Start up ArgoUML.

Go to the menu Edit->Settings and look at the Environment tab. Find the entry labeled ${argo.ext.dir}. Create that directory if it does not already exist.

Copy the plug-in jar and any other jars required by it into that directory.

Start up ArgoUML again, and you should see the plug-in's startup banner (if it has one, of course).


CategoryFromCookbook

Extending ArgoUML (last edited 2009-02-08 09:18:51 -0700 by linus)