Figure 1. Over-modeling an EJB (click the image for a full-size version)
Published on dev2dev (http://dev2dev.bea.com/)
http://dev2dev.bea.com/pub/a/2006/05/modeling-enterprise.html
See this if you're having trouble printing code examples
by Jeff Davies
05/09/2006
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.
Figure 1. Over-modeling an EJB (click the image for a full-size version)
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.
Figure 3. Common deployable modeling (click the image for a full-size version)
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.
Figure 4. A better deployable module diagram (click the image for a full-size version)
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.
|
For some reason, deployment diagrams usually get short shrift in most UML books. In many books the chapter on deployment diagrams ranges anywhere from two to six pages, with only the simplest of sample diagrams. In my opinion these diagrams are among the most important in all of UML. These diagrams allow you to express the architecture of a single software system or even the entire IT department, and they can be a critical factor in finding the source of performance problems in your production environment.
A typical company has a fair number of environments: development (at least one of these), testing (possibly more than one of these), performance, staging, and of course, the production environment. Many organizations also maintain a disaster recovery environment, in case of natural or man-made disaster. But there is little value in maintaining deployment diagrams for all these environments. The development, testing, and performance environments usually change far too quickly to warrant any serious modeling of the software deployed on them. The staging, production, and disaster recovery environments are (or should be) so similar in nature that modeling the production environment alone is usually sufficient to capture the essence of your deployment space.
Here is where UML 2.0 really shines. From the changes that appeared in UML 2.0, it's obvious a lot of people felt that deployment diagrams were very important. In the early part of a project, I recommend modeling your deployments at a logical level. Use nodes in the most general of terms. I also recommend creating these diagrams in the earliest stages of the project. Deployment is a critical part of your project planning, not an afterthought.
While I do see deployment diagrams in the field, most of them stop at the logical model. It is important to model the deployment of all your systems and not model each software system independently. Gone are the days of silo applications. We live in a world of interconnected systems, and those interconnections need to be planned and mapped.
The fact is that a good, physical deployment diagram can be instrumental in helping you to figure out problems in production. Did the system work fine when it was launched into production but now is having problems? Sometimes, the system showing symptoms of distress is not the cause of the problem. Instead, a system either upstream or downstream may not be performing as expected and that performance problem manifests itself in an entirely different part of the system.
There is an old parable about a raja who asked to have three men, blind from birth, describe an elephant by touching only a single part of that elephant. The man who felt the elephant's ear thought an elephant was a winnowing basket. The man who touched the tail said an elephant was a type of brush. The man with his arms wrapped around the leg of the elephant said an elephant must be a tree. An elephant, like a production environment, is composed of many parts. If you can't see and understand the entire thing, then you are like one of the blind men in the parable; Your conclusions as to the true nature of any problem will most likely be wrong. However, modeling such a large system is a non-trivial exercise. If you try to represent too much of the ecosystem on a single diagram, you'll be wallpapering your walls with massive (and useless) printouts.
Therefore, I recommend organizing your physical deployment diagrams into a hierarchy. At the top of the hierarchy is a complete picture of the "elephant," the entire software ecosystem. Due to the nature of such a diagram, it contains very few physical deployment details and is more focused on the logical relationships of the major systems.
Figure 5 is a visually simple diagram of a production environment. From this simple diagram you can see that the overall architecture is hub and spoke. You can also see the entire enterprise is logically divided into seven distinct groups, and you can guess from the central nodes name of "Service Infrastructure" that these logical, functional areas are connected through a services layer. From this diagram you can begin to drill down to gain more detail. Let's zoom in on the Customer Relations Management (CRM) system.
Figure 5. A deployment overview diagram
In Figure 6 I have changed the diagram scope to zoom in on the CRM system. In this diagram you can see three commercial applications included in the subsystem: Siebel, Salesforce.com, and ACT!. Salesforce.com really is a Web hosted application that lives on the Salesforce.com servers, but from my enterprise point of view, it is considered a part of the enterprise.
Figure 6. The CRM domain
You can also see from the diagram that there are two home-grown subsystems: The first allows customers to view their account status, order products, and engage in other "self service" activities provided through the Siebel system; the second, the CSR Command Center, is a custom application that allows the customer service representatives of the company to perform any function on behalf of the customer. In addition, it provides functionality not normally available to the customer, like tracking lead information about contacts before they become customers.
Next I zoom in on the Customer Self Service (CSS) subsystem to get a much more detailed look at the system.
Figure 7. The CSS physical deployment details (click the image for a full-size version)
Figure 7 shows a physical deployment diagram in all its glory. In fact, this diagram is at the upper limit of content density. Notice the nested elements in the Domain instance (the large box in the center of the diagram). In general, I find the maximum level of nesting should be three levels deep. Anything beyond that and the diagram begins to exceed the scope of its message. This diagram shows the following things:
In a single diagram, I have provided a significant amount of information that it useful to the Development, SCM, and Production Services teams.
Tip! - Three levels of nesting are usually sufficient.However, you need another, complimentary diagram focused on the WebLogic Server-specific details. The target audience for this diagram is primarily the developers and the SCM groups. Figure 8 is an example of this type of diagram.
Figure 8. A WebLogic Server-focused diagram (click the image for a full-size version)
Here I show additional, WebLogic Server-specific configuration information. You can see cluster addresses, multicast addresses, and multicast ports. You also see that a data source named customerDS has been created and targeted to the BackEnd cluster, meaning both servers in that cluster have access to that data source. I could use similar constructs to model JMS topics and queues, persistent stores, and more.
Furthermore, you see that the deployable modules defined in earlier diagrams are shown here, along with how they relate to the WebLogic clusters. The BackEnd cluster (and all its servers) have the customer.ear file deployed to them. Similarly, the WebPortal cluster and its servers have the customer.war file deployed on them. By referring to the deployable modules diagram, you can quickly close the loop on this information.
As mentioned previously, UML stereotypes are a powerful notation tool that allow you to capture additional information about elements in your model. Most modeling tools come with UML taxonomies for J2EE, Web services, and other technologies. If your tool does not come with these predefined taxonomies, or if the predefined taxonomies do not meet your specific needs, you can quickly create your own. Figure 9 shows the taxonomy used in this article. Feel free to customize this sample to suit your specific needs
Figure 9. A Stereotype taxonomy for WebLogic Platform models (click the image for a full-size version)
The important thing to remember with stereotypes is to use them uniformly. Your models should have to pass a review process to ensure they meet the standards set for your company. This helps you create standardized models, which in turn helps promote clear communication among your IT departments and sub teams. Maintain your stereotype model independently (that is, in its own model) and then import your stereotypes into your project models. This will save you time and ensure that you use the most current stereotype taxonomy in your current projects.
I have covered a lot of detail in this article. While certainly there is more to modeling effectively than what I've presented here, this article should help you create better models and diagrams, improve the communication of these details between different groups in your IT department, and provide some standards and a methodology to help you manage your software ecosystem more effectively. Remember that modeling is a supporting effort for what is truly important: executable software systems.
Jeff Davies works as an AquaLogic Evangelst at BEA Systems. He has 20 years of experience developing software, including commercial products like ACT!(tm) for Windows and Macintosh.
Return to dev2dev.