Modules should be externally configurable.

Description

The ability to configure a module to it’s usage context increases our ability to reuse the module across contexts, whereas tightly coupling configuration to the module prohibits reuse. External configuration allows a module to be reconfigured across environemtns, and even within it’s existing environment, without demanding redeploying  the module. Figure 1 illustrates External Configuration, where an XML configuration file is used by the Client class to configure the client.jar module.

Figure 1: External Configuration

Implementation Variations

Different configuration files can be used for different contexts. The configuration file can be included in the module or included in a separate module, depending on the flexibility desired. Figure 2 illustrates a configuration file that is not deployed with the module. A flexible alternative is to provide a default configuration file with the module, but allow for the module to be configured with an alternative configuration file. Including a default configuration file within the module is one aspect of providing a module’s Default Implementation.

Figure 2: External Configuration File

Consequences

Sample Code

Show example using Spring to configure a module with a uid/pwd combination.

For instance, many applications must provide credentials to connect to a database. Web applications often use a standard userid and password combination so that a pool of connections are available to clients. If a module encpasulates this information

Wrapping Up

Create a facade serving as a coarse-grained entry point to the modules underlying implementation.

Description

Often times, configuring fine-grained modules can be a burden, especially when multiple fine-grained modules are typically used in conjunction but forces prevent module designers from combining the fine-grained module into a single coarse-grained entity. In these situations, a module facade can be used to expose a subset of the functionality contained within a group of fine-grained modules. A module facade allows a group of fine-grained modules to operate as a coarse-grained module. Figure 1 illustrates a Module Facade.

Figure 1: Module Facade

Implementation Variations

The module facade can configure the fine-grained modules.

Module facade can also act as a mediator to help break dependencies between modules. This is quite similar to escalation.

Consequences

All fine-grained modules must be deployed whenever the coarse-grained module is deployed.

Sample Code

Wrapping Up

Exceptions should be close to the class or interface that throw them.

Description

Sadly, dealing with exceptions in enterprise software systems is often an afterthought. But allocation of exceptions to modules has significant implications on the modularity, and more specifically the dependencies between modules, within our software system. Placing the exception close to a class that catches it will often cause a cyclic dependency between the module containing the class that throws the exception and the module containing the class that catches the exception. Exceptions should always be placed in a module closer to the class that throws the exception than a module closer to the class that catches the exception. Figure 1 illustrates this scenario.

Figure 1: Colocate Exceptions

Implementation Variations

Whereas separate abstractions says that interfaces should be close to the classes that use them, exceptions should be close to the class that throws them.

If multiple classes from separate modules throw the same exception, the demotion should be used to manage the dependencies between the two modules.

Similar to separate abstractions – that is where we place the interface.

Consequences

Sample Code

Wrapping Up

Modules should be independent of the runtime container.

Description

Modules with excessive runtime container dependencies are heavyweight modules that cannot execute outside the confines of the runtime container. A good example of a heavyweight technology is Enterprise JavaBeans (EJB), and the meteoric rise in popularity of lighter weight frameworks, such as Spring, are the direct result of the shortcomings of heavyweight technologies. While lightweight modules are not container dependent, they are still able to leverage the infrastructure capabilities (e.g., security, transactions) of the container. Lightweight modules with no container dependencies have two significant advantages.

• They are portable across runtime environments. For instance, a lightweight module can be deployed in a Java EE environment, but it can also run directly atop the JVM. Or, a module might be designed to work in a runtime supporting OSGi, but it can also function if an OSGi framework isn’t available.
• The are testable. Because they lack environmental dependencies, they can be tested in isolation, outside the confines of the environment to which they’ll ultimately be deployed.

Additionally, it’s easy to argue that lighter weight modules are also easier to maintain, since their contents aren’t polluted with excessive dependencies. Developing light weight modules demands that container dependencies be abstracted away. Figure 1 illustrates how the client.jar module is made independent of the runtime.jar through the use of the abstraction.jar module, which encapsulates the container dependencies and coordinates the interaction of client.jar module in the runtime environment. As a result, the Client class will have no dependencies on the runtime.jar nor the abstraction.jar modules’ APIs.

Figure 1: Container Independence

Implementation Variations

External configuration can be used to configure a module so that it operates correctly in a specific runtime environment. In these situations, External Configuration is a pattern that is used to achieve Container Independence since the configuration dependencies are moved to an external configuration file. A superceding framework then manages module configuration. However, there are subtle differences between External Configuration and Container Independence that validates pattern individuality. External configuration is used to configure a module so that it can be used across contexts. Container Independence is leveraged to ensure a module is portable across containers.

For instance, configuring a module with a userid and password combination so that it can be used to access different database instances is an example of external configuration, not container independence. While poor practice, hardcoding the userid and password combination wouldn’t create dependencies on any runtime container, though obviously would limit the context in which the module could be reuse.

In many cases, developers don’t need to roll their own code to abstract away the container dependencies. Instead, a framework is used. The most common mechanism to achieve container independence is through dependency injection, where a module’s dependencies are injected at runtime. Many dependency injection frameworks also provide important infrastructure capabilities that help ensure the module remains container independent. For instance, in the example below that uses Spring DM, the framework provides dependency injection capabilities but also provides critical functionality surrounding OSGi service management.

Consequences

Container Independence significantly reduces the amount of infrastructure code a developers needs to write. While this provides significant benefits that enable testing and increases portability, it can also result in complex infrastructure code that is complex to write and manage. When a dependency injection framework is used, xml configuration files tend to proliferate. Fortunately, the tradeoff is often worth the benefit.

Sample Code

Let’s consider two very simple modules – a client and a service, as illustrated in Figure 1. Also shown is a configuration file that will be used to help us realize container independence.

Figure 1 – Simple Client Module Using a Service Module

