Modular Architecture » Base Pattern

Cohesive Modules

kirk knoernschild — Wed, 23 Dec 2009 02:11:24 +0000

Statement

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.

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.

Module Reuse

kirk knoernschild — Tue, 22 Dec 2009 02:55:11 +0000

Statement

Emphasize reuse at the module level.

Description

One of the oft cited benefits of object oriented development is reuse. Mostly, we’ve failed miserably in achieving any degree of reuse that is directly attributable to objects. A large part of this failure is very likely because using objects does not guarantee reuse, but actually requires a significant amount of thought, effort, and usually refactoring to make reuse happen. As I’ve witnessed it though, the heart of the problem is identifiable.

The object paradigm introduced many new ideas to the development community, but none were so revolutionary as polymorphism and inheritance. Giving developers these two powerful language constructs created a new way of thinking about, and designing, software applications. Given that the advantage of object oriented development was higher degrees of reuse, there was a natural tendency to believe that it was these two new constructs that would enable, and virtually guarantee, reuse. Nothing is further from the truth, however. Instead, these two powerful constructs have little to do with facilitating reuse directly. In the last few years, we’ve actually found that ImplementationInheritance hinders reusability more so than facilitating reuse by locking a developer into a rigid design with little ability to meet the changing needs of most complex software systems. In fact, structured programming techniques, which have been around for more than 30 years, can be used to achieve reasonable degrees of reuse. I’ve witnessed many situations where legacy COBOL code that was well-written could easily be reused.

So, to start, we need to break away from the thinking that objects help us create more reusable software. Instead, objects help us create more extensible software, which is an enabler of reuse. Using inheritance and polymorphism allows us to create designs that are more flexible. It’s this flexibility, and the ability to plug different implementations into a class referencing an abstraction, that allows us to create generic software that can be configured to meet our needs. The ability to slightly modify the behavior of a chunk of code typically results in more reusable code. As a guideline, the less something does, the more reusable it will be. The trick, of course, is to make something general and configurable enough so that it’s reusable in a variety of contexts, while also making it do enough so that it’s useful. Given that extensibility and configurability are indirect enablers of reuse, it’s much more common to reuse a set of collaborating classes over an invidual class. We discussed this tension between use and reuse in Chapter 6.

Herein lies one of the greatesst problems with achieving reusability using object oriented development. The class, a combination of attributes and behaviors, which is commonly the focal point of most object oriented designers, is not an adequate reuse construct. Reuse is a matter of scale, and attempting reuse at the class level is to small scale to realistically expect that high degrees of reuse can be achieved.

Of course, there are other factors that contribute to our inability to achieve higher degrees of reuse. Many highly touted design techniques, such as the Unified Modeling Language (UML) and patterns, tend to draw our attention toward class design. Attempts to use the design techniques to create robust designs before coding only excacerbates the problem, and for large systems with many classes and many developers the problem grows even worse. Instead of attempting to reuse at the class level, we should turn our attention to using the object oriented concepts to design more flexible class relationships.

Of course, most of us have experienced some degree of success with class level reuse, especially within an application. Utility classes are common in most applications, and are generally reusable. But even these utility classes can be difficult to reuse across applications . To reuse within an application, all classes can be bundled together. But to reuse across applications, classes need to be bundled separately into cohesive units. If dependencies between these individual units are not managed carefully, reuse will not follow. A failure to bundle your code correctly is one of the leading causes for the most common form of reuse – copy and paste. To effectively achieve higher degrees of reuse, we need a higher level unit of modularity around which code can be organized, bundled, and deployed. This higher level unit of modularity is the component, or in Java, the JAR file. The reuse release equivalence principles states this a bit more succinctly:

The unit of reuse is the unit of release.

Instead of emphasizing reuse at the class level, we should emphasize reuse at the module level. Then, using object oriented design concepts, we create flexible clss designs that are extensible, configurable, and exhibit low degrees of coupling. We bundle these classes into cohesive and independently deployable modules that can then be easily reused. A flexible class design allows you to refactor your modules by moving classes to different modules based on need.

The most compelling evidence suggesting that we should emphasize reuse at the module level is through examination of the open source community and many of its frameworks. The most widely adopted and successful open source products are JAR files that can be easily incorporated into your application. The most flexible of these offerings provide hooks into the framework that allow you to customize it to your need. But all emphasize the module as the unit of reuse.

Implementation Variations

Horizontal modules span business domains, and do not contain functionality that is industry specific. It’s much easier to develop horizontal modules for reuse because their usage pattern is consistent and well-known. Most open source software, such as Struts, Hibernate, and Spring fall into this category. Vertical modules, on the other hand, are specific to a business domain. They offer behavior rich with functionality specific to your organization. Many of the modules developed for business software fall into this category.

Horizontal modules are much easier to develop than vertical modules. The challenge with vertical modules is that you are forced to predict the requirements of future usage scenarios, which is an impossible task. For instance, Hibernate, a widely used persistence framework, allows you to bridge the object and relational world regardless of which backend relational database you are using. Attempting to develop an Employee object that is reused across the enterprise is mostly impossible since different applications within your organization will require different behaviors of the Employee.

Since vertical modules are so much more difficult to reuse, it’s important to create these modules with the least amount of functionality that is common to all applications that will use it. Therefore, you have to be very cautious in adding any degree of rich behavior. A good starting point is a modules that facades a backend datasource, and returns raw business objects with little functionality. These business objects, while offering little functionality, contain the data and other methods that allow the object to be configured to it’s context.

There are two main impediments you’ll encounter when trying to reuse modules. First, the module doesn’t offer the right level of functionality that you need, and you cannot customize the modules to fit your conext. This is typically a problem when the module has not been created at the correct level of granularity. The module does more than what you want. When developing modules, it’s important to only offer functionality that you know is appropriate. If you question whether the module should do something extra, you should either avoid putting the behavior in the module, or offer the ability to configure the module so that the behavior can be turned off. Second, you may find that amodulehas too many heavyweight dependencies on something else, thus preventing you from reusing it because you do not want those heavyweight dependencies. If you SeparateAbstractions and provide ExternalConfiguration, you’ll likely be able to remove some of the unwarranted dependencies as well as allow the component to be more easily configured to context.

Services differ from modules in that services typically span distribution boundaries whereas modules are invoked in-process. For years, industry luminaries have predicted that services will revolutionize software reuse. I’m not convinced that this is true. Services along will not provide the revolutionary boost to software architecture that’s necessary. It will be just as easy to create heavyweight and unusable services as it is to create heavyweight and unusable components. In Chapter 4, we discussed the concept of architecture all the way down. Truly great applications are going to require a solid design from the class structure, to the module structure, and finally to the service level. If you create a robust suite of modules, that are loosely coupled and wired together at run-time, these modules can be used to compose your services.

Module management can be difficult. A large number of modules with multiple versions of each make it difficult for others to ensure they are using the correct version of a modules. A repository in your version control software is a great places to store the binaries of your modules. An application’s build process can be configured to pull the correct version of the module from the repository during each build.

NOTE ON OSGI AND SUPPORT FOR MULTIPLE VERSIONS HERE.

Consequences

Emphasizing reuse at the component level offers a much greater probability that you’ll succeed in your reuse efforts. However, the pipe dream of assembling applications from pre-built components will likely never come true. Organizational change will always dictate that software be customized and it’s unlikely that organizations within an industry will standardize their processes since this standardization eliminates a company’s competitive advantage. However, a suite of robust components will help an organization deliver software more quickly. The ability to assemble these components, add to them, and build custom software on top of them will help an organization achieve and sustain their competitive advantage.

Maximizing the reuse of a component usually means creating smaller components that do less. This can make component management a difficult task. Contrarily, larger components that do more will be easier to manage, but may not be as reusable. It can be very difficult to balance these two competing agendas. I have found that early in the development lifecycle, while the software is still in a very dynamic state, larger components tend to be easier to manage. As distinct areas of reuse are identified, these larger components can be broken out into smaller, more reusable components. Attempting to define smaller fine-grained components earlier in the lifecycle is difficult since you are forced to guess the functionality of a component. This is usually a lost cause.

Sample Code

An insurance company receives policy applications that are scanned into a system. The scanned copy of the image is stored in an enterprise document management system. Optical Character Recognition (OCR) software extracts data from the scanned image and stores the data to an operational application database. Before storing the data to the database, the data must pass through a series of business rule validations, and the policy is flagged with a status based upon the outcome of the business rules.

A separate web application is used by the Underwriting department to review the policy information, cleanse any data incorrectly interpreted by the OCR software, and ultimatly allow the Underwriter to assess the insurability of the customer. Any changes to the policy information must pass through the same set of business rule validations. However, if any of the validation rules fail, instead of setting a flag on the policy, the Underwriter is prompted to correct the information.

In this scenario, we have two independent systems that must share some common validation rules. One approach is to develop a distributed service that is deployed once and invoked by each of the applications. In lieu of incurring the performance hit of a distributed call, we’ll opt to develop a component that helps us validate the policy information. To do this, however, we must ensure that the component does not have any application dependencies. Of course, we’d have to do the same for a service, but more on that a bit later.

The OCR software sends the data feed in XML format. Our initial pass at validating the information leads us to creating a Policy class. The constructor of our Policy class accepts the XML String and parses it out to build the Policy object. The validate method can then be called to ensure the data is correct before calling the save method to store the data to the application database.

package com.extensiblejava.policy;

import java.util.*;
import java.io.*;
import javax.xml.parsers.*;
import org.xml.sax.helpers.*;
import org.xml.sax.*;

public class Policy {

   private String firstName;
   private String lastName;
   private String tobaccoUser;
   private Date dateOfBirth;
   private String maritalStatus;

   public Policy(String xmlString) {
      try {
         SAXParserFactory factory = SAXParserFactory.newInstance();
         SAXParser parser = factory.newSAXParser();
         InputSource source = new InputSource(new StringBufferInputStream(xmlString));
         parser.parse(source, new PolicyDefaultHandler(this));
      } catch (Exception e) {
         e.printStackTrace();
      }
   }
   void setFirstName(String firstName) { this.firstName = firstName; }
   void setLastName(String lastName) { this.lastName = lastName; }
   void setTobaccoUser(String tobaccoUser) { this.tobaccoUser = tobaccoUser; }
   void setDateOfBirth(Date dateOfBirth) { this.dateOfBirth = dateOfBirth; }
   void setMaritalStatus(String maritalStatus) { this.maritalStatus = maritalStatus; }
   public String getFirstName() { return this.firstName; }
   public Date getDateOfBirth() { return this.dateOfBirth; }
   public String getLastName() { return this.lastName; }
   public String getMaritalStatus() { return this.maritalStatus; }
   public String getTobaccoUser() { return this.tobaccoUser; }
   public void validate() {
      //validate the data.
   }
   public void save() {
      //save the data.
   }
}

Listing 1: The Policy Class

The PolicyDefaultHandler, in the same module as policy, sets the individual attributes on the Policy object as the XML string is parsed.

package com.extensiblejava.policy;

import java.util.*;
import org.xml.sax.helpers.*;
import org.xml.sax.*;

class PolicyDefaultHandler extends DefaultHandler {
   private Policy policy;
   private String attribute;
   public PolicyDefaultHandler(Policy policy) {
      this.policy = policy;
   }
   public void characters(char[] ch, int start, int length) {
      String element = new String(ch, start, length);
      this.setPolicyAttribute(element);
   }
   public void startElement(String uri, String localName, String qName, Attributes attributes) {
      this.attribute = qName;
   }
   private void setPolicyAttribute(String value) {
      if (this.attribute.equals("firstname")) {
         policy.setFirstName(value);
      } else if (this.attribute.equals("lastname")) {
         policy.setLastName(value);
      } else if (this.attribute.equals("dateofbirth")) {
         Calendar cal = Calendar.getInstance();
         Integer month = new Integer(value.substring(0,2));
         Integer day = new Integer(value.substring(3,5));
         Integer year = new Integer(value.substring(6,10));
         //System.out.println(value.substring(0,2) + "  " + value.substring(3, 5) + "  " + value.substring(6, 10));
         cal.set(year.intValue(), month.intValue() - 1, day.intValue());
         policy.setDateOfBirth(cal.getTime());
      } else if (this.attribute.equals("tobaccouser")) {
         policy.setTobaccoUser(value);
      } else if (this.attribute.equals("maritalstatus")) {
         policy.setMaritalStatus(value);
      }
   }
}

Listing 2: The PolicyDefaultHandler Class

The result is a valid Policy object that can now be validated and saved to the database. The above approach works well for the OCR and scanning application. However, the Policy is tightly coupled to the XML and cannot be used in our Underwriting application. For the validation rules and persistence behavior on our Policy class to be reusable in another application, we must not only decouple our Policy class from this XML String, but we must also ensure that the Policy class can be deployed independent of the XML behavior. In the situation above, because our Policy class is so heavily dependent on the XML parsing functionality, the Policy behavior we want to reuse cannot be deployed separately. Intead, a single policy.jar module is our only deployable unit, as shown in Figure 1.

Figure 1: The Policy Module

To fix the problem with Policy above, we have to physically separate the process of constructing the Policy object from the format of the data used to construct Policy. To achieve this separation, our Policy class has been refactored to accept an abstract PolicyBuilder to it’s static buildPolicy method.

package com.extensiblejava.policy;

import java.util.*;
public class Policy {
   private String firstName;
   private String lastName;
   private String tobaccoUser;
   private Date dateOfBirth;
   private String maritalStatus;
   public static Policy buildPolicy(PolicyBuilder policyBuilder) {
      return policyBuilder.build();
   }
   public Policy(String firstName, String lastName, String tobaccoUser, Date dateOfBirth, String maritalStatus) {
      this.firstName = firstName;
      this.lastName= lastName;
      this.tobaccoUser = tobaccoUser;
      this.dateOfBirth = dateOfBirth;
      this.maritalStatus = maritalStatus;
   }
   public String getFirstName() { return this.firstName; }
   public Date getDateOfBirth() { return this.dateOfBirth; }
   public String getLastName() { return this.lastName; }
   public String getMaritalStatus() { return this.maritalStatus; }
   public String getTobaccoUser() { return this.tobaccoUser; }
   public void validate() {
      //validate the data.
   }
   public void save() {
      //save the data.
   }
}

Listing 3: Decoupled Policy Class

The Policy class has now been decoupled from the construction of the Policy object using XML as the input source. The PolicyBuilder interface defines the build method that the implementing class must provide to construct the Policy instance.

package com.extensiblejava.policy;
public interface PolicyBuilder {
   public Policy build();
}

Listing 4: PolicyBuilder Class

We now define a PolicyXMLBuilder implementation, which we’ll put in a separate module that will build the Policy instance.

package com.extensiblejava.builder.xml;

import java.util.*;
import java.io.*;
import javax.xml.parsers.*;
import org.xml.sax.helpers.*;
import org.xml.sax.*;
import com.extensiblejava.policy.*;
public class PolicyXMLBuilder implements PolicyBuilder {
   private String xmlString;
   private String firstName;
   private String lastName;
   private String tobaccoUser;
   private Date dateOfBirth;
   private String maritalStatus;
   public PolicyXMLBuilder(String xmlString) {
      this.xmlString = xmlString;
   }
   public Policy build() {
      try {
         SAXParserFactory factory = SAXParserFactory.newInstance();
         SAXParser parser = factory.newSAXParser();
         InputSource source = new InputSource(new StringBufferInputStream(xmlString));
         parser.parse(source, new PolicyDefaultHandler(this));
      } catch (Exception e) {
         e.printStackTrace();
      }
      return new Policy(this.firstName, this.lastName, this.tobaccoUser, this.dateOfBirth, this.maritalStatus);\
   }
   void setFirstName(String firstName) { this.firstName = firstName; }
   void setLastName(String lastName) { this.lastName = lastName; }
   void setTobaccoUser(String tobaccoUser) { this.tobaccoUser = tobaccoUser; }
   void setDateOfBirth(Date dateOfBirth) { this.dateOfBirth = dateOfBirth; }
   void setMaritalStatus(String maritalStatus) { this.maritalStatus = maritalStatus; }
}

Listing 5: PolicyXMLBuilder Class

Finally, a simple integration test proves correctness.

package com.extensiblejava.policy.test; import junit.framework.*; import junit.textui.*; import com.extensiblejava.policy.*; import com.extensiblejava.builder.xml.*; import java.util.*; import java.io.*; public class PolicyXMLTest extends TestCase { public static void main(String[] args) { String[] testCaseName = { PolicyXMLTest.class.getName() }; junit.textui.TestRunner.main(testCaseName); } protected void setUp() {} public void testPolicy() throws Exception { String policyXML = ""+"Jane"+"Doe"+"M"+"01/10/1967"+"N"+""; Policy policy = Policy.buildPolicy(new PolicyXMLBuilder(policyXML)); assertEquals("Jane", policy.getFirstName()); assertEquals("Doe", policy.getLastName()); assertEquals("M", policy.getMaritalStatus()); assertEquals("N", policy.getTobaccoUser()); Calendar cal = Calendar.getInstance(); cal.setTime(policy.getDateOfBirth()); assertEquals(10, cal.get(Calendar.DAY_OF_MONTH)); assertEquals(1967, cal.get(Calendar.YEAR)); assertEquals(1, cal.get(Calendar.MONTH) + 1); } }

Listing 6: PolicyXMLTest Class

Since the construction of the Policy class has now been separated out into a separate module, we have the ability to deploy the Policy behavior independent of the XML construction process. The new module structure can be seen in Figure 1.

Figure 2: Policy Module Diagram

Since the functionality to validate and save policy information has been separated from the XML construction process, the policy.jar module can now be deployed independent of the policyxml.jar module. Defining a new implementation of PolicyBuilder in the Underwriting application should allow us to construct the Policy instance from the data retrieved from the application database.

This resulting structure offers some significant advantages. Through the example, we’ve already illustrated how the policy functionality can be reused across applications. In the future, if we decide to deploy the policy functionality as a service invoked via a distributed protocol, such as EJB or JMS, the modular approach we’ve taken will help faciliate that endeavor.

Wrapping Up

The Reuse Release Equivalence Principle implies that software is reused at the same unit of functionality at which is deployed. In Chapter 2, we defined a software module and highlighted that a module is a unit of deployment and a unit of intra-process reuse. By definition, modules are the only software entity that match this set of criteria and designing good software modules presents development teams another option for how they choose to reuse software entities.

Manage Relationships

kirk knoernschild — Tue, 22 Dec 2009 01:49:58 +0000

Statement

Design module relationships.

Description

A relationship between two modules exists when a class within one module imports at least a single class within another module. In other words:

If changing the contents of a module, M2, may impact the contents of another module, M1, we can say that M1 has a Physical Dependency on M2. [JOUP02]

In Figure 1, you can see a component diagram and accompanying code that illustrates two different types of module dependencies.

Figure 1: Direct and Indirect Dependencies

Dependencies can manifest themselves in different ways. The most straightforward is a direct dependency, where a client module depends directly on a service module, as show at left in Figure 1. A direct dependency, the kind shown in Figure 7.1, is where a module uses the services offered by another. Direct dependencies require you to include the dependent module in both the build classpath and the runtime classpath. Neglecting to include the dependent module in the build classpath will result in compile errors, and neglecting to deploy the dependent module may result in run-time errors if a class in the dependent module is referenced at run-time by the module using it. If it’s never referenced at run-time, the classloader doesn’t try loading the class, and no problems arise. However, if at run-time the class is referenced, and the module isn’t found on the classpath, an exception arises. It’s a rather dangerous practice to ignore run-time dependencies that are required build time dependencies, since changing the behavior of the using component will still result in a valid compile, but could result in a run-time ClassNotFoundException.

Indirect, or transitive, dependencies involve at least three module, were a service module is also a client module dependent on some other module. The module diagram shown at the right side of Figure 1 illustrates an indirect dependency, where the service module is a client module of the subsystem module and a service module to the client module. Here, the client module has an indirect relationship to the subsystem module, and if something changes in the subsystem module, it may ripple through the other modules.

If you’re performing a LevelizedBuild, indirect dependencies need not be included in the build-time classpath. The same rules for run-time inclusion hold for indirect dependencies as for direct dependencies. To resolve the potential problems cited above with build-time versus run-time contention, I’d suggest creating a Test Module that is executed as part of the build. This allows you to verify the functionality of the module being compiled, and you can easily experiment with the build-time classpath to determine if a module absolutely must be deployed. But remember, it is dangerous to deploy only dependent modules used at a given point in time, since changing the behavior of the client component can unknowingly alter what’s required at run-time.

Implementation Variations

When designing module relationships, there are some important implementation details to consider. For example, a service module must be included in the build classpath of the client module. Failing to do so will result in a compile error. If the client module references a class in the service module at runtime, then the service module must also be included in the runtime classpath, as well. Failing to do so will result in a ClassNotFoundException.

Modules with excessive incoming and outgoing dependencies are the most difficult to manage because they are widely reused but also difficult to change and test. Because of this, it’s ideal if modules are either heavily depended upon or heavily depend upon another module. Unfortunately, this isn’t always possible. In these cases, other modularity patterns can help ease the tension when modules have a lot of incoming and outgoing dependencies.

Understanding the relationships between modules makes it easier to isolate the impact of change to a specific set of modules, which is not something easily done at the class level. We saw an example of this in Section 5.5.1. In the example above, changes to the client module clearly indicate that the impact of change is isolated only to the client module. Likewise, changes to the service module indicate the impact of change could spread to other classes within the service module as well as classes within the client module. Without designing and understanding module relationships, it’s difficult to understand the impact of change.

Java does not enforce that a package and corresponding classes be included in only a single phsycal entity. In fact, there are some situations where this is obviously violated. For instance, the javax.servlet.http.HttpServletRequest class can be found in both the j2ee.jar and servlet-api.jar components. While it’s feasible to place the same class in multiple .jar files, you have to exercise caution when doing so for two reasons. First, if you are compiling with one .jar file and deploying with another, you run the risk of inconsistent versions. Your application may compile with the correct version, but experience run-time problems if the deployed .jar file contains classes from a different version. Second, only one version of a class can be deployed. If you deploy multiple versions of a class, you’ll risk a ClassCastException at run-time if the ClassLoader attempts to load both classes. This can be an especially tricky problem to debug. So while it’s possible to bundle a class in multiple .jar files, it is not recommended.

Managing component relationships is a critical issue when developing large enterprise applications. There are two types of component relationships that need to be managed. Incoming dependencies are present when a component has other components dependent on it. A component with a large number of incoming dependencies should be a StableComponent. The best way to ensure a component’s stability is by making it an AbstractComponent. Outgoing dependencies are present when a component is dependent on classes in one or more other components. Each time you define a new outgoing dependency on another physical entity, you are expanding the knowledge of a component. While you may be increasing the richness of what the component has to offer, you may also be limiting it’s reusability across a wider array of contexts. To minimize a components outgoing dependencies, you should consider creating AbstractComponents. AbstractComponents are especially necessary if a component has a large number of incoming dependencies.

Components with a lot of incoming dependencies are obviously reused more, and changing them requires a bit more ceremony. They must be tested thoroughly, and pushed out to all applications that use them. Changing components with many incoming dependencies is primarily a maintenance and deployment issue.
Components with a lot of outgoing dependencies can be changed easily, but not tested easily. It’s difficult to independently verify components with many outgoing dependencies, since they cannot be tested in isolation. Your goal should be to minimize outgoing dependencies, and where outgoing dependencies are necessary, the outgoing dependency should be on AbstractComponents. By minmizing a component’s outgoing dependencies, you increase the testability of the component. A TestComponent can be created for each component that allows you to test a component in isolation, helping to ensure the component’s correctness.

It’s not completely terrible if you find that some components have many incoming dependencies, while other components have many outgoing dependencies. However, you should avoid components that have both many incoming and outgoing dependencies where the outgoing dependencies are not on AbstractComponents. Of all scenarios, this one is a testing, maintenance, and deployment issue all wrapped into one. Worse yet, is when your many incoming and outgoing dependencies form AcyclicRelationships.

Consequences

There are a lot of things to consider when designing module relationships. In general, a module has incoming dependencies, outgoing dependencies, or a combination of each. Different forces affect modules depending on the types of dependencies they possess.

Modules with a lot of incoming dependencies are more difficult to change because they are being reused by more client modules. Because of this, it’s imperative that they undergo more thorough and rigid testing, and steps should be taken to minimize changes to these modules (like using AbstractModules).

Modules with a lot of outgoing dependencies are easier to change because they are reused by fewer modules. Unfortunately, these modules are more difficult to test in isolation because of their dependencies on other modules.

There are ways to alleviate each of these challenges. Designing abstract modules, ensuring module relationships are acyclic, and separating abstractions from the classes that realize them are each examples.

I’ve experienced some significant advantages in designing component relationships. They allow me to view the system from a perspective that is much different than when I browse the classes. A medium sized application might consist of thousands of classes, but may be composed of only a few dozen components. Browsing these component relationships allows me to more easily see how the system is structured. It’s an especially helpful way for me to see how changes might impact other areas of the system. Knowing the component dependencies enables me to identify those classes that may be affected by changing a class in a dependent component.

Defining component relationships also serves as a system of checks and balances against a system’s logical structure. When layering a system, it’s important that each layer has a clearly defined set of responsibilities. Layering components guarantees consistent responsibilities within each layer. Only importing those classes from dependent components ensures I’m well aware of the ramification of change. These relationships enforce architecture, and any new relationship created between two previously independent components should be given serious consideration.

You should exercise caution any time you import a new class where a component relationship doesn’t already exist between the components because the coupling of the components increases. Instead of willy nilly importing whatever is needed, you’re forced to make an important design decision. Do you really want to create the new dependency, or is the decoupling of components important enough to warrant additional design flexibility? This additional flexibility can often be achieved by using interfaces to enable classes to communicate with other classes in non-dependent components. In fact, this is one example of how patterns emerge within your system, and SeparateAbstractions in Chapter XX shows how interfaces can be used to avoid component coupling.

But component relationships offer more value than simply dictating class relationships. When deploying applications, a component is the minimal unit that is deployed. Attempting to deploy one component without deploying all dependent components results in run-time issues. Of course, it’s not necessary that all dependent components be deployed in the same file. Separating components into various files gives you great flexibility in how the application is deployed and how the componets are reused. Should you decide to separate dependent components across files, it’s imperative that all dependent files be deployed together, knowing you’ve given yourself greater flexibility in how the functionality contained within each component can be reused.

I’ve actually written quite a few batch applications in Java. Typically, these batch applications are not projects of their own, but part of a larger project that also has a web interface. For instance, a batch application might receive an incoming data feed, and save the data to a database. It may perform some validation and flag some records in error. The web interface may provide users the ability to correct those errors, perform the same validation, and persist the cleansed data back to the database for downstream processing.

To avoid duplication in the batch and web application,it’s important to reuse the code that performs the validation and saves the information to the database. Because the batch application will likely run in a separate JVM, and usually outside the context of a J2EE container, the core components used by both batch and on-line must be separated into files independent of either the batch or on-line systems. Knowing the component relationships allows me to accomplish this much more easily.

Neglecting to define components dependencies has a tremendous impact on reuse. While you will reuse behavior at the class level, the inability to deploy self-contained units will often deflate your hopes of reusing your logic across applications. Planning your deployment strategy is a critical step in establishing a robust infrastructure. It’s a frustrating experience to find that what you thought was a reusable software component is actually dependent on code that you don’t want to deploy with a given application. Defining your PhysicalLayers and CohesiveComponents allows you to realize your reuse goals much more easily.

Sample Code

Tight coupling between modules is a bad idea. Fortunately, there hat allow us to invert and eliminate module relationships. These techniques are leveraged by a lot of the modularity patterns. The code for each of the samples can be found in the edcie project on my Google code repository. Each examples includes a build script and a simple test case. To execute them though, you’ll need GraphViz if you want to use JarAnalyzer. To invoke the build scripts without invoking JarAnalyzer, you can simply type:

ant compile

Keep in mind that each variation of the system has the exact same behavior!

Figure 2 illustrates the acyclic modules from Section 5.2.2. Obviously the customer.jar module depends on the billing.jar module, implying that billing.jar is required by customer.jar at both build and runtime. But what if we wanted to use the customer.jar module without the billing.jar module? With a bit of trickery, I can actually invert the relationship between the customer.jar and billing.jar modules.

NOTE: Start with this diagram in Abstract Modules to illustrate why we want to depend only upon abstractions. For instance, we add a new Bill. Just show how we can manage relationships between customer.jar and billing.jar module and how the build script can bundle these into their own modules. Then, move Inverting Relationships to Abstract Modules.

Note: Be sure to discuss tools that can be used to manage module relationships. JarAnalyzer, build script, and IDEs.

Figure 2: Acyclic Module Relationships

Inverting Relationships

I start by refactoring the Bill class to an interface. (refactoring the Bill class to an interface). Then, to avoid split packages (where classes in the same package are bundled into separate modules), I move the Bill class into the same package as the Customer class. (same package as the Customer class.) The new class diagram is shown in Figure 3, along with the inverted module relationships shown at right.

Figure 3: Inverting Module Relationships

Eliminating Relationships

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 4.

Figure 4: Eliminating Relationships Between Modules

Wrapping Up

Identifying the modules is the first step in designing modular software systems. Shortly following, however, is managing the relationships between those modules. It’s these relationships between modules that I refer to as the joints of the system (Section 5.4) (the joints of the system), and it’s these areas of the system that demand the most nurturing to ensure a flexible system design. If care isn’t given to managing the relationships between modules, separating out the system into a set of modules isn’t going to provide significant advantages.