Message: choose option import only

You will be presented with a dialog explaining "import only" mode. Since we are only working here on "passive" reverse engineering, not code generation (forward engineering).  we will accept this option for increased efficiency by checking the option in the next dialog:

Choose code engineering set name and import-only option

You may use any name you like, here I simply use the name of the Application
(you may also choose to org.indicate.the.package.structure).

The Use set to import code only option is chosen because we will only be reverse engineering.

Edit code engineering set to select source

Once the code engineering set is created it will appear under the Code Engineering Sets node, however it is not yet populated.

Select the code engineering set and then choose Edit from its context menu ...

WARNING: reverse engineering changes can't be undone

Heed the warning before proceeding:

Reverse Options: default

At first you will be presented with the default reverse options, as shown.. We wil be fine tuning this options before proceeding:

Reverse options: fine tuning

I recommend that when reverse engineering a Java project for the first time you at least select the automatic class diagram generation, and explore also  the Model Visualizer, within the Visualization group.

WARNING: Unless you are experienced and familiar with the code I recommend that you DO NOT choose the option to Create class fields as Associations, because it will generate Associations to utility classes like java.lang.String and java.lang.Integer, as well as to trivial classes within your Application.

(Instead I will be showing you how to "create roles" for selected properties using the context menu or by "dragging" a Property out of a Class, which action also offers more cognitive reinforcement, as you witness an associative "connection" being generated before your eyes.)

If the code is unlikely to change, then you may wish to generate additional Analysis dependencies between Classifiers and Packages, however these can be difficult to maintain if code changes frequently, and for your first reverse engineering trials I recommend that you avoid them.

Create diagram for reverse engineering and choosing its name and location

Because I have selected the visualisation option to Create New Class Diagram I am now prompted for a name and location for the diagram. In this case I have chosen to name the diagram after the single Package containing all generated Class elements, and I am also placing it in that package (which can then be hyperlinked to that diagram).

After reverse always check the messages window to find any unresolved dependencies

Before you proceed to examine the generated model elements or diagrams it is a good idea to always check the messages window.

In this case we see that 2 Classes SingleFrameApplication and FrameView that are used by the JavaDesktopApplication have not been found, and model elements from them are created in the Default package, which you might like to think of as an "inbox" for unknown elements.  Checking in the IDE one can find these unresolved classes from appframework-1.0.3.jar, which are:

org.jdesktop.application.SingleFrameApplication
org.jdesktop.application.FrameView

You now have some choices:

1. ignore the warning and live with the unresolved classes SingleFrameApplication and FrameView polluting your model in the Defaults package
2. massage the unresolved classes by hand into a manually created UML Package org/jdesktop/application (very error prone)
3. delete the unresolved classes and repeat the reverse after adding the required JAR to the the classpath (much better, see next pages)

If the appframework-1.0.3.jar had been included in advance in the classpath the problem (deliberately provoked for this tutorial) would not have arisen, so it is a good idea to examine dependencies as much as possible in your IDE before performing reverse on large applications.

Creating navigable package diagrams and focus diagrams

As a first shot I've used Select All to apply Symbol Properties to all elements to Suppress Attributes and Suppress Operations, following be the Organic Layout. This forms a good starting point to navigate to hyperlinked "focus diagrams" for each Class.

Unfortunately this code is not very "UML-friendly", there are not obvious relationships between the Classes, and because "create Dependencies" was not used the reverse has relied entirely on Java fields, so there is nothing here to "wire up" yet. We'll return to this theme later.

Let's now create some focus class diagrams and hyperlink to them from the featured classes.

Analysing a Class and its nearest neighbours in a "focus" diagram

The JavaDesktopAboutBox Class has a single Java field, shown in the model as a UML attribute Property closeButton: JButton.

Next we will now see how to convert this attribute (a text representation) into a Property end of an Association (a graphical representation).