Listing 1 illustrates the start method of a class in the service module that is registered as an OSGi service, enabling other classes to discover the class when requesting the service. As can be seen, the code is heavily dependent on the OSGi framework packages, and this prohibits the code from being used outside the context of an OSGi runtime.

import java.util.Properties;
import com.extensiblejava.hello.service.HelloService;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceListener;
import org.osgi.framework.ServiceEvent;
import org.osgi.framework.ServiceRegistration;

public class HelloServiceImpl implements HelloService, BundleActivator {

	private ServiceRegistration registration;

	public void start(BundleContext context) {
		Properties props = new Properties();
		props.put("Language", "English");
		registration = context.registerService(HelloService.class.getName(), this, props);
        }
        public String sayHello() {
		return "Hello World!! ";
	}

	public String sayGoodbye() {
		return "Goodbye World!!";
	}
}

Listing 1: Heavy Container Dependencies

Any client that hopes to use this class that has been registered with the OSGi service registry also needs to leverage the OSGi framework. Listing 2 illustrates a sample client in the client module that interacts with OSGi to obtain a reference to the service registered in Listing 1.

package com.extensiblejava.hello.client;

import com.extensiblejava.hello.service.HelloService;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import org.osgi.util.tracker.ServiceTracker;

public class HelloConsumer implements BundleActivator {

	private ServiceTracker helloWorldTracker;
	private HelloService helloService;

	public void setService(HelloService helloService) {
		this.helloService = helloService;
	}

	public void removeService() {
		this.helloService = null;
	}

	public void start(BundleContext context) throws Exception {
		helloWorldTracker = new ServiceTracker(context, HelloService.class.getName(), null);
		helloWorldTracker.open();
		HelloService hello = (HelloService) helloWorldTracker.getService();

		if (hello == null) {
			System.out.println("Hello service unavailable on HelloConsumer start");
		} else {
			System.out.println(hello.sayHello());
		}
	}

	public void stop(BundleContext context) {
		HelloService hello = (HelloService) helloWorldTracker.getService();
		if (hello == null) {
			System.out.println("Hello service unavailable on HelloConsumer stop");
		} else {
			System.out.println(hello.sayGoodbye());
		}

		helloWorldTracker.close();
    }

}

Listing 2: Heavyweight Client

The heavyweight nature of this code prevents it from being used outside the context of the OSGi framework, and also prohibits unit testing. Keeping our exact same module structure as illustrated in Figure 1, we leverage Spring DM to remove all dependencies on the OSGi framework. Listings 3 and 4 show the updated code that leverages Spring DM, illustrating all OSGi dependencies have been removed. To achieve this, we’ve needed to deploy the Spring DM modules to the OSGi runtime, and have also introduced the appropriate configuration file that informs Spring DM how to treat these modules. The configuration file is shown in Listing 5.

package com.extensiblejava.hello.service.impl;

import java.util.Properties;
import com.extensiblejava.hello.service.HelloService;

public class HelloServiceImpl implements HelloService {

	public String sayHello() {
		return "Hello OSGi Spring World!! ";
	}

	public String sayGoodbye() {
		return "Goodbye OSGi Spring World!!";
	}
}

Listing 3: Independent HelloServiceImpl Class

package com.extensiblejava.hello.client;

import com.extensiblejava.hello.service.HelloService;

public class HelloConsumer {
	private HelloService hello;

	public void setHelloService(HelloService hello) {
		this.hello = hello;
	}

	public void start() throws Exception {
       System.out.println(hello.sayHello());
	}

	public void stop() throws Exception {
		System.out.println(hello.sayGoodbye());
    }

}

Listing 4: Independent Consumer Class

<osgi:reference id="helloService" interface="com.extensiblejava.hello.service.HelloService"/>

<bean name="helloConsumer" class="com.extensiblejava.hello.client.HelloConsumer"
		init-method="start" destroy-method="stop">
  		<property name="helloService" ref="helloService"/>
</bean>

Listing 5: Spring XML Configuration File

Wrapping Up

Container dependencies result in heavyweight modules that are difficult to reuse and maintain. Eliminating these dependencies helps improve the ease with which modules can be tested. Modules with no container dependencies are also portable across runtime environments and can be used in a variety of different contexts. Dependency injection is a common technique used to help ensure modules aren’t container dependent.

Module relationships should be levelized.

Description

Levelized modules demands that module relationships be acyclic. Any cycles in module relationships therefore prevents levelization. There is a close relationship between levelized modules and physical layers, though the two are not the same. Physical layers aims to create one or more modules that are functionally equivalent to the typical layers composing an application. Levelized modules are more fine-grained than physical layers. While a typical software system may have only three or four layers, within each layer might exist multiple levels.

To levelize modules relationships, do the following:

• External modules are assigned level zero.
• Modules dependent only on level zero modules are assigned level one.
• Modules dependent on level one are assigned level two.
• Modules dependent on level n are assigned level n + 1.

Figure 1 shows levelized modules. Even though the topclient.jar module is dependent on client.jar, a Level 1 module, topclient.jar is also dependent on the midlevel.jar module, which is a Level 2 module. Because of this, topclient.jar module is a Level 3 module. More generally, if a module is dependent on an n – 1 leve module, the module is an n level module, even if it’s also dependent on modules lower in the level hierarchy.

Figure 1: Levelized Modules

Implementation Variations

Levels and layers, what’s the difference? Layers have much more do with responsibility, whereas levels have much more to do with understanding the system structure, especially the dependencies. Levels are more granular than layers. Within a single layer might exist multiple levels, but multiple layers can never exist at a single level.

The Levelized Modules pattern sits squarely between Physical Layers and Acyclic Relationships (not just in the book, but in concept, as well). Levelized Modules demands that the module structure be acyclic. If it weren’t, the cycle would make it impossible to clearly identify the levels. And as we discussed above, levels tend to be a bit more granular than layers.

