Modularity plays an important role in software architecture. It fills a gap that has existed since we began developing enterprise software systems in Java. This chapter discusses that gap and explores how modularity is an important intermediary technology that fills that gap.

Defining Architecture
There are numerous definitions of architecture. But within each lies a common theme and some key phrases. Here are a few of the definitions. From Booch, Rumbaugh, and Jacobson (1999):

An architecture is the set of significant decisions about the organization of a software system, the selection of the structural elements and their interfaces by which the system is composed, together with their behavior as specified in the collaborations among those elements, the composition of these structural elements and behavioral elements into progressively larger subsystems, and the architecture style that guides this organization - these elements and their interfaces, their collaborations, and their composition.

Now, from the ANSI/IEEE Std 1471-2000 (the Open Group):

The fundamental organization of a system, embodied in its components, their relationships to each other and the environment, and the principles governing its design and evolution.

In the Open Group Architecture Framework (TOGAF), architecture has two meanings depending on context (the Open Group):

1. A formal description of a system, or a detailed plan of the system at component level to guide its implementation
2. The structure of components, their inter-relationships, and the principles and guidelines governing their design and evolution over time

Examining these definitions reveals many common keywords, which I've made bold in the various definitions. Important underlying cur­rents are embodied by these keywords. But, these keywords lead to some important questions that must be answered to more fully understand architecture. What makes a decision architecturally significant? What are the elements of composition? How do we accommodate evolution of architecture? What does this have to do with modularity? As we delve into these questions, I want to start with a story on software architecture.

A Software Architecture Story
The story of software architecture reminds me of the following story (Hawking 1998):

A well-known scientist (some say it was Bertrand Russell) once gave a public lecture on astronomy. He described how the earth orbits around the sun and how the sun, in turn, orbits around the center of a vast collection of stars called our galaxy. At the end of the lecture, a little old lady at the back of the room got up and said: "What you have told us is rubbish. The world is really a flat plate supported on the back of a giant tortoise." The scientist gave a superior smile before replying, "What is the tortoise standing on?" "You're very clever, young man, very clever," said the old lady. "But it's turtles all the way down!"

-A Brief History of Time by Stephen Hawking

Software architecture is "turtles all the way down." How? This section discusses these ideas.

The Ivory Tower
Many of us can relate to the ivory tower. In dysfunctional organizations, architects and developers fail to communicate effectively. The result is a lack of transparency and a lack of understanding by both sides. As shown in Figure 1, architects bestow their wisdom upon developers who are unable to translate high-level concepts into concrete implementations. The failure often occurs (although I recognize there are other causes) because architecture is about breadth and development is about depth. Each group has disparate views of software architecture, and although both are war­ranted, there's a gap between these views. The architect might focus on applications and services, while the developer focuses on the code. Sadly, there is a lot in between that no one focuses on. This gap between breadth and depth contributes to ivory tower architecture.

A Software Architecture Story

Adapted from http://www.rendell.org/jam/upload/2009/1/tower-12054835.jpg

Turtles and the Tower
Without question, the ivory tower is dysfunctional, and systems lack­ing architectural integrity are a symptom of ivory tower architecture. So, assuming good intent on the part of the architect and the developer, how can we bridge the gap between breadth and depth? How can we more effectively communicate? How do we increase understanding and transparency?

Let's revisit the definition of software architecture by exploring another definition. My favorite definition of software architecture was offered by Ralph Johnson in an article by Martin Fowler (2003). He states:

In most successful software projects, the expert developers working on that project have a shared understanding of the system design. This shared understanding is called "architecture." This understanding includes how the system is divided into components and how the components interact through interfaces. These components are usually composed of smaller components, but the architecture only includes the components and interfaces that are understood by all the developers . . . Architecture is about the important stuff. Whatever that is.

The key aspect of this definition that differentiates it from the ear­lier definitions in this chapter is that of "shared understanding," which implies that there is a social aspect to software architecture. We must have a shared understanding of how the system is divided into components and how they interact. Architecture isn't just some technical concept; it's also a social construct. Through this social aspect of architecture, we can break down the divide between architects and developers.

