by Jeff Davies
UML has been used for modeling software systems for many years now. However, I rarely find any detailed discussion or examples around modeling modern software systems and technologies. For example, modeling applications and their deployments requires the development of a taxonomy of stereotypes and an organized approach to the scope and layout of the diagrams to be truly useful. Modeling is especially important in complex environments not just for the benefit of the software engineers that are writing the code, but also for the software configuration management and production services teams that are responsible for properly configuring and deploying these software systems. This article demonstrates several effective ways to model modern software systems that can be used to accurately and concisely communicate the architectural details.
It wasn't that long ago that a useful enterprise application was built from a handful of entity beans, even more sessions beans, and some JSPs. EJBs were packaged in JAR files and JSPs were simply stored in the Web server's class path. If there is one thing you can count on in the software industry, it is exponential growth in software size, functionality, and complexity. Software size has increased to the point where portions of each enterprise application are stored in compressed format in WAR and EAR files. The complexity of software systems requires effective modeling to help manage the designs and interrelationships. The functionality of software is now at a point where you need to define a whole new paradigm to manage it: services.
Software complexity must be managed; our enterprises depend on it. This management takes the forms of both planning and communication. Today, you use UML to help plan software architecture, design, and deployment. You also use it to communicate those plans to the various departments in enterprises that must create, install, and maintain enterprise software.
UML 1.X was pretty good when it came to modeling code. It was weak with regard to modeling the packaging and deployments of software systems. With the advent of UML 2.0, UML has improved on its ability to model the core software systems. However, UML 2.0 really shines when modeling software packaging and deployments.
The purpose of this article is to demonstrate several effective ways to model modern software systems to accurately and concisely communicate architectural, design, and deployment details to the responsible parties in your enterprise. I don't claim this is the only way to model modern software. UML is rich in modeling dialects. However, if you are unsure how to quickly model software in UML 2.0, especially modeling BEA WebLogic Platform-specific information, this article will help you.
I favor the more agile approach to modeling. Modeling software systems does not directly benefit a company; the executable software holds the benefit. However, modeling is an effective communications tool to help provide the multiple departments in your company with the same understanding of how the software system is to be built, deployed, and operated.
Less really is more when modeling software. Code lives and grows over time; models are still-life images, snapshots of the design thinking at a particular moment in time. As a result, it is not very useful to model every little detail of a software system. The details of a software system change in an organic manner. It's best to model the parts that make up the heart of the software. These models tend to remain useful for a much longer period of time.
I'll start with a model that is very code-specific, and work my way to software packaging and deployment diagrams. Along the way, I think you'll get a good feel for the level of detail that is appropriate for your organization. It's important to always ask yourself, "Does this diagram help people to understand the design?"
First, let's take a quick look at what I call "over-modeling." Figure 1 shows a UML diagram for a single entity bean that uses bean managed persistence. You have seven boxes on the diagram that show the three main interfaces and their root interfaces, along with the implementation class.
At first glance, there appears to be a lot of content here. However, the model is just verbose. There is very little content in this diagram. The bulk of the diagram really shows the basic mechanics of an entity bean. An engineer with even a beginner's knowledge of EJBs would find this diagram monotonous. If you provide an entire design document filled with this level of "fluff" you run the risk of your engineers quickly getting bored and dismissing the design document as "useless."Tip! - Model the important parts of the system, not the trivia.
Let's take a look at a revised version of the same diagram. It removes the fluff and focuses more on the content that is important. Boilerplate code and constructs should almost never be modeled, unless they give some very specific benefit to the diagram (like providing context). For example, denoting a function like
ejbActivate() does not add clarity or content to the diagram and therefore you should not model it. Just because the EJB spec says the method must be present in the implementation class does not mean it needs to appear in your model.
Figure 2. A concise EJB model
Aside from not modeling the obvious, there is a fundamental difference between the two diagrams: the liberal use of stereotypes. Stereotypes are a powerful way to convey orthogonal information about any model element. Another useful aspect of using stereotypes is that the information you define is carried with the object, not the diagram. In Figure 1 the JNDI information was captured in a note on the diagram. That keeps the JNDI information specific to the diagram. In Figure 2 I have defined some tagged values for the
<<EntityBean>> stereotype that captures the JNDI information. Tag definitions are attributes of a stereotype. By defining tag definitions for your stereotypes you accomplish two goals: You provide some hints to your architects and designers about what kind of information should be included with each stereotype; and you introduce some modeling standards to your organization. By using a stereotype and filling in the related tag definition values, you make that information available to every single diagram in which the element appears. Most UML tools will allow you to selectively hide stereotypes and their tag definitions, enabling you to customize each diagram without changing any of the data that is important to the model. I will provide a sample stereotype taxonomy later in this article.
Now I'll take the functional code and model how it should be packaged into a deployable module. This is an important step that is often completely overlooked in software modeling projects. However, it's also an area where misunderstandings are common and those misunderstandings usually end up costing the company money as the project suffers delays, and recoding, to correct the problem.
J2EE projects are usually packaged as an EAR file or a WAR file. JAR files are still used, but now usually appear as elements of EAR or WAR files. In UML, files are represented as Artifacts. Artifacts are used to model things that reside on a node. (A node usually represents a device, often a computer, but it can also represent a virtual device.) For example, documents, files, executables, and libraries are all modeled as artifacts in UML. Deployable software falls under this definition, so you model it as an artifact.
These types of diagrams are among the rarest found in the field. I have seen only two companies that model at this level. Those that create these models often fall into the trap of modeling the "definition" of the deployable module. Take a look at Figure 3 and you'll see what I mean.
The first thing wrong with this diagram is that it is "modeling the obvious." The "App-Inf," "webapp," and "meta-inf" directories add no value to the diagram. Similarly, the modeling of the "customer.properties" file is highly questionable. It's just noise in the diagram. The second thing wrong with the diagram in Figure 3 is that it only models the "definition" of the module. It is still very software focused, showing the Customer EJB residing in the com.bea.customer Java package structure. Modeling the package structure can add value, depending on the needs of your organization, but this diagram really misses the boat. It should include more than just the information needed by the software engineers; it should include information important to the software configuration management team. That missing information is the "context" of the deployment module. The teams that have to run the software need to know how to deploy it, therefore the context is important to them.Tip! - A deployment model needs to show the "definition" and the "context."
A quick look at Figure 4 will make this clear. This diagram looks at both the definition of the deployment module and the context in which that module must exist. The context provides resources that the module depends on in order to function correctly. This tells your SCM and production teams to ensure they provide these resources or the software wont run.
This diagram is now useful to anyone who has to create the execution environment for the application. They now know they need to configure a JMS queue and a JDBC driver in the environment because the application will expect to see these. Critical information on the JMS queue and JDBC driver are also included. Even though I do not model every detail here, by modeling the environmental dependencies, I give the SCM team the chance to ask additional questions. Furthermore, the database administrators may like to see this diagram. Most likely it would prompt some questions from them about the table structure of the customer DB, indices, keys, and the like.
A good model doesn't just answer questions, it causes people to think and ask additional questions. That may seem odd at first blush as you'd think the point of modeling to answer questions and record decisions. That's true, but UML is not designed to model everything. Some things, like database design, are best modeled in a more domain-specific tool. Some information is best defined in a pure textual format. A good model can serve as a springboard for more detailed thinking and design in other parts of your organization.Tip! - Good models answer some questions and raise others.
You may have noticed something the diagrams have in common: Each diagram has a specific purpose and a focused message with a specific audience in mind. You don't create diagrams for the sake of the diagrams themselves. You create diagrams to communicate to your intended audiences. Each diagram should contain a focused message. That message may be: "Here are the relationships of this [concept | class | object | node] to its immediate neighbors," or "Here is the behavior of the method." As with all forms of communication, if you don't have a specific message to convey, odds are the recipient of that message won't understand your message at all.Tip! - Every diagram should have a specific purpose.
Also notice in Figure 4 that I avoid modeling the fine-grained details of both the JMS queue and the JDBC driver. A JMS queue could have additional tagged values for message buffer size, paging directory, insertion paused at startup, and on and on. You normally don't model this data because it's the type of thing that changes from one environment to the next (that is, when you move the software from your testing environment to your production environment), and these values also change during the application tuning process. Specifying their values in advance usually provides no benefit. There is one exception to this: If your company has a policy of taking the final production configuration values (that is, the values of the application configuration) after it has been tuned for performance, then I would include those values in the model.
Pages: 1, 2