In fact, there aren’t many implementation variations of Levelized Modules, which brings into question it’s value as a pattern to begin with. But I’ve decided to include it because it can be valuable to levelize modules as it provides an extra mechanism to more easily understand module relationships within the conceptual layers. Either a system’s modules are levelized, or they aren’t! But if the modules are levelized, than it’s a guarantee that the modules also exhibit acyclic relationships, though levelization does not guarantee layers because, again, levelization emphasizes dependencies between modules and layers emphasizes responsibilities. There are a few important things to think about when levelizing modules, though.

Coarse grained modules at lower levels of the system have a significant impact on the ability to easily reuse these modules. In general, lower level modules should have fewer outgoing dependencies and more incoming dependencies. In other words, modules in lower level layers should be lower level modules, and these modules should be finer grained and lighter weight than higher level modules. Likewise, modules in higher level layers will likely be higher level modules, though it’s perfectly acceptable that a Level 1 module exist in a higher level layer. For instance, a UI Utility module may have no outgoing dependencies, and therefore be a Level 1 module, but exist in the UI layer because of it’s behavior. At this point, it’s easy to question why this is valuable. We’ll see shortly!

An especially important piece of criteria to consider when levelizing modules is whether you’ll allow module levels to span layers. The decision to enforce a strict levelization scheme over allowing a relaxed scheme will have a significant architectural impact. In theory, a strict scheme might seem better, but in practice a relaxed scheme is easier. A mixture of the two is likely most pragmatic, and it must be a conscious decision each time you decide to allow a levelized module to span multiple layers.

Consequences

Levelization can provide insight to the complexity of dependencies within various layers. For instance, a level 5 module found in the data access layer indicates a rather complex set of dependencies for a module that is very likely used heavily throughout the system. Excessive dependencies in lower level modules have the greatest capacity to increase overall cost of maintaining a system. A good candidate for refactoring, perhaps!

Levelized Modules also offer the opportunity to perform a Levelized Build. If a team cannot easily identify the levels within the system, the only opportunity to perform a Levelized Build exists across the Physical Layers, which may not offer the flexibility necessary. For very large and complex systems, a Levelized Build might be necessary to keep build time fast, which is especially important for teams practicing continuous integration.

Levelization also help improve the module testability. Test Modules can be created for each module, and the levelization will provide guidance on the module test strategy. Lower level modules are inherently easier to test that higher level modules because they lack the complex dependency structure. For instance, modules in the UI layer can be perceived as more difficult to test independently because we have to create mocks and stubs for all of their dependencies. But a Level 1 module in the UI layer indicates no outgoing dependencies, and therefore provides insight to how easy the module will be to bring under test.

Levelization improves ability to understand the system structure. The team has the ability to extract and understand the module relationships in a large software system, allowing us to efficiently and accurately verify throughout the development lifecycle that these dependencies are consistent with our overall architectural vision. Levelization also provides insight to how reusable modules are. For example, reusing a level 3 module comes with the implicit knowledge that one or more level 2 and one or more level 1 modules must also be included in the application.

Levelization can serve as the foundation for an enterprise reuse strategy. Look at it this way. If modules are levelized, lower level modules are inherently easier to reuse because they have no outgoing dependencies. Because they have no outgoing dependencies, we can build these modules independent of the rest of the system. This separate build means that the module can evolve independently. Development of the module can exist outside the context of the application, in parallel, and each time the module is built, it can be included as part of the application (picture would really help here illustrating what I’m talking about – separate IDE project, VC project, build project, binary pulled into IDE, not source).

Sample

As mentioned, levelizing modules is slightly different than physical layers. Figure 2 illustrates this difference. As can be seen here, the levels don’t necessarily coincide with layers. At least, a single layer isn’t necessarily confined to contain a specific set of levels. The billpayutils.jar module is in the control layer based on the set of responsibilities it provides. However, it’s lack of dependence on any level 3 or level 4 modules in the domain layer Even though the billpayutils.jar module is in the control layer make it a level 2 component because it’s only dependency is on the level 1 dbutils.jar module.

Because the modules are levelized, we now have the opportunity to perform a levelized build, and we can more clearly understand build order. The Level 1 dbutils.jar module must be built first. Once finished, possibly as part of a completely separate build, the the billdata.jar and findata.jar modules can be built. Yet so too can the billpayutils.jar module, even though it’s in the Control Layer. Unless we understand module levelization, the opportunity to maximize the efficiency of the build may be lost. So too might we lose the opportunity to realize many of the other advantages of levelization.

Figure 2: Levelized Modules and Physical Layers

Wrapping Up

Levelize Modules sits squarely between Acyclic Modules and Physical Layers. If the module structure is acyclic, then module relationships can be levelized. Levelization helps understand the dependency structure of the application, and it’s benefits include build optimization, reuse, ease of testing, and a clear understanding of system structure.

Module behavior should serve a singular purpose.

Description

Cohesion is a measure of how closely related and focused the various responsibilities of a module are. In the worst case scenario, little emphasis is placed on the allocation of classes to modules. Instead, modules are assembled at random, and the likelihood that modules suffer from lack of cohesion is high. In the best case scenario, modules exhibit high degrees of functional cohesion and the entities composing the module each work in conjunction to fulfill module behavior.

In general, cohesion is a qualitative measurement that is difficult to measure. Instead, we typically refer to a software module as either possessing high cohesion or low cohesion. Modules with higher degrees of cohesion are preferred. There are key difficulties that arise when modules suffer from low cohesion, including the inability to understand the software system and difficulty maintaining the software system.

Reusing modules that lack cohesion is also difficult. Module consumers rarely need all of the random behaviors provided by modules lacking cohesion, and the random behaviors often increase dependencies on other modules. In general, modules that lack cohesion degrade the overall quality of a software system’s architecture.