To ensure shared understanding, we have to architect "all the way down." Architects cannot worry only about services, and developers can­not worry only about code. Each group must also focus on a huge middle ground, as illustrated in Figure 2.

Focusing exclusively on top-level abstractions is not enough. Empha­sizing only code quality is not enough either. We must bridge the gap through other means, including module and package design. Often, when I speak at various conferences, I ask the audience to raise their hands if they devote effort to service design. Many hands raise. I also ask them to raise their hand if they spend time on class design and code quality. Again, many hands go up. But when I ask if they also devote effort to package and module design, only a small percentage leave their hands raised.

This is unfortunate, because module and package design are equally as important as service and class design. But somewhere along the way, with our emphasis on services and code quality, we've lost sight of what lies in between. Within each application or service awaits a rotting design, and atop even the most flexible code sits a suite of applications or services riddled with duplication and lack of understanding. A resilient package structure and corresponding software modules help bridge the divide between services and code. Modularity is an important intermediate technology that helps us architect all the way down and is the conduit that fills the gap between breadth and depth.

The Goal of Architecture

Adapted from http://www.rendell.org/jam/upload/2009/1/tower-12054835.jpg

We need to focus on modularity to ensure a consistent architecture story is told. It is the glue that binds. It's the piece that helps bridge low-level class design with higher-level service design. It's the piece that helps bring down the ivory tower, enhance communication, increase transparency, ensure understanding, and verify consistency at multiple levels. It is the piece that allows us to "architect all the way down" and allows us to realize the goal of architecture.

Modularity helps address the social aspect of software architecture, but it also helps us design more flexible software systems - that is, systems with resilient, adaptable, and maintainable architectures. Examining the earlier definitions of architecture leads us to the goal of architecture. The Johnson definition of architecture as quoted by Fowler makes it apparent that architecture is about the important stuff. In the following statement, Booch makes it clear that something is architecturally significant if it's difficult to change (2006):

All architecture is design but not all design is architecture. Architecture represents the significant design decisions that shape a system, where significant is measured by cost of change.

Based on these statements, it's fair to conclude that the goal of soft­ware architecture must be to eliminate the impact and cost of change, thereby eliminating architectural significance. We attempt to make some­thing architecturally insignificant by creating flexible solutions that can be changed easily, as illustrated in Figure 3. But herein lies a paradox.

The Paradox
The idea behind eliminating architecture isn't new. In fact, Fowler men­tions "getting rid of software architecture" in his article "Who Needs an Architect?" (2003). The way to eliminate architecture by minimizing the impact of cost and change is through flexibility. The more flexible the system, the more likely that the system can adapt and evolve as necessary. But herein lies the paradox, and a statement by Ralph Johnson presents and supports the idea (Fowler 2003):

. . . making everything easy to change makes the entire system very complex . . .

As flexibility increases, so does the complexity. And complexity is the beast we are trying to tame because complex things are more difficult to deal with than simple things. It's a battle for which there is no clear path to victory, for sure. But, what if we were able to tame complexity while increasing flexibility, as illustrated in Figure 4? Let's explore the pos­sibility of designing flexible software without increasing complexity. Is it even possible? In other words, how do we eliminate architecture?

Figure 4 Maximizing flexibility, managing complexity

Eliminating Architecture
As the Johnson quote clearly points out, it's not feasible to design an infi­nitely flexible system. Therefore, it's imperative that we recognize where flexibility is necessary to reduce the impact and cost of change. The chal­lenge is that we don't always know early in the project what might eventu­ally change, so it's impossible to create a flexible solution to something we can't know about. This is the problem with Big Architecture Up Front (BAUF), and it's why we must make architectural decisions temporally. In other words, we should try to defer commitment to specific architectural decisions that would lock us to a specific solution until we have the req­uisite knowledge that will allow us to make the most informed decision.

