In this final article, we will look at Documenting a Software Architecture in Java EE. We will first look at the analysis and design of an object-oriented architecture. We will look at how given a specified business problem, the architect designs a modular solution that solves the problem using Java EE. This is part of a larger series of articles to help you prepare for the java architect exam. The most recent article looked at the design of a java architecture, “Tutorial:Design of Java Architecture for the Java Architect Exam”.

Analysis and Design of Object-Oriented Architecture

The one constant of every system is the need for change. This presents a fundamental challenge to every software architect. The need to develop and maintain software systems has driven interest in various approaches to software development and design. One of these approaches, object-oriented technology has proven over time to be one of the most effective paradigms for the design and implementation of large scale systems. Among the distinctive features of object-oriented technology are classes, instances and abstraction. As most readers will have some grounding in these concepts, we will concentrate on the areas that will prove valuable for the certification exam.

System development involves creating systems that satisfy the requirements which are captured and evolve during the development lifecycle. The requirements represent problems to addressed via the system in order to resolve these problems. Natural languages are used to communicate the requirements. Programming languages such as technology-based implementation languages (i.e. Extensible Markup Language (XML), the Structured Query Language (SQL), Java, C#, etc) are used to communicate the details of the system. As these natural languages are less precise than programming languages, there has been the development of modeling languages such as the UML in order to bridge the gap between the requirements and the system.

A modeling language such as UML can be applied throughout the system-development process as a means for gathering the requirements needed in order to implement the prospective system. UML can also be applied to different types of systems, domains, and processes as such we use UML to communicate about software systems or business systems in various domains or industries such as manufacturing, banking, e-business, and so forth. UML can be applied with any process or approach. It is supported by a large variety of tool vendors, industry-standardized, and not a proprietary or closed modeling language.

Defining the Project Lifecycle

The project lifecycle is a key concept for understanding the purpose of a project. The lifecycle maps the progress of the project from start to finish. At its most basic level, projects have two phases: planning and execution. In longer more complex projects, another layer is required to be added to the lifecycle of the projects by subdividing the planning and execution phase further into analysis, design, development, and implementation. The subdivision of the project lifecycle phases can be seen in the table below:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-projlifecycle.jpg
Figure: Detailed Project Lifecycle

The table is a summary of the classic project lifecycle phases and outlines the activities to be planned and executed for each phases. The development process that we outline here is based on the Rational Unified Process (RUP). It is an incremental process used by development managers to manage a software project. By using RUP, a project can be broken down into phases and iterations. The iterations are focused on progressively reducing areas of risk around the project. Each phase has a series of deliverables such as documentation or software that can be demonstrated and validated against the project’s objectives and goals. The iterations are used by the development manager to manage the project. Within each iteration plan there is a detailed description of the upcoming phase of work. It defines the roles of all the activities as well as the artifacts to be delivered in that iteration. RUP also outlines a set of criteria for productivity and progress that can be measured during the iteration and the specific start and end dates for product delivery.
RUP identifies four phases for projects, each of which focuses the team on a particular aspect of the project and its associated milestones. The four phases are:
  • Inception - the focus of this phase is the project scope.
  • Elaboration - the architecture as well as the requirements of the product being built must be defined by the end of this phase.
  • Construction - the software must be developed or constructed in this phase.
  • Transition - the software must be rolled out to users during this phase.


The phases of RUP are analogous to the classic lifecycle phases of analysis, design, development, and implementation. The key difference being that they are targeted at mitigating and managing risks during project development. Also in deference to classical project lifecycle which is based on the waterfall method, modern project frameworks like RUP are iterative. The frameworks are geared for project leaders as the RUP management discipline provides a process for software development managers to use in order to produce an overall project plan. The plan is focused on deliverables, and must be measurable, flexible, and aligned to progress towards your end state. Finally the plan should define the responsibilities and dependencies of the development team.

Key Aspects of Object Oriented Modeling with UML

UML is a language for modeling and communicating the attributes, qualities and behaviour of a system and its requirements. We do this by understanding the subject through the use of an alphabet, words, sentences, paragraphs, sections, and documents. Writing sentences is analogous to UML diagram fragments. The words are the equivalent to concepts and relationships between concepts in UML and the alphabet is the equivalent to the symbol fragments such as lines, rectangles and other graphical elements.

In any complex project, the requirements and implementations technologies are complex and evolve during its lifecycle. Similarly the the language for the model must be able to communicate about the system, but also enable use to manage the change and complexity during the process of communication. We will focus on outlining UML, syntax and semantics so that you will be able to properly communicate using the language of UML.

Elements - Key Concepts in Object Oriented Modeling with UML

Object oriented modeling is based on a few key elements. We will detail them below.

Class
A class defines an object type and its characteristics. This includes structural features and behavioral features. The structural features define what the objects of the class know, and the behavioral features define what objects of the class can do. For example, a Manager class has names (what it knows), and it can initiate and terminate projects (what it does). The structural features include attributes and associations, while behavioral features include operations and methods.

Associations
An association defines a type of link and the characteristics of its links, and a link is an instance of an association. A specific relationship is shown as a line path and may be labeled with the fully underlined name of its general relationship. The figure below demonstrates two specific links of the associations for 3 objects:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-associationrelationship.jpg
Figure: Association Relations with Objects

The figure shows that Robert, who is a seller, publishes the Availability Notice which holds one product. This notation and naming convention between a class and its instances, or an association and its instances, is used throughout the UML and is known as a type-instance dichotomy.

In object oriented modeling the world is seen as a collection of unique objects. Each object has its own lifecycle where it knows it attributes, its behaviors and how it can communicate with other objects. The features are what an object knows and does. Features belong to two broad categories or types: attributes and operations.

Attributes - What an object knows is called an attribute. It is basically the data held by the object. A class is the blueprint for an object. An instance of the object is created from the class (blueprint). Therefore the class defines attributes and the object holds the values for these attributes. So you can have two object instances of the same class each having their own unique identity while holding the same values for the same attributes. Attributes are held in the second compartment of a UML diagram listed as text strings. We can filter the attributes to only communicate those that we wish to show. Structural features in classes are those items that communicate the class’s structure. In classes these are associations and attributes. Classes with attributes are shown in the figure below:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-classeswithattributes.jpg
Figure: Classes with attributes

The figure below shows objects based on the classes with values for the attributes shown above:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-objectswithattributes.jpg
Figure: Objects with attributes values

Operations - Object behaviour is encapsulated in operations. Operations are how an object does processing. A class defines an object’s operations and methods. A class may have a third compartment listing operations as text strings. A class's methods can also be described using other UML modeling techniques. In the case of an object, it does not have a third compartment since all objects of a particular class hold the same operations and methods. We can filter the which operations are communicated for a given diagram. The figure below shows classes with attributes and operations:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-classwattrandops.jpg
Figure: Class with Attributes and Operations

Communication with Messages and Stimuli

The means of communication between objects in an OO application is to send messages to each other. Communication between objects via their links are known as a stimulus, while communication between classes via their associations is known as a message. So to be clear, a stimulus is an instance of a message, which is analogous to how an object is an instance of a class, which is analogous to how a link is an instance of an association. The client is the sender of the message or stimulus, and the supplier is the receiver of message. In UML, a message or stimulus is shown as an arrow attached to an association or link pointing from the sender toward the receiver and labeled with a sequence number showing the order in which the message or stimulus is sent. This is normally followed by a colon and the name of the operation to be invoked. The figure below shows an example of a that a manager assigns activities and tasks to a team based on a project's requirements.

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-generalinteraction.jpg
Figure: General Interaction

Principles of the Object Orientation

There are four principles of the object-oriented paradigm which facilitate better management of change and complexity. We detail these principles below.

Abstractions
In the OO world, concepts and relationships are called abstractions. General abstractions are classes and associations while specific abstractions are objects and links. Any well done abstraction should be well defined and hold essential information in order to understand it while excluding extraneous information. Using well-defined abstractions, allow us to better manage complexity by focusing on the simplest and most essential information.

Encapsulation
When we use classes to combine attributes and operations that only shows some of these attributes and operations via public methods we are doing what is known as encapsulation. This process of combining attributes and operation to create classes and objects (also known as localization) allows us to better manage change and complexity by limiting the number of places to be addressed when a change occurs. Generally it will be limited to a class or classes related to a particular activity or process within the application.

Generalization
Generalization is an inheritance link indicating one class is a superclass of another. It is the relationship that exists between a more general class and a more specific class to show that the more specific class receives the attributes, relationships, operations, and methods from the more general class. The generalization relationship is shown as a solid-line path from the more specific class to the more general class, with a large hollow triangle at the end of the path connected to the more general class. The use of a generalization allows us to better manage change and complexity. It gives us the ability to reuse existing abstractions in order to define new abstractions. And changes that are made to the more general class in the hierarchy are then propagated down to its more specific classes. The figure below shows an example of a generalization:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-generalization.jpg
Figure: Generalization Relationship

Polymorphism
is the ability to create a variable, a function, or an object that has more than one form. It is the ability to have multiple methods for a single operation. The generalization between a more general class and a more specific class tells us that objects of the more specific class are simply specialized objects of the general class. This means that objects of the specific class are being substituted for objects of the general class. Polymorphism allows us to improve our ability to manage change and complexity by reusing operations with new methods as well as communicating requests without having to manage which of the actual methods is being invoked.

Diagrams - The Paragraphs of UML

Paragraphs is a grouping of sentences on a common subject. In UML a diagram is the UML equivalent of a sentence. In this section we will look at how a diagram consists of a grouping of diagram elements about a common subject as well. There are two broad categories of diagrams that we use in UML for modeling. They are structural and behavioral models. We will detail both.

Paragraphs and Structural Modeling

Structural modeling facilitates the understanding and communication of the elements of which consists a system as well as the functionality provided by a system. We details some of structural modeling diagrams provided by the UML below.

Class Diagram
Class diagrams depict the structure of a system in general. Class diagrams have the following types of elements:
  • A class - is drawn as a solid-outline rectangle labeled with a name, this represents a general concept.
  • An association - is drawn as a solid-line path labeled with a name, this represents a relationship between classes.
  • An attribute - is drawn as a text string in a class's second compartment, this represents what objects of the class know.
  • An operation - is drawn as a text string in a class's third compartment, this represents what objects of the class can do.

The figure below shows an example of a class diagram:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-classdiagram.jpg
Figure: Class Diagram

Object Diagrams
Object diagrams depict the structure of a system at a particular point in time. Object diagrams have the following types of elements:
  • An object - is drawn as a solid-outline rectangle labeled with a name a colon and finally the name of its class, all fully underlined. The names are optional, and the colon is only required if the class is specified.
  • A link - is drawn as a solid-line path labeled with the name of its association fully underlined, this represents a specific relationship between objects.
  • An attribute value - is drawn as a text string followed by an equal symbol and its value in an object's second compartment, this represents what the object knows.

The figure below is shows an example of an object diagram:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-objectdiagram.jpg
Figure: Object Diagram

Use Case Diagram
Use-case diagrams depict the functionality of a system. Use-case diagrams have the following types of elements:
  • An actor - is drawn as a "stick figure" icon that represents users or external systems with which the system in question interacts.
  • A use case - is drawn as an ellipse and represents a functional requirement that is described from the perspective of the users of a system.
  • A communicate association - is drawn as a solid-line path from an actor to a use case and represents that the actor uses the use case.

The figure below shows an example of a use case diagram:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-usecasediagram.jpg
Figure:Use Case Diagram

Component Diagrams
Component diagrams, are also known as implementation diagrams, since they are physical versions of the class diagrams, depicting the implementation of a system. Component diagrams contain the following types of elements:
  • A component is drawn as a rectangle with two small rectangles protruding from its side and represents a part of the system that exists while the system is executing.
  • A dependency relationship - is drawn as a dashed arrow from a client component to a suppler component and represents that the client component uses or depends on the supplier component.

The figure below is an example of a component diagram:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-componentdiagram.jpg
Figure: Component Diagram

In the object-oriented paradigm, the focus is on using objects, in the component-based paradigm, the focus is on using components. Irrespective of the paradigm employed, they are both based on the same principles of abstraction, encapsulation, generalization, and polymorphism.

Deployment Diagrams
Deployment diagrams shows the physical implementation of software and hardware. It is the complement of the component diagram. Deployment diagram illustrates the configuration of runtime processing elements such as servers, routers, load balancers and other hardware as well as the software components, processes, and objects that they comprise. The software component instances represent runtime manifestations of classes. The element types of deployment diagrams are the following:
  • A node - is drawn as a three-dimensional rectangle and represents a resource that is available during execution time. A component that resides on a node is nested inside the node.
  • A communication association - is drawn as a solid-line path between nodes and represents a communication path between the nodes.

The figure below shows an deployment diagram for a system with a number of different elements including application servers, routers, load balancers, enterprise service bus, LDAP server, Email Servers, two legacy systems and clustered database servers:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-deploymentdiagram.jpg
Figure: Deployment Diagram

Behavioral Modeling

Behavioral modeling helps us to understand and communicate how elements behave in the organization’s environment. It shows how the elements interact and collaborate to provide the functionality required in the system. UML provides a number of diagrams that are used for modeling behaviour. These are detailed in the sections below.

Sequence Diagrams
The sequence diagram illustrates explicitly a series of interactions as they flow through the system to arrive at the desired objective. The sequence view is especially useful in real-time applications and for complex scenarios which have critical time dependencies. The horizontal axis shows the elements involved in the interaction, and the vertical axis represents time proceeding down the page. Sequence diagrams have the following types of elements:
  • Classes and objects - are depicted in the same way as on class diagrams. Objects may also be shown much the same way as on object diagrams.
  • A lifeline - is depicted as a vertical dashed line from an element and represents the existence of the element over time.
  • A communication - is drawn as a horizontal solid arrow from the lifeline of the sender to the lifeline of the receiver and labeled with the name of the operation to be invoked, this represents that the sender sends a message or stimulus to the receiver.

The figure below shows an example of a complex sequence diagram:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-sequencediagram.jpg
Figure: Sequence Diagram

Collaboration Diagrams
Collaboration diagrams are interaction diagrams like sequence diagrams. They convey the same information as sequence diagrams, but instead focus on object roles rather than the times that messages are sent. A collaboration diagram shows the relationships among objects. Collaboration diagrams have the following types of elements:
  • Classes and objects - these are depicted in much the same way as on class diagrams. Objects can also be shown in much the same way as on object diagrams.
  • Associations - these are depicted in much the same way as on class diagrams. Links may also be shown much the same way as on object diagrams.
  • A communication - these are depicted as an arrow attached to a relationship pointing from the sender toward the receiver. It is labeled with a sequence number showing the order in which the communication is sent followed by a colon followed by the name of the operation to be invoked. It represents that the sender sends a message to the receiver.

The figure below demonstrates an example of a collaboration diagram.

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-collaborationdiagram.jpg
Figure: Collaboration Diagram

State Diagram
State diagrams represent the different states that objects in the system undergo during their lifecycle. The objects in the system change states in response to events. State diagrams have the following types of elements:
  • A state - is depicted as a rectangle with rounded corners and represents a condition or situation of an element.
  • An event - is an occurrence of receiving a message.
  • A transition - is depicted as a solid line from a source state to a target state labeled with an event, this represents that if the element is in the source state and the event occurs, it will enter the target state.
  • Initial state - is when an element is created, it enters its initial state. This is depicted as a small, solid, filled circle. The transition originating from the initial state may be labeled with the event that creates the element.
  • Final state - is when an element enters its final state. This is depicted as a circle surrounding a small solid filled circle similar to a bull’s eye. At this point the element is destroyed. The transition to the final state can be labeled with the event that destroys the element.

The figure below shows an example of a state diagram:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-statediagram.jpg
Figure: State Diagram

Activity Diagram
An activity diagram is similar to a state diagram but is shows all or most of the states as action states in which all or most of the transitions are triggered by completion of the actions in the source states. It depicts the activities and responsibilities of elements. Activity diagrams have the following types of elements:
  • An action state - is depicted as a shape with straight top and bottom with convex arcs on the two sides, this represents processing.
  • A control-flow transition - is depicted as a solid line from a source action state to a target action state, this represents that once the source action state completes its processing, the target action state starts its processing.
  • An initial action state - is depicted as a small solid filled circle, the control-flow transition originating from the initial state specifies the first action state.
  • A final action state - is depicted as a circle surrounding a small solid filled circle (a bull's eye), the control-flow transition to the final state specifies the final action state.
  • An object-flow - is depicted as a dashed arrow between an action state and an object, this represents that the action state inputs or outputs the object. An input object flow, which points to an action state, represents that the action state inputs the object. An output object flow, which points to an object, represents that the action state outputs the object.
  • A swimlane - is depicted as a visual region separated from neighboring swimlanes by vertical solid lines on both sides and labeled at the top with the element responsible for action states within the swimlane, this represents responsibility.

The figure below shows an example of an activity diagram:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-activitydiagram.jpg
Figure: Activity Diagram

Other Elements

There are other elements in UML that are purely notational as well as those that serve to extend the language. For example Notes are a purely notational instrument while stereotypes and properties are extensions of UML. These are discussed below.

Notes
A note is depicted as a rectangle with a bent upper-right corner and may be attached to another element using a dashed line. They are used to represent a comment.
The figure below shows an example of a note being used:

Tutorial:Documenting of the Software Architecture for the Java Architect Exam-c9-notesstereotypesproperties.jpg
Figure: Notes, Stereotypes and Properties

Stereotypes
A stereotype is a new class of modeling element introduced during the modeling process. Stereotypes must be based on certain existing classes in the meta model and can extend these classes only in certain predefined ways. They are depicted as a text string keyword enclosed in guillemets («», pronounced gee-a-may) or double-angle brackets, before or above the name of an element that indicates the specific meaning associated with the element. The figure above shows the use of a stereotype <<Table>> for the Product class.
This indicates that the class represents a database table.

Properties
Properties represent characteristics of the particular element. They are depicted as a comma-delimited list of text strings inside a pair of braces ({}) after or below the name of an element. You can use either natural or computer language to express a property. The text string representing a property can take on two forms:
  • A text string can be a tagged value, shown as a keyword-value pair representing a characteristic of the element and its value.
  • A text string may be a constraint, shown as a text string that can be expressed in the Object Constraint Language (OCL) representing a condition the element must satisfy.

The figure above shows a property for the Product class where a condition for start and end dates must be met.

Sections - Grouping the Paragraphs or View

A UML section is a similar to a section in a book or report. It is a grouping of architectural views. An architectural view is a grouping of diagrams addressing a related set of concerns about the system. The different architectural views determine the various ways in which one can comprehend the nature of the system. For example, one could organize all of the figures in this article into different views, including those for addressing functional, structural, behavioral, and other pieces of the product auction system. The elements that make up a view are known as view elements. For example, we define all the elements in the figures as view elements when we classify the diagram on which they appear into a specific view.

Since UML is a language and not a methodology, there is no prescribed method for any explicit architectural views, but the UML diagrams can be organized around the following generally used architectural views:
  • The use-case or user architectural view - this view focuses on the functionality of a system with the use-case diagrams used to communicate what functionality the system provides to its users.
  • The structural or static architectural view - this view focuses on the structure of a system through the use of class and object diagrams to communicate what elements and relationships make up the system.
  • The behavioral or dynamic architectural view - this view focuses on the behavior of a system through the use of sequence, collaboration, state, and activity diagrams to communicate the interactions and collaborations of the elements of which consists the system.
  • The component or implementation architectural view - this view focuses on the implementation of a system via component diagrams to communicate how the system is implemented.
  • The deployment or environment model architectural view - this view focuses on the implementation environment via deployment diagrams to communicate how the implemented system resides in its environment.

One can used any diagram type for an any architectural view despite the prototyping of each type of diagram around a single architectural view. For example, an interaction diagram are often used in a use-case view to communicate how users interact with a system. The flexibility of UML as a modeling language allows us to define our architectural views to suit our needs when necessary. For example, we could define a data store architectural view and define a new type of diagram, based on a database schema diagram, to communicate the tables in a database and their relationships. This would facilitate us creating other types of diagrams to communicate the triggers and stored procedures in a database. In the previous article, "Tutorial:Design of Software Architecture for Java Architect Exam", we something similar with many of the diagrams we used to link the user interaction design with the system design.

Documents - Grouping the Sections

Finally, when we have brought together all of our sections into a particular grouping around a common subject we arrive at a UML document. We can also include other non-UML diagrams, textual documents, and supporting information. UML documents are models. A model is our representation of the system to be built. So all the figures in this article along with supporting textual documentation are the model of the product auction system. The elements that make up a model are known as model elements such as any element used on the diagrams in this article, with any supporting documentation need to communicate about that element, forms a model element.

There is an analogous relationship between UML model and their key constituent parts and a database model and its key constituent parts. UML models, architectural views, and diagrams have similar relationships as databases, views, and queries. A database contains data, views that organize subsets of the data into meaningful information, and queries are used to extract those subsets of useful information. Similarly a model element within the model, through a particular view elements provide useful information about the system.
There is nor explicit steps for how UML models are applied for developing a system. This is left to you to use your preferred methodology for transforming the requirements of the system into an actual model using the various architectural views. This is because UML is only a language.

Summary

The models and diagrams of UML allow us capture and communicate our understanding of the requirements and system throughout the system development lifecycle process. They enable us to manage change and complexity as well as assess our understanding before resources are allocated in producing a system that could possibly be unacceptable or insufficient to satisfy the requirements. Models capture all the detail in bridging the gap between requirements and systems. In our models, we capture the details in the design and implementation of the system that show our understanding of the requirements as well as our confidence that the system we meet the organizations ongoing needs.