Implementation Variations

There are two key elements that affect module cohesion. These follow:

• The rate at which the software entities within a module change.
• The likelihood that the software entities within a module are reused together.

Based on these statements, it’s easy to draw the following conclusion:

• Classes which change at different rates belong in separate modules.
• Classes that change at the same rate belong in the same module.
• Classes not reused together belong in separate modules.
• Classes reused together belong in the same module.

Unfortunately, this simple logic is flawed because it doesn’t consider the intricate relation between rate of change, reuse, and the natural shifts that occur throughout the development lifecycle. It’s possible, even likely, that classes change at different rates but are reused together, or that classes change at the same rate but are rarely reused together. Indeed, there is a tension between rate of change and reuse, and we must consider the following combinations.

• Classes within a module that change at the same rate and are reused together.
• Classes within a module that change at a different rate and are reused together.
• Classes within a module that change at the same rate and are not reused together.
• Classes within a module that change at a different rate and are not reused together.

The first and fourth scenarios are the easiest to accommodate. When classes change at the same rate and are reused together, it’s logical that they belong in the same module. Likewise, classes that change at different rates and are not reused together belong in separate modules. The final two scenarios, which tend to be most common, are also the most challenging.

Fortunately, the natural shifts that occur throughout the development lifecycle provide insight to dealing with the second and third scenarios, and encourage us to emphasize one of these aspects more than the other. Early in the development lifecycle, when the system is volatile and change is rampant, packaging the classes based on rate of change should supersede packaging based on reuse. As the system stabilizes, we should focus on packaging the classes based on reuse since the rate of change is much less.

Consequences

Early in the development lifecycle, when change is rampant, we are encouraged to package classes into more coarse-grained module. This is logical. Because change is rampant and widespread, packaging into coarse-grained modules means less module management as change occurs. We don’t have to worry as much about managing dependencies between modules. Unfortunately, this can lead to dire consequences if not dealt with on an ongoing basis. Failure to refactor the modules as the system stabilizes results in a software system composed of coarse-grained modules.

The ramifications of coarse-grained modules are discussed in Chapter 6, Section 6.1. Coarse-grained modules make the modules easier to use, but the increased ease of use comes at the price of reusability. It’s vital to recognize that shifts will occur throughout development As the rate of change lessens, it’s imperative to turn our attention toward the cohesive properties of the modules that affect reuse.

Sample

Figure 1 illustrates the initial version of our system, where Bill instances are routed to an appropriate place so they can be handled (ie., rejected or paid). Unfortunately, the bill.jar module lacks cohesion, since the Bill and Router instances are each bundled and deployed in that module. The lack of cohesion affects reuse, as we cannot reuse Bill without the Router nor reuse the Router to handle other types of entites that might require routing.

Figure 1: Module Lacking Cohesion

The code for the Bill class is shown in Listing 1. As can be seen, a Router is passed to the Bill constructor, which is used when the Bill’s route method is called. The Router is an abstract class with an abstract route method on it. The TypeARouter shown in Figure 1 extends the Router and provides an implementation for the route method.

package com.extensiblejava.bill;

import java.math.*;
import com.extensiblejava.route.*;

public class Bill {
	private String type;
	private String location;
	private BigDecimal amount;
	private Router router;

	public Bill(String type, String location, BigDecimal amount, Router router) {
		this.type = type;
		this.location = location;
		this.amount = amount;
		this.router = router;
	}
	public String getType() {return this.type;}
	public String getLocation() {return this.location;}
	public BigDecimal getAmount() {return this.amount;}
	public String route() { return this.router.route(this); }
}
}

Listing 1: The Bill Class

To increase cohesion of the bill.jar module, routing functionality can be moved to it’s own module, as shown in Figure 2.

Figure 2: Cohesive Bill and Route Modules

The only change required to bundle the functionality separately was to modify the build script. Previously, the build bundled all classes into a single module. The modified script, shown in Listing 2 with the lines responsible for creating the bundles highlight, illustrates how the functionality is allocated to the separate bundles.

<target name="dist" depends="compile">
   <jar jarfile="${dist}/bill.jar" basedir="${bin}" includes="com/extensiblejava/bill/**"/>
   <jar jarfile="${dist}/route.jar" basedir="${bin}" includes="com/extensiblejava/route/**"/>
   <jar jarfile="${dist}/bill-test.jar" basedir="${bin}" includes="com/extensiblejava/test/**"/>
   <junit printsummary="yes" haltonfailure="yes">
      <classpath>
         <pathelement path="${dist}/route.jar"/>
         <pathelement path="${dist}/bill.jar"/>
         <pathelement path="${dist}/bill-test.jar"/>
         <pathelement path="${lib}/junit.jar"/>
      </classpath>
      <test name="com.extensiblejava.test.RouterTest" outfile="junitresults">
         <formatter type="plain"/>
      </test>
   </junit>
</target>

Listing 2: Modified Build Script

Unfortunately, there is still a glaring problem with the module structure illustrated in Figure 2. A cyclic dependency exists between the bill.jar and route.jar modules. Applying the AcyclicRelationships pattern will help eliminate the cyclic dependency. When applying the AcyclicRelationships pattern to break the cycle between the bill.jar and route.jar modules, we also applied the SeparateAbstractions pattern. Otherwise, the cycle would have persisted. Upon doing so, the final module structure would resemble what’s illustrated in Figure 3. Note the addition of the Routable interface, which is implemented by Bill. It’s the Routable interface, and it’s placement in the route.jar module that eliminates the cycle.

Figure 3: Cohesive Modules with Acyclic Relationships

Wrapping Up

Highly cohesive modules are easier to understand, maintain, and reuse. In many cases though, it can be difficult to create cohesive modules early in the development lifecycle, when the team may not have a clear understanding of system behavior. As this insight is gained, the development team should structure the system to ensure highly cohesive modules are available.