It's also why we must take great care in insulating and isolating deci­sions we're unsure of and ensuring that these initial decisions are easy to change as answers to the unknown emerge. For this, modularity is a miss­ing ingredient that helps minimize the impact and cost of change, and it's a motivating force behind why we should design software systems with a modular architecture. In the UML User Guide (page 163), Booch talks about "modeling the seams in a system." He states (1999):

Identifying the seams in a system involves identifying clear lines of demarcation in your architecture. On either side of those lines, you'll find components that may change independently, without affecting the components on the other side, as long as the components on both sides conform to the contract specified by that interface.

Where Booch talks about components, we talk about modules. Where SOLID Booch talks about seams, we'll talk about joints. Modularity, combined ^{principles, 319} with design patterns and SOLID principles, represents our best hope to joints, 56 minimize the impact and cost of change, thereby eliminating the archi­tectural significance of change.

Modularity: The Missing Ingredient
Two of the key elements of the architectural definitions are component and composition. Yet there is no standard and agreed-upon definition of component¹ (reminding me of architecture, actually), and most use the term loosely to mean "a chunk of code." But, that doesn't work, and in the context of OSGi, it's clear that a module is a software component. Devel­oping a system with an adaptive, flexible, and maintainable architecture requires modularity because we must be able to design a flexible system that allows us to make temporal decisions based on shifts that occur throughout development. Modularity has been a missing piece that allows us to more easily accommodate these shifts, as well as focus on specific areas of the system that demand the most flexibility, as illustrated in Figure 5. It's easier to change a design encapsulated within a module than it is to make a change to the design than spans several modules.

Modularity: The Missing Ingredient
Is It Really Encapsulated?
In standard Java, there is no way to enforce encapsulation of design details to a module because Java provides no way to define packages or classes that are module scope. As a result, classes in one module will always have access to the implementation details of another module. This is where a module framework, such as OSGi, shines because it allows you to forcefully encapsulate implementation details within a module through its explicit import package and export package manifest headers. Even public classes within a package cannot be accessed by another module unless the pack­age is explicitly exported. The difference is subtle, although profound. We see several examples of this in the patterns throughout this book, and I point it out as it occurs. For now, let's explore a simple example.

Standard Java: No Encapsulation
Figure 6 illustrates a Client class that depends upon Inter, an inter­face, with Impl providing the implementation. The Client class is pack­aged in the client.jar module, and Inter and Impl are packaged in the provider.jar module. This is a good example of a modular system but demonstrates how we cannot encapsulate implementation details in standard Java because there is no way to prevent access to Impl. Classes outside of the provider.jar module can still reach the Impl class to instantiate and use it directly.

In fact, the Impl class is defined as a package scope class, as shown in Listing 1. However, the AppContext.xml Spring XML configuration file, which is deployed in the client.jar module, is still able to cre­ate the Impl instance at runtime and inject it into Client. The App-Context.xml and Client class are shown in Listing 2 and Listing 3, respectively. The key element is that the AppContext.xml is deployed in the client.jar module and the Impl class it creates is deployed in the provider.jar module. As shown in Listing 2, the AppContext .xml file deployed in the client.jar file violates encapsulation by referencing an implementation detail of the provider.jar module. Because the Spring configuration is a global configuration, the result is a violation of encapsulation.

Listing 1: Impl Class

package com.p2.impl;
import com.p2.*;
class Impl implements Inter {
public void doIt() { . . . /* any implementation */ }
}

Listing 2: AppContext.xml Spring Configuration

<beans>
<bean id="inter" class="com.p2.impl.Impl"/>
</beans>

Listing 3: Client Class

package com.p1;

import com.p2.*;
import org.springframework.context.*;
import org.springframework.context.support.*;

public class Client {
public static void main(String args[]) {
ApplicationContext appContext = new
FileSystemXmlApplicationContext(
"com/p1/AppContext.xml");

Inter i = (Inter) appContext.getBean("inter");
i.doIt();
}
}

