|Repository Support||Round-Trip Engineering|
|Exporting Diagrams||HTML Documentation|
|Part Two||Model Navigation||Pick Lists|
Version 3 of Together/J by TogetherSoft is impressive in both its breadth and depth of functionality. We've taken the time to perform an in-depth review of this ground-breaking UML modeling tool. 'A Review in Progress' is meant to convey both that this review is still ongoing as well as the huge progress we have seen in this UML design tool.
Since this evaluation took place over time, and because TogetherSoft has been assiduously updating their versions, several 3.X versions of TJ3 were tested over this time span, and continual improvements in the software were noted. The latest version of TJ3 tested was version 3.2, build 895, dated 3/4/2000.
Our test suite followed our own UML Tool Selection Criteria fairly closely. Links to these criteria are provided in the respective sections below and are identified by the following icon found to the left of each section title:
The test suite for TJ3 was run on two of today's dominant software development platforms: Red Hat Linux 6.0 and Microsoft Windows 2000. The configurations used to run the test suite are modest by today's standards. We set out to prove that a good system is adequate to run TJ3 - you don't need a top-of-the-line system.
A number of our tests were run using the CashSales sample model which is packaged with TJ3. This sample is a nice improvement over the FamilyTree sample model that was packaged with earlier versions of Together/J and shows how TogetherSoft has aimed its sites squarely at the business market with its new version. See a screenshot we took of TJ3 displaying the class diagram for the CashSales model.
To get an idea of the memory requirements of TJ3, we ran the Gnome System Monitor, an excellent utility for observing what's going on in a Linux system. When TJ3 was first launched, the memory requirements listed for java (the JVM) were 53 MB. Upon loading the sample model and doing some basic model navigation the memory footprint climbed up to 67 MB. This is a bit chunky, no doubt, but let's hold judgement until we see how TJ3 ran through our tests. Suffice it to say: 128 MB is a minimum memory configuration.
Building on TJ3's unique model-code synchronization capability, TogetherSoft has taken a similarly unique approach to supporting the functionality provided by a repository. Essentially, the source code is the basis for the repository. This may be considered to be a radical or even heretical approach by object purists, but it really does work! Moreover, this approach capitalizes on the significant investment in time and money organizations already make in version control systems (VCS).
This is how it works. You begin modeling and whenever class diagrams are being developed, TJ3 automatically synchronizes the source code with the model by creating or modifying corresponding Java files. At any point in this process the Java source files can be checked-in to the VCS system. Recall from our criteria that one major purpose of the repository is to enable joint development for large projects. By checking-in code to the VCS system, the code becomes the synchronization point for collaborating. When somebody on the project wants to change the model, the strategy is to check-out the relevant source files, make modifications using TJ3 and then check these changes back in through VCS.
TJ3 facilitates this use of the VCS system as the repository by providing outstanding integration with VCS systems. Support is included for SCC (Windows) and CVS (Linux). We tested with SCC support on Windows and found the integration with Microsoft's Source Safe to be excellent. You check files in and out of VCS by right clicking on a class in the Explorer Pane and selecting the Version Control menu. The following operations are supported from the menu: Add, Get, Check In, and Check Out. A little lock icon next to the class name in the Explorer Pane tells you the lock status of a given file.
Given the tight integration between TJ3 and VCS systems, it is surprising that TJ3 does not provide an easy way to persist a project itself to a repository. A TJ3 project consists of a TPR project file, diagram files, and files for other state information. When a development project uses the VCS system to 'take a label' against the code (identify a consistent version by a version label applied to all of the source files), this is an appropriate point to preserve and identify the matching UML design. We would like to see TJ3 be able to check-in a consistent set of model-specific information as a unit to the VCS system so that it can later on be checked-out and used as documentation for a version, or as the starting point for a new iteration. Providing a 'differencing' capability for models would also be nice but may be complex to implement.
Now you can see why TJ3's repository approach may be considered a bit radical if not heretical. By focusing a project so quickly on the generated code and relying on the code as the mechanism for collaborating, TJ3 can potentially detract the focus from higher-level modeling. In practice, though, our experience has shown that the advantages of model-code synchronization throughout the development lifecycle can outweigh these disadvantages. If TJ3 were to provide better versioning control support for the model itself, as we mentioned above, then this could help alleviate this issue of focus by allowing the model to be a unit which is shared as well as the code.
Our initial attempt at configuring TJ3's VCS integration was a little difficult because of inadequate documentation. It turns out that you need to use the Version Control dialog box, accessed from the Options->Default menu item, to setup the VCS integration first. See a screenshot of the Version Control dialog box. Subsequently you use the File->Project Properties dialogue to enable the version control feature for your project and associate your project with a module in the VCS system.
The most significant benefit of TJ3's repository strategy is the fact that it effectively leverages existing VCS infrastructures. Because VCS systems are out of necessity so reliable, they engender a strong degree of confidence in developers that the repository won't lose or corrupt a model. And because they are so familiar to developers, they are easily adopted as a repository for modeling information. As one additional note, VCS integration is becoming a standard feature for mature development tools today. Two prominent examples we are familiar with are Visual SlickEdit and Allaire's Homesite.
One feature distinguishes TJ3 from all other UML tools and this is the support for continuous model-code synchronization. As we mentioned earlier, the emphasis on code at early stages of model development is a radical idea. While radical, this approach is not new - Peter Coad and Dietrich Charisius, TogetherSoft's founders and chief architects, have been developing this novel approach to modeling for almost a decade.
One major rationale behind providing tight synchronization between the model and the code is to prevent a very common occurrence in other modeling environments - models become out of synchronization with code due to the effort to resynchronize them during or after the coding phase. Once this happens it becomes hard to use the model as documentation for the code as well as to use the model as the starting point for a new iteration.
TJ3 solves this problem by always analyzing the underlying Java source files to make sure that the model correctly reflects what they contain. What this accomplishes is that whenever code is modified outside of TJ3 at any phase of an iteration, resynchronization may occur simply by launching TJ3 and opening the project. Better yet, you may even change a Java file in an external editor or IDE and return to an open TJ3 project and TJ3 will note the file difference and instantly synchronize.
Two strengths enable TJ3 to function well in this type of development environment. The first is TJ3's extremely fast Java parser. This enables TJ3 to rapidly reverse engineer Java code whenever it detects a file update and to compare the class details with those reflected in the model in order to apply any updates. The other strength is TJ3's intelligent layout engine. Diagrams always reflect the latest state of a system and may be quickly redrawn by the layout engine to produce clean and attractive layouts.
By now you are probably wondering which comes first - the cart or the horse. Isn't modeling supposed to precede coding? In general the answer should always be yes. However, what TJ3 does is obscure what has until now been a basic assumption - that there is a clear demarcation between modeling and coding. This is an essential point. TJ3 breaks the rules and says that it is okay to work in a fluid environment, wherein you do what is comfortable while always maintaining the integrity of the model as a foundation for the design.
As a prime example of this flexibility, you may modify the code for a class in TJ3's editor window and hop back to the diagram, which will immediately show the results. Why would you want to do this? If working with the Java syntax is quicker and more natural, TJ3 says that this is okay. TJ3's flexibility allows you to do what is natural for you, rather than forcing you to struggle with the graphical editing of UML notations. Conversely, if you prefer to edit the UML notation, the editor window will instantly reflect the changes made to the underlying Java code.
One distinct advantage that this tight model-code synchronization provides is that TJ3 may be used to quickly create a model for existing code which may never have had a model or was modeled in another tool. When creating a project in an existing directory which contains Java source files, TJ3 immediately reverse-engineers the code to create the model and provides an automatic layout of the default class diagram. TJ3's first approximation at a layout is very good and is usually pretty close to what you want. This is an excellent way to document existing systems.
A caveat which should be mentioned when working with TJ3 on large projects is that TJ3 can slow down significantly if you create a monolithic project which contains a number of packages, each in a subdirectory. This is because TJ3's need to maintain synchronization requires it to analyze all the Java source in a project to detect changes when a project is opened or when focus is restored to TJ3 after using another tool. To avoid this scalability issue you may create multiple projects using package-level granularity and rely on importing classes from other packages to show coupling. A higher level project may then be created which imports the individual packages.
Another point to mention is that TJ3 does use code markers which show up as javadoc-style comments in the Java code. Unless you are fanatical about the way your code looks, these are not problematical at all.
TJ3 provides the capability of exporting diagrams in two different image formats: GIF and WMF (Windows meta-file format). The performance is fairly quick once the JVM loads the required class files to do the export (i.e. may be slow the first time).
We found the export of WMF files to be an intriguing feature because this file format uses vectors to store the diagram. What is intriguing about vectors? Because vectors may be scaled when the diagram is imported into the target environment.
We ran a test of this feature by exporting the CashSales class diagram as a WMF file and then importing the diagram into Microsoft Word. When we first printed the diagram from Word, some of the details inside the classes were truncated width-wise. This happened because the diagram was too wide for the page if it were to be drawn to scale, and therefore the boxes for the classes were made narrow enough so that the whole diagram would fit on the page, leaving insufficient width for the details inside each class. By decreasing the height of the diagram and increasing the width a bit more we were able to quickly get the desired result and the diagram could be printed with full visibility of all of the details.
Based on our tests with TJ3-produced WMF files we became pretty convinced that a vector graphic format is the best export format for importation into other documents, if it can be used. However, WMF files are limited to import into Microsoft-platform applications. Another proprietary format, Postcript (PS), is also a candidate for UML tools vendors to employ for scalable vector graphics. Postcript has wider industry support, especially in the publishing industry.
However, neither WMF nor Postscript are supported in today's generation of web browsers. (Although PDF, which may be created from Postscript documents, is supported by web browsers, nevertheless, you must purchase PDF Writer/Distiller software separately). Recall that our original criterion for Exporting Diagrams was based on importation into either a published document or a web browser.
To achieve true standards-based vector graphics export/import functionality, UML tools vendors will soon have an option, hopefully. The Scalable Vector Graphics (SVG) recommendation from the W3C is an XML grammar for stylable graphics which has progressed to a mature version 1.0 specification in "last call review" stage (3/3/2000). Once fully approved you may look to HTML browser vendors for support in their next-generation browsers.
Why SVG? Because a set of UML diagrams exported using this vector graphic format may be linked in with web pages. A reader of an "over the web" UML design document would be able to employ such graphical navigation techniques as zooming and panning within the browser to more easily explore a large UML diagram. Also, this format should dramatically improve the speed with which large diagrams may be loaded over the web compared to GIF-format diagrams. As proof, see how quickly Macromedia Flash presentations are loaded into the browser today! Based on these insights, we've added SVG to our wish-list criteria for UML tools, In the Future…
To highlight the dramatic difference between GIF images and scalable graphics in a publishing environment, we have prepared a simulation by creating an Adobe PDF file which includes two instances of the CashSales class diagram, one an imported GIF diagram and the other an imported WMF file, both created by TJ3's diagram export facility. You may download this PDF document and view it in Adobe Acrobat. Try zooming to a very high level such as 800 or 1600 percent and compare the results for the GIF diagram to the WMF diagram. This experiment is not unrealistic: you may want to prepare a wall chart which is scaled to a level which enhances readability.
HTML generation from the CashSales model worked like a charm under TJ3. Actually, the first time this test was run we were a bit doubtful and went back several times to repeat the test from a fresh launch of TJ3 to confirm the results. Granted the model is not exactly large, but remember this is supposed to be Java which is slow, right? OK, so let's see the results.
It took approximately 1 minute at 100% CPU utilization for TJ3 to generate the following:
Among the GIF files generated were the following diagrams:
As a sample of what TJ3 produces, see the screenshot we took of a browser displaying a class diagram.
The HTML produced by TJ3 employs frames to divide the browser window into 3 different portions:
Unless you have a lot of screen real estate, you most likely won't feel comfortable with the narrow view provided by the Diagram Frame. This is always a disadvantage when using frames within a browser. Fortunately, there is a trick that you may employ to get a better view of diagrams in the model: right click on the Diagram Frame and select Open Frame in New Window (Netscape) to have the browser create a separate window for the diagram.
The javadoc documentation format is employed by TJ3 for the class details in the Details Frame. TJ3 produces a very faithful javadoc rendition of class details. Other diagrams such as state and sequence diagrams do have associated javadoc-like documentation but are clearly outside the scope for which javadoc was intended. Nonetheless, the details for these diagrams are quite useful as well.
One of the slickest features of the HTML rendition is the highly effective use made of hyperlinks. Click on a class in a class diagram and a hyperlink quickly brings up the details for the selected class. Better yet, click on an operation within a class diagram and you will navigate straight to the definition for this operation in the Details Frame. Similar navigability features are demonstrated by the state and sequence diagrams produced for this example model. To achieve this, TJ3 produces quite a number of image maps and associated hyperlinks, no mean feat.
Copyright © 2000 Objects by Design, Inc. All rights reserved.