Use factories to create a modules implementation classes.

Description

One of the challenges we face with abstract coupling is creation of the implementation class. A client class cannot create an implementation class if we want the two classes abstractly coupled. Figure 1 illustrates the Implementation Factory pattern.

Figure 1: Implementation Factory Pattern

Implementation Variations

Implementation Factory is often used with Abstract Module and Separate Abstractions.

Where does the factory live.

What is the factory? Class or framework such as Spring.

Injection or Lookup.

Consequences

Sample Code

Figure 1: Implementation Factory using Spring

In abstract modules, we were left wondering how to create the implementation class without referencing the concrete class within the client.jar module.

Wrapping Up

Place abstractions and the classes that implement them in separate modules.

Description

You create an abstract class or interface to help reduce coupling between classes. This offers the ability to create new implementations of the abstraction without impacting clients dependent on that abstraction. In this sense, abstract coupling allows you to add new classes to your system without modifying existing classes, and it does so by reducing the dependency relationship between classes.

But coupling classes abstractly does not help reduce the dependency structure between components, especially if the abstraction and the classes that realize the abstraction reside in the same component. So while abstract coupling allows you to effectively reduce coupling between classes, it does not help to eliminate coupling between components. The abstract modules patterns is a prime example of this, where the client.jar module is still tightly coupled to the service.jar module even though the Client concrete class is not directly coupled to the ServiceImpl class.

The ability to deploy client.jar without service.jar does not exist given the structure in Figure 10.1.1. But what if I have a situation where I need to use client.jar without service.jar, or possibly with a new implementation. Even if I create new implementations of the Service interface, I’m still required to deploy service.jar with client.jar due to the placement of Service interface. In order to avoid this nasty problem, I can move the Service interface to the client.jar. This still allows me to configure the Client class with the appropriate Service implementation, yet the client.jar is not dependent on the service.jar module. In fact, the direction of the relationship has been inversed. Instead of client.jar depending on service.jar, the service.jar is now dependent on client.jar.

By simply changing the placement of classes, I’ve changed the dependency relationship between my modules. We saw an example of how module relationships can be inverted in the Module Relationships pattern Sample Code section. But inverting the dependency relationship may not always be what we’re interested in doing. Certainly, we know have the ability to use client.jar without service.jar, but can no longer use service.jar without client.jar. If we need the ability to use both client and service independent of each other, I need a different structure that accommodates this need. When this situation arises, the Separate Abstraction pattern can be used.

Fortunately, it’s as easy as moving the Service interface to a new component that both client.jar and service.jar modules are dependent upon. Figure 1 illustrates the new structure. In most cases where you take this approach, the new module will be an entirely abstract module. We refer to an abstract module as a specification module.

Figure 1: Separate Abstractions Pattern

Implementation Variations

SeparateAbstractions solves two different problems using a common technique. If there are two modules involved in the relationship, by separating the abstraction from the implementation, you are inverting the relationship between the two components. Using an ImplementationFactory will help maintain this separation. When more than three components are involved, SeparateAbstractions allows you to physically decouple two components where no relationship exists between the two components in either direction.

Consequences

Invariably more complex structure to manage.

The two key ingredients when you SeparateAbstractions is deciding where you should place the abstraction and where you should place the implementation. Since there could be many different implementations, they key to making this decision is figuring out your dependencies keeping in mind that the components containing the implementation will be dependent on the component containing the abstraction.

Since all implementations will only have a single abstraction, the placement of the abstraction is key to creating the component relationships that you want. In general, you want to keep the abstraction as close as possible to the classes that depend upon it. Here are some general guidelines to making this happen.

• If only a single class, or set of classes in the same package, rely upon the abstraction, then place the abstraction in that package.
• If a set of classes that span multiple packages all rely upon the abstraction, but all packages exist within the same component, place the abstraction in a separate package in that component.
• If a set of classes that span multiple components all rely upon the abstraction, and you want to keep each of those components independent of each other, then place the abstraction in separate component.

SeparateAbstractions allows you to eliminate a module relationship. The module depending on the abstraction needs to be injected with an implementation or have some way to lookup the implementation at run-time. Creation of the appropriate implementation is another important consideration. If a lookup approach is taken, the lookup mechanism should use reflection to avoid introducing the dependency. If injection is used, you’ll need a separate component that performs the creation. SeparateAbstractions is concerned with flexibility, but comes at the price of complexity.

When assembling components, you may find that two otherwise independent components share common state. You’ll likely want to avoid having each component initialize and manage that state separately due to overhead, and possibly unreliable processing. Doing so also incurs  and unneccessary performance burden. If the state that each component relies upon is simply data that each requires to perform some processing, then it’s fairly easy to populate a bean defined by each component and pass the bean into the class requiring that data. But in situations involving more than state, each component may need to call back on an external entity. In this case, you cannot put the functionality on the bean since the bean would then require the ability to talk to the component. In order to accommodate this scenario, each component would need to define it’s own abstraction (the approach taken in Figure 10.1.2) or each component would need to depend on another component containing the abstraction (the approach taken in Figure 10.1.3).

Sample Code

In Abstract Modules, we depend upon the abstract elements of a module. In Implementation Factory, we used a factory to create the implementation class. Now, by moving the abstract class to a separate module, we can completely eliminate the relationship between the two modules.

Inverting the relationships allows us to deploy the customer.jar module independent of the billing.jar module. Again, it’s all about need. But I’d like to explore another option based on another important need – the ability to test and deploy modules independently. Before inverting the relationships, I am able to test and deploy the billing.jar module independently. After inverting the relationships, I can test and deploy the customer.jar module independently. But what if I want to test or deploy both modules independently? To do this, I need to completely eliminate the relationship altogether.