OSGi and Encapsulation
Now let's look at the same example using OSGi. Here, the Impl class in the provider.jar module is tightly encapsulated, and no class in any other module is able to see the Impl class. The Impl class and Inter interface remain the same as in the previous examples; no changes are required. Instead, we've taken the existing application and simply set it up to work with the OSGi framework, which enforces encapsulation of module implementation details and provides an intermodule communication mechanism. Figure 7 demonstrates the new structure. It's actually an example of the Abstract Modules Pattern. Here I separate the Spring XML configuration into four different files. I could have easily used only two configuration files, but I want to keep the standard Java and OSGi frame­work configurations separate for each module. The provider.jar module is responsible for the configuration itself and exposing its capabilities when it's installed. Before we describe the approach, here is a brief description of each configuration file:

Figure 7 Encapsulating design with OSGi

• client.xml: Standard Spring configuration file that describes how the application should be launched by the OSGi framework
• client-osgi.xml: Spring configuration file that allows the Client class to consume an OSGi µService
• provider.xml: Spring configuration with the provider.jar module bean definition
• provider-osgi.xml: Spring configuration that exposes the bean  definition in provider.xml as an OSGi µService

Before we look at how the two modules are wired together, let's look at the provider.jar module, which contains the Inter interface, Impl implementation, and two configuration files. Again, Inter and Impl remain the same as in the previous example, so let's look at the configuration files. The provider.xml file defines the standard Spring bean con­figuration and is what was previously shown in the AppContext.xml file in Figure 7. Listing 34 shows the provider.xml file. The key is that this configuration is deployed with the provider.jar module. Attempting to instantiate the Impl class outside of the provider.jar module will not work. Because OSGi enforces encapsulation, any attempt to reach the implementation details of a module will result in a runtime error, such as a ClassNotFoundException.

Listing 4 provider.xml Configuration File

<beans>

<bean id="inter" class="com.p2.impl.Impl"/>
</beans>

How does OSGi prevent other classes from instantiating the Impl class directly? The Manifest.mf file included in the provider.jar module exposes classes only in the com.p2 package, not the com.p2.impl pack­age. So, the Inter interface registered as an OSGi µService is accessible by other modules but not by the Impl class. Listing 3.5 shows the section of the Manifest.mf illustrating the package export.

Listing 5 provider.xml Configuration File

Export-Package: com.p2

The provider-osgi.xml file is where things get very interesting, and it is where we expose the behavior of the provider.jar module as an OSGi µService that serves as the contract between the Client and Impl classes. The configuration for the provider.jar module lives within the provider.jar module, so no violation of encapsulation occurs.

Listing 6 shows the configuration. The name of the µService we are registering with the OSGi framework is called interService, and it references the Impl bean defined in Listing 3.4, exposing its behavior as type Inter. At this point, the provider.jar module has a interService OSGi µService that can be consumed by another module. This service is made available by the provider.jar module after it is installed and activated in the OSGi framework.

Listing 6 provider.xml Configuration File

<osgi:service id="interService" ref="inter"
interface="com.p2.Inter"/>

Now, let's look at the client.jar module. The client.xml file con­figures the Client class. It effectively replaces the main method on the Client class in Listing 3.3 with the run method, and the OSGi framework instantiates the Client class, configures it with an Inter type, and invokes the run method. Listing 7 shows the client.xml file, and Listing 3.8 shows the Client class. This is the mechanism that initiates the process and replaces the main method in the Client class of the previous example.

Listing 7 Client.xml Configuration File

<beans>
<bean name="client" class="com.p1.impl.Client"
init-method="run">

<property name="inter"
ref="interService"/>
</bean>
</beans>

Listing 8 The Client Class

package com.p1.impl;
import com.p2.*;
import com.p1.*;
public class Client {

private Inter i;
public void setInter(Inter i) {
this.i = i;
}

public void run() throws Exception {
i.doIt();
}
}

The Inter type that is injected into the client class is done through the client-osgi.xml configuration file. Here, we specify that we want to use a µService of type Inter, as shown in Listing 9.

Listing 9 Client.xml Configuration File

<osgi:reference id="interService"
interface="com.p2.Inter"/>

The Manifest.mf file for the client.jar module imports the com.p2 packages, which gives it access to the Inter µService. Listing 10 shows the section of Manifest.mf showing the package imports and exports for the client.jar module.