/*
* JavaDesktopAboutBox.java
*/
package javadesktopapplication;
import org.jdesktop.application.Action;
public class JavaDesktopAboutBox extends javax.swing.JDialog {
public JavaDesktopAboutBox(java.awt.Frame parent) {
super(parent);
initComponents();
getRootPane().setDefaultButton(closeButton);
}
@Action public void closeAboutBox() {
setVisible(false);
}
/** This method is called from within the constructor to
* initialize the form.
* WARNING: Do NOT modify this code. The content of this method is
* always regenerated by the Form Editor.
*/
//
private void initComponents() {
..
setDefaultCloseOperation(javax.swing.WindowConstants.DISPOSE_ON_CLOSE);
..
getContentPane().setLayout(layout);
..
pack();
}
// Variables declaration - do not modify                     
private javax.swing.JButton closeButton;
// End of variables declaration                       
} 

Reversing from bytecode by reversing from classpath

We now wish to explore those operations of JDialog that are inherited and used by JavaDesktopAboutBox.

Since the JDK jars are already included in the project's Java classpath, we can use the convenient Reverse from Classpath menu ..

Displaying only selected attributes/fields and operations/methods using Edit Compartment

We now choose to display with Edit Compartment > Operations only those operations of JDialog inherited and used by JavaDesktopAboutBox

Exploring beyond the nearest neighbour in a "focus" diagram

It turns out that JavaDesktopAboutBox uses operations from higher up than its immediate Generalization supplier JDialog. Let us now explore a bit wider, more than 1 relationship away from the "focus" element JavaDesktopAboutBox.

While it is possible in MagicDraw UML to Display Related Elements to infinite depth, I advise against it in most cases; one is far more likely to create manageable diagrams and to learn more by moving 1 step at a time out from an element of interest .. 

Managing physical, logical, and graphical groupings of software model elements

Let us now turn our attention to the reverse engineered JavaDesktopView class, which has a number of Properties typed by classes from javax.swing.

It will soon be seen that if one converts these attributes to Property ends of Associations the focus diagram for JavaDesktopView can become unwieldy ..

Using physical packaging to group Class symbols graphically

In the JavaDesktopView example all attributes that were turned into Property ends of Associations were from the same Package (javax.swing) so one can easily group them graphically using a Package. All of the grouped elements can now be moved at once (easier and more robust than using multi-select).

Notice how I've chosen to show the package name with its owner in the tab, and the owner need then not be shown for the owned Classes.

Extreme care must be taken when moving Class symbols into Package symbols in diagrams that the ownership is not changed ! Check the ownerships carefully first lest you corrupt the model !

Depending on the system involved this physical grouping strategy can be quite effective, and it works quite well when only a few packages are involved, however it does not scale well in all systems, and although quite widespread this practice is NOT robust against changes in the design and/or packaging ! The most flexible grouping can be achieved with "parasitic" logical grouping that does not affect the ownership and enables far more flexble diagramming and representation of class collaborations.

Creating a "focus" Class diagram with immediate Associations

I have created a "focus" Class Diagram for javavariables.Main, which I've hyperlinked to Main by dragging the diagram icon from the model browser onto the Main Class symbol in this same diagram.

Because Main does not know directly of the strange Package's implementations, they are not shown in this diagram, for that would preempt implementations of Thing and Factory.

There remains however one explicit reference to an default implementation Thing_ (and later we'll discover that there are also references to Thing_ and Factory_ implementations in the methods through local variables, however these are not exposed as Associations, because they don't reverse from Java fields to UML attributes or Property ends of Associations).

Java users new to UML should note carefully how a visibility indicator appears on the Property at the end of each Association to Thing:

• '+' indicates 'public'
• '#' indicates 'protected'
• '-' indicated 'private'

The same indicators appear on the remaining attributes (which we'll examine in detail soon).

Let's see first how the package overview might look .. 

Improved Package Overview diagram

The Package Overview Diagram has been improved:

• Features of Classifiers are not shown except:
  • the features of the Thing Interface are shown to enable the 3 Associations to it to be drawn easily (a compromise)
• The packaging of the strange implementations has been shown
• One can also see 2 additional classes involving arrays and containers we'll examine shortly
• Some loose grouping of elements concerning factories and elements concerning things have been made

Before resuming our study on lets's look briefly at one strategy for logically grouping and graphically the elements to do with factories and things ..

One can show a Property as both an attribute and as a Property end of an Association

Here I have dragged the CLASSY_THING : Thing Property out of the attributes compartment of javavariables.Main to create an Association with it as the Property end. I have then also selected the option [All] under Symbol Properties >  Show Association Ends as Attributes:

Now one can see the Property in both the attributes compartment as a Property end of an Association !

BTW one can also use a "callout" into a Note to get at information not otherwise displayed on an Association end.

Visit also:

• How do I get a Class to still show attributes converted to roles (Association ends) ?

Reversing Java collections

The class javavariables.HasCollections has some Java lists, sets, and maps:

 public List<Thing> lThings; 

 public List<List<Thing>> lolThings;

 public List<String> lStrings;

 public Map<String,Thing> map;
}