As it turns out, because I’ve got a pretty flexible class structure after I inverted the relationships (lot’s of abstract coupling), I can do this by simply bundling the two interfaces – Bill and DiscountCalculator – into a separate module. No other coding changes required. I start by moving them to a new package, which we’ll case base. (moving them to a new package called base). Then, I modify my build script (modify my build script) to bundle these two interfaces into a separate base.jar module, and we have successfully eliminated the relatinonship between the bill.jar and cust.jar modules. This is illustrated below in Figure 1.

Figure 1: Separating Abstractions to another Module

Wrapping Up

Depend upon the abstract elements of a module.

Description

Modules  heavily depended upon have many incoming dependencies. In other words, you may have many modules that all depend on a single modules. On one hand, this is a good thing because you’ve managed to maximize reuse. But reuse has it’s challenges. If the modules you’re reusing heavily requires a change, the ramifications of that change can ripple throughout all dependent modules. Changing a heavily reused module can be quite a maintenance headache.

There are two types of changes a modules can undergo. If you change a method signature of a public method on a public class, you can introduce compile errors into other areas of the application. While this might seem the most severe, it’s the easiest to correct. The negative ramifications of this type of change are fairly obvious, and if you do change a method signature, it’s important that you search for all referencing classes and make the correction. As a general rule, instead of changing the method signature, I’ll typically deprecate the old version and create the new version of the method with the updated parameters. This allows other developers to incrementally make changes.

You might feel safer if you only have to change a method implementation, or possibly a private method. But changing an implementation can have a farther reaching impact than you might expect. While you’ll certainly isolate all compile errors to the module, a much more stealth problem arises. Something must have driven the functional change being made. In the case of changing a module that is heavily depended upon, at least one of the dependent modules is the driver for that change. But you cannot only consider that single context when testing the change, but must also consider all other dependent modules. No compiler will tell you if you’ve introduced a change that won’t work with other modules not considered by the decision that drove the change. It’s much easier to make a change if you know that the effect of change is contained to just a single module.

Some modules within an application are very widely used. A module that can be used by any other module is a global package. An example of a global module is one containing utility classes that provide helpful methods to manipulate strings and format dates. You have to be very cautious when changing global modules. A small problem can cause widespread failure.

When you’re designing the dependencies between modules, depending upon only the abstract elements increases flexibility. It gives you the ability to more easily extend and maintain areas of your application by defining new modules with classes that implement or extend the abstraction. Most important, clients of the modules now have the freedom to receive different implementations because they are no longer coupled to an implementation, but instead are coupled to an abstraction (ie. an abstract class or interface).

In Figure 1, you can see the client1 package is dependent on the service package. Examining the contents of client1, you’ll notice that the dependency of the Client class is on the Service interface. This is supported by the associated code. Therefore, the client1 package is dependent upon only the abstract elements in service. This relationship is enforced, and cannot be violated, because the ServiceImpl class is given only package scope.

Figure 1: Depending on the Abstract Elements of a Module

The stability [MARTIN] of a package is a metric used to help determine the likelihood that a package will experience change. In Chapter 14, I examine this stability metric. Stable packages resist change, and are desirably the most heavily depended upon packages in the system. In Figure 7.4.1, you see the service package used by three other packages. The service package should be as stable, or resistant to change, as possible.

Implementation Variations

Depending on only the abstract elements of a package carries a price. Creating the implementing class can no longer be done by using the new keyword to create an instance of the implementing class. Instead, you have to consider some of the following options:

• Object Factory – To avoid dependencies on the concrete elements of a package, an object factory can be used to create the appropriate concrete instances. This offers a few advantages. First, the factory is the only area of the application referencing the concrete class. Adding new concrete classes that extend the abstraction is much easier. Second, if there are rules associated with creating the instances, these rules are well encapsulated within the factory. If the rules change, you’ll have a single maintenance point.
• Dynamic Creation – In some situations, you’ll find that using the Class class is more appropriate than an object factory. I’ve found this approach to work best in a couple of cases. In a web application, if I need to create certain classes at server startup, I’ll use the Class class and specify the concrete class to instantiate in a startup properties file. This allows me to create new classes that can be plugged into my application when the server starts up by simply defining the new class and then specifying it’s fully qualified name in the appropriate properties file. The second scenario is when I’m using an Abstract Factory [GOF]. Specifying how the appropriate concrete factories get created is also useful to specify in a properties file. In most other cases, I’ll use the object factory approach described above.

I don’t think it’s imperative that all dependencies on a package be abstract all the time. There are situations where referencing the concrete class directly is appropriate, and it eases the burden of designing a creation mechanism. However, you can certainly depend on some abstractions in a package, while also referencing concrete classes in that same package. It’s no coincidence that the most stable packages are packages that also have the majority of incoming dependencies on abstract classes or interfaces. This leads to two interesting observations.

Abstract classes or interfaces should absorb most incoming dependencies, whereas outgoing dependencies should originate from concrete classes. While simpler, you’ll want to avoid a heavily dependent package with a lot of concrete classes  because a single change can have a significant ripple effect across all dependent packages. You’ll also want to avoid packages with a lot of abstract packages that have no incoming dependencies. I’ll leave it as an exercise to the reader to determine why such a package is utterly worthless. In Chapter 12, I’ll explore some metrics that can help evaluate the robustness of your package structure.

The example in Heuristic 7.4 clearly illustrated the value of a dependency on only the abstract elements of a package. I’m not going to rehash that material here. You might, however, be interested in referring to Heuristic 11.2, which is closely related to Heuristic 7.5, but offers an additional perspective.

Consequences

If you have to change a stable module, you’ll experience a ripple effect throughout much of the application. Unless it’s a very simple change, the ripple effect is almost certain to cause a problem somewhere. Of course, you’ll probably have a gut feeling telling you what to expect of your change, and you should listen. The more you have to change stable packages, the less maintainable you’ll find the application.