Listing 10 Client.xml Configuration File

Import-Package: com.p2

Independent This simple example has several interesting design aspects.² The provider.jar module is independently deployable. It has no dependencies on any other module, and it exposes its set of behaviors as a µService. No other module in the system needs to know these details.

Answering Our Questions
The design could have also been made even more flexible by packaging the Impl class and Inter interface in separate modules. By separating the interface from the implementation, we bring a great deal of flexibility to the system, especially with OSGi managing our modules.

At first glance, it might also appear to contradict the External Config­uration pattern. When defining the external configuration for a module, we still want to ensure implementation details are encapsulated. External configuration is more about allowing clients to configure a module to its environmental context and not about exposing implementation details of the module.

The key takeaway from this simple demonstration is that the classes in the provider.jar module are tightly encapsulated because the OSGi framework enforces type visibility. We expose only the public classes in the packages that a module exports, and the µService is the mechanism that allows modules to communicate in a very flexible manner. The µService spans the joints of the system, and because OSGi is dynamic, so too are the dependencies on µServices. Implementations of the µService can come and go at runtime, and the system can bind to new instances as they appear.

Again, we'll see several more examples of this throughout the remain­der of the discussion. Even though you can't enforce encapsulation of module implementation using standard Java, it's still imperative to begin designing more modular software systems. As we'll see, by applying sev­eral of the techniques we discuss in this book, we put ourselves in an excellent position to take advantage of a runtime module system.

Earlier, this chapter posed the following questions after introducing the three definitions of software architecture. Through explanation, we answered each question. But to be clear, let's offer concise answers:

• What makes a decision architecturally significant? A decision is architecturally significant if the impact and cost of change is significant.
• What are the elements of composition? The elements of composition include classes, modules, and services.
• How do we accommodate evolution of architecture? Evolution is realized by designing flexible solutions that can adapt to change. But flexibility breeds complexity, and we must be careful to build flexibility in the right areas of the system.

Conclusion
The goal of architecture is to minimize the impact and cost of change. Modularity helps us realize this goal by filling in a gap that exists between top-level architectural constructs and lower-level code. Modularity is the important intermediate that helps increase architectural agility. It fills a gap that exists between architects and developers. It allows us to create a software architecture that can accommodate shifts. Modularity helps us architect all the way down.

1. In his book Component Software: Beyond Object-Oriented Programming, Clemens Szyperski makes one of the few attempts I've seen to formally define the term component. He did a fine job, too.
2. Although this example builds upon the OSGi Blueprint Specification, some of you may not be huge fans of XML. If that's the case, Peter Kriens has an implementation that uses OSGi Declarative Services. The sample can be found at http://bit.ly/OSGiExamples in the aQute. poma.basic directory.

References

• Booch, Grady, James Rumbaugh, and Ivar Jacobson. 1999. The Unified Modeling Language User Guide. Reading, MA: Addison-Wesley.
• The Open Group. The Open Group Architecture Framework. www.open­group.org/architecture/togaf8-doc/arch/chap01.html
• Hawking, Stephen. 1998. A Brief History of Time.
• Bantam. Fowler, Martin. 2003. "Who Needs an Architect?" IEEE Software.
• Booch, Grady. 2006. On Design. www.handbookofsoftwarearchitecture. com/index.jsp?page=Blog&part=All

•   •   •

Disclaimer:  This excerpt is from the book "Java Application Architecture: Modularity Patterns with Examples Using OSGi" (Robert C. Martin Series) by Kirk Knoernschild, published by Pearson/Prentice Hall Professional, March 2012, ISBN 0321247132, Copyright 2012 Pearson Education, Inc. For more info please visit the publisher site, www.informit.com/title/0321247132

• Java Application Architecture: Modularity Patterns with Examples

'); for(i = 0; i < google_ads.length; ++i) { document.write('
• '); document.write('' + google_ads[i].line1 + '
  '); document.write('' + google_ads[i].visible_url + '
  '); document.write(google_ads[i].line2 + ' ' + google_ads[i].line3); document.write('
'); } document.write('