Let's see first what happens on reverse if we select the option to Resolve collection generics ...

Choose packages for package Dependency Diagram

Make sure that you only select those packages required, and avoid the UML profiles and the top-level package (usually called Data), and don't select packages from the FileView unless really required ..

Resulting Package Overview Diagram with «virtual» Dependencies

On choosing Finish (without fine tuning selected relationships and symbol properties) we have an automatically generated Package Overview Diagram with «virtual» Dependencies, and automatic layout.

Sequence diagram reverse of static method Main.main()

As another example, here is the reverse of the javavariables.Main.main() method (adapted slightly), which shows how it first gets a defaultThing(), then a newThingViaFactory() (with the default configured Factory), and then it configures itself with a StrangeFactory_ implementation before again getting a newThingViaFactory(). Note that there are 2 sequence diagram LifeLines representing the two different assignments of Thing implementations to the one local Java variable Thing factoryThing as different times.

Showing elements related to the elements of a Package

Here I've used Related Elements > Display Related Elements to show the InterfaceRealizations and Generalizations from the elements of Package strange. I've also used Display Elements > Display Paths to show the virtual Dependency of Factory on Thing. This already provides some context for the elements of strange.

Here are some subtle tips about how I've diagrammed:

• I've chosen to include the strange Package symbol in the diagram, which provides a clear boundary for its elements, and I'm also showing its (owner) so that I don't have to show the owner on its contained elements.
• I am showing the (owner) of all other supplier elements.
• There is no need here to show the operations of the Interfaces because they are clear from the overriding strange classes
• One might be tempted to also  "package" the supplier elements, and this can be useful when they are from a stable library, however in general that strategy does not scale well; if the physical ownership of the supplier elements changes it would corrupt this diagram, a very unwelcome form of graphical coupling !
• The fact that StrangeThing_ extends Thing_ is in fact only an implementation detail (it could just as easily implement out() directly) so I've placed Class Thing_ "on the other side" from the Interfaces. This trick is a theme you'll notice throughout this eSchool, one wishes to progressively indicate the spirit of service orientation and separation of interface/contract from implementation.

Would it be a good idea to also show here how the Package is used? Would it be nice to include - for example - Main, which uses the strange Package ? The problem with that strategy is that it introduces another form of graphical coupling, and it preempts the usage context of the strange classes. It can also prevent modularisation, which is a good way to test whether your diagramming style has too much coupling. It is often better to use a separate "architectural" diagram that shows the interactions of particular classes in a "class collaboration" ...

Avoiding elements external to a Package in its Package overview diagram and module

In this variation on a overview diagram for Package strange I've included some elements that use the strange elements either directly or indirectly. I've also used Display Elements > Display Paths to show the virtual Dependency of Factory on Thing, and similarly some other selected virtual Dependencies. And I've added a Usage from Main.main() to StrangeFactory_. What a mess ! This will never modularise, let's see why:

Firstly, note that although both Factory and Thing come from outside the strange Package, this package depends on them anyway, so having them in the diagram does no harm.

Including the client Main, however, is a problem, along with its owned Associations with end Properties thing_, uPublic,  and factory_.

Including the virtual Dependencies are also a Problem, because by default they are generated in the Virtual dependencies Package.

And even the annotation stereotype «AVOID» may be a problem unless it is packaged in a profile known to Package strange when modularised.

Let's see what happens when we attempt to create a module naively from this strange Package .. 

Reverse of LocalTest.Main() implementation to Sequence Diagram