Sample Code

Figure 1: Abstract Module

Wrapping Up

If Heuristic 7.2 is arguably the most important, Heuristic 7.5 arguably yields the most flexibility. While the resulting design is a bit more complex, you’ll find you can achieve some pretty amazing results when applying patterns in conjunction with Heuristic 7.5. When layering an application, your resulting package structure should be uni-directional. But in some cases, you might have a very strong desire to violate your layered relationships because of the perceived need to reference a method on a class in an upper level layer. Heuristics 11.2 and 11.3 offer interesting perspectives, and some interesting techniques that will allow you  to make explicit calls to methods on classes in upper layers without jeopardizing the hard work you’ve put into designing your package relationships.

The focus on package relationships helped me establish some clear and concise goals. Because the underlying datasource might change, I wanted to avoid coupling to a relational database, and this meant avoiding any dependency on java.sql. The desire to remain independent of java.sql create the need for a few additional classes to ensure I realized my goals. While not the only contributor, package relationships certainly played a large role in driving my class design.

As you’ve seen with most of the package heuristics, layering is a central theme. But a number of other design patterns have also emerged. In our example, the SelectDAO is a Strategy [GOF],  the FileDataCache is a Facade[GOF], and the BaseDAO serves as a factory for it’s implementers.

There are also a few other situations in the examples that  could use some attention. Passing the String and SortedMap as parameters to the retrieve method on the SelectDAO lacks  flexibility. While outside the scope of this discussion, I discuss some options in Heuristic 11.1.

Each module should have a corresponding test module.

Description

Writing tests is one of the most important activities you should perform as a developer. Create a robust suite of tests has significant advantages, both long and short term. Short term, tests help you verify that the code you write does as you intend. Creating tests also helps you design your system. Since classes should be independently testable, a natural by-product of test driven development is that your classes will exhibit lower degrees of coupling.

Test driven development has long-term benefits too. When refactoring your code, or adding new functionality to an existing code base, a suite of tests can be repeatedly run to guarantee that your changes haven’t broken anything that once worked. Inevitably though, bugs will surface and tests can help tremendously in proving the source of the bug and then help you fix it. When bugs do surface, most developers form a mental picture of the cause of the bug, and this helps them determine the place in the system to begin looking. But it always seems that some developers have better luck fixing bugs than others. It’s a frustrating experience when you’re told a bug has been fixed, only to find that either it hasn’t been fixed correctly, or that fixing the bug has caused another area of the system to break. Why do some developers have better luck fixing bugs that others? A few simple scenarios should yield some answers.

Lazy developers will operate on their initial hunch and simply change the area of the system they suspect is causing the error, and release those changes without proper test to other developers. Lazy developers typically experience very little consistent success with fixing bugs.

A better approach taken by some developers is to duplicate the error by running the application using the same conditions as when the bug was encountered. Once the error is duplicated, they’ll typically use a debugger or logging statements to nail down the exact location of the bug. After the location is nailed down and the code has been corrected, they’ll run the application again to prove the bug has been fixed. While some testing is better than no testing, this approach is also seriously flawed. Running the application doesn’t allow you to focus specifically on the source of the bug because you are testing the application as a whole.  Additionally, without a suite of test cases, you may be able to prove that your change fixed the problem in the scenario it was discovered, but you cannot guarantee that your changes didn’t break something elsewhere in the application. It’s unrealistic to expect each developer to test the entire application each time a change is made. Few developers are disciplined enough to repeatedly perform such a mundane exercise. Another disadvantage is that this approach is not automated and repeatable, and you’ll always run the risk that future changes will break it again. You may fix the problem initially, only to find that future changes introduce a similar problem. Proving that you fixed the problem today doesn’t prove that the problem won’t surface again tomorrow.  Developers adopting this approach typically introduce more bugs than they fix.

Those developers who use test driven development typically have a greater degree of success in fixing bugs since a robust suite of test cases already exist that prove other areas of the system still function as intended. However, you still have to be very judicious in your approach to correcting the error. Simply fixing the source of the bug and running the existing suite of tests to prove that the bug has been corrected won’t always work.

The most successful developers typically have a very regimented approach. The approach goes something like this. Their first step is to create a new test case that reproduces the problem. The reasoning here is that if the existing suite of tests don’t reproduce the problem, then the existing suite of tests don’t test that condition, and a new test is needed. Once the problem has been reproduced, developers will fix the bug and run the test again. This time, the test should pass. If the test does pass, you can start feeling pretty good that you’ve fixed the error. But you can’t stop here. You should also run all other tests within the application to prove that your changes haven’t broken something else. Only after you do this can you feel reasonably comfortable knowing the problem has been fixed.

Adopting a sound approach to testing involves much more than simply saying that you write tests. A robust testing strategy means that you’re working hard to write classes that can be tested independently.  A unit test emphasizes testing classes as a standalone unit. This typically implies that you want to decouple the class you’re testing from any outside forces, such as a database or legacy integration with a backend system. Testing classes independently implies that you are devoting effort to decoupling your classes by injecting dependencies into the class under test. This means that the classes you’re testing must depend on abstract classes or interfaces for the services they use, and the test case will inject a stub into the class under test. The stub is a simple implementation of the abstraction that exists for testing purposes only, and isn’t used in versions of the system running outside of the test suite.

Test ing classes independently using unit tests is valuable, but it’s also valuable to test the integration aspect of multiple classes or components. For instance, you might create an integration test that retrieves information from a database table to prove connectivity with the backend database, or to prove that when two components are wired together, they continue to function as expected. Any test that requires access to a force external to the class originally under test is considered an integration test. While integration tests are useful, you should be cautious to avoid testing business logic in your integration tests. You should not check that the result of the test is a specific data value, but instead focus on the structure of the information being what you expect, that the connectivity between two entities is functional, or to ensure the integration point is still what you expect. Becoming “test infected” means that you aren’t writing tests because you’ve been told you need to, but that you create a suite of unit and integrations tests to help you write higher quality code and design more resilient software.

There are other types of tests that can be very useful as well. A design test allows you to make assertions about the design metrics of the system. Tools such as JDepend can be used to create tests that check for dependencies between packages. Performance tests allow you to verify the response time of a test. JunitPerf offers extensions to the Junit testing framework that allows you to write performance tests. Finally, functional tests allow you to create user level tests. Tools such as JwebUnit or Fitnesse allow you to create functional tests.

Our discussion to this point has served as primarily a review of sound testing strategies for class level testing. Assuming you are devoted to creating robust test suites, there is no magic in creating a TestComponent. If you’re applying some of the other useful patterns in this book, a TestComponent is a very natural by-product, and is mainly an exercise in how you bundle your test cases. For any set of classes bundled in a component, the corresponding test cases are bundled in a separate TestComponent. But similar to a unit test case that should test a class independently, a TestComponent should also be able to test a component while only depending on components required by the component under test. You should avoid introducing any new dependencies from within the test component. Otherwise, you cannot say for certain that you’re testing only the component’s functionality. A good rule of thumb when creating a TestComponent is that the TestComponent should be one level higher than the component under test. This helps ensure you aren’t introducing additional dependencies that aren’t required.

Recall that levelizing your component hierarchy requires that you have AcyclicRelationships between all components. TestComponents should also have AcyclicRelationships. If you find that the TestComponent is more than a single level higher, it’s a  good indication that the TestComponent is using  another component’s classes as stubs for the component under test. You have to give careful consideration to the placement of integration, design, performance, and functional tests. It’s very likely that these types of tests will introduce undesirable TestComponent dependencies. Strategies for dealing with the placement of these other types of tests will be discussed next. Figure 1 illustrates a Test Module.

Figure 1: Test Module

Implementation Variations

You’ll want to share some utility classes across TestComponents. In this situation, you can either duplicate the utility classes, or create a lower level test utility component that contains the test utility classes.

It is certainly tempting for a TestComponent to define dependencies on other components that contain implementations for classes within the component under test. While resisting this temptation is difficult, it’s also important. Defining additional dependencies on other components within your test component will save you a bit of time in creating the test cases, but it will also compromise the integrity of your test. By using classes in other components as your stubs, you cannot be certain that a failing test case is the result of a flaw in the component under test, or a bug in the component classes you are using as your stubs.

Notes on Integration vs. Unit tests here
If you’re creating integration, performance, functional or design tests, you might consider splitting these integration tests out into another separate TestComponent if the integration tests introduce dependencies on other components. Using a LevelizedBuild can help in determining where these other tests should be placed.
There are some cases, however, where a TestComponent will need, and even want, to introduce additional dependencies. For instance, if the component under test relies heavily upon database interaction, it’s likely that the connections to the database are obtained from your J2EE containers javax.sql.DataSource. Ideally though, you’ll execute your test outside the container’s environment. In such situations, you’ll find you want to introduce new dependencies to components that allow you to execute the tests standalone. To deal with database connections, a good approach would be to use the Commons Database Connection Pool (DBCP) component. Of course, another approach well worth considering is creating your classes so that they can be tested independent of a database connection.

If you leverage Abstract Modules, you’ll be able to create mocks or stubs to ensure modules can be test independently of each other. Figure 2 illustrates this.

Figure 2: Test Module with Abstract Module

Consequences

Test modules increase testability by allowing you to test modules independent of each other. Once a modules functions correctly as an independent unit, any error is the result of integration with other modules. Application level integration tests can be helpful in this situation.

Sample Code

Recall the example using a Callback in the discussion on the Acyclic Relationships pattern. Figure 3 illustrates the relationship between the customer.jar and billing.jar modules resulting from the relationship between the Customer and Bill classes.

Figure 3: Module Relationships

Based on these module relationships, we can already create a separate test module for the billing.jar module. Listing 1 illustrates the test case to test the payment functionality of Bill.

package com.kirkk.test;

import junit.framework.TestCase;
import java.math.BigDecimal;
import java.util.*;
import com.kirkk.cust.*;
import com.kirkk.bill.*;

public class PaymentTest extends TestCase {

   public PaymentTest(String arg0) {
      super(arg0);
   }

   public static void main(String[] args) {}

   public void testPayment() {
      Customer customer = new Customer();
      customer.createBill(new BigDecimal(500));

      Iterator bills = customer.getBills().iterator();

      while (bills.hasNext()) {
         Bill bill = (Bill) bills.next();
         BigDecimal paidAmount = bill.pay();
         assertEquals("Paid amount not correct.", new BigDecimal(485).setScale(2), paidAmount);
      }
    }

   public void testPaymentWithoutCustomer() {
      Bill bill = new Bill(new DiscountCalculator() {
         public BigDecimal getDiscountAmount() { return new BigDecimal(0.1); }
         }, new BigDecimal(500));

      BigDecimal paidAmount = bill.pay();
      assertEquals("Paid amount not correct.", new BigDecimal(450).setScale(2), paidAmount);
   }
}

This test case results in the relationships between modules shown in Figure 4, where we can now see the billingtest.jar test module.

Figure 4: The PaymentTest Module

The PaymentTest is actually an integration test because it uses the Customer to to test the Bill.

Wrapping Up

Like unit testing, where classes are ideally tested in isolation, a test module allows you to test modules in isolation. A test module can help identify undesirable module dependencies. Then, utilizing other patterns, these dependencies can be broken if that’s the desirable course of action. Unlike unit testing, a test module is a more granular kind of test. Test modules also provide excellent insight on how to configure a module and interact with its Published Interface.