Spring Issue, April 2000 - IBM...Working with XML Documents in UML jim conallen jim is the Web Modeling Evangelist for Rational Software. The XML technological revolution, like most

Spring Issue, April 2000

Cover Story

Working with XML Documents in UMLjim conallen

Features

Partner Perspective: Integrating Legacy Applications Using XMLChris Holmes and Rich Newcomb

Grokking COM+UML: The Server-Centric ModelDr. Al Major

System Integration, Manufacturing Process, and Warm Potato SaladChristian Buckley and Darren Pulsipher

Database Modeling and Design Using Rational Rose 2000eEric Naiburg

Consistency CheckingMichael Moors

Bridge the Gap Between UML Modeling and EJB DevelopmentKevin E. Kelly

From Waterfall to Iterative LifecyclePhilippe Kruchten

Departments

Publisher's Note Magnus Christerson

Editor's EmailTerry Quatrani

Amigo Page Grady BoochAll Good Things

Rose 101 Naveena BerenyEpilogue

Extreme Rosejim conallenWorking with XML Documents in UML

Extending RoseJohn HsiaCommon Questions from Experienced REI Users

the web modelerjim conallenModeling Web Clients with UML and Rose

Copyright © 2000 Rational Software and CMP, a United News & Media company.

http://www.therationaledge.com/index.html

http://www.rational.com/rose

http://www.rational.com/uml

http://www.therationaledge.com/rosearchitect/mag/backissu.html

http://www.therationaledge.com/rosearchitect/sm/index.html

http://www.therationaledge.com/rosearchitect/products/index.html

http://www.therationaledge.com/rosearchitect/book/book.html

http://www.therationaledge.com/rosearchitect/contact/index.html

http://www.therationaledge.com/rosearchitect/index.html

http://www.rational.com/

http://www.cmp.com/

http://www.unm.com/

Working with XML Documents in UML

jim conallen

jim is the Web Modeling Evangelist for Rational Software.

The XML technological revolution, like most innovations related to the Web, is accompanied by a lot of confusion. Unfortunately, it will take a lot more than this simple article to clear up any of that. Instead, this article is intended for those fluent in UML and some XML, but haven't really thought about putting the two together before (or have thought about it, and decided that calling it an early day and making a trip to the pub would serve everyone's interests better). For those about to embark in this territory, fear not: the practicality and usefulness of expressing XML document structures in UML does make sense, and a lot of us have been thinking about it for some time now.

The first thing that needs to be addressed is why. I have been accused in the past of being a modeling zealot, and of modeling things in UML that really needn't be modeled. I once modeled the usage of a new water cooler in the office with UML, and had the use case diagram taped to the cooler for those unsure of its intended purpose. That was a case of frivolity. Modeling XML document structures, on the other hand, has very practical uses for system architects and designers. In fact, the use of XML documents for structured data interchange in a system can be considered architecturally significant.

What is of even more importance is the fact that designers and implementers will have to build systems that work with XML documents. As a result, designers and implementers are concerned with the structure of certain classes of XML documents, namely, Document Type Definitions (DTDs). An XML document is to a DTD what an object is to a class. When building systems, designers and implementers work with DTDs, not with individual XML document instances.

Even more useful than DTDs are schemas. Schemas in general are an alternative way to express XML document structures, most of which are expressed in XML itself. In this way, the same XML parser that parses the document also parses the document structure definition. XML Data is presently the most promising schema candidate for providing the most appropriate information for XML usage and definition. In addition to defining valid XML structures, schemas allow us to associate datatypes, comments, and other useful information with the structure. Unfortunately, only DTDs are recognized as an official standard, and it is likely










that most XML document interchange will rely on DTDs for document structure definition.

The modeling of DTDs, therefore, is what is of interest to the designer and implementer. A DTD represents a class of XML documents that will be used in the system. A DTD document specifies the structure and composition of an XML document instance. Systems are designed to receive and produce XML documents that validate against certain DTDs. The ability to express arbitrary DTDs with UML enables designers to include in the model the structure of information that is being interchanged externally or between different parts of the system.

Much more semantic information is expressed in the DTD itself (over the parser), which is generic by its very nature. The two most common types of parsers for XML are the Document Object Model (DOM) and the Simple API for XML (SAX). The DOM provides an object interface to an XML document, whereas the SAX uses an event-driven model for parsing. Even with these commonly available parsers, much of the work for implementers and designers is in navigating the documents.

Because the DOM provides a very generic interface to a document, a significant amount of work must be done to access document elements. Much of this work is repetitious and can very well be encapsulated and wrapped by a set of accessor classes. A similar situation exists for SAX. These interfaces present a situation where the designer and implementer are working primarily with (or against, depending on your level of cynicism) the API and not with the actual business-level content, where we would rather have our development teams working.

The role of DTDs in UML is one that expresses the structure of a class of XML documents that the system has to process (accept, modify, and produce). Having the DTD of documents that the system has to process incorporated in the UML model of the system allows designers to use it as a reference. The key to this is, of course, doing so at the appropriate level of abstraction and detail. For example, all XML documents can be modeled via the DOM, but just including the DOM in the model of your system is not of much practical use, especially when you know there is a limited set of document structures that your system will be processing. What is useful, however, is expressing the DTDs that your system uses in the UML, and then using them as reference points for the other parts of the system.

The typical scenario is this: an application needs to be created that works with an industry standard DTD - let's say in the office supply market. This standard was defined by an industry consortium to enable the electronic interchange of information between companies. My system needs to be able to accept and process XML documents that adhere to the DTD. I first express the DTD in my UML model of the system. We'll look at the proposed mapping in a minute. The next step an architect or designer might do is rework, or even extend the DTD. My particular company might accept this document, and even use it internally. However, when used internally, some additional elements might need to be added. Because this is a design-level activity, and is most likely a result of other factors already expressed in the UML model, making these changes in the model

with Rose makes a lot of sense.

The next step that would probably be taken is the creation of an object wrapper around the document. Since working with the DOM or SAX is tedious, and not where we want our development staff spending their time, the goal of the designer would be to create a customized object interface around the XML documents. This customized interface should provide an easier to use API for the developer, freeing him/her to concentrate on the task of implementing business logic, not XML logic. The good news is that several companies already provide utilities to automatically create a Java-based wrapper around XML document instances. IBM provides such capabilities with their Visual DTD application. Visual DTD is a DTD editing application that has an option to save a DTD as a schema and to generate Java code that, used in conjunction with its XML Toolkit and a couple of other classes, provides a reasonably intuitive interface to XML document instances without all the tedium of working directly with the DOM.

The bad news is that this direct mapping of DTD-to-Java code may not be the most suitable interface for the particular task at hand. It could be better. In our office supply scenario, one industry standard DTD would be used by different segments of the industry, some are suppliers, some retailers, others consumers. Depending upon who you are and your level of usage, your ideal interface to the document might be different. For example, retailers might be more concerned with summaries and totals, whereas consumers would be mostly concerned with sizes and colors. Creating these even more customized interfaces to XML documents requires some effort and skill on the part of the designer, and the tool and notation for doing this are Rose and UML. With the DTD expressed in UML, and possibly even with an automatically generated prototype of the interface, it is possible to use Rose to further customize the interface, and regenerate the Java code, this time from Rose.

With this scenario in mind, let's examine it in a little further detail. But before I delve any deeper, one disclaimer: the DTD/UML mapping I am about to introduce is based on some early beta work here at Rational. It is likely that there will be some changes made to it before it is incorporated into a released version of Rose. At the time of this writing most of the new DTD features in Rose are available in the current beta. This article is not intended to be a tutorial of these new features, but merely to introduce the ideas and concepts behind the inclusion of DTDs in our models, and to get some early feedback on it.

DTD/UML Mapping

The easiest way to understand how to express a DTD in UML is with an example. In our scenario, there is an industry standard DTD that we must work with. So it is likely that we have some type of DTD to begin with. The following represents a simplistic DTD to represent a purchase order:

<!DOCTYPE purchase-order [

<!ELEMENT date (#PCDATA)>

<!ATTLIST dateformat CDATA "dd-mm-yyyy"

><!ELEMENT account (#PCDATA)><!ELEMENT itemno (#PCDATA)><!ELEMENT itemdes (#PCDATA)><!ELEMENT quantity (#PCDATA)><!ELEMENT comment (#PCDATA)><!ELEMENT item ((itemno,itemdes,quantity)|(comment))><!ELEMENT purchase (date,account?,item+)><!ATTLIST purchase

status CDATA "initiated" >

]>

In this example, a number of elements and a couple of attributes are defined (we'll save the discussion of entities and notations for another article).

DTD elements map to classes in the logical view, which are stereotyped <>. Their attributes map nicely to the class's attributes. The biggest challenge in this mapping is how to map the content model of an element. An element's content model is, for the most part, what the element can contain (see Table 1).

In our example code, most of the elements either contain only parsed character data or specify child elements. One of the biggest challenges in creating a DTD mapping for UML is how to handle child elements. Child elements are specified in groups with parenthesis ( )'s , and ordered with choice ( | ) and sequence ( , ) connectors. Additional occurrence indicators specify how often a child element may occur (see Table 2).

Given this, we can see that a purchase element consists of a date, optional account, and one or more item elements. An item element consists of either an itemno, itemdes and quantity element, or can be a comment. To model this in UML, we need a way to represent these groupings. This is done with a new stereotyped element, <>. This class acts as a generalized grouping operator, similar to the n-ary model element in OMT. Its icon is a simple diamond. Figure 1 shows the UML diagram of our simple DTD using these stereotypes .

In Figure 1, we see a tree-like structure, which is expected, since XML is inherently hierarchical. This diagram shows another stereotyped class: <>. The class #PCDATA is, of course, the representation for parsed character data (the XML term for text).

Looking at the root class, purchase, it can be seen that it contains a group of three child elements. The type of group is indicated by the role constraint AND. This constraint corresponds to the sequence connector ( , ). The ordering of the child elements is important in XML. Unfortunately for our situation here, UML containment

semantics do not include ordering, so we express this information as ordinal numbers in the role constraints.

The key points in Figure 1 are:

● Directional associations indicate ownership. ● Grouping classes are nested, to further emphasize ownership. ● Sequence ordering is captured as ordinal values in the role

constraint. ● Role constraints indicate the type of grouping: sequential or

choice (AND, OR).

Now that we have expressed our DTD with UML, we can augment it or even change it, then regenerate a new DTD. For now, however, we will be content to just have the DTD expressed in our model.

The next step in the process is to generate a prototype Java-based object interface based on the DTD. IBM's Visual DTD application allows us to generate a set of Java wrapper classes that provide a customized interface to XML document instances that validate against this DTD. Figure 2 shows the Visual DTD graphical view of the DTD. Notice its similarity with the UML representation.

Generating the Java wrapper code from Visual DTD and then reverse engineering it back into Rose gives us the diagram in Figure 3. In this class diagram, it can be seen that our XML document has a very simple and intuitive interface that makes it easy to access and change XML document content.

Much of the work involved with XML access is delegated to the superclass of all of these customized wrapper classes: IBMXMLElement (Figure 4). This class does all of the work in traversing the XML document (using the DOM) and accessing element values and attributes. This superclass provides methods to set and get an element's values and manage child elements. The support for managing multiple instance children is basic and requires working with basic Vectors; but it does provide most of the functionality that an implementer working with this type of XML document instance needs.

There is an additional "factory" class that manages the XML document instance and its element's lifecycle. This includes the ability to create new documents, load existing documents, and even save them to files.

The final step in working with XML documents is to further customize the wrapper to suit the particular needs of the application. This, of course, could be done in Rose against the Java classes. When the interfaces are customized, and perhaps even the DTD itself is customized, both can be used to forward engineer new code for the system.

Conclusion

Expressing XML structures in UML models makes a lot of sense when you consider how XML documents are actually used in the system. Designers and implementers will eventually have to work with them. With the right set of tools, DTDs can be incorporated in our UML model, and wrapper code can be generated and even customized. This makes the job of the development team tasked with using XML in systems much easier.

NOTE: All of the work discussed in this paper is very new, and we expect this mapping to change. Please visit www.rational.com for updates and more information. Also, I'm very interested in what you think about all this. Is this how you want Rational to help provide support for XML development? Do you have any suggestions or comments? Please let me know at [email protected]. Thanks.

Footnotes

1. When DTDs are used, a separate parser (or language) is required.

2. SAX is most convenient for very large documents that might otherwise not fit in memory.

3. The Technology Preview edition of Visual DTD is available from IBM's Java Web site.

4. Object Modeling Technique was a precursor to UML originally created by Jim Rumbaugh, et. al.

5. This particular diagram was reverse engineered from the DTD source with the first beta release of Rose 2000e.

Back to table of contents



mailto:[email protected]


http://www.cmp.com/

http://www.unm.com/

Integrating Legacy Applications Using XML

Chris Holmes & Rich Newcomb, Blueprint Technologies

Companies are moving rapidly to allow employees and customers alike access to business processes on the Internet, in the form of suites of enterprise applications. Many of the applications already exist and perform their functions well. Companies want to integrate these older legacy systems into the new distributed architecture that the Web affords.

In this article, we will present an architectural strategy for integrating legacy applications using open standards, and we will show how the utilization of XML (eXtensible Markup Language) can help to position an organization's legacy systems for the future.

Legacy Applications, New Forces

Legacy applications provide the backbone for a typical organization's business processes and transactions. They are the tried-and-true solutions. On the other hand, they are in a constant battle with obsolescence. The one thing that we know for certain is that a legacy system will eventually be replaced with something newer. The only question is, "When?"

In an organization, there are at least three forces that may be acting upon its legacy applications (see Figure 1). The first of these is the need for the organization to improve its competitive advantage through better access to information and business processes across the enterprise. That is, the organization needs to perform Enterprise Application Integration (EAI.) EAI involves updating an organization's business process and applications so that the enterprise applications may share data and better work together. An organization with integrated enterprise applications has quicker access to relevant, coordinated information and processes from a variety of internal sources. Today, legacy applications must be made capable of integrating with other applications within the enterprise.

FIGURE 1










Another force that may be acting is the need to support business processes through the Internet. For example, an organization may wish to give employees remote browser-based access to the company time reporting system. Or a company may wish to utilize the Internet to improve inter-company communication with its business partners. Making legacy systems capable of supporting Internet solutions has become a common requirement.

A third force that is constantly acting upon any legacy application is the necessity for the organization to question the application's relevance. An organization must periodically ask whether its existing applications are performing sufficiently. Also, an organization must ask whether its applications are providing the correct level of functionality. If the answer to either of these questions is "No," it may be time for the organization to replace or upgrade those legacy applications. In short, organizations must protect themselves from legacy system obsolescence.

A Strategy for Integration

From the aforementioned discussion, it should be clear that some mechanism must be applied to the typical legacy application so that it will remain relevant and capable of supporting an organization's future needs-so that it can be integrated. Additionally, once the application is integrated, an approach for shielding the organization from the future obsolescence of that application is in order. There are two questions, then, that we must ask: "What are the characteristics of this integration mechanism?" and, "How is the integration mechanism manifested?"

There are two criteria for the mechanism that we prescribe for preparing a legacy system for integration:

1. The application must be made capable of supporting a consistent messaging interface through multiple communications mechanisms.

2. The application's messaging interface should be defined in terms of the organization's business transactions.

Here we can scope the term "communications mechanism" to refer to both application level protocols (such as HTTP, IIOP, RMI, and DCOM) and networking protocols (such as TCP/IP and UDP). Next, the term "messaging interface" describes the formatted messages that the application sends and receives. Regardless of the

communications used, the application should be capable of sending and receiving exactly the same type of messages, formatted in exactly the same way. By preparing the system to be accessed by multiple communications mechanisms in advance, obsolescence by technology can be minimized. This is because the ability to add not only new clients, but also new types of clients, is built into the core of the system.

There are two key points within the second characteristic description. First, since it is clear that any application is in place to support some business process, the interface to the integrated application should be defined using the terminology and artifacts of that business process. By adhering to this principle, the organization shields itself and its systems from the eventual replacement of the legacy system. The second key point is that the interface should be defined with transactional granularity. That is, a message that is received by the application should be a request to process a complete transaction.

The second question that we have asked is "How is this mechanism implemented?" While the remainder of this article will provide the detailed answer to that question, the short answer is this:

A legacy application can be prepared for integration through the implementation of a layered architecture pattern (see Figure 2) where the following apply:

1. The outer-most layer supports the receipt and return of XML formatted messages through any given communications mechanism.

2. The second layer is responsible for interpreting XML formatted requests, invoking the appropriate operations upon the legacy system, and formatting the responses into XML

3. The legacy system interface becomes the third layer.

FIGURE 2: Layered architecture pattern.

The implementation of this pattern yields one or more communications adapters that send and receive XML formatted messages. These adapters will be used for integrating the legacy system.

XML

XML is a standard from the World Wide Web Consortium (W3C) that is intended to "play an increasingly important role in the exchange of a wide variety of data on the Web." It is specifically designed to fix the problems that have hindered HTML from becoming a true data interchange format. The XML specification defines a framework for developing custom markup languages, similar to HTML. However, XML is not a markup language itself. Rather, while XML defines a set of rules for structuring text-based documents, it does not dictate the tags that should be used.

Given that HTML is so widely used, with millions of Web pages implemented in HTML, why should we replace it? First, HTML is a presentation interchange format, not a data interchange format. That is, HTML tags define how text should be displayed, not what the content actually means. For this reason, deciphering the semantic content of an HTML document textually can be extremely difficult. Also, HTML dictates a standard, finite set of tags agreed upon by committee. Even if content-specific tags could be added to HTML, the process would likely take a long time. For these reasons, HTML is not a good candidate for data exchange.

By defining a framework for creating markup languages, XML has solved the basic problems inherent in HTML. Now anybody can create a custom markup language and define the rules for how that language is formatted and validated. Furthermore, a custom markup language may be defined in terms of content rather than presentation. This is important because the primary client of XML data interchange may not be a Web browser. It is clear that moving presentation information out of the data description frees the data to be used in a variety of contexts.

This simple example illustrates the difference between HTML and XML. To display the shipping address for a customer, an HTML document may use simple formatting tags such as to cause the name to be displayed in bold type and to begin new lines for the other elements. In HTML, an address might look like this:

John Smith5215 Grand Ave.Edina, MN 58523

The output of this would probably appear correctly in a browser, but there is nothing in the HTML tags to indicate the purpose of the information, such as the fact that the first line is the customer name. However, if the format of addresses change (for example; the system needs to work with international addresses) recapturing the context of the information becomes difficult.

Contrast the HTML example with a simple XML document, containing the same address information:

<Address><Name>John Smith</Name><Street>5215 Grand Ave.</Street><City>Edina</City><State>MN</State><ZipCode>58523</ZipCode></Address>

Changing the markup tags of the address to be content-based rather than presentation-based has made it much easier to extract and understand the content. By tagging the data, it is much easier to validate and search the data.

So, why is XML the message formatting choice for system integration? There are a several reasons:

1. XML is quickly becoming a standard for data interchange. Many COTS products are now supporting XML interfaces natively so that they can be integrated more easily. Major vendors such as Microsoft, Sun, and IBM greatly increase the viability of the approach.

2. XML is platform independent. Because XML is text-based, XML documents can be exchanged between virtually any operating system along any type of channel that supports text.

3. XML is easy to write and understand. The authors of XML took the power of SGML and simplified it so that it could be easily parsed and easily created. Anybody who has ever seen HTML will immediately know how XML works.

4. There are many XML tools. There is an increasing number of tools available, many free, that support most languages. For additional resources, see the inset entitled, "Some Interesting XML Sites."

There are drawbacks to using XML. Since XML is interpreted, it is not as efficient as a binary model. In addition, it is necessary that participants in the exchange of XML data interpret the fields, or elements, or an XML document in the same manner.

A Layered Architecture

The architecture presented in this article allows legacy systems to perform business domain-level services via an XML-based interface, regardless of the client type or communications mechanism employed. In order to accomplish these objectives, three basic architectural layers are defined: the Communications Layer, the XML Services Layer, and the Legacy System Layer.

Communications Layer

The Communications Layer supports the adaptation of the desired functionality to a number of communications mechanisms. This layer allows clients of the legacy application to use various mechanisms, such as CORBA (IIOP), RMI, DCOM, or HTTP, to invoke the services defined by the interface to the application. To accomplish this, a component is built for each desired protocol. For example, an HTTP server or a CORBA server might be created.

The key concept here is that the communications mechanisms are distinct from the actual XML message parsing, message interpretation, and subsequent return message production. This functionality takes place within the XML Services Layer. This approach makes the system more extensible. The Communications Layer receives XML messages and passes them to the XML Services Layer, and from the legacy application out to the client.

We have considered two alternative approaches to communications using XML. The first is to expose the actual domain-level service interfaces to the client via whatever mechanism the client is using. Implementing this approach, a CORBA server adapter might support transactions such as:

interface OrderService {XMLString processOrder(XMLString args);XMLString orderHistory(XMLString args);XMLString removeOrders(XMLString args)};

The alternate approach is to provide a generic interface that accepts all requests and routes those requests to the correct service. The CORBA interface for that approach might look something like the following:

interface ServiceIF {XMLString perform(String serviceName,

String transactionName, XMLString params);

};

There are positive and negative aspects to each of these approaches. In the first approach, the programmatic interfaces are more intuitive for use by the clients. However, adding new services changes the interface to the component, which may be a burden, especially in a statically bound implementation environment.

The benefit of the second approach lies in that there are fewer services defined in the interfaces, but it defeats the purpose of using a well-defined interface in the first place.

Classes in this layer are fairly straightforward. Their role is to provide a communications bridge to the actual services. For example, you may wish to serve up XML over HTTP, choosing to use Java Servlets for the implementation. The Servlet would simply take parameters from an HTTP PUT request, format those into XML, and forward the message to the Service Layer for processing. Once the Service Layer has completed the operation, the Servlet would receive the resulting XML and put it on the Servlet output stream (see Figure 3).

FIGURE 3: Implementing a communication bridge with Java Servlet.

XML Service Layer

The XML Service Layer defines how the services in the system are actually invoked, as well as how the data returned by the services are formatted. XML formatted requests are forwarded to this layer via the Communications Layer (which takes care of all binding and protocol issues). The classes in this layer parse the transaction requests and invoke the appropriate operations upon the legacy system. Note that the classes within this layer are the only classes that need to have any knowledge of XML.

Service transactions should take on a level of granularity (coarse-grained) that is similar to a system-level use case. It is important to have services with the right granularity. When building distributed systems, it is quite common for designers to specify interfaces that are much too fine-grained. This is especially common in CORBA-based systems, where you attempt to make full use of distributed object interfaces, rather than distributed services. Fine-grained interaction models do not scale well, and it is difficult to clearly define and manage transactional boundaries. In order to balance this tendency, it is helpful to think about a service transaction as a coarse-grained operation that is performed by the system rather that as a fine-grained operation that is fulfilled by an object within the system. The result is an interface with the right degree of coupling.

The classes within the XML Service Layer are organized into packages that include the Service Invocation Package, XML Parser Package, and one or more Application Service packages (see Figure 4). The Service Invocation package contains classes that receive requests from the Communications Layer, filter those requests, and forward them to the appropriate classes within the Application Service Packages. An Application Service package contains classes that fulfill specific service transactions implemented by the business behavior provided by the legacy system. These classes work with the XML Parser to extract and format the contents of an XML message.

FIGURE 4: Service Layer package.

Legacy System Layer

The Legacy System Layer contains the legacy application and its adapters. The responsibilities of the legacy application are to provide the business-level behaviors and to enforce the business rules. These behaviors are invoked by objects within the XML Services Layer in the execution of service transactions. The legacy application does not need to know anything about XML. Furthermore, that application should not need to know about the new infrastructure in which it resides.

Problems may occur if a legacy system's interface is not robust enough to handle the expanded requirements or if the legacy system has no interface at all. In the first case, the organization should question the motivation for integrating the system in the first place - it fails the relevancy test. In the second case, an interface could be created using a wide variety of EAI techniques. These techniques range from writing API's to screen scraping.

Conclusion

The multilayer architecture presented in this article provides a solution for integrating a legacy system into an environment that may have heterogeneous clients, ranging from Web browsers to business partner (B2B) applications. The keys to the architecture are the utilization of XML formatted messages, and a clean definition of layer responsibilities. There are additional benefits to the approach that we have outlined. First, the approach calls for an organization to establish and document (in XML) a transactional business process model for any given system. This model will pay dividends in the future, as legacy applications are updated or replaced. Also, following this architecture, despite the variety of client types supported by integration infrastructure, a change to the structure and content of a message interface, or to the specific transactions supported, will be completely isolated from the infrastructure.

About the Authors

Chris Holmes is a software architect for Blueprint Technologies. He consults on the architecture and design of large distributed systems. His experience includes Web-based systems, XML, CORBA, Java, C++, and VB. He is a Microsoft Certified Professional and a Rational certified OOA&D and RUP consultant. He is currently involved developing architecture for UPS's Web package-tracking services.

Rich Newcomb is a Software Architect at Blueprint Technologies in McLean, VA. He has a background in the design and development of distributed, Object-Oriented, and component-based solutions within the modeling and simulation domain. He is currently involved in the architecture and design of an e-commerce application for NASA.




http://www.cmp.com/

http://www.unm.com/

Grokking COM+ UML: The VC++ Server-Centric Model

Dr. Al Major

Dr. Al Major is the author of COM IDL and Interface Design from Wrox Press.

In the previous issue of Rose Architect, I summarized my thoughts on structural UML models for COM+. In that article, I described the first two realization levels of a COM+ UML model: the interfaces-only model and the classes-and-interfaces model. Although both these models are concrete in the sense that code can be written against them, they are client-centric and do not specify anything about actual implementation. The programming language1 generated by the UML at this level is COM+ IDL (or equivalently, a binary type library).

In this article, I will take a look at the next level of realization, the server-centric implementation model. Specifically, the classes-and-interfaces model described in the previous article is refined by mapping it on to the constructs of a specific implementation language, such as VB or C++. This process can be viewed as going from IDL to the specific language, either VB or C++. Here, I'll look at the VC++ Server-Centric Model.

Why Bother?

Before going any further, let's stop and examine the issues at a higher level. What are the real benefits of having this third level of realization, one that connects the IDL/UML elements to C++ UML elements? In other words, what does it add to a pure C++ UML model that has no knowledge of COM or IDL? There are two obvious benefits:

1. The classes-and-interfaces and interfaces-only models that correspond to your C++ implementation are important. These are the models (think of them as the external API) that are visible to a COM+ user of your C++ server.

2. The existence of a mapping between IDL and C++ allows the COM+ client models to be reverse engineered from the actual implementation files. As we all know, in these days of ultra-short time-to-market, the process of implementation tends to modify the original specification










model. Reverse engineering the client models is critical to keeping them useful.

In addition, as I briefly indicated in the previous article, the mapping from UML to IDL can contain extra degrees of freedom, which permit radically different actual implementation architectures. The canonical example is, of course, an association that represents an outgoing interface. Such an association can be mapped either onto the DCOM style Connectable-Object protocol or to a COM+ style Pub-Sub protocol. Typically, an IDL model by itself will not be able to fully capture the specifics of the implementation differences, a C++ model is required for the purpose. If the mapping between the classes-and-interfaces UML model and the C++ UML is rich enough, it can automatically generate (reverse engineer) the appropriate code (model). This sort of intelligent stereotyping holds great promise for automatic code generators, but it is highly framework dependent and I will not discuss it any further in this article.

Mapping to VC++

In the interest of preserving space, I will not present a tutorial on the mechanics of using Rose 2000 to work with VC++ projects. Rather, I will focus on the actual mapping from the classes-and-interfaces model to the VC++ realization. This realization happens to be framework specific, but it is still tool independent to a degree.

I'll start with the interfaces-and-classes diagram that I created for a control in the last article. This is duplicated in Figure 1 with one change: I've added the additional interface ICustom to the coclass Control. I did this because all the other interfaces exposed by Control are dual interfaces, and I wanted to show the mapping for a non-dual interface as well.

FIGURE 1: Classes-and-interfaces model for control.

Let's examine the requirements here. What I want to do is show how this client-centric model is realized using C++ server code.

If you've done naked C++ COM programming, you know that there are many approaches to implementing such an IDL-level specification. These include multiple inheritance, single inheritance with composition, single inheritance with aggregation, and so on ad nauseam. There is no canonical or correct way to map an IDL-based classes-and- interfaces model to a C++ implementation.

The ATL Framework

The situation is simplified if you use a C++ framework that constrains the available design space. One such framework is the ActiveX Template Library (ATL), a package that is included with Visual C++. ATL is a framework for building extremely small, high-performance COM servers and has rapidly become the method of choice for building COM+ object models in C++.

The mapping from IDL to ATL is relatively straightforward in the general case. ATL has several features that make this possible:

● There is a single ATL class associated with any COM class.

● Interfaces are associated with the ATL class using a table-driven scheme based on the so-called INTERFACE_MAPs.

● An IDL interface maps directly onto a C++ interface (a C++ class that has only pure-virtual methods, for example).

● ATL provides various template-based C++ classes for boilerplate implementations of many of the common ActiveX and OLE-DB interfaces. In general, these so-called Impl classes are in the multiple-inheritance list of the main ATL class.

IDL to ATL

This makes it possible to draw the following diagram to show the relationship between IDL and C++/ATL (see Figure 2).

FIGURE 2: C+ /ATL realization of IDL.

In Figure 2, the primary C++/ATL class, CControl is represented as being a realization or implementation of the COM class Control. The code corresponding to CControl is shown in Figure 3.

If you're familiar with ATL, you'll recognize this as the standard ATL technique for interface implementation, i.e. multiple inheritance from all interfaces exposed by the corresponding COM class. The inheritance from ICustom is obvious. Inheritance from the dual interfaces is less clear because it takes place in the declaration of the templatized IDispatchImpl class, as shown in the following code snippet:

template <class T, ...>class ATL_NO_VTABLE IDispatchImpl : public T

The methods of all the interfaces being realized by the coclass are declared and implemented by this primary ATL class. These are just ordinary C++ methods, so I haven't bothered to show them in the code snippet. Sometimes these methods are inherited from one of the Impl base classes.

Notice that I suppressed all details of the C++ inheritance structure in Figure 2. This was done deliberately, since it tends to obscure the essential relationship here: the fact that CControl is the ATL class that is responsible for the implementation of Control.

It is, of course, possible to view the complete C++ model for CControl. Figure 4 shows how it appears when viewed in Rose 2000.

http://www.therationaledge.com/rosearchitect/mag/current/spring00/f3fig3.html


As you can see, Rose 2000 has appropriately captured the generalization relationship2 between CControl and the various C++ classes on its multiple inheritance list. Take a look at IDispatchImpl. It is correctly represented as an instantiation of a C++ template class. However, the instantiation relationship to IDispatchImpl is not visible. This in turn means that the inheritance relationship with the dual interface IControlScript is not visible. This is not a huge shortcoming, since the relationship is based on an idiom that is extremely familiar to ATL developers, and not much information is gained by making it visible. I am, however, pointing out this incomplete representation for those who are initially confused by Figure 4.

A Blurring of Lines

There is one issue here that I find somewhat problematic. Notice that CControl has an explicit generalization relationship with ICustom. Although it is not clear from this diagram alone, this is the same UML entity as the ICustom interface that is present in the IDL-based classes-and-interfaces diagram. The IDL interface and the corresponding C++ interface are assumed to be the same entity. Not only is this conceptually incorrect, it is inconsistent with the approach taken towards COM classes: the IDL coclass is different from the corresponding C++/ATL class (for example, Control vs. CControl). In the interest of promoting clarity, I believe the appropriate approach is to follow the coclass example. For instance, have a separate C++ interface (actually a class) that is related to the IDL interface by an implements or realizes relationship.

Of course, you've probably thought of the obvious related point. What's the appropriate way to treat IDL struct, enum, and union? This question is a little premature, since Rose 2000 does not yet have complete support for these data structures (it can reverse-engineer them, but it can't generate them), but worth asking. In this case, a stronger argument can be made for using the same entity in both the IDL and the C++ diagrams. Unlike the case with interfaces, where IDL and C++ have very different interface semantics (specifically with regard to inheritance), IDL struct, enum and union semantics are similar to those of C++. Where they are different (extra attributes), the IDL version always has richer semantics. Despite this argument, it might still make sense to model the IDL and C++ entities separately for the sake of consistency.

Outgoing Interfaces

Rose 2000 does not have explicit support for outgoing interfaces of classes. As I explained in my last article, outgoing interfaces can be implemented in many ways, all of which may be correct. In general, this requires multiple relationship stereotypes (or multiple options within the specification of a stereotype). As COM+ support in Rose matures, I would advocate adding relationship stereotypes at least for Pub-Sub and Connectable-Objects. The latter is


directly supported by ATL, and it is only a matter of time before the former is supported as well.

The remaining aspects of Rose 2000 ATL support depend on Rose 2000 C++ support, and are not worth repeating in this article.

Summary

In this article, I looked at the VC++ server-centric model, especially as supported by Rose 2000. I showed you that there was a need to relate the client-centric IDL models to the component-centric implementation. Next, I summarized several important features of the ATL framework that help to simplify the mapping from UML to C++/ATL. And I showed you the structural mapping between the IDL UML classes-and-interfaces model and the C++/ATL implementation, highlighting several advanced features of Rose C++ support as well as a lack of clean separation between the IDL and C++ entities. I finished by looking at outgoing interfaces and the complexity of mapping them on to IDL and C++.

Footnotes:

1. IDL isn't a full-fledged programming language. It's used to declare interface structure rather than interface semantics.

2. Unlike the relationship between an IDL class and the interfaces it implements, this is a real generalization relationship with deep inheritance semantics.

About the Author

Dr. Al Major is the author of COM IDL and Interface Design from Wrox Press. His current passion is the Scaling to Sagan project, a scaleability initiative based on the DNA 2000 architecture. In his murky past Al has, among other things, been a Wall Street Rocket Scientist, cofounded one of the earliest e-commerce companies, BrainPlay.Com (now KBKids.Com), trained hundreds of developers and consulted for Fortune 500 companies and DotCom startups. He has the dubious distinction of having had his picture appear on the front page of the Wall Street Journal. The "Dr" is a more-or-less legitimate honorific, since Al received his Ph.D. in Computer Science from Yale University. He can be reached at [email protected].





http://www.cmp.com/

http://www.unm.com/

System Integration, Manufacturing Processes, and Warm Potato Salad

Christian Buckley & Darren Pulsipher, QOSES

Christian Buckley

Darren Pulsipher

Software engineering and project management share many parallels, but nothing stands out as clearly as how to integrate the activities of numerous teams or individuals or projects, and still deliver a consistent product. Developing software is a complex world of ever-changing requirements and fine-tuning code - and so you'd think more time would be spent ensuring the system has been designed efficiently. In a perfect world, each effort would leverage key learnings from past projects, combine the skills and critical input from the vast array of cross-functional team members, and act as a template for future projects. Oh, that we lived in a perfect world...

"What are you mumbling?" My wife asks. In the comfortable silence of our Saturday afternoon drive down Highway 5 into the heart of California, I hadn't noticed that I was talking to myself.

"Oh, nothing. Work stuff."

My focus returns to the road. I've been driving for almost two hours to get to my family's annual reunion. This year's gathering will most likely fall in line with the last few outings, resulting in scraped knees and other mishaps for the kids, everyone eating too much too fast, and then all of those annoying questions about how my work is going - the answers to which they don't really understand or care about in the first place. Well, maybe it's not so bad...perhaps it's the two hours of driving that's souring my attitude. Or maybe it's my project at work. I just can't seem to get my arms around this latest development effort. So many disparate parts, and somehow I need to pull it all together into a cohesive package and get this product out. I have developers at each other's throats over features being developed independently of each other, and the product timeline is behind schedule because of these problems. I wish they would truly embrace my visual modeling recommendations.

"You're talking to yourself again."

"Sorry." I turn on the radio to cover any other rambling that might escape from my lips.

My wife lowers the volume and turns to me. "You know, I bet the potato salad is getting warm in the sun. Should we stop and pick up some kind of cooler with ice?"










"No. We're almost there. What's the big deal? So the potato salad is warm. Don't eat any."

"Don't you care if the salad goes bad? What if someone gets sick from our salad? Don't you care about ruining the whole day by making people sick?"

"We're only talking about potato salad. One little bowl of chopped vegetables and mayonnaise will not bring the entire day to a screeching halt."

Wait a minute. What am I saying? This sounds all too familiar. I recognize what I'm doing here - I'm guilty of a crippling attitude prevalent in so many engineers at my company. I've created something potentially faulty, and I'm adding it to the system, knowing that there could be problems down the road.

I've just caught myself throwing the potato salad "over the wall."

Sizing Up the Wall: The Manufacturing Process

No one ever wants to think themselves guilty of throwing a project or code over the wall, and yet by not thinking about how our work integrates into the project as a whole, that's what we are doing. Think about your current development processes: how do they integrate into the processes of your coworkers? Your project team? Your company as a whole? My guess is that there is room for improvement. It's common to find developers working in silos - focusing almost entirely on specific features, and not thinking about how their work plays into the larger picture. System integration and the processes around manufacturing are typically overlooked, and rarely planned effectively. So let's talk about that perfect world: you build the feature set. You package it with the other parts in the system and with the results of your team's development. You test the components as a whole and make adjustments. You release the product.

The steps it takes to design a piece of code (your manufacturing process) should be scaleable. At the macro level, it is the coordination of projects, work teams, and company resources to deliver that product to the customer. On a micro level, the heart of your system design is the outline of the integration, packaging, and delivery of the product. The purpose of this article is not to get into development methodologies, but there are fundamental steps that all projects must undergo. Whether developing code or managing the development of a product across multiple teams, there are four steps to this process: Build, Package, Test, and Release.

Build

You need to create processes that allow you to compile the system effectively and efficiently. These processes should be scaleable, repeatable, and take into account the key learnings of your team. And here are some things to watch out for during the build process:

● Circular dependencies between libraries compiled. The largest problem with circular dependencies is deciding which library to build first. Time after time you'll find yourself building one of the libraries twice. This can be avoided by either creating a

third library that both libraries depend on, or by combining both libraries into one library. It is very difficult to find this circular dependency when more than two libraries are involved. This is where the benefits of visual modeling surface - circular dependencies can be graphically represented very quickly.

● Complex dependencies for compilation. The more complex the dependencies, the less likely the ability to build components in parallel. Again, graphical representation is the only way to really see what is going on. You can easily see in a component diagram the dependencies between components (libraries and binaries), and try to minimize them by consolidating libraries or by breaking into smaller libraries those that are heavily used. The key is to minimize the number of dependencies between classes. This will increase compile time and make for a more repeatable build process.

● Generation of secondary and tertiary derived objects for compilation. Interface Definition Language (IDL) generates header files and source code. Header files are used in libraries of other components to generate object files to be put into libraries. With the expanded use of IDL, we have another problem we need to worry about. Typically, IDL compilers will generate client and server implementation header files that other libraries depend on before they can be built. UML has the ability to define those interfaces to libraries, and can be described using component diagrams. When described in the model, the makefile and build system can easily recognize what is happening within the system (Figure 1).

FIGURE 1

Package

Every good designer recognizes that presentation can be as important as the design itself. The same is true for software development. Take the time to optimize your presentation, and preserve the integrity of your project requirements. Ask yourself, "Now that I have built all of the libraries and binaries for the system, where will they reside when I install the system?" Do all of the binaries go into one directory? Do they run at start up? Where do dynamic libraries dwell? Is there more than one machine in the system? Where does each component reside?

Test

Let's face it, in the majority of projects, the testing of the product will require additional compilation of code and a rehash of requirements over software and hardware particulars above and beyond the target platform. We know that this happens, so it's important to be prepared for it. A well-planned testing environment can save precious time typically wasted trying to figure out if the problem is a real bug or just some kind of setup or environmental issue. There is nothing more frustrating than having a bug move back and forth in an endless cycle of "fixed" and "unresolved" due to a problem with an environment.

Delivery

Details, details, details. The key to successful delivery is in your ability to master the details. When completing your product or project, remember that there are important bits of information that the end customer requires - and which make all the difference in the successful release of your work. Ask yourself some fundamental questions about the customer experience. What are the machine requirements for the product? Does the user need Windows or UNIX? What version of the operating system is necessary? How much memory does the product require to install and to run?

You can see how these questions could be critical to the successful launch of a program, but how do they apply to turn-key solutions? In this case, it is even more imperative to scrutinize every aspect of the customer experience. Chances are that a team of manufacturing engineers will need to physically build the system before it gets shipped to the customer. An even more sensitive customer relationship involves the field service rep walking through the installation process onsite and in front of the customer. Add complexity to your customer experience, and the details surrounding delivery grow exponentially. Will the product be shipped on a CD or over the Internet? Will it be packaged with something else or by itself? Is your product ready for this kind of encounter? Have you thought about how your code fits into this process?

I shut the back of my Blazer and jump into the car. The detour only cost us about 25 minutes - however, I can't be sure the potato salad was free from any effect at the molecular level. I figure the twelve dollars I just spent on a foam cooler and two bags of ice is worth the peace of mind. I wouldn't want any family members blaming me for ruining their festivities. Although...

"I was thinking - these family get-togethers are always so intellectually...vacant. An episode of food poisoning might inspire a healthy round of conversation at next year's family reunion." I was half joking. Maybe more than half.

"Don't even think about it." Twenty-five minutes of sitting in the car with three screaming kids had left my wife without a sense of humor.

"And don't start telling people about how they should model everything," she continues. "You know my parents take you very seriously and can never tell when you're pulling their leg, so for you to sit there and talk on and on about your work stuff - I just wish you'd talk about something a little more engaging."

"Hey, I think it's great that your Dad downloaded the free version of Rational Rose and played around with it. Maybe he learned something new, and we'll have a decent conversation this afternoon."

She isn't impressed. She gives me a quick look that signals the conversation is over. With that cue, I switch the radio on and drift back to my thoughts on work.

Scaling the Wall: UML Implementation Diagrams

The first step to building your manufacturing processes is to

establish a naming convention for filenames in your source-code tree. Most compilers help with this task by requiring filename suffixes in order to compile. A consistent naming convention will pay off in the long run when new people are added to your team. By starting this habit now, you'll save them from hours of searching for a particular implementation for a class. And by using Rational Rose, you can get the added benefit of jumping directly to the source through the component diagram.

The next step is to take a look at your component diagrams. Should they contain the whole source code directory hierarchy? It all depends on you. Some people need to show all of the individual files in the component diagrams, while others just show the components (libraries and binaries) and the interfaces within the system.

What Is Compiled?

Since I come from the UNIX world, and even today do much of my development on more than one platform, I use makefiles as my method of compilation. In UML, component diagrams show you the dependencies between components. Utilizing this information, you can write the dependency rules of your system easily in your makefiles from the component diagram. Figure 2 is a simple example.

FIGURE 2

Notice that the component foo.exe is dependent on the library bar.dll and goo.dll. The corresponding makefile would be something like this:

Foo.exe : bar.dll goo.dll

Check out the QOSES website (www.qoses.com/downloads) for a makefile generator created from component diagrams.

Where Will it be Installed?

Over the years I have worked as a build and release engineer, and I have heard everything from "Hey, it worked on my machine!" to "Didn't you install this new library?" Often times we completely ignore the fact that our products need to be installed and run on multiple machines and multiple operating systems. We need to define the directory structure of the installation including documentation, library binaries, help files, and examples.

At the top-level component diagram, I typically define an installation package. The installation package defines the directory hierarchy of the installation of the product. I create packages for each platform onto which the product will be created. Inside each platform package, I create directory hierarchies using packages and represent libraries and binaries by the component model element. Ancillary files such as help files and examples are included as components within these diagrams.

The component diagrams illustrate where each of the libraries are to be positioned on each machine, but they do not show the requirements for each machine or how the machines will communicate. Deployment diagrams can be used to display the connections between machines, their individual and shared requirements, and their individual processes.

Each machine is shown as a processor in Rose. The connections between machines are connections between the processors. One thing to remember is naming the type of connection between machines: is it HTTP? CORBA? NFS? Remember that other developers should be able to review your design and build the necessary machines to run your product. In the specification window for a Processor, you can include multiple characteristics. I typically use this to describe the operating system requirements, memory requirements, third party tool requirements, etc...

How Will it Run?

We're almost there. The product has been built, compiled, and tested on numerous systems within your lab setting. But what about a test run on your customer's system? How often do you come across a customer machine that has not been fine tuned - even worse, the user has applied numerous operating system patches to get their system Y2K compliant. Some libraries that you expect to have installed - aren't. Or the latest version of a dll has been installed but is not compatible with your product. These types of problems are difficult to diagnose and fix.

The deployment diagrams demonstrate how machines will communicate, but do a poor job at showing how processes communicate. In the past, I have borrowed a modeling trick from the book Use Cases and UML (see Figure 3).

FIGURE 3

1. Create a package at the top-level logical view package named "Process View." Next, create the following hierarchy for process class definition (Figure 4).

2. For each process in the system, create a class.

3. For each process, create a class diagram (Figure 5).

4. For each process, assign interfaces that each process can handle.

5. In scenario diagrams, show the communication between processes by using color and objects that represent boundaries (Figure 6).

FIGURE 5

Check out Bouquet from the QOSES Web site (www.qoses.com/products/) for an automated script to build this for your model.

The Wall Comes Tumblin' Down

The end result is an efficient and effective design system that integrates the many parts of your system. Within the life of one feature set, planning ahead can stop you from wasting several days of development time. As systems become more complex, the lack of supporting designs for build and release systems can be paralyzing. UML provides the mechanisms for describing the system, and helps system integrators manage change and complexity.

We pull into the parking lot adjacent to the family gathering, already in full swing, and come to a halt next to Cousin Larry's 1978 Ford Pinto. As I look out across the park, something doesn't feel quite right. Everything looks...different. The kids scamper out of the car and join the gaggle of children assembled around an array of playground equipment. My wife sits motionless, peering out the front of the car. She also notices the difference.

"There's Aunt Harriet. This is definitely our family, but something is..." She can't quite put her finger on it.

I can't hide my bewilderment. "It looks like someone actually organized this thing. But that can't be right. That would be unheard



http://www.qoses.com/products/

of. Maybe we've just crossed over into the Twilight Zone. That looks like your Father - but wearing a tie?"

We exit the vehicle and assess the festivities. From afar, we can see that the tables are organized by family unit, the food by regional cuisine (someone has even gone so far as to provide flags of origin for the international dishes), and the agenda for the day displayed prominently from a white board near the beverage table. There's something else on the board - is that a sequence diagram outlining the day's activities?

As we approach the group, family members see us and start filing forward to welcome us...and ask questions. Uncle Stan wants to know about the visibilities of attributes. Someone else asks for the definition of a nondeterministic state machine. And Grandma wants to know whether a subclass that inherits the attributes and operations of its superclass can override those attributes with its own?

My wife is stunned. "What is going on?"

"Apparently, the family has decided to move to a model-based paradigm." I shrug my shoulders, and sit down for what I'm sure will be an interesting afternoon.

About the Authors

Darren Pulsipher and Christian Buckley are co-founders of QOSES, a software and process development company and RoseLink Technology Partner based in Tracy, CA. (www.qoses.com) The QOSES Web site offers the Internet's largest collection of free Rose scripts and models, Bouquet (an add-on for Rational Rose), and the Quarry Pattern Mining Tool. While Christian chooses to avoid large family gatherings, Darren would like to point out, just for the record, that this article in no way expresses his opinions, written or implied, on family reunions and his participation in conversations with extended family members. Really.



http://www.qoses.com/


http://www.cmp.com/

http://www.unm.com/

Database Modeling and Design Using Rational Rose 2000e

Eric Naiburg, Rational Software

Eric Naiburg is a product manager with Rational Software. He is responsible for the Rose Data Modeler product. He has recently relocated from New Jersey to join the Redmond, Washington, team, which is where the Data Modeler product is written. Prior to Rational, Eric worked for Logic Works/Platinum Software, where he had been a technical sales representative and Product Manager for ERwin, a data modeling tool.

When you look at the development process and a team working on any given project, they generally break into various groups. There may be people performing the functions of business analyst, developer, data analyst, DBA, and more. These groups are working toward one common goal: to solve a particular business problem in the best way possible. This includes time to market, quality, effectiveness of solving the business problem, performance, cost, and many other factors. If the above is true and I believe it is, then why are all these teams using different tools, processes, notations, and methodologies? Using Rational Rose 2000e and the UML, your entire project team can work together, sharing information from the gathering and maintenance of requirements through the entire process of development.

Extensions have been made in Rose 2000e that support physical database modeling and design, allowing teams to work together more effectively. By utilizing the strength of the UML, you can reverse engineer a relational database into a meaningful UML diagram. Rose allows you to create a new database diagram in the UML (Figure 1), then generate the DDL to create your database tables, columns, indexes, triggers, etc. Once this UML database diagram is created, you can create an object model in a class diagram based upon the database structures, and you can map the existing database to the objects in your new object model. If you are beginning with the object model and want to start your database design, simply create a database model based upon the persistent objects in your object model.

Requirements can be traced directly to the database by linking the object and data models using the UML. And having both visual modeling and design in one tool and notation allows you to further trace database elements all the way back through activities, use-cases, and requirements. When a new requirement is uncovered, your team can work together to solve the requirement, with a complete understanding how it affects each group. For example, if the database team is working on a database model and they uncover a column that was not originally captured in requirements, they can add it to the database, to the object models, and to the requirements. If this new column was just added to the database without sharing information to the requirements and object models, then the development team would not know of its existence. Perhaps they might see it on a data model somewhere or on some document, but that's an inefficient and inexact way to work. It makes far better sense to share information between all teams in real time while the decisions are being made.

How is it Done?

There are three basic types of development: object-oriented, data-centric, and legacy. Object-oriented development starts with the business requirements, which then drive to an object model. Persistent objects are then carried forward to the data model, and then the database is created. Once the database and application are created, they are bound together using data











access components that are aware of both the database and application components.

Data-centric development begins with the business requirements, and then a database is derived. Once this happens, the model can be translated into an object model and application development begins. The application components and database are created and then tied together using some sort of data access. This data access can be hard-coded DML in the application, stored procedures in the application and/or database, data access run-time components, or various other data access methods.

The term "legacy development" doesn't have to mean "old," just applications and databases that already exist. Often it is used to update or add applications to meet changing business needs - taking advantage of what already exists while adding additional data to the database as well.

As in the aforementioned methods, a business problem is being solved here. Business requirements are captured, the application is reverse engineered into an object model, the database is reverse engineered into a data model, and they are both updated and manipulated to add the new business requirements. They then need to be tied together via some data access method and readied for production.

Taking advantage of the UML

Rose 2000e now has data model functionality. This gives you the ability to create a new data model; capturing information like tables, columns, indexes, constraints, default values, tablespaces, descriptions, triggers, referential integrity (using triggers or declarative RI), and much more. Once the model is created, a database schema can be generated to create the database.

Using the UML for database design has many advantages over the traditional ER notations. The UML was based largely upon the ER notations, and includes the ability to capture all information that is captured in a traditional data model. The additional compartment in the UML for methods or operations allows you to capture items like triggers, indexes, and the various types of constraints directly as part of the diagram. By modeling this, rather than using tagged values to store the information, it is now visible on the modeling surface, making it more easily communicated to everyone involved.

One of the biggest questions in development is where to enforce constraints. In the application? On the database? Both? By having the ability to display these constraints, and even transfer them between the object and data models, your team can work together to decide how to implement these constraints, thus ensuring that they are capturing the correct information. There is little chance of creating conflicting rules if information is shared across teams and documented fully. By implementing information in both the database and the application, you avoid the problem of miscommunication. Also, the new data modeling functionality can capture information from existing databases or existing script files by reverse engineering information directly from these sources.

In Rational Rose 2000e, the changes made to support data modeling include changes to Rose itself, especially the addition of some UML stereotypes and the tagged values that support them. When you are in a data model, or are using a data modeling element, the specifications within Rose are specific to the data model and data modeling terms.

Some of the new stereotypes include those shown in Table 1. Within these stereotypes, each element includes many tagged values to better qualify the data modeling element. Tagged values are used to capture additional information about a specific element. These can be descriptions, properties, values, and more. Some of these are shown in Table 2.

Mapping the Data Model with the Object Model

In Rational Rose 2000e, there are various ways that a data model can be created. If a database already exists, you can reverse engineer directly from the database or from a script file, creating a matching data model in Rose. You can create a data model from scratch using the tools within Rose, then either create a database directly or create a DDL script from the model. Once the data model is created, simply select "create object model," and the mapping begins. A wizard will walk you through the steps of creating an object model from the database model. One of the steps (which Rose handles automatically) is creating many-to-many relationships, replacing associative tables in the process. Choose patterns to transform the data model into a logical object model. Regardless of what process you take to migrate from the data model to the object model or to move and rename objects, they will be mapped correctly to the originating database elements going forward.

If the object model already exists, you can create a corresponding data model

with all the correct mappings by choosing to create a data model from an object model in Rose. When the data model is created, any additional changes made to either model will be tracked and mapped to the corresponding model elements. There is a one-to-many mapping between the object to the data models. This gives you the ability to create many data models from a single application model. This is very important, as applications often need data from several databases in order to be complete. Just as in creating an object model from the data model, in the object-model-to-data-model scenario, there is a set of patterns that the user can apply to the transformations, including the rolling up and down of tables based upon generalizations. For example, if you have three classes - person, customer, and employee - they can be transformed into tables in multiple ways. You can create a one-to-one mapping for each class to table. You can roll the information that is in person, customer, and employee tables making two tables from the three classes. Or you can create one big table with all of the information from the three classes combined into a person table (Figure 2).

FIGURE 2: Rational Rose Data Modeler Column Editor for the column Region in the Customer Table. All of the attributes of a column are described including its mapping to the object model. The object model includes two classes: Customer and Address, which are mapped to the Customer table. The Customer.Region column is mapped to the Address.Region attribute. Rose Data Modeler tracks all your mapping information.

Because of space limitations, it would be impossible for me to fully explain the features and functions of Rose 2000e, so I refer you to www.rational.com for more information. But the bottom line is that, in today's development world, it has become increasingly important for all development, business analysis, and database teams to work together as one, sharing all information quickly and easily. Rose 2000e recognizes this fact and accommodates with forward and reverse engineering of DDL, object-relational mapping (including automatic transformation), and the ability to create a data model using Rose and the UML. In this way, your entire team can use the same tool and notation, making it easier for them to work together efficiently and to communicate effectively.




http://www.cmp.com/

http://www.unm.com/

Consistency Checking

Michael Moors, Rational Software

Michael Moors is Senior Technical Support Engineer for Rational Rose at Rational Software.

A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines. - Ralph Waldo Emerson, 1873.

Yeah, well what did Emerson know? OK, so he was a great writer, but he's a little harsh on consistency, isn't he? But then again, I guess we'll have to forgive him for dying before he could learn just how important it is to be consistent in modeling. After all, when you have to publish or give a model to a third party, you want it to be consistent and you want it to look good. And by using the right Rose features, scripts, add-ins, and checklists, you can achieve a degree of consistency in your models that would make even Emerson reconsider how "foolish" it is. Let's explore some of the ways you can achieve these results. Oh, and it's probably best if you read the entire article before looking into your own model(s).

Models grow, as Christian Buckley and Darren Pulsipher explained in their article on "Growing Roses" (Rose Architect, Vol. 2, No. 1). Growing models are special, because they are not always syntactically correct. "For instance, during model editing, the model will frequently be syntactically incorrect, and the tool needs to be able to allow for syntactical incorrectness in this mode."1 The Amigos also call this "Inconsistent models for work in progress,"2 because "the Final model must satisfy various validity constraints to be meaningful."3

When growing models, you will probably (roughly) follow a process as described as follows: first, you create Actors, then Use Cases, then Scenarios. Here your model is already inconsistent. In UML, an object is an instance of a class. When you have finished creating the scenario diagrams, you will need to define classes for every object. To do this, open the object specification dialog and select <New> from the Class dropdown list. This will create a new class and make the object an instance of this new class. When you think you have created or assigned classes for each object, select menu Tools:Check Model. If Rose shows an error dialog that says, "There are errors. See the log for details," select menu Window, option Log to open the log window. Rose will show error(s) similar to:

00:50:19| Error: Unresolved reference from Package "Use Case View"00:50:19| to ClassItem with name (Unspecified)00:50:19| by Object "Michael".

This means that Rose found an object called "Michael" in a package called "Use Case View," and the object has an unresolved reference to a class that is not specified. In other words, you forgot to create or assign this object to a class.










When you assign objects to classes, Rose stores a reference to the class in the object. If for some reason Rose cannot find the class that is referenced, it will report an unresolved reference. In this case, you forgot to create a reference. The Rose menu option Report:Show Unresolved Objects will report all unresolved objects in the currently active sequence or collaboration diagram in a special dialog that gives you the option to browse to that object.

Any Amigo would tell you that this is just the beginning: "For example, a message in a sequence diagram might be allowed before any operations are defined for the class.''2

You might also have noticed error(s) similar to:

01:07:21| Error: Unresolved reference to Operation with name Write article01:07:21| in Message Write article between John and Michael01:07:21| in Sequence Diagram: Use Case View / Rose Architect Vol.2, No 4.

This means that Rose found a message called "Write article" that is sent from "John" to "Michael" in sequence diagram "Rose Architect Vol.2, No 4.," which has a parent called "Use Case View," and the message has an unresolved reference to an operation called "Write article." The parent can be anything that can contain a sequence diagram. In Rose 2000, that is a use-case or a package. Now you will have to create or assign operations for each message. Right-click on the message and select to create a new operation that is assigned to that message. Rose will warn you if you have not yet assigned a class to the object and will ask you if you wish to do so at this point. The Rose menu option Report:Show Unresolved Messages will report all unresolved messages in the currently active sequence or collaboration diagram in a special dialog that gives you the option to browse to that message. Rose will report every object that does not have a valid reference to a class. When you create a new message, Rose will not report it in the log window. Once you enter text for the name of the message, Rose will create a reference (to an operation) that cannot be removed, even if you delete the name of the message. Make sure that the reference is pointing to an existing - and loaded - operation. If the message has a name, it should have a reference to an operation.

It can sometimes be tricky to find the object or message mentioned in the log window. When you are modeling, make sure that you give every element a name, which will avoid the useless text from showing up in the log. Ideally, each name should be unique. If you are having trouble finding the mentioned elements, I would advise using a specialized script or add-in instead. You can download my version at www.rationalrose.com/modelchecker/. Rose Model Checker (Figure 1) provides an Explorer-style interface, automatically fixes unresolved references, and allows single-click navigation directly to the offending element.

FIGURE 1: Rose Model Checker output

http://www.rationalrose.com/modelchecker/

Once you have created and assigned operations for each message, you will not see any errors reported by menu Tools:Check Model. However, your model is not yet fully semantically correct. If one object sends a message to another object, there must be a link between the objects. You can explicitly show those links in Rose by pressing the F5 key in a sequence diagram, which creates the corresponding Collaboration diagram in which links are shown. When you open the Link Specification dialog for a link, you will see that the Assoc field states "unspecified." Unassigned links are not reported by menu Tools:Check Model, but they are reported by Rose Model Checker and a script I wrote called "Check Links," which is available at The Unofficial Rose Web Site (www.rationalrose.com/). This site contains my personal Web-enabled collection of Rose resources. Rose Model Checker also allows you to create missing associations for all messages or for just a single message.

Multi-User Mode Inconsistencies

Designing has always been my favorite occupation. Before software took over my life, I studied to become a theater technician. Designing a good light plan for a script of a play is an artistic, but very challenging, task. The best light plan is practically invisible, it completes the play without being noticed itself. But even with the best script and the best light plan, the success of a play depends on teamwork. The same is true for application design and development: it is a team effort, too. When multiple users have to work on the same model, you have to split up your model into several files called "controlled units," which can cause other inconsistencies. When you delete a model element from the model (using CTRL+D), Rose will also remove any reference to it. If you did not load all units, Rose will not be able to check unloaded units for reference removal. At some point in time, you might execute menu Tools:Check Model in Rose, and the log will show the references that Rose was not able to delete. From the log, you can determine the name and location of the missing element. When you recreate this element, Rose will automatically fix the reference. Often, it is possible to remove the unresolved reference manually by, for example, deleting the element containing the unresolved reference. You can use Rose Model Checker to list types of elements with unresolved references and delete them one by one or all at once. There is also a Rose Script called "Unres Zapper" that can remove some of the types of broken references.

You can prevent the creation of unresolved references by loading all units before deleting elements from a model and making sure that the units are write-enabled. Rose can change the units. If you know which units contain references to the element to be deleted, you only have to

http://www.rationalrose.com/

load those units. At the aforementioned Web site is a script that reports all units with references to a selected element, and there are several scripts that help you load controlled units or load a workspace (predefined group of units).

Rose can also give you another hint about unresolved references. You might encounter a circle with an "m" inside attached to a model element on a diagram (Figure 2). You will not see these if you disabled the AdornUnresolvedReferences option. Rose will show these adornments if it cannot find the element that the icons represent. This means that the representing elements are not loaded in the model, or that they have been deleted without removing this icon from the diagram (because the diagram was not loaded).

FIGURE 2: Unresolved references.

Null and Unspecified Values

The text on page 109 of The UML Reference Manual3 explains that a complete model cannot have unspecified values, because they are not meaningful in a well-formed model. When you check your model, make sure that all elements have a name and that all attributes, operation arguments, operation return values, and parameterized class arguments have types. Rose Model Checker reports empty type fields. Also, make sure that the containment of all attributes and roles are specified.

Something that is important, but difficult to check is the correctness of attribute types, operation arguments, operation return values, and parameterized class arguments. Frequently, you will change the name of a class and Rose will not update all arguments that have the class in the type field. Rose Model Checker can detect types that are not fundamental and also do not exist as classes in the model.

Access Violations

An access violation occurs when a class in one package references a class in another package in the absence of an import relationship between the two packages. An access violation will also occur when a package references a class from another package, whose export control is set to Protected, Private, or Implementation. In such cases, the presence of an import relationship between the two packages has no bearing. All references to implementation classes from different packages are sited as violations. Rose provides a very nice GUI for these kinds of inconsistencies - Report:Show Access Violations shows a list of violations created by generalizations, "realize" relationships, dependencies, and "instantiates" relationships. But it does not show violations created by association classes or types. You can select a violation and double-click or press the Browse button to pop-up the

diagram and highlight the violating relationship. This does not work if there is no dependency, so before using this functionality, make sure that all dependencies are modeled. You should have dependencies whenever you use another class as a type or in a relationship.

Finishing touch

Your model is ready for release now, but when you go to publish the model, there are some additional things to check.

If you are not using any of the add-ins, it is best to keep them disabled while you work on the model. New (empty) models with all (Enterprise) add-ins enabled are 121 KB; but when you disable the add-ins, the new (empty) model is 7 KB. You can also reduce the size of your existing models when you have not yet cloned new property sets. To do this, disable all add-ins, create a new model, control the Model Properties, load an existing model, select menu Tools:Model Properties:Replace (you will also lose all cloned property sets), and save the model again. Always archive, send, or publish your model files in ZIP format. When you publish your model on a Web site, use Rose Web Publisher to upload an HTML version for quick access. When sending to a third party that does not have Rose, you can also use the Web Publisher and provide an HTML-based model.

If you are planning to distribute the model on paper or to distribute only diagrams, you should be more careful when checking consistency. Specialized scripts would be required to check whether every modeling element is represented in the diagrams. When you set AutoConstructMainDiagrams=Yes in Rose.ini, Rose automatically creates a Package Overview diagram in each package. This diagram contains all elements and their relationships in that package. But relationships that cross package boundaries are not automatically drawn by Rose, you must use a script to do this. You can manually find all diagrams of one association by entering it in the Edit:Find dialog. This works best if you (mostly) used unique names.

More About Inconsistencies

There are too many different inconsistencies and too many different messages displayed by Tools:Check Model to explain all of them here. Besides, that would make for a very long and very dull article. Here, however, it was merely my intention to provide a clear view of inconsistencies and how to deal with them. If you want to see which different error messages Tools:Check Model reports, or if you want to see a model with many different types of unresolved references, download and install Rose Model Checker. In the installation directory, you will find the example.mdl model. Open this with Rose and try Tools:Check Model. You can also use this model to practice resolving inconsistencies. Rose Model Checker's online Help provides a tutorial and every error report also explains how that specific inconsistency can be created, prevented, and fixed. Finally, to get the latest information about inconsistencies and consistency checking, go to The Unofficial Rose Web Site.

Conclusion

One might think that we would not have to worry about all this if Rose enforced syntactic rules to avoid such problems. The Amigos feel the same: "Unfortunately, enforcing syntactic rules of this sort without exception would make the tool unusable."2

Therefore, it is important to use a good checklist, apply the built-in Rose

features, and collect specialized scripts and add-ins that make those tasks easier.

Footnotes

1. The Unofficial Rose Web Site, www.rationalrose.com/.

2. Ivar Jacobson, Grady Booch, and James Rumbaugh, The Unified Software Development Process, Addison-Wesley, page 30.

3. James Rumbaugh, Ivar Jacobson, and Grady Booch, The Unified Modeling Language Reference Manual, Addison-Wesley, page 109.

4. Also check www.rational.com/sitewide/support/technotes/rose.jtmpl#rr and look for Technote 3700 (sometimes it is unavailable because of updating), and www.rational.com/technotes/rose_html/Rose_html/technote_3700.html.

About the Author

Michael Moors is Senior Technical Support Engineer for Rational Rose at Rational Software. Helping customers is not his only trade. He gives workshops, seminars, training, and demonstrations. And Michael loves to develop scripts, models, analyzer projects, add-ins, and Web sites. You can meet him almost every day online in the Rose Café.



http://www.rationalrose.com/

http://www.rational.com/sitewide/support/technotes/rose.jtmpl#rr

http://www.rational.com/technotes/rose_html/Rose_html/technote_3700.html


http://www.cmp.com/

http://www.unm.com/

Bridge the Gap Between UML Modeling and EJB Development

Kevin Kelly, Rational Software

Kevin E. Kelly is a Rose Evangelist at Rational Software.

Until recently, the paring of Enterprise JavaBeans™ (EJB) development and UML modeling wasn't exactly a match made in high-tech heaven.

Luckily, things just got easier with Rational Rose and an add-on from InLine™ Software called the "UML Bridge for Rational Rose." InLine's UML Bridge supports forward, reverse, and round-trip engineering of EJBs with Rose, allowing you to model an EJB in Rose and then translate the Rose model into an EJB component in the InLine Standard product. Alternately, you can build an EJB component in the InLine Standard product and then reverse engineer it into Rose.

When an EJB is reverse engineered into Rose in this way, the EJB is represented as a single class with an appropriate stereotype such as <> for an entity bean, or <> for a session bean. The UML Bridge also has a smart merge capability that integrates differences between the Rose model and the EJB source file or JAR. This allows for full round-trip engineering. The UML Bridge can be invoked from within Rose or from within the InLine Standard product.

The InLine Standard product is a plug-in for popular Java IDEs that extends their functionality with support for EJB editing, assembly, and deployment. It automatically maintains the relationships between all EJB source files and keeps them in sync. It also generates everything needed to deploy the EJB including primary key and implementation classes, home and remote interfaces, and deployment descriptors for the target application server.

The InLine Standard supports several popular IDEs such as Sun's Forte for Java, Symantec's VisualCafé, and Inprise/Borland's JBuilder. It also supports the following application servers: BEA's WebLogic Server, Oracle's Oracle 8i, and IBM's WebSphere. InLine Standard supports all JBDC-compliant databases. In order to use the UML Bridge for Rational Rose, you must have Rose installed, a supported IDE installed, and a supported application server installed. Only then do you install InLine Standard and the UML Bridge. Upon installation, the UML Bridge adds the appropriate modeling stereotypes to Rose and the EJB creation wizards.

So those of us who use Rational Rose J or Rational Rose Enterprise Edition can now visually model an EJB, and then rapidly deploy it using the UML Bridge for Rational Rose and the InLine Standard plug-in for its Java IDE. By simplifying the forward, reverse, and round-trip engineering of EJBs, we can move between design and deployment of e-business and enterprise applications that use EJBs more quickly, allowing us to focus on solving business problems rather than writing code.










More information on the UML Bridge can be found on InLine's Web page at: www.inline-software.com/products/umlbridge/index.html.

One final bit of information: both Rational and InLine are involved in the development of the JSR-000026 UML/EJB Mapping Specification, which defines a UML profile for EJBs (that includes the UML Bridge modeling stereotypes). More information on this mapping standard can be found at http://java.sun.com/aboutJava/communityprocess/jsr/jsr_026_uml.html.



http://www.inline-software.com/products/umlbridge/index.html

http://java.sun.com/aboutJava/communityprocess/jsr/jsr_026_uml.html


http://www.cmp.com/

http://www.unm.com/

From Waterfall to Iterative Lifecycle: A tough transition for project managers

Philippe Kruchten, Rational Software

Philippe Kruchten is the Director of Process Development at Rational Software. He leads the development of the Rational Unified Process, based in Vancouver, Canada. He has been with Rational Software since 1987.

The following is an excerpt from Project Management Using the Rational Unified Process by Gerhard Versteegen (Springer-Verlag, 2000). For more information, please visit www.springer.de/.

Although the Rational Unified Process advocates an iterative or spiral approach to the software development lifecycle, do not believe for one second that the many benefits it provides come for free. Iterative development is not a magical wand that, when waved, solves all possible problems or difficulties in software development. Projects are not easier to set up, to plan, or to control, just because they are iterative. The project manager will actually have a more challenging task, especially during his or her first iterative project, and most certainly during the early iterations of that project, when risks are high and early failure possible. In this article, I shall discuss some of the challenges of iterative development from the perspective of the project manager. I will also describe some of the common "traps" or pitfalls that I have seen project managers fall into throughout my consulting experience, in addition to reports and war stories from my colleagues at Rational Software.

More Planning Work

Iterative development does not necessarily mean less work and shorter schedules. Its main advantage is to bring more predictability to the outcome and the schedule. It will bring higher quality products, which will satisfy the real needs of the end-users because you have had time to evolve requirements, a design, and an implementation.

Iterative development actually involves much more planning and is therefore likely to put










http://www.springer.de/

more of burden on the project manager: an overall plan has to be developed, and detailed plans will in turn be developed for each iteration. It also involves continuous negotiation of tradeoffs between the problem, the solution, and the plan. More architectural planning will also take place earlier. Artifacts (plans, documents, models, code) will have to be modified and reviewed and approved again and again at each revision. The changes of tactics or the changes in scope will force some continuous replanning. The team structure will have to be modified slightly at each iteration.

Trap: Overly detailed planning up to the end.

It is typically wasteful to construct a detailed plan end-to-end, except as an exercise in evaluating the global envelope of schedule and resources. This plan will be obsolete before reaching the end of the first iteration. Before you have an architecture in place, and a good grip on the requirements - which occurs roughly at the LCA milestone - you cannot build any realistic plan.*

So incorporate precision in planning commensurate with your knowledge of the activity, the artifact, or the iteration being planned. Short term plans are more detailed and fine grained. Long term plans are maintained in coarse grained format.

Resist the pressure that unknowledgeable or ill-informed management may bring to bear in an attempt to elicit a "comprehensive overall plan." Educate and explain the notion of iterative planning and the wasted effort of trying to predict details far into the future. An analogy that is useful is a car trip from New York to L.A. You plan the overall route, but only need detailed driving instructions to get you out of the city and onto the first leg of the interstate.

* LCA = LifeCyle Architecture = End of the Elaboration phase = the point in time when you need to baseline your architecture, your requriements, your plans, and where normally all your risks have been mitigated.

Planning the exact details of getting through Kansas - let alone the arrival in California - is unnecessary and silly: you may find that the road through Kansas is under repair and you need to find an alternate route. And so on...

Acknowledging Rework Up-Front

In a waterfall approach, too much rework comes in the very end, as an annoying and often unplanned consequence of finding nasty bugs during final testing and integration. Even worse, you discover that most of the cause of the "breakage" comes from errors in the design, which you attempt to palliate in implementation, building workarounds that lead to more breakage.

In an iterative approach you simply acknowledge up-front that there will be rework and, initially, a lot of rework: as you discover problems in the early architectural prototypes you need to fix them early. Also, in order to build executable prototypes, stubs and scaffolding will have to be built, to be later replaced by more mature and robust implementations. In a healthy iterative project, the percentage of scrap, or rework, should diminish rapidly; the changes should be less widespread as the architecture stabilizes and the hard issues are being resolved.

Trap: Project not converging.

However, iterative development does not mean scrapping everything at each iteration. Scrap and rework has to diminish from iteration to iteration, especially after the architecture is baselined at the LCA milestone. Developers often want to take advantage of iterative development to do gold plating: introduce yet a better technique, redo this and that, etc. The project manager has to be vigilant so as to not allow the rework of elements that are not broken, elements that are OK, that are good enough. Also, as the development team grows in size and as some people are moved around, newcomers are brought in. They tend to have other ideas on how things should be done. Similarly, customers (or their representatives in the project: marketing, product management) may want to abuse the latitude offered by iterative development to accommodate changes, and to change or add requirements with no end. This effect is sometimes called Requirements Creep. Again, the project manager needs to be ruthless in making tradeoffs and in negotiating priorities. Around the LCA milestone, the requirements are baselined, and unless the schedule and budget are renegotiated, any change has a finite cost: getting something in means pulling something out.

And remember that "perfect is the enemy of good." (Or in French: "le mieux est l'ennemi du bien."

Trap: Let's get started, and we'll decide where to go later.

Iterative development does not mean perpetually fuzzy development. You do not just start designing stuff and coding it, just to keep the troops busy, or hoping that suddenly clear goals will emerge out of it. You still need to define clear goals, put them in writing, and get concurrence from all parties. Then you have to refine them, and expand them, and again get concurrence from all parties. The bright side is that in iterative development, you need not have all the requirements stated before you start designing, coding, integrating, testing, and validating them.

Trap: Falling victim of your own success.

An interesting risk comes near the end of a project, at the moment the "consumer bit" flips. By this we mean that the users go from believing that nothing will ever be delivered to believing that this team might actually pull it off. The good news is that the external perception of the project has shifted: on Monday, they would have been happy if anything would have been delivered, but on Tuesday they become concerned that everything won't be delivered. And that's the bad news. Somewhere between the first and second beta, all of a sudden you find yourself inundated with features that people are concerned will not make it into the first release. These become major issues. The project manager goes from worrying about delivering minimal acceptable functionality to a situation where every last requirement now becomes "essential" to the first delivery. It is almost as though when this bit flips, all outstanding items get elevated to an "A" priority status. The reality is that there are still the same number of things to do, and the same amount of time to do them in. While external perception may have changed, prioritization is still very, very, important.

If at this crucial moment the project manager loses his nerve and starts to cave in on all these requests, he actually puts the project schedule in danger again! It is at this point that he or she must continue to be ruthless and not succumb to new requests. Even trading something new for something taken out may increase risk at this point. Without vigilance, one can snatch defeat from the jaws of victory.

Putting the Software First

In a waterfall approach, there is a lot of emphasis on "the specs" (i.e., the problem-space description), and getting the specs right, complete, polished, and signed-off. In the

iterative process, the software we develop comes first. The software architecture (i.e., the solution-space description) needs to drive the early lifecycle decisions.

Customers do not buy the specs; it is the software product that is the main focus of attention throughout, and both the specs and the software evolve in parallel. This focus on "software first" has some impact on the various teams: testers, for example, may have been used to getting complete, stable specs and are given plenty of advanced notice to start testing, whereas in an iterative development, they have to get to work at once, with specs and requirements that are still evolving.

Trap: Focus on the wrong artifact.

"I am a project manager, so I should focus on having the best set of management artifacts I can; they are key to everything." Not quite true! Although good management is key, the project manager must ensure in the end that the final product is the best that can be produced. Project management is not an exercise in covering your butt by showing that you have failed despite the best possible management.

Similarly, you may have been bitten in a previous job by poor requirements management, and choose to focus on the best possible spec; it will be of no use whatsoever if the corresponding product is buggy, slow, unstable, and brittle.

Hitting Hard Problems Earlier

In a waterfall approach, many of the hard problems, the risky things, the real unknowns, are pushed to the right in the planning process, for resolution in the dreaded system integration activity. This leaves the first half of the project as a relatively comfortable ride, where issues are dealt with on paper, in writing, not involving many stakeholders (testers, etc.), not involving hardware platforms, and not involving the real users or the real environment. And then, suddenly the project enters integration hell, and everything breaks loose. In iterative development, planning is mostly based on risks and unknowns, so things are tough right from the onset. Some hard, critical, and often low-level technical issues have to be dealt with immediately, rather than pushed out to some later time. In short, as someone once said to me, in an iterative development, you cannot lie (to yourself or to the world) very long. A software project destined for failure should meet its destiny earlier in an iterative approach.

One analogy is that of a university course in which the professor spends the first half of the semester on relatively basic concepts, giving the impression that this is an easy class and allowing the students to get good marks at the mid-term without too much effort. Then, in the closing weeks, a sudden acceleration takes place, wherein the professor tackles all the hard topics shortly before the final exam. The most common scenario at this point is that the majority of the class buckles under the weight, doing a lamentable job on the final exam. It is amazing that otherwise intelligent professors are surprised at this repeated disaster, year after year, class after class. A better approach is to front-load the course, doing sixty percent of the work before the mid-term, and tackling some of the challenging stuff early. Don't waste precious time in the beginning, solving the non-problems or doing the obvious or trivial stuff. The most common reason for technical failure in startups: "They spent all their time doing the easy stuff."

Trap: Putting your head in the sand.

It is often tempting to say: "This is a delicate issue, a problem for which we need a lot of time to think. Let us postpone its resolution until later, this will give us more time to think about it." The project then embarks on all the easy stuff, never dedicating much attention to the hard problem, and when it comes to the point where a solution is needed, hasty solutions and decisions are taken, or the project just derails. You want to do just the opposite: tackle the hard stuff immediately. I sometimes say: "If a project must fail for some reason, let it fail as soon as possible, before we have expended all the time and money."

Trap: Forgetting about new risks.

So you did a risk analysis in the project's inception, and used it for planning. But then you forgot about risks that develop later in the project. They will come back to bite you later. Risks should be re-evaluated constantly - probably on a weekly basis, but at least monthly. The original list of risks you came with was just tentative. It is only when the team starts doing concrete development (software first) that they will find out many other risks.

Clashes of Lifecycle Models

The manager of an iterative project will often see clashes with his environment and other organizations: top management, customers, and contractors who have not adopted or even

understood the nature of iterative development. They expect completed and frozen artifacts at key milestones; they do not want to review requirements in small installments; they are shocked by rework; and they do not understand the purpose or value of some ugly architectural prototype. They perceive iteration as just fumbling purposelessly, playing around with technology, developing code before specs are firm, and testing throwaway code.

At a minimum, make your intentions and plans clearly visible. If the iterative approach is only in your head and on a few whiteboards shared with your team, you will run into a lot of trouble later on.

The project manager must protect the team from external attacks and politics, not letting the outside world disrupt or discourage the team. He or she must act as a buffer. However, in order to be "the steady hand on the tiller," the project manager must have built trust and credibility with the external community. So visibility and "tracking to plan" is still important; in light of "the plan" being somewhat unconventional in many people's eyes, it is actually more important.

Trap: Different groups operating on their own schedule.

It is better and easier to have all groups (or teams or subcontractors) operating against the same phase and iteration plan. Often, project managers can see some time optimization in fine tuning the schedule of each individual team, which then end up having its own iteration schedule. All the perceived benefits will be lost later, and all teams will be forced to synchronize on the slower group. As much as feasible, put everybody on the same heartbeat.

Trap: Fixed-price bidding at inception.

Many projects are pushed into bidding for a contractual development far too early, somewhere in the middle of inception. In an iterative development, the best point in time for all parties to do such bidding is at the LCA milestone (end of elaboration). There is no magic recipe here: It takes some negotiation with and education of the stakeholders, showing the benefits of an iterative development, and, eventually, a two-step bidding process.

Accounting for Progress is Different

The traditional earned-value system to account

for progress is different since artifacts are not complete and frozen, but they are reworked in several increments. If an artifact has a certain value in the earned-value system, and if you get credit for it at the first iteration where you create it, then your progress is overly optimistic. If you only get credit when it becomes stable two or three iterations later, your measure of progress becomes depressingly pessimistic. So, when using such an approach to monitor progress, artifacts must be decomposed in chunks. For example: initial document (40%), first revision (25%), second revision (20%), final document (15%), and each chunk must be allocated a value. You can then use the earned-value system without having to complete each element.

An alternative would be to organize the earned-value around the iterations themselves, and gauge the value from the evaluation criteria. Then the intermediate tracking points (usually monthly) reported in the Status Assessment would be built around the Iteration Plan. This requires a finer-grain tracking of artifacts than the traditional requirements spec, design spec, etc. because you're tracking the completion of various use cases, test cases, and so on.

As Walker Royce says: a project manager should be more focused on measuring and monitoring changes - changes in requirements, in the design, in the code, than counting pages of text and lines of code. And Joe Marasco adds: look out not only for change, but for churn. Things that change multiple times to return to the same starting point are symptoms of deeper problems.

On the positive side, having concrete software that runs early can be used by the wise project manager to get some early credibility points, to show off progress in a more meaningful fashion than just completed and reviewed paperwork and hundreds of check-boxes ticked off. Also, engineers prefer "demonstrations of how it works" rather than "documentation of how it should work." Demonstrate first, then document.

Deciding on Number, Duration, and Content of Iterations

What do we do first? The manager who is new to iterative development often has a hard time deciding about the content of iterations. Initially, this planning is driven by risk, technicality and programmability, and by the level of importance of the functions or features of the system under construction. (The Rational Unified Process gives guidelines for deciding number and duration of iteration.) The criteria also evolve throughout

the lifecycle: in construction, planning is geared to completing certain features or certain subsystems in transition, fixing problems, and increasing robustness and performance.

Trap: Pushing too much in the first iteration.

We talked earlier about not tackling the hard problems first. On the other hand, going too far in the opposite direction is also a recipe for failure. There is a tendency to want to address too many issues and cover too much ground in the first few iterations. This fails to acknowledge other factors: a team needs to be formed (trained), new techniques need to be learned, new tools must be acquired. Often, also, the problem domain is new for many of the developers. This can frequently lead to a serious overrun of the first iteration, which may discredit the entire iterative approach. Or, the iteration is aborted - declared done, when nothing runs - which is basically declaring victory at a point where none of the lessons can be drawn, missing most of the benefits of iterative development.

When in doubt, or when confronted with crisis, make it smaller somehow (this applies to the problem, the solution, the team). Remember that completeness is a late lifecycle concern. "Appropriate incompleteness" should be the manager's early lifecycle concern.

If the first iteration contains too many goals, split it into two iterations, and then ruthlessly prioritize which objectives to attempt to achieve first.

It is better to shoot for a simpler, more conservative goal early in the project. Note that I didn't say easy. Having a solid, acquired result early in the process will help build morale. Many projects that miss the first milestone never recover. Most that miss it by a lot are doomed despite subsequent heroic efforts. Plan to make sure you don't miss an early milestone by a lot.

Trap: Too many iterations.

First, a project should not confuse the daily or weekly builds with iterations. But also, since there is a fixed overhead in planning, monitoring, and assessing an iteration, an organization that is unfamiliar with this approach should not attempt to iterate at a furious rate on its first project. The duration of an iteration should also take into consideration the size of the organization, its degree of geographic

distribution, and the number of distinct organizations involved. Revisit our "six plus or minus three" rule of thumb.

Trap: Overlapping iterations.

Another very common trap is to make iterations overlap too much. Yes, indeed, you will need to start planning the next iteration somewhere towards the last one-fifth of the current iteration, but attempting to have a significant overlap of activities, i.e., starting detailed analysis, design, and coding of the next one before you have finished the current one and gotten the lessons out of it may look attractive when only staring at a GANTT chart, but will lead to all kinds of problems. Some people will not be committed to follow up and complete their own contribution to the current iteration; they may not be very responsive to fixing things up or will just decide that they will take any and all feedback into consideration only in the next iteration. Some parts of the software will not be ready to support the work that has been pushed forward, etc. Although it is possible to divert a small part of the manpower to do some work unrelated to the current iteration, this should be kept minimal and exceptional. This problem is often triggered by the narrow range of skills of some of the organization members, or a very rigid organization: Joe is an analyst, and this is the only thing he can or wants to do, he does not want to participate in design, implementation, or testing. Another negative example: a large command and control project had its iterations so overlapped that they were basically all running in parallel at some point in time. This required management to split all the staff across all iterations, thus there was no hope of applying lessons learned from earlier iterations towards later ones. See Figure 1 for a few common "anti-patterns" of iteration planning.

FIGURE 1: Some dangerous iteration patterns.

A Good Product Manager and A Good Architect

To succeed, a software project needs both a good project manager and a good architect. Having the best management possible and using iterative development will not lead to a successful product without a good architecture, and vice versa: a fantastic architecture will fail lamentably if the project is not well managed. It is therefore a matter of balance, and focusing solely on project management will not lead to success. The project manager cannot simply ignore architecture: it takes both architecture expertise and domain expertise to determine the twenty percent of the stuff that should go into early iterations.

Trap: Use the same person as the PM and the architect.

This will work only on the small projects, the 5- to 10-person projects. For any larger endeavor, having the same person play the role of both project manager and architect will usually end with the project neither properly managed nor well architected. First, it requires different skill sets. Second, each one of them is more than a full time job. This requires that the two coordinate a lot - daily - and that they listen to each other and compromise. They are a little bit like the director and the producer of a movie, aiming at a common goal but responsible for totally different aspects of the undertaking. We have seen many projects where for various reasons - history, power, ego, distrust - the two roles are played by the same person. These projects rarely succeed.

Conclusion

At this stage, I know you may be discouraged: so many problems ahead, so many traps into which to fall. If it is so hard to plan and execute an iterative development, why bother? Rejoice, there are recipes and techniques to systematically address all these issues, and the payoffs are greater than the inconvenience in terms of achieving reliably higher quality software products. Some key themes: "Attack the risks actively or they will attack you" (Tom Gilb), software comes first, acknowledge scrap and rework, choose a project manager and an architect to work together, and exploit the benefits of iterative development.

The waterfall model made it easy on the manager and difficult for the engineering team. Iterative development is much more aligned with how software engineers work but at some cost in management complexity. Given that most team have a five-to-one (or higher) ratio of engineers to managers, this is a great tradeoff.

Although iterative development is harder than traditional approaches the first time you do it, there is a real long-term payoff. Once you get the hang of doing it well, you will find that you have become a much more capable manager, and you will find it easier and easier to manage larger and more complex projects. Once you can get an entire team to understand and think iteratively, the method scales much better than traditional approaches.

Acknowledgments

Thank you to my Rational colleagues John Smith, Dean Leffingwell, Joe Marasco, and Walker Royce for sharing their experience in iterative project management and helping me with this article, which is now a chapter in a new book on software project management by our colleague Gerhard Versteegen, in Munich.

Further Reading

Gilb, Tom. Principles of Software Engineering Management, Addison-Wesley, 1988.

Rational Unified Process 5.5, Rational Software, 1999.

Royce, Walker. Software Project Management - A Unified Approach, Addison-Wesley-Longman, 1999.




http://www.cmp.com/

http://www.unm.com/

Publisher's Note

Magnus Christerson

Magnus Christerson, Director of Product Management for Rose Visual Modeling Products.

As you can tell from our cover, one of our featured topics in this issue of Rose Architect is XML. In fact, we've got two articles on the subject. First, we have a partner contribution from Chris Holmes and Rich Newcomb of Blueprint Technologies who write about XML integration in Integrating Legacy Applications Using XML. Second, our Extreme Rose column this time around comes from my friend Jim Conallen with his article Working with XML Documents in UML. These articles are very complementary, and do a great job of providing practical information for those of us developing for the Web.

Other articles of special interest for those of us involved in e-development include Jim Conallen's return as The Web Modeler with an article on how to model web clients with UML and Rose; and our Amigo Page, which is proud to feature another contribution by Grady Booch. In this issue, Grady takes a look at All Good Things, his view of web application development, and the importance of having a strong process in place so that "history doesn't repeat itself."

This issue also takes a special look at the new data modeling capability in our latest version of Rose: Rational Rose 2000e. My colleague Eric Naiburg, author of this version of Inside Rose, gives us the basics of creating a data model in Rose 2000e, and explains why using UML for database design is the smart way to go.

I'm proud to announce that the second part of guest contributor Dr. Al Major's article, Grokking COM+ UML, is here. Focusing on the VC++ Server-Centric Model, and supported by Rose 2000, he discusses the need to relate client-centric IDL models to component-centric implementation. Dr. Major's previous article was fascinating, and I'm sure you'll agree that part two was well worth the wait.










Our "usual suspects" this time around include Kevin Kelly, who has good news for people developing EJBs; Darren Pulsipher and Christian Buckley, who take us to a very interesting family reunion (complete with UML implementation diagrams and warm potato salad); and John Hsia, who answers some of the most commonly asked questions regarding the REI. The topic of consistency checking is the focus of an article by Michael Moors, Naveena Bereny gives us her "epilogue" as the author of Rose 101, and Terry Quatrani, our Editor-in-Chief, once again dispenses advice and answers. (By the way, I highly recommend her book, Visual Modeling with Rational Rose 2000 and UML - even if she didn't mention me in the acknowledgment section.)

My thanks to all for your continued readership, and for all your questions and comments about Rose Architect. We welcome your feedback. If you have story suggestions, or would like to write for a future issue of the magazine, please contact our editor at [email protected].

All the best,Magnus Christerson, Publisher





http://www.cmp.com/

http://www.unm.com/

Editor's E-mail

Terry Quatrani

Terry Quatrani is the author of the best selling book Visual Modeling with Rational Rose 2000 and UML.

Dear Terry,

Could you please tell me how to show conditions in a sequence diagram? Here is my scenario: I have two objects, A1 and A2. If condition C1 is true, then A1 will call message M1 of the A2 object. But if condition C1 is false, then A1 will call message M2 of the A2 object.

Thanking you in advance,Alyssa

Dear Alyssa,

Conditional logic in a sequence diagram is not yet supported in Rational Rose. However, you can still show the condition in the diagram. You use a script to do this. The steps are:

1. Select the text box icon on the toolbar.

2. Click on the diagram to place the text box.

3. While the new text box is still selected, enter the desired text. Do not de-select the text.

4. Depress the shift key.

5. Select the message for the script.

6. Select the Edit: Attach Script menu command. (This attaches the script to the message, which means that the script will move whenever the message arrow is moved.)

A sequence diagram with conditional logic is shown in Figure 1.

Happy modeling, TQ

FIGURE 1: Sequence Diagram with conditional logic.










Hello Terry,

I use Rational Rose 98i and JDeveloper. I want to reverse engineer my code to a Rose Model, but unfortunately, I am having problems. I always get the following error message in my log window:

Error Resolving qualified name Frame occurred in File E:\Program Files\Oracle\JDeveloper 3.0\myprojects\personal\personal.java

My classpath entry in Windows NT is as follows:

E:\Program Files\Oracle\JDeveloper 3.0\java1.2\jre\lib\;E:\Program Files\Oracle\JDeveloper 3.0\myprojects

Could you please help me solve my problem?

Thanks,Greg Scholl

Dear Greg,

You are having problems because Rational Rose cannot find the Frame class. You need to add the rt.jar file to your classpath. Select the Tools: Java: Project Specification menu command, navigate to the directory containing rt.jar, and add that directory to your classpath. This should take care of your problem. TQ

Dear Terry,

I read the question from Lian Zarafa in the summer issue of Rose Architect. You answered that reverse engineering is only available in Rose Enterprise and Rose VB/Professional. I use the Rose 98i Enterprise edition, and I tried to reverse engineer the mfc42.dll by dragging it into a component diagram. But it was just like Lian had described-there is only a file link placed under the Component View folder. So, I'd like to put the question to you

again: How can I use this functionality? Is there anything else to do?

Thank you very much and many greetings from Germany.

Frank Hinze

Frank,

Only DLLs that contain typelib info are reverse engineered. Unfortunately, mfc42.dll does not contain any typelib information. In that event, the DLL is treated just like any other file-it is linked instead.

The typelib importer provides visual feedback as to how it will treat a drag/drop file. If the typelib import is enabled and it detects the presence of typelib data, it will change the drop target cursor to a "+" sign. Otherwise, Rose will display a shortcut drop cursor (the "bent" arrow) if the drop target accepts hyperlinks.

Hope this helps,TQ




http://www.cmp.com/

http://www.unm.com/

Amigo Page

Grady Booch

Grady Booch is Chief Scientist at Rational Software.

All Good Things

The future is here, so they say - it just hasn't been evenly distributed.1

Nowhere is this more apparent than in the context of the Internet. Not surprisingly, from inside the industry, we largely take the Internet for granted. Frankly, it's hard to imagine doing business without it. Personally, I'm connected 24/7, am online about 10 hours per day and, as a result, am partly to blame for the world's shortage of telephone numbers (consider my home phone numbers, cell phones, office numbers, fax, ISDN line, and T1 connection, and you'll find more bandwidth than one person can meaningfully use at a time). However, if you take into account the some six billion people in the world, a sizable majority has not experienced the Internet, does not have access to the Internet, and will likely not have access for some time. The percentages of users who do have access vary considerably from country to country, with the United States and certain European countries leading the pack. In mid-December, reports indicated that around 50 million individuals surfed the Web, with sites such as Yahoo receiving tens of million of those visitors.2 These are all impressive numbers, but they still represent a fraction of the potential. That there is such a high potential is perhaps what drives some of the valuations of Internet companies, many of which have never experienced a profit yet are graced with valuations that defy all rational explanation. Indeed, not only is there a growing gulf between individuals who are either technological haves or have nots, there's also a considerable gulf between companies that really grok the Internet and those that do not.

Last century, I wrote an article that laid out my thoughts regarding how a company might grok










the Internet to its advantage.3 Some companies, such as Cisco and Lucent, are involved in the development of the Web, meaning that their business is largely focused upon delivering the infrastructure upon which the Web works. Others, such as Rational, are involved in developing by the Web, meaning that their business is focused upon doing software engineering via the Web (imagine a day in the life of a developer, who manipulates the artifacts of her project and interacts with the other team members on her project - all through the Web). Finally, all dot-com companies, as well as traditional brick-and-mortar companies transmogrifying themselves into click-and-mortar companies, are involved in developing for the Web, meaning that their business is focused upon delivering a user experience on the Web.

For all such companies thus engaged with the Web, there is an embarrassment of riches. Financially, there exist considerable amounts of capital in the marketplace with which to fuel new Web-centric efforts. Business-wise, there is tremendous demand for services delivered across the Web.4 Technically, the barriers to entry are very low: lashing up a reasonable Web application these days can be done with open-source software (such as Apache, the Web's most popular server), simple scripting languages (Perl being the most used), and many off-the-shelf components (there exist a plethora of middleware products, from Microsoft's DNA to IBM's WebSphere, as well as components for encryption, credit card processing, Web site personalization, and so on).

However, despite the ease with which one may create a meaningful Web presence, I do find that virtually every company driving its business to the Internet faces the same four pain points as they mature their site into a complete Web system

First, there is the challenge of building a compelling user experience. Slapping up a set of static pages is a start, and in fact it's not a bad start for many projects. Very quickly, however, a business will want to offer higher degrees of interaction. Many projects fail at this point by focusing upon eye candy rather than deep content. If you get over that temptation, then the world of scripting, Active Server Pages, Java Server Pages, Macromedia's Flash, and Servlets give you a wide range of technical choices whereby you may turn that Web site into a Web application.5 In the process, however, most projects experience a clash of cultures, with their content creators speaking a different language than their software developers. From

the perspective of a content creator, content is king; hence, all tools and workflows center around the manipulation and control of that content. From the perspective of a software developer, code rules; hence, all tools and workflows center around that artifact and its neighbors. A successful business will learn how to reconcile these two sets of stakeholders, such that the user experience derives from a balance of raw content and underlying software mechanisms.

Second, there is the challenge of speed - a slow Web experience ensures that users will get bored and move on. Building an application for normal loads is straightforward, but building an application for literally unimaginable levels of use is something that ends up coloring every strategic design decision. In classical client/server systems, the development team would have a reasonable handle on the number and types of users. On the Web, however, all bets are off: the Web literally offers a window to the world. Therefore, the traffic that an application might have could easily be numbered in the millions. There do exist all sorts of tricks of the trade that help, from mirroring to load balancing to IP redirection. However, the need for speed will always tend to warp a system's architecture, as is found in the tradeoffs of using a messaging protocol between Web server and application server versus more tightly coupled remote procedure calls.

Third, there exists a need for continuous change. A static Web application is a dead Web application. Not only must a project keep the content of its site fresh, but it must constantly adapt to changing business rules and new technology. An organization that's able to sustain a nimble development organization is one that will rise above its competitors. Quite bluntly, that's a hard thing to do, made harder by the fact that, once launched, you really can't take a Web application down. Even a modest Web application will consist of a few thousand moving parts. If it's a vibrant site, many of those parts will experience continuous change, albeit at different rates of change. In particular, the data associated with that site will change relatively slowly, followed by more rapid change in its business rules, and even greater rates of change in presentation and in content. It's not unusual for a Web application to undergo a face-lift after just a year or two of use, and for most sites, content changes daily, if not even more rapidly. On top of all this business-induced changed, there's change in the underlying technology: the very protocols of the Web are changing with the emergence of technologies such as WebDav and XML. A development

organization must keep 100 percent of its attention focused on pushing a quality product out the door in a repeatable and sustainable fashion, but must also have another 100 percent of its attention focused on changing technology. To do otherwise will mean that the Web application will suffer a slow, lingering death of technical obsolescence.

Finally, there is the pain of legacy. For all early and pure dot-com companies, legacy was simply not an issue, because their applications started out as virgin systems with little or no constraints imposed by historical pieces of software. For all others, legacy is a very real issue: moving to the Web does not mean you can shut off your business until your Web site is live. Instead, you have to keep your business running while you make the transition. Furthermore, your organization probably has considerable investment in existing software, especially in software that offers a significant competitive advantage in the marketplace. In any case, it's simply impractical to throw away all that code. The value of that software notwithstanding, legacy code offers its own challenges, especially as the team tries to move it to the Web. You can make some headway by slapping a new presentation layer upon an existing client/server system, but taking that application all the way to the Web usually requires some skillful surgery that, hopefully, will not kill the business in the process.

Surprisingly, some of the early dot-com companies have started to experience legacy problems, specifically with legacy Perl and Java. In the presence of low technical barriers to entry, many an organization has started down the path to the Web by throwing scripts around a previously static site. One can go down this path a considerable distance, adding lots of value to the user experience along the way. Inevitably, however, the team will wake up one day and realize that they've got a system that has no identifiable architecture, is increasingly difficult to change, and tends to break in unexpected and in very difficult to understand ways. When that happens, it's a sure sign that the team has lost control of the application's architecture and is now at the mercy of the legacy they built earlier, one line of code at a time.

So what's the solution? The obvious answer is that even though developing for the Web is very much a here-and-now activity, we simply cannot limit our thinking to the moment. We've got to think beyond tomorrow, beyond next week, and into a reasonable future so that what we create

today will still be practical a year from today. Luckily, e-development, like history, is a cumulative beast that builds upon previous experience to create the next event. Remember the quote about those who do not learn from the past being doomed to repeat it? That's the way it is with development. We must learn from our mistakes or else we are dooming ourselves (and our customers) to the same old problems.

I have long been an advocate of having a strong process in development - a method to your madness, as it were. And that is especially true here. The discipline imposed by something like the Rational Unified Process is crucial in the development of e-business applications. First, it can be tailored to individual roles, thereby giving your content creators and your software developers common ground on which to work. Second, by mapping out a plan of attack for your project, you avoid the pitfall of missing crucial issues down the road. It effectively eliminates the surprise factor, which so often crops up in projects where change is a fact of life.

Experience has shown that the most successful Web applications tend to follow a use-case driven, iterative, and incremental process. Driving the face of a Web application via use cases ensures that you'll deliver a user experience that meets the needs of your system's stakeholders. Applying an iterative and incremental process is equally important, especially in the Web space, where a vibrant site is typically undergoing continuous change anyway. Applying an iterative and incremental process lets your team mitigate the common problems experienced by an undisciplined team: your system will have an identifiable architecture, it will be resilient to change, and it will behave in predictable ways.

Many teams developing Web applications are seriously undertooled. The macho programmer's declaration, "Give me Emacs, gnu, and a place to stand, and I will move the world," may work for some classes of applications, but when you are orchestrating a diverse team of content creators and software developers to build a Web application, you need much more. Tools for requirements management will help you control the scope of each release. Tools for modeling will help you control your system's architecture. Tools for configuration management will help you control all the artifacts of development as well as all your system's content artifacts. Finally, testing tools will help you deliver a quality user experience.

Obviously, the Internet is here to stay. And, just as obviously, what the Internet is now will be quite different from what it is five years from now. Unfortunately, none of us moonlight on the Psychic Friend's Network, so we can't predict how we'll need to develop in the future. However, as Alan Kay has stated, "The best way to predict the future is to invent it." With a lot of forethought, a strong process, and the right tools, we can do just that - making our jobs both today and next year a little easier.6

Footnotes

1. Koolhaas, R. and Mau, B. S, M, L, XL. New York, New York: The Monacelli Press, p. 572.

2. "Internet Economy Index." The Industry Standard. December 27, 1999 - January 3, 2000.

3. Booch, G. "Development of the Web, by the Web, and for the Web." Object Magazine. 6(6).

4. The chief architect of a major bank in Switzerland once remarked to me that "the computer is the bank," meaning that the essence of that bank's business was essentially all manifest in software.

5. Jim Conallen of Rational distinguishes the two thusly: a Web application is a Web site where user input (including navigation through the site and data entry) affects the state of the business.

6. Remember, the code you write today may be maintained by your children and children's children some day!




http://www.cmp.com/

http://www.unm.com/

Rose 101

Naveena Bereny

Naveena Bereny is the Marketing Engineer for Rational Rose. She has a Master's degree in Computer Science from Arizona State University and five years of experience using, supporting, and marketing object-oriented methods and tools. She can click a mouse around a Rose diagram faster than your eyes can follow.

Epilogue

Epilogue: A concluding section that rounds out the design of a literary work. (Merriam Webster's Collegiate Dictionary, 10th edition.)

I don't actually fool myself into thinking that my Rose 101 columns are "literary works," but this is, in fact, a concluding section. This will be my last article for Rose Architect as I'm leaving Rational to (surprise!) join an Internet startup company. But before I leave, I wanted to report that I've had a chance to explore Rose 2000 (which was released late last year) and I've found some nifty new features that definitely caught my attention.

My favorite is the bird's eye view, where you can examine an extremely large Rose model at a very high (altitude) level, then zoom in on the parts that interest you the most. For those of you who haven't used it yet, here's a quick way of trying it out. First, open a really large class diagram. See the little hand symbol in the bottom right corner of the class diagram? Click on it and you should see the bird's eye view. You can now move around this view and zoom in on desired sections of this large diagram. Cool, huh?

One of my other favorite features is the Java(tm) automatic code generation. Rose 2000 lets you automatically generate Java code for the classes that you model on your diagram. Here's a Rose 101 demo:

● Set the default language to Java in the Rose model. ● Drop a class named test on the Rose model, and assign it to

a component also called test. Assign this to be a Java component.

● Select the class, then the Tools:Java:Project Specification menu command.

● Select the Detail tab. The very last check box, "Automatic Synchronization Mode," should be checked.

● To see this work, go ahead and generate Java code for this class.

● Browse to the code using Tools:Java:Browse Code and add a new attribute or operation. Save the code. The new item will be reflected in the model automatically.

● This feature only works with the built-in Java editor.










I'm sure most of you have already explored Rose 2000 on your own, but I did want to explain these two favorite features, and refer you to www.rational.com/products/rose for the complete list of what Rose 2000 can do.

Before I go, I also wanted to pass on one more general Rose tip. Many of you have sent me e-mails (and thank you to all my faithful readers), asking about what resources are available to Rose users. I'm sure many of you have already visited some of these sites, but perhaps some of you are unaware of these resources. I think all of them are especially valuable to novice Rose users. Actually, these resources are good for users at any level of expertise with Rose. You might want to bookmark them and check back regularly to see what is new.

Tutorials

The UML CD is, itself, a wealth of information. If you know someone who is just starting out with UML, this is one of the best resources you can give them. The tutorial is available at http://www.rational.com/umlcd/index.jtmpl.

Booklist

There is a reading list available for beginning, intermediate, and power Rose users at www.rational.com/products/rose/gstart/books/index.jtmpl.

Partner Products

Ever had one of those "it would be really cool if I could do this with Rose, but I can't" thoughts? Chances are, there is a partner who can help you. Visit these two sites: the Rational Partners page at http://www.rational.com/products/rose/prodinfo/partnernews.jtmpl (this is the official Rational Software Partner Products site); and the Rose Architect article written by John Hsia, which lists partners and their products and can be found online at www.rosearchitect.com/mag/archives/summer99/extend.html.

Technical Support

The technical support pages are full of information with FAQs and technical notes to help you along. You can find this page at www.rational.com/products/rose/support/index.jtmpl.

Training

If you are looking for some Rational Rose training, Rational University offers several courses You can also check the schedules of the Rational University at www.rational.com/university/schedule/index.jtmpl.

User Groups

Talk amongst yourselves about Rose and how you are using it. We have two cafés set up: Rose Café at http://cafe.rational.com/HyperNews/get/hn/rosecafe.html, and

http://www.rational.com/products/rose

http://www.rational.com/umlcd/index.jtmpl

http://www.rational.com/products/rose/gstart/books/index.jtmpl

http://www.rational.com/products/rose/prodinfo/partnernews.jtmpl

http://www.rosearchitect.com/mag/archives/summer99/extend.html

http://www.rational.com/products/rose/support/index.jtmpl

http://www.rational.com/university/schedule/index.jtmpl

http://cafe.rational.com/HyperNews/get/hn/rosecafe.html

UML Café at http://cafe.rational.com/HyperNews/get/hn/umlcafe.html. Both of these cafés are excellent sources for peer discussion.

Case Studies

Are you starting a new project and would like to see if someone has "been there, done that" before you? Check out www.rational.com/products/rose/gstart/case/index.jtmpl. (There's even a way to contact Rational about how you can be featured in a future case study.)

The Best Resource

Of course, I have to admit that one of my favorite resources is Rose Architect itself, which you can find online at www.rosearchitect.com. We archive all of our back issues here, so if you've misplaced your old copies or want to refer colleagues to a particular article, you can read it on the Web.

Finally, I just wanted to say that I've had a wonderful time being part of the Rose Architect editorial staff. Through my columns, I've met many devoted Rose users and have enjoyed reading the diverse articles that are published in each issue. It will be strange to read future issues without seeing my words in them, but I honestly won't miss the craziness of deadline week and the stress of occasional writer's block. Oh, and don't worry, Rose 101 isn't going away, it'll just be "under new management" in the next issue. Thank you for everything!

À Bientôt



http://cafe.rational.com/HyperNews/get/hn/umlcafe.html

http://www.rational.com/products/rose/gstart/case/index.jtmpl

http://www.rosearchitect.com/


http://www.cmp.com/

http://www.unm.com/

Working with XML Documents in UML

jim conallen

jim is the Web Modeling Evangelist for Rational Software.

The XML technological revolution, like most innovations related to the Web, is accompanied by a lot of confusion. Unfortunately, it will take a lot more than this simple article to clear up any of that. Instead, this article is intended for those fluent in UML and some XML, but haven't really thought about putting the two together before (or have thought about it, and decided that calling it an early day and making a trip to the pub would serve everyone's interests better). For those about to embark in this territory, fear not: the practicality and usefulness of expressing XML document structures in UML does make sense, and a lot of us have been thinking about it for some time now.

The first thing that needs to be addressed is why. I have been accused in the past of being a modeling zealot, and of modeling things in UML that really needn't be modeled. I once modeled the usage of a new water cooler in the office with UML, and had the use case diagram taped to the cooler for those unsure of its intended purpose. That was a case of frivolity. Modeling XML document structures, on the other hand, has very practical uses for system architects and designers. In fact, the use of XML documents for structured data interchange in a system can be considered architecturally significant.

What is of even more importance is the fact that designers and implementers will have to build systems that work with XML documents. As a result, designers and implementers are concerned with the structure of certain classes of XML documents, namely, Document Type Definitions (DTDs). An XML document is to a DTD what an object is to a class. When building systems, designers and implementers work with DTDs, not with individual XML document instances.

Even more useful than DTDs are schemas. Schemas in general are an alternative way to express XML document structures, most of which are expressed in XML itself. In this way, the same XML parser that parses the document also parses the document structure definition. XML Data is presently the most promising schema candidate for providing the most appropriate information for XML usage and definition. In addition to defining valid XML structures, schemas allow us to associate datatypes, comments, and other useful information with the structure. Unfortunately, only DTDs are recognized as an official standard, and it is likely










that most XML document interchange will rely on DTDs for document structure definition.

The modeling of DTDs, therefore, is what is of interest to the designer and implementer. A DTD represents a class of XML documents that will be used in the system. A DTD document specifies the structure and composition of an XML document instance. Systems are designed to receive and produce XML documents that validate against certain DTDs. The ability to express arbitrary DTDs with UML enables designers to include in the model the structure of information that is being interchanged externally or between different parts of the system.

Much more semantic information is expressed in the DTD itself (over the parser), which is generic by its very nature. The two most common types of parsers for XML are the Document Object Model (DOM) and the Simple API for XML (SAX). The DOM provides an object interface to an XML document, whereas the SAX uses an event-driven model for parsing. Even with these commonly available parsers, much of the work for implementers and designers is in navigating the documents.

Because the DOM provides a very generic interface to a document, a significant amount of work must be done to access document elements. Much of this work is repetitious and can very well be encapsulated and wrapped by a set of accessor classes. A similar situation exists for SAX. These interfaces present a situation where the designer and implementer are working primarily with (or against, depending on your level of cynicism) the API and not with the actual business-level content, where we would rather have our development teams working.

The role of DTDs in UML is one that expresses the structure of a class of XML documents that the system has to process (accept, modify, and produce). Having the DTD of documents that the system has to process incorporated in the UML model of the system allows designers to use it as a reference. The key to this is, of course, doing so at the appropriate level of abstraction and detail. For example, all XML documents can be modeled via the DOM, but just including the DOM in the model of your system is not of much practical use, especially when you know there is a limited set of document structures that your system will be processing. What is useful, however, is expressing the DTDs that your system uses in the UML, and then using them as reference points for the other parts of the system.

The typical scenario is this: an application needs to be created that works with an industry standard DTD - let's say in the office supply market. This standard was defined by an industry consortium to enable the electronic interchange of information between companies. My system needs to be able to accept and process XML documents that adhere to the DTD. I first express the DTD in my UML model of the system. We'll look at the proposed mapping in a minute. The next step an architect or designer might do is rework, or even extend the DTD. My particular company might accept this document, and even use it internally. However, when used internally, some additional elements might need to be added. Because this is a design-level activity, and is most likely a result of other factors already expressed in the UML model, making these changes in the model

with Rose makes a lot of sense.

The next step that would probably be taken is the creation of an object wrapper around the document. Since working with the DOM or SAX is tedious, and not where we want our development staff spending their time, the goal of the designer would be to create a customized object interface around the XML documents. This customized interface should provide an easier to use API for the developer, freeing him/her to concentrate on the task of implementing business logic, not XML logic. The good news is that several companies already provide utilities to automatically create a Java-based wrapper around XML document instances. IBM provides such capabilities with their Visual DTD application. Visual DTD is a DTD editing application that has an option to save a DTD as a schema and to generate Java code that, used in conjunction with its XML Toolkit and a couple of other classes, provides a reasonably intuitive interface to XML document instances without all the tedium of working directly with the DOM.

The bad news is that this direct mapping of DTD-to-Java code may not be the most suitable interface for the particular task at hand. It could be better. In our office supply scenario, one industry standard DTD would be used by different segments of the industry, some are suppliers, some retailers, others consumers. Depending upon who you are and your level of usage, your ideal interface to the document might be different. For example, retailers might be more concerned with summaries and totals, whereas consumers would be mostly concerned with sizes and colors. Creating these even more customized interfaces to XML documents requires some effort and skill on the part of the designer, and the tool and notation for doing this are Rose and UML. With the DTD expressed in UML, and possibly even with an automatically generated prototype of the interface, it is possible to use Rose to further customize the interface, and regenerate the Java code, this time from Rose.

With this scenario in mind, let's examine it in a little further detail. But before I delve any deeper, one disclaimer: the DTD/UML mapping I am about to introduce is based on some early beta work here at Rational. It is likely that there will be some changes made to it before it is incorporated into a released version of Rose. At the time of this writing most of the new DTD features in Rose are available in the current beta. This article is not intended to be a tutorial of these new features, but merely to introduce the ideas and concepts behind the inclusion of DTDs in our models, and to get some early feedback on it.

DTD/UML Mapping

The easiest way to understand how to express a DTD in UML is with an example. In our scenario, there is an industry standard DTD that we must work with. So it is likely that we have some type of DTD to begin with. The following represents a simplistic DTD to represent a purchase order:

<!DOCTYPE purchase-order [

<!ELEMENT date (#PCDATA)>

<!ATTLIST dateformat CDATA "dd-mm-yyyy"

><!ELEMENT account (#PCDATA)><!ELEMENT itemno (#PCDATA)><!ELEMENT itemdes (#PCDATA)><!ELEMENT quantity (#PCDATA)><!ELEMENT comment (#PCDATA)><!ELEMENT item ((itemno,itemdes,quantity)|(comment))><!ELEMENT purchase (date,account?,item+)><!ATTLIST purchase

status CDATA "initiated" >

]>

In this example, a number of elements and a couple of attributes are defined (we'll save the discussion of entities and notations for another article).

DTD elements map to classes in the logical view, which are stereotyped <>. Their attributes map nicely to the class's attributes. The biggest challenge in this mapping is how to map the content model of an element. An element's content model is, for the most part, what the element can contain (see Table 1).

In our example code, most of the elements either contain only parsed character data or specify child elements. One of the biggest challenges in creating a DTD mapping for UML is how to handle child elements. Child elements are specified in groups with parenthesis ( )'s , and ordered with choice ( | ) and sequence ( , ) connectors. Additional occurrence indicators specify how often a child element may occur (see Table 2).

Given this, we can see that a purchase element consists of a date, optional account, and one or more item elements. An item element consists of either an itemno, itemdes and quantity element, or can be a comment. To model this in UML, we need a way to represent these groupings. This is done with a new stereotyped element, <>. This class acts as a generalized grouping operator, similar to the n-ary model element in OMT. Its icon is a simple diamond. Figure 1 shows the UML diagram of our simple DTD using these stereotypes .

In Figure 1, we see a tree-like structure, which is expected, since XML is inherently hierarchical. This diagram shows another stereotyped class: <>. The class #PCDATA is, of course, the representation for parsed character data (the XML term for text).

Looking at the root class, purchase, it can be seen that it contains a group of three child elements. The type of group is indicated by the role constraint AND. This constraint corresponds to the sequence connector ( , ). The ordering of the child elements is important in XML. Unfortunately for our situation here, UML containment

semantics do not include ordering, so we express this information as ordinal numbers in the role constraints.

The key points in Figure 1 are:

● Directional associations indicate ownership. ● Grouping classes are nested, to further emphasize ownership. ● Sequence ordering is captured as ordinal values in the role

constraint. ● Role constraints indicate the type of grouping: sequential or

choice (AND, OR).

Now that we have expressed our DTD with UML, we can augment it or even change it, then regenerate a new DTD. For now, however, we will be content to just have the DTD expressed in our model.

The next step in the process is to generate a prototype Java-based object interface based on the DTD. IBM's Visual DTD application allows us to generate a set of Java wrapper classes that provide a customized interface to XML document instances that validate against this DTD. Figure 2 shows the Visual DTD graphical view of the DTD. Notice its similarity with the UML representation.

Generating the Java wrapper code from Visual DTD and then reverse engineering it back into Rose gives us the diagram in Figure 3. In this class diagram, it can be seen that our XML document has a very simple and intuitive interface that makes it easy to access and change XML document content.

Much of the work involved with XML access is delegated to the superclass of all of these customized wrapper classes: IBMXMLElement (Figure 4). This class does all of the work in traversing the XML document (using the DOM) and accessing element values and attributes. This superclass provides methods to set and get an element's values and manage child elements. The support for managing multiple instance children is basic and requires working with basic Vectors; but it does provide most of the functionality that an implementer working with this type of XML document instance needs.

There is an additional "factory" class that manages the XML document instance and its element's lifecycle. This includes the ability to create new documents, load existing documents, and even save them to files.

The final step in working with XML documents is to further customize the wrapper to suit the particular needs of the application. This, of course, could be done in Rose against the Java classes. When the interfaces are customized, and perhaps even the DTD itself is customized, both can be used to forward engineer new code for the system.

Conclusion

Expressing XML structures in UML models makes a lot of sense when you consider how XML documents are actually used in the system. Designers and implementers will eventually have to work with them. With the right set of tools, DTDs can be incorporated in our UML model, and wrapper code can be generated and even customized. This makes the job of the development team tasked with using XML in systems much easier.

NOTE: All of the work discussed in this paper is very new, and we expect this mapping to change. Please visit www.rational.com for updates and more information. Also, I'm very interested in what you think about all this. Is this how you want Rational to help provide support for XML development? Do you have any suggestions or comments? Please let me know at [email protected]. Thanks.

Footnotes

1. When DTDs are used, a separate parser (or language) is required.

2. SAX is most convenient for very large documents that might otherwise not fit in memory.

3. The Technology Preview edition of Visual DTD is available from IBM's Java Web site.

4. Object Modeling Technique was a precursor to UML originally created by Jim Rumbaugh, et. al.

5. This particular diagram was reverse engineered from the DTD source with the first beta release of Rose 2000e.






http://www.cmp.com/

http://www.unm.com/

Table 1

Back to Article

</html

Table 2

Back to Article

</html

Figure 1: UML representation of the purchase DTD.

Back to Article

</html

Figure 2: Visual DTD representation of the purchase DTD.

Back to Article

</html

Figure 3: UML Class diagram of Java class DTD wrappers.

Back to Article

</html

Figure 4: XML element wrapper superclass.

Back to Article

</html

Extending Rose

John Hsia

John Sunda Hsia is the author of the training class "Extending Rational Rose." As a Technical Lead Engineer with the RationalLink partner program, he manages the training support of RoseLink, RequisiteLink Partner Program, and ClearCaseLink partners in their effort to create add-ins and integrations. John has spent almost ten years working with visual modeling tools, object-oriented methodologies, structured methodologies, and meta-CASE tools. John can be reached at [email protected].

Common Questions from Experienced REI Users

Over the past three years, I've consistently come across some common questions during my interaction with students in the Extending Rose class and with partners in the Rose Technology Program. In this issue, we will explore the answers to a few of these commonly asked questions:

● How do I navigate associations? ● Can I manipulate two Rose models from RoseScript? ● How do I access state and activity semantics? ● How do I get the contents of a diagram? ● Why not go directly to the model file?

How Do I Navigate Associations?

When a user creates a single association for the first time, Rose is really creating three REI objects. As you would expect, an association is created. In addition, a role is created for the class on each side of the association.

Navigating from a given class to the other associated classes doesn't require knowledge of the semantics stated in the previous paragraph. In fact, there is a method that will get this information directly:

Class.GetClients (relationKind:Integer, relationType:Integer) : ClassCollection

The parameters of this method will control what type of relationships to navigate. As an example, a call with the arguments (0, 0) will get classes with all relationships (inheritance, dependency, realization, and, of course, association) to the current class whereas the arguments (0, 4) will retrieve classes with association relationships. Keep in mind that this method only navigates one level of relationships. In addition, this method does not return the association or role objects where interesting information may be captured.











A less direct alternative is to work through the actual association object and the role objects. Getting to the associations that a class is involved with is easy:

Class.GetAssociations : AssociationCollection

Getting to the class on the other side of an association requires that the role object that corresponds to the class is on the other side:

Class.GetAssociateRoles : RoleCollection orAssociation.GetOtherRole (thisClass:Class) : RoleThe second step is getting at the actual class:Role.Class : Class

So, why would one want to bother with the role object? As it turns out, that's where the interesting association information is located. If you're interested in properties such as navigable qualifiers (i.e. role.keys), constraints, role names, or cardinality, there are attributes for each of these. In addition, aggregation and composition relationships aren't separate REI objects but, rather, they are associations with the appropriate values for the role properties role.aggregate and role.containment, respectively.

What about the association object? As one would expect, the name of an association (i.e. association.name) and any custom properties would be found here. A less commonly used UML construct called an "association class" is also represented here. For those not familiar with this, an association class stores the attributes and operations assigned to an association relationship (e.g. "date of marriage" might be an attribute on a "married to" relationship between two "person" classes).

In the REI, the association class is just an object. From the association, one can navigate to the association class through:

Association.LinkClass : Class

As you would expect, a class object also has some methods in support of this relationship:

Class.IsALinkClass : BooleanClass.GetLinkAssociation : Association

Can I Manipulate Two Rose Models from RoseScript?

Absolutely. You can manipulate two Rose models through the use of COM. RoseScript can already manipulate one model - the model loaded into the current Rose session. Since Rose can only handle one model at a time, the second model would have to be loaded into a second session of Rose on the same machine. This second session of Rose would be a COM server to a RoseScript in the initial Rose session. A sample RoseScript that extracts the names of the classes in two models is shown in Figure 1.

FIGURE 1: Print names of all classes in 2 Rose models.

As you can see, the objects from the second Rose session are all typed as "Object" (lines 2-4) rather than the specific REI type (line 13). This late or dynamic binding is necessary, as Rose doesn't support early binding . If early binding is important to you, your logic will have to reside outside of RoseScript in a COM client (e.g. VB) that accesses two Rose COM servers.

How Do I Access State and Activity Semantics?

The difficulty in getting to the semantics created through the state and activity diagrams usually revolves around the State/Activity Model represented by the REI object called StateMachine. If you've ever inserted a statechart diagram, or an activity diagram, you undoubtedly noticed that a StateMachine was created in the browser. As signified by the nesting level, this model is actually created at the level where you created the new diagram (i.e. package, use case, class, state, activity, or operation). Chances are you also noticed that the StateMachine contains your newly created diagram as well as any elements (states and activities, for example) you might have created in these diagrams.

There are six different contexts where StateMachines can be created. Depending on the context, the method to get to the StateMachine will be different. The most straightforward ones are:

UseCase.StateMachine : StateMachineClass.StateMachine : StateMachine

For activities and states, the approach is less direct:

Activity.GetStateMachines.getat(1)

State.GetStateMachines.getat(1)

As it turns out, GetStateMachines returns a collection of StateMachines. Fortunately, it always returns a collection of one as state and activities cannot exist outside this context and Rose will not allow more than one state machine. For packages and operations, the technique is even less direct:

Category.StateMachineOwner.StateMachines.getat(1)Operation.StateMachineOwner.StateMachines.getat(1)

So a traversal through the REI object StateMachineOwner is necessary. In the last two cases, both the existence of a StateMachineOwner and the return of a collection by StateMachines are simply placeholders for future functionality.

From the StateMachine object, interesting statechart and activity diagram information such as transitions, states, diagrams, swimlanes, activities, decisions, and synchronizations can be retrieved. From these objects, other semantics can be easily accessed. Just check out these objects and you'll be pleasantly surprised.

How Do I Get the Contents of a Diagram?

If you're like most users, you have probably had some difficulty relating model semantics to what's presented in a diagram or vice versa. To set your expectations correctly, the REI has always been more focused on exposing model semantics rather than the aesthetic presentation of a diagram. All that said, the more recent releases of Rose have increased their support for diagrams in the REI.

There is a diagram object for each type of diagram (e.g. ClassDiagram, StateDiagram). From all diagram objects, you can find the interfaces for common activities such as laying out the diagram (Diagram.layout) or generating a windows metafile (Diagram.render*).

As for mapping between semantics and presentation, one has to understand a little more about the architecture of Rose. Rose has an architecture that involves only having one definition of each model element and views from each diagram where the model element is referenced. For example, when you create a class for the very first time in a class diagram, Rose is really creating two REI objects - a definition (i.e. class) and a presentation object (i.e. classview). Any subsequent references to this same class in another diagram will only result in the creation of a presentation object. Likewise, deleting a class from a diagram (i.e. delete key) only removes the presentation object, whereas deleting the class definition (i.e. ctrl-d) removes the definition along with all views.

In Rose, the definition object and the presentation object are represented by descendants of the roseitem object and the itemview object respectively. To continue with our class example, there is a descendant of roseitem called class, and there is a descendant of itemview called classview. Classview contains all the presentation properties of a class in a particular

diagram such as position, font, and color.

Now to our original question - mapping between the class object and the classview object. Let's explore navigating from a class to a class view via an example. In Figure 2, you'll find a RoseScript that prints out the x,y-coordinate information for all the classes in the currently active diagram. On line 21, we call the method getClassView to get the classview object from the class. This is one of very few specialized methods:

ClassDiagram.getClassView(theClass Class) : ClassViewStateDiagram.getStateView(theState Class) : StateViewStateDiagram.getStateViews(theState Class) : StateViewCollectionStateDiagram.getSwimlaneViews(theSwimlane Class) : SwimlaneViewCollection

FIGURE 2: Print the coordinate information for classes in curent diagram.

For most classes (e.g. use cases), you'll have to use the generic method:

*Diagram.getViewFrom(theItem RoseItem) : ItemView

To navigate from the view to the roseitem, one only needs to look at the item property:

ItemView.Item : RoseItemClassView.Item : RoseItemStateView.Item : RoseItem

...

The returned RoseItem object will have to be typecast to the appropriate specialized class. See line 7 in Figure 2 for an example.

Why Not Go Directly to the Model File?

First of all, what is the model file? Most experienced Rose users know that the Rose model is stored in an ASCII file called the model file (*.mdl) . This ASCII file is somewhat readable by humans. More importantly, it is parsable. In fact, a few daring partners have chosen to parse or generate this file rather then use the COM interface. For rather large models or for add-ins that need semantics that aren't exposed in Rose, this may be a reasonable alternative. But this approach has some inherent risks:

1. The file format is subject to change. Whereas existing REI interfaces continue to be supported, your integration might have to be upgraded for each new release of Rose - even a service pack. As an example, Rose 98i Service Pack (June 1999) included activity diagrams. If your parser wasn't written to understand this, or if your parser wasn't extremely intelligent, chances are your integration would have failed.

2. The file format is undocumented. This means that it is possible for you to generate a format that is inconsistent.

3. Updating or merging information is problematic at best. To add a new class into an existing model, you'll have to read and understand the current model file. Then you'll have to add the new definition, create any necessary cross references, and hope that everything is still consistent. With the REI, just make the right call(s) and the rest is taken care of for you.

4. COM is also available on UNIX. Sometimes users use the model file because of their development platform (UNIX, for example). As it turns out, the REI is also accessible via COM on UNIX. Previous to Rose 98i, libraries from Bristol Technologies were required to make this happen. For 98i and later, WinSoft from MainSoft is needed.

5. You'll have to manage the control units. Remember that with control units, some aspects of a model may physically reside in files outside of the model file. As a result, you'll have to keep an eye out for these in the model file and manage them yourself. Don't forget that these external files might also reference other external files so you'll have to navigate these references recursively. What fun!

If these risks aren't enough, it's worthy to note that with very few exceptions, Rational's own add-ins don't go directly to the model file. If you didn't get the message by now, I'll be just a little more direct - USE THE REI, AVOID THE MODEL FILE! If you still decide to use the model file directly, take these words to heart - BE AFRAID, BE VERY AFRAID!

Conclusion

The questions addressed here do not cover all the issues that experienced users will run into. They are just a few questions that I've encountered numerous times where the answers may not be all that obvious. With eight different diagrams in the UML and with over 130 REI objects to choose from, there is no doubt that the appropriate method or object for a particular need won't always be intuitive. In some rare cases, the required method or object won't be available. Rational Software's intention is to expose all semantics of the model - though there are still some unexposed details. So please, be patient when searching the REI and either you will find what you need or, chances are, Rational Software has that feature slated for an upcoming release. Either way, your patience will pay off.

Footnotes

1. For more details on COM, RoseScript, and binding, check out the article "Using COM in Your Rose Extensibility Solution," from the Winter 2000 issue of Rose Architect.

2. For this example to work, the script must be executed via a custom menu option. If you attempt to execute this from the RoseScript editor, the currently active window will be the text editor and not a ClassDiagram.

3. There are other extensions for controlled units (parts of the model stored external to the model file), but essentially the file format is the same.anced scripts, and you're stuck.




http://www.cmp.com/

http://www.unm.com/

the web modeler

jim conallen

jim is the Web Modeling Evangelist for Rational and the author of Building Web Applications with UML from Addison-Wesley's Object Technology Series. There's a chance he'll soon be coming to a town near you to deliver one of his Academy Award-nominated talks on, as he puts it, "object-oriented Web-related things." He can be reached at jconalle

@rational.com.

Modeling Web Clients with UML and Rose

In my first article on modeling Web-centric systems with UML, I briefly introduced the Web Application Extension (WAE), an extension to UML that allows us to model the Web-specific elements of a Web application. The whole goal and purpose of WAE is to allow the designer to accurately capture and represent the entirety of the business logic execution of a Web application, regardless of where that logic is actually being executed (client or server), and most importantly, at the right level of abstraction and detail for architects, designers, and implementers. In this article we'll take a closer look at modeling the client, since this is the area that has the most Web-specific architectural elements.

Before we continue, however, I have to reiterate the importance of distinguishing the difference between business logic and presentation logic in the system. Presentation logic includes things like pop-up menus, fly over hints, and other mechanisms that enhance the user interface. Business logic, on the other hand, implements the rules and processes of the business (the main reason for the system's existence). Even though presentation logic is important to nearly all applications, it does not directly contribute to the business logic of the system, and so belongs in a different part of the model or as a completely separate user interface model. By separating these two concerns it is possible to develop and evolve them independently. This is particularly important in e-commerce applications where the look and feel needs to change on a regular basis, but where the actual business logic remains the same.

One of the most significant architectural elements of a Web application is the Web page. Depending upon the particular architecture, the pages might be scripted files or compiled code. Most of a Web application's activity is instigated by page requests. Some pages contain code that is executed on the server, and use server-side resources such as databases and transaction processing monitors (TPM). Others are simply HTML formatted files. In either case, from the client's point of view, an HTML-formatted page is returned and rendered.

JavaScript

In today's sophisticated Web application there is a good chance that some of the system's business logic is executed on the client. The simplest example of this is HTML form validation. An input form can be checked for required fields, valid dates, and other locally computable values before being submitted to the server. Designing forms this way helps cut down on the server load and gives quicker feedback to the user. Typically, this is done with JavaScript on the client. When the user clicks on the button to submit the form to the server, the form's values are examined. If the form passes validation, then it is submitted to the server; otherwise, a message is presented to the user indicating the problems.

The HTML in Figure 1 specifies a form with two editable fields and a button. Notice that the button is not a SUBMIT button. The actual submission of the form is done with JavaScript. One other feature of this page is a hyperlink to another page. In this example, a form is defined along with four JavaScript functions. The UML class












diagram for this is shown in Figure 2.

FIGURE 2

In this diagram, it is not certain whether this page was dynamically constructed. If it was there would be another class in the model stereotyped <<server page>> that has a <<build>> relationship to the <<client page>>.

In some instances, validating user input is not trivial. In these situations, an object-oriented approach to providing the validation routines is helpful. This involves the use of custom JavaScript objects. Even though JavaScript is not a pure object-oriented language, it can be used in an object-oriented fashion, including the use of custom objects. (For more information on the use of JavaScript in HTML, see David Flanagan's JavaScript: The Definitive Guide, 3rd Edition, O'Reilly and Associates, 1998.) To expand the example above, we can create an EmailAddress object in JavaScript that is delegated to perform the e-mail address validation. The JavaScript for this custom object is given in Figure 3.

FIGURE 3

function validateEmail(){ var msg; msg = "";

if ( this.addr.search("@") < 0 ) { msg = "Invalid email address"; } return msg; }function EmailAddress( addr ) { this.addr = addr; this.valid = validateEmail;}

The function EmailAddress is a constructor function. It makes use of the operator to set not only its attributes but its methods as well. By convention I begin constructor functions with a capital letter to indicate that they are, in a sense, class level operations. The updated validate function uses the EmailAddress object by creating an instance of it with the JavaScript new operator and passing it a string. What is returned is the property addr and an operation valid(). The new validate function is given in Figure 4.

FIGURE 4

function validate() { var validationErrors; var msg; var form; var email; validationErrors=""; form = document.forms('PersonalInfo'); email = new EmailAddress(form.email.value); msg = email.valid(); validationErrors = appendMsg(validationErrors, msg); msg = checkName( form.Name.value ); validationErrors = appendMsg(validationErrors, msg);

if (validationErrors=="") { form.submit(); } else{ alert( validationErrors ); }}

The UML class diagram for this version of the HTML page is given in Figure 5. EmailAddress is represented in the model as a class stereotyped <<JavaScript Object>>. In this particular example, there is no member attribute of the <<client page>> that holds an instance to a EmailAddress object, yet because it depends on it, a dependency relationship is drawn in the model. This dependency relationship is a cue to any code generators to include the EmailAddress constructor and validateEmail() function in a script block in the page.

FIGURE 5

Events

Although not as common in the business logic model as in a presentation model, event handlers can be defined to react to user- and browser-initiated events. The OnLoad event, for example, is raised by the browser once the document has fully loaded. This is a useful event to handle if information on the page needs to be initialized before the user begins working with the page. Event handlers are typically specified as parameters in HTML tags. For example, the OnLoad event handler is specified in the <body> tag:

<body onload="initializePage()">

In this example, the JavaScript function initializePage() is called as soon as the page is loaded. Since this information is architecturally significant, it needs to be captured in the model. Tagged values are used to capture this information. In Rose, a special property page can be defined to capture this information (and make it available to any code generator). Figure 6 shows the specification dialog and the WAE tab that captures this information.

FIGURE 6

Applets and Controls

Some applications require even more sophistication of the client than JavaScript can provide. The use of Java Applets or ActiveX controls provide Web application architects a means to provide truly sophisticated behaviors on the client. Modeling a Java Applet or ActiveX control in the Web application world is, for the most part, no different than in any other application. The only difference is in associating the applet or control with the Web page. This is done with a directional "by reference" aggregation association. The association to the applet or control is stereotyped <<object>>. This <<object>> association represents the HTML <object> tag. Tagged values (Rose properties) of the <<object >> association are used to capture the necessary information about the object (its location on the network, ID, etc.).

If a <<client page>> included a calendar applet to allow the user to select and navigate dates, the HTML object tag might look something like the following: <object codetype="application/java" classid="java:Calendar.class" codebase="http://myserver/javaclasses/"> <param name="date" value="01/01/2000" type="data"> </object>

This tag specifies a Java Applet, its location on the network, and a parameter with which to initialize it. All of this information is architecturally significant, and needs to be in the model. Since this information is not inherently part of the applet, but rather how it is used in the context of this particular <<client page>>, this information belongs with the <<object>> association. The class diagram expressing this relationship is illustrated in Figure 7, and the Rose specification dialog for the association is shown in Figure 8.

FIGURE 7

FIGURE 8

Conclusion

What I've presented in this article so far just touches on the issues and techniques for modeling HTML client behavior with UML and Rose. The use of the WAE stereotypes enables us to address HTML and JavaScript in an object-oriented fashion. Even though code generation was hinted at in this article, the ability to provide even basic code generation and reverse engineering is presently not available. (There are some significant issues that need to be addressed in order to provide generalized code generation in diverse environments like Microsoft's Active Server pages, Java Server Pages, and Java Servlets.) The ability to model and express detailed design is currently available with Rose. The WAE stereotypes can be downloaded from Rational's Web site at www.rational.com.




http://www.cmp.com/

http://www.unm.com/

Figure 1

Back to Article

</html