Using Reverse Implementation one obtains more sense of architectural collaboration of elements in this simplified client-server system (although the choice of a StrangeFactory_) is still a bit buried. How can we code in Java in way that admits more access to this information already at the Class and Association level ?

Coding to expose Dependencies as Java fields with lazy initializers

Here I demonstrate a style of Java coding that supports generation of end Properties of Associations from explicit Java fields, rather than burying Dependencies as Java local variables. It enables one to "wire up" UML models of Java code associatively.

In UMLfriendlierTest there are explicit Java fields for the choices of LocalClient_ and StrangeFactory_, which are created and configured through "lazy" protected operations client() and factory(), which act as lazy variable operations; the fields are never used directly, only ever by calling the lazy ops.

Also, the Interfaces Serve and Manage are only accessed through service accessors  serve() and manage(), which in turn trigger the lazy server() method. I call this approach cascading lazy methods, and it makes for very tidy and systematic coding, because one always knows where a field is initialized (in the lazy op), and it is efficient because resources are only allocated if and when needed. (One can even code with cascading lazy ops for real-time work and create an entire system by calling one lazy op up front.) If no client-side initializationis required these service accessors could also be completely in the Server_ implementation.

From an implementation point of view there is no compelling need to create an explicit Manage manage_ field, as manage() can always just return server(), although it does help to store a Manage interface during initialization. It is there primarily to ensure that the UML model can be easily wired up associatively on reverse.

For comparison, I did not create an explicit Serve serve_ field, so it is not directly wired up from the UMLfriendlierTest. How can one indicate that Dependency without changing the Java code to admit an associative interpretation on reverse ?  One could use virtual Dependencies again (by choosing the option to Create Dependencies between Classifiers on reverse in MagicDraw UML). Alternatively, UML2 specifies a special "ball and socket" notation for Classifier-level Dependency wiring of provided and required Interfaces, which we'll examine briefly next ..

Architectural "ball and socket" Dependency wiring

By drawing a Usage relationship from a Classifer that "requires" a service to an Interface that is "provided" as an InterfaceRealization from another Classifier one can create a Ball-and-Socket notation, which is a concise architectural notation for Classifier level diagrams (not to be confused in MagicDraw UML with the Lollipop-and-Fork notation for ports, available both in Classifier level diagrams and in composite structure diagrams).

In the example below the Interfaces Serve, Manage, and Factory have been "dependency wired" using Ball-and-Socket notation. Each Interface is provided exactly one and required exactly once, demonstrating a complete system.

While the InterfaceRealizations are automatically created on reversing Java (from the Classes that implement a given Interface), there is no facility when reverse engineering in MagicDraw UML to automatically create the Usage relationships (which are subject to architectural interpretation).Thus, if you are relying on reverse-engineering only, I advise you to create UML-friendly explicit Java fields to promote a graphical associative representation of these dependencies as end Properties of Associations to complement the "manual" Usage notation.

Custom forward-engineering suites and MDA system can however generate corresponding Java fields from Ball-and-Socket notation.

The Convert To Port menu item

The Convert To > Port menu item is available on attribute Properties (only).

Viewing Ports as "little square boxes" on the boundary of a Class in a Class diagram

You can also display Ports on a Class in Class diagram using "little square box notation" (one can in fact resize the box to any rectangular size) by choosing the context menu item Related Elements > Display Ports:

You can then select to display all or only particular ports in a checkbox selection dialog (see image below).

If you choose this representation please DO NOT attempt to connect the ports up externally in class diagram ! Connectors are instance-like (or Link-like) and have nothing to seek in a class diagram, except within the internal structure compartment of a Class. 

Port-based server in Class diagram with boundary

Here is a graphical port-based representation of the port-based server example in Class Diagram.

One can optionally choose to show the Type of the Port, or also to not show the name (often the Type is sufficient to indicate the role of a Port).

Note how the InterfaceRealizations to the provided Interfaces are automatically created.

If they are not present you can use Related Elements > Display Paths.

(If there is more than one InterfaceRealization or Usage to an Interface it is not an error, it is an indication that there is architectural redundancy in the Dependency Wiring.)

Client with usage Port class

Here is the first step in representing a Java client with a "usage Port", one that "requires" an Interface. I've reversed to attribute Properties only. 

Only the inner class Serve$ uses the Serve Interface directly, not the outer Class PortClient, which only ever calls Serve$.getNameOfNewThing().

Let's now see how this can be represented graphically .. 

Review of some relationships indicating "usage"

I have applied the same procedure to create a usage Port manage$:Manage$ which requires the Interface Manage, as indicated by a Usage relationship.

The class Administrator uses Interface Manage indirectly - via the requiring Port typed by Manage$ - to set a Factory of some unspecified service provider to be a StrangeFactory_ implementation. In as sense it also "uses" the StrangeFactory_, and this is also indicated with a Usage relationship. One must take care not to confuse these usages of Usage (excuse the UML puns).

I have also shown the reverse-engineered Property manage_:Manage at the end of an Association from the requiring port class Manage$, which is yet another way to indicate usage (however it is NOT a UML Usage relationship).

We'll now see why it is important to indeed use the UML Usage from a requiring Port when building composite structures (leveraging the holon nature of EncapsulatedClassifiers) ...

Composite Structure Diagram with provided "lollipops" and required "forks" Interface notation

Unlike in the Classifier-level Dependency Wiring "Ball-and-Socket" notation, the instance-level "lollipop and fork" notation for provided and required interfaces does NOT show an editable Interface symbol (because an Interface is a Classifier).  It is information about the Port of a Property (and indeed if you click on a "lollipop" or "fork" it will open up into a Port spec dialog).

I've also include some Connectors manually, i.e. they aren't generated on reverse engineering the Java code. 

So what do UML connections correspond to in Java ? And how can we interpret them under reverse engineering ?

Next we'll see an interpretation in Java code of connecting these elements up .. 

Assembly connections as Java references to services

One interpretation of "assembly connection" in a Java system is the passing of a reference to a required service Interface.

This is illustrated in the following code, where references to the Manage and Serve Interfaces are obtained from the port-based PortServer_ (via an Interface PortServer) and passed to the port-based classes Administrator and PortClient on construction (in lazy instantiators), which in turn pass those references to their Ports' constructors. This approach combines well with cascading lazy instantiators, so that the entire creation and wiring up of the system is triggered in the top-level system constructor in advance (if desired) or as and when needed.

public class PortBasedComposite {

 private PortServer_ server_;

 @Lazy
 protected PortServer server() {
  if (server_==null) {
   server_ = new PortServer_();
  }
  return server_;
 }

 private PortClient client_;  

 @Lazy
 protected PortClient client() {
  if (client_==null) {
   client_ = new PortClient(server().serve()); //connect !
   client_.printNameOfThing();
  }
  return client_;
 }

 private Administrator administrator_;

 @Lazy
 protected Administrator administrator() {
  if (administrator_==null) {
   administrator_ = new Administrator(server().manage()); //connect !
  }
  return administrator_;
 }

 public PortBasedComposite () {
  administrator();
  client();
 }

 public static void main(String[] args) {
  new PortBasedComposite();
 }
}

There are however some problems with this naive strategy:

• A UML Interface does not have Ports, so a symbol of a Property typed by Interface PortServer in a composite structure diagram can't show Ports; the server with ports is not well encapsulated.
• The Ports of the port-based classes seem to be bound to particular implementations of provided and required Interfaces.
• While the "Connector as reference" approach works ok for simple Ports that provide 1 Interface, it turns out that it does not scale well to complex Ports.

What is needed is a better abstraction of the port-based contract than is possible with a UML Interface, as well as abstract Port implementors that define only what Interfaces are required and provided, without stating where or how they are required and provided, so that they can be flexibly delegated to different internal parts with Ports.  For this purpose a new example and some useful terms and definitions will be introduced ..

The «portface» Class as abstract contract for a service provided by a Port

This diagram introduces the elements and notation for the simplest possible truly abstracted and encapsulated port-based service under my Java-friendly "Portface" recipe, tuned for MagicDraw UML.

A simple service Serve with an operation doServe() will appear to be provided by an abstract Server "Portface" Class via a Port serve_:Serve_, where Serve_ is an abstract «port» Class. The Server «portface» contract is implemented by the concrete Server_ Class, which creates - in its implementation of the abstract "hook" port creation method myServe_() - a concrete Serve__ implementation of the Serve_ «port» Class (which in turn promises to provide the Serve service Interface).

Easy, obvious, and no sneaky tricks, right ? Let's walk through it carefully to find out why, what, when and whether ..

Serve: is an Interface with no special characteristics. It could be any interface from an existing system. It is not named IServe "Eclipse-style", although it would not be deadly if it were. (We'll see soon that the use of 'I' as a prefix in front of every Interface quickly leads to pollution in the UML models, especially in the provided/required "lollipop/fork" notation, however you are free to use it if you wish.) Typically Serve would have a number of operations, which should be named as verbs like serve(), doServe(), serveFast(), serveSlow(), serveSecure() etc. Note that it is NOT named "Server" (which is rather the thing that owns the port that offers the service), and it is not a noun ! It is named after the "archetypal" verb action of the operations it provides, which ideally represent collectively a certain aspect of the system.

Serve_: is an abstract Class that promises to provide the Serve interface (eventually). It would be tempting to already implement doServe() in a concrete Serve_, however that makes it difficult to sensibly delegate from Ports typed by it, i.e. it would break the rules of substitutable encapsulation that we wish to achieve with port-based software engineering in the first place. Also, as we'll see shortly, implementing directly in a concrete Port does not scale well when dealing with complex ports that provide and/or require more than 1 Interface, so to keep the pattern consistent Serve_ has to be abstract. It will be called the abstract port implementor.

Server: is the abstract «portface» Class that defines the port contract. A clients will interact with a usage of Server via its public Ports, or alternatively via the service accessors (like serve()), that - after the pattern of the recipe - will return a serve_:Serve_ that is known to provide a Serve Interface.We'll explore as we go the difference between a client depending only on a specific Interface service (obtained via a service accessor operation, which is a BehavioralFeature ), and a client depending on a public Port (a StructuralFeature). In any case either the client has to have access to a Feature of the Server, or it has to be passed a reference from another player that "connects" the client to the Port (or possibly only to the Interface provided by the Port).

In the reversed UML model the Java field Serve_ serve_; appears as a Port serve_:Serve_ (noting that Port extends Property). The existence of serve_ is ensured by the abstract "hook" Server.myServe_(), which in the concrete implementation of the Server will typically trigger creation of a compatible port implementation, or will eventually return a delegate that meets the contract for the abstract port class Serve_.

So why - given that the provided Interface Serve can be accessed by public accessors like serve() on the parent Portface anyway - is the Port serve_:Serve_ public ? Doesn't that also break encapsulation ? Not if the Class typing the Port is abstract and if it does not offer any public methods other than those promised through the provided Interfaces. Because serve_:Serve_ is public it can be exported from the boundary of an internal :Server to the boundary of an external higher-order system.

Server_: is a concrete implementation of the abstract «portface» Server. Because this is a simple implementation (it will not delegate to ports of internal part Properties), in its implementation of the port creator myServe_() it will merely return an instance of its local concrete implementation Serve__ (note the double underline) of the abstract port class Serve_, keeping in mind that in general a «portface» Class might provide n services via m ports, so it implementations might have to offer (or fetch from factories) implementations of many Port types.

This case does not however require any Interfaces, it only provides a single Interface. Next we'll see how to handle required Interfaces as well ..

A service required via a Port of a «portface» Class

The abstract Manager «portface»  Class requires a service Help via a port manage_:Manage_, where Manage_ is an abstract «port»  Class that also provides a Manage service. The constructor of Manager invites injection of a Help Interface, which it then passes to the Manage_(help:Help) constructor on creation of its port manage_ via the port creation "hook" myManage(help:Help):Manage_ , which has a parameter for a Help. The abstract Manage_ stores the Help in a protected help_, which can then be accessed in the concrete implementation Manage__ of the abstract port Class Manage_.

As far as clients of a Manager are concerned there is only a service accessor manage():Manage; there is no need for clients to have access to or know about the existence of a Help within the Manager, nor how it is used.

Let's now combine the Server and the Manager to build a more complex system, ensuring that the Manager is given the required Help ..