Title: The Encapsulate Context Pattern

Encapsulate Context was born after a query to accu-general in Summer 2002. I don't think I was looking to write a pattern but I'm glad I did - in retrospect I wish I had begun writing patterns earlier. However, writing patterns is hard work and time consuming. Between the first draft and the version you are about to read 18 months elapsed. The paper may bear my name but it wouldn't be the paper it is without the help of many others.

The version here hasn't changed in several months and is the same as that printed in the EuroPLoP 2003 conference proceedings. This doesn't mean it won't change again, to some degree patterns are living entities that change as people use them and gain experience. So, I wouldn't be surprised if the pattern appears again, elsewhere, with further revisions.

A system contains data, which must be generally available to divergent parts of the system, but we wish to avoid using long parameter lists to functions or global data; therefore, we place the necessary data in a Context container and pass this object from function to function.

Encapsulate Context is principally written for software developers designing and writing programs. The pattern was originally written for C++ developers, however examples have been reported from other languages such as Java and Smalltalk. It is believed that users of any language will find the pattern useful, although C++ developers may find the pattern of particular interest.

By exploring the pattern in depth this paper offers a rigorous explanation of where the pattern occurs, the forces and the consequences of using the pattern. For reference purposes a summary section has been included at the end of the paper. Experienced developers may prefer to read the summary first before reading the entire paper.

In traditional structured programming, global data is minimised by use of function call parameters. This tradition has continued, with some modifications in object-oriented programming. For example:

void ProcessMarketTrade(MarketMessage& msg,
                     MarketDataStore& store) {
  if(msg.Trade() == Sell)
    store.Sell(msg.Commodity(),
               msg.Price(), msg.Quantity());
  else
    store.Buy(msg.Commodity(),
              msg.Price(), msg.Quantity());
} // ProcessMarketTrade

We now decide that any trade which results in a negative quantity should result in an error message, hence the function Sell must have access to the log manager, consequently a handle must be passed down. The code becomes:

void ProcessMarketTrade(MarketMessage& msg,
                       MarketDataStore& store,
                       LogManager* log) {
  if(msg.Trade() == Sell)
    store.Sell(msg.Commodity(), msg.Price(),
               msg.Quantity(), log);
  ... as before ...

Such changes have a habit of reoccurring, so, when we add a transaction history the code changes again:

void ProcessMarketTrade(MarketMessage& msg,
                MarketDataStore& store,
                LogManager* log,
                TransactionHistory& history) {
  if(msg.Trade() == Sell)
    store.Sell(msg.Commodity(), msg.Price(),
               msg.Quantity(), log, history);
  ... and so on ...

Several problems are clearly apparent. First the parameter list is growing with a negative effect on comprehensibility, even though the additional code is trivial it increases the bulk. Secondly, we are breaking encapsulation. Initially Sell was an encapsulated function, by adding more and more parameters its inner workings are being exposed.

More ominously, we have a ripple effect running through interface and implementation code. The function that calls ProcessMarketTrade must itself have access to LogManager and TransactionHistory, and in turn, the function that calls that function, and so on. Even though these functions will only act as pass-throughs for the handles they are affected.

Less obvious is the capacity for redundant code to enter the system. If at some future date we dispense with the transaction history then removal impacts at least three different functions. To be sure, the temptation would be to disable the code while leaving it in place, hence we simply make it an anonymous parameter in Sell:

void MarketStore::Sell(Commodity& c,
                       Price& p,
                       Quantity& q,
                       LogManager* log,
                       TransactionHistory&) {
  ....

In choosing not to delete the history in full we are storing up complications for future refactorings, we are also half-way to implementing the Poltergeist anti-pattern (Brown1998).

These problems are exacerbated when a dependency inversion design is adopted. We may decide to recast our market message processing as a Command pattern (Gamma1994):

class MarketMessageCommand {
public:
  virtual void Action(MarketDataStore&,
                      LogManager*) = 0;
  ....
};
class Buy : public MarketMessageCommand {
public:
  virtual void Action(MarketDataStore&,
                      LogManager*);
  ....
};
class Sell : public MarketMessageCommand {
public:
  virtual void Action(MarketDataStore&,
                      LogManager*);
  ....
};

To ensure substitutability each MarketMessageCommand must implement Action with the same signature as the abstract base class. Consequently commands such as Buy are complicated with parameters which are unused. Worse, the potential for ripple effects is magnified across all objects in the hierarchy. If the exchange introduces a programmatic way of signalling transition point in the trading day with an enumeration such as:

enum TradingDay { 
  Closed, PreOpen, Open, Settlement, Suspended
};

A new market message is needed to handle this, but so too is a state variable:

class TradingDayChange : public MarketMessageCommand {
public:
  virtual void Action(MarketDataStore&,
                      LogManager*,
                      TradingDay& activity);
  ....
};

Since our new message can change the state activity a new parameter is needed, to maintain a common signature this parameter must be added to MarketMessageCommand and all derived classes. Again, we are increasing the length of the parameter list, introducing a ripple effect and adding complexity. Our main loop may look like:

int main() {
  MarketDataStore marketData;
  LogManager *log(LogFactory());
  TradingDay exchangeStatus(Closed):
  MessageSource source;
  while(true) {
    auto_ptr<MarketMessageCommand>
                      w(source.NextMessage());
    w->Action(marketData, log, exchangeStatus);
  }
  delete log;
  return 0;
}

Faced with the problem of adding yet more parameters we may be tempted to consider global variables. After all, an exchange is open or closed, there is only one instance of such a flag surely? A tempting solution, the exchange status is a simple variable, initialisation is not a significant problem, and being stack based a memory leak is a non-issue.

However, for LogManager a global variable is decidedly less tempting. The example above strictly controls the use of log through scope and parameter passing, were the same variable global it could potentially be accessed before creation, e.g. the MarketDataStore constructor may choose to log a message.

We would then be forced into the position of trying to enforce creation before use. This is known to be problematic and the best known solution (access through a function) suffers from known issues in multi-threaded systems. Further, the same problems occur in reverse when cleanly ending the program.

While we may be able to survive one or two such global variables we quickly find the number increasing, first the exchange status, then the log manager, what of our transaction history? Have we loaded any DLL plug-ins? Better have a global list of their handles. As we add more global variables it becomes harder to reason about the initialisation sequence for each - particularly important when one makes use of another. It is also more difficult to reason about the internal state of the program because it is dispersed with no central point of reference.

Even with the best will in the world the old issues of globals still exist. Judicious use of namespaces, and careful coding may afford us the luxury of a few globals but the old issues have not gone away, merely repositioned or hidden for a while.

The solutions so far suggested do nothing to improve either the testability of our system or the transfer of components to follow-on projects. Suppose we wish to use our MarketMessageCommand in a market simulator. Long parameter lists, and global variables force us to implement plumbing around the hierarchy so we can use the commands.

Likewise, if we wish to write a test harness for our hierarchy, or force test data through the system we must implement the necessary plumbing to support the classes.

Each additional parameter or global variables makes the classes and methods more specific and less of a commodity. Without such specifics, the MarketMessageCommand hierarchy implements generic, run-time polymorphic handling of messages. Longer parameter lists increase coupling, tying classes closer to the environment, shorter interfaces are more loosely coupled and result in a more general the class.

The nub of the problem is the ever-expanding parameter list. At first this appears simply unsightly, however, as we can see, the need pass more and more parameters is a real issue.

Access to common data is important to many systems. Many systems contain data which must be generally available to divergent parts of the system, e.g. configuration data, run-time handles and in-memory application data.

However, we wish to avoid using global data - such data is normally regarded as poor engineering practice. Traditionally the problem is addressed by passing such data as function call parameters but over time parameter list become longer. Long parameter lists themselves have an adverse effect on maintainability and on object substitutability.

While access to such data is a common requirement neither of the two common techniques are without problems. Access to the data is not as trivial as it first appears, and as any system grows the drawbacks of each solution become greater.

There are several forces that any solution to this problem must accommodate for it to be widely applicable.

Provide a Context container that collects data together and encapsulates common data used throughout the system.

For example:

class Context { LogManager* log_; ComandLineOptions cmdOpts_; ApplicationData* store_; .... };

Rather than supply multiple parameters, we supply a Context object. The object acts as a container for program state data, a central repository for widely used data within the system. The Context object provides few, if any, functions itself. The object is passed, or more likely a reference is passed, to functions when they are called - utilising the "parameterize from above" paradigm.

There are typically three types of data found in a context class:

The example given here uses one context class for simplicity. While the simplicity of a single context has a lot to recommend it, without careful attention the class may become a kitchen-sink, overwhelmed with any, and all, data in a system. When this happens we start to see the emergence of a Blob anti-pattern (Brown1998).

To counter the drift towards Blob we can split the class into two or more discrete classes, e.g. one for system data and handles with a second for application data (see Figure 1).

Figure 1. Solution places context data in a single container

Specifically, we can distinguish three types of split:

Such splits will mitigate the Blob tendencies but also detract from the pattern simplicity. Splitting the Context class should also help improve compile times, since we can assume that although some functions will need to be passed all the fragments of the original context, many will require fewer fragments thus reducing dependencies.

However, while it may be desirable to split the Context class for a variety of reasons this can be taken too far. The use of many fine-grained Context objects may return us over long parameter lists.

Thus, any implementation of Encapsulate Context pattern should consider the following issues:

These issues must be addressed together as the answers to each question influences the others.

Applying this solution to the example given at the start of this paper we get:

// MarketContext.hpp
class LogManager;
class CommandLineOptions;
class MarketDataStore;
class MarketContext {
  LogManager* log_;
  CommandLineOptions opts_;
  MarketDataStore* marketData_;
public:
  MarketContext(LogManager*,
                CommandLineOptions&,
                MarketDataStore*);
  LogManager* Log();
  MarketDataStore* MarketData();
  CommandLineOptions& CmdOptions()
                                const;
};

With this context class the presence or absence, of a TransactionLog is abstracted to a detail about MarketContext.

The class should take a minimal role in the lifetime of enclosed classes, it is better to present these as ready constructed to the class. This removes life-cycle issues from the domain of the context class, and, because enclosed classes are often just references or pointers, the .hpp interface file should only need forward declarations thereby reducing potential ripple effect. (The decision on whether to use pointers or references to object is outside the scope of this paper.)

Continuing this example the body of the program is refactored:

class MarketMessageCommand {
public:
  virtual void Action(MarketContext&) = 0;
  ....
};
int main() {
  LogManager* log(LogFactory());
  CmdLineOptions options(argc, argv);
  MarketDataStore marketData;
  MarketContext context(log, options,
                        &marketData);
  MessageSource source;
  while(true) {
    auto_ptr<MarketMessageCommand>
                     w(source.NextMessage());
    w->Action(context);
  }
  return 0;
}

The context provides access to data which otherwise may be made Singleton, global or both, for example the LogManager.

As a result of the pattern, several of the forces detailed above are resolved or balanced:

In addition there are other beneficial consequences:

However, there are several less desirable consequences:

Many of the issues raised in the discussion section suggest further variations of this pattern beyond those outlined already. It is also possible to see how, taken together, Arguments Object, Introduce Parameter Object, Singleton, Open Arguments and Encapsulate Context may represent part of an entire pattern language. We may tentatively label this pattern language Context Objects.

For example, Singleton could be redefined as an example of Encapsulate Context where there is only one instance of the Context Object, and the object is accessed via a global variable instead of via parameter passing.

There are four groupings within which to consider variation within the Context Objects pattern language:

The creation of a Context Objects pattern language is beyond the scope of this paper. However, it is clear that such a language could unify existing patterns and probably help identify more patterns.

The author looks forward to hearing about such a project and is more than willing to participate in such an endeavour.

The examples presented are given in C++ although it is expected that the pattern is generally applicable to all languages. The author looks forward to hearing of implementations in Java and C# especially

In any non-trivial system there will be a number of data elements that are widely used throughout the program, e.g. log manager and the application data model. Typically these will be classes in their own right and accessed through handles (references or pointers.) Since global data is regarded as poor practice it is likely that these handles will be passed by way of function call parameters. However, this technique can soon lead to long parameter lists which are not only difficult to understand but tend to make the program more fragile.

Therefore, we create a context class that encapsulates these data elements, and pass a handle to this object to the diverse functions.

While similar techniques have been suggested by others (e.g. Nobel1997, Fowler2000) this pattern discusses the forces and consequences when applied system wide. This can bring considerable benefits to a design, but if used recklessly can result in a number of known anti-patterns.

Rather than use a single context class it may be appropriate to design a system with several. These are divided along temporal, horizontal or vertical lines to ensure that each is consistent and promotes good design.

This pattern was the result of a conversation on the accu-general mailing list entitled: "overload 49 and state" with significant contributions from Kevlin Henney and Josh Walker, running from 18th June 2002. I am grateful to Kevlin for acting as initial pattern shepherd and Josh for reviewing the results and providing an additional example. The paper was further shepherded by Frank Buschmann in April 2003 for submission to EuroPlop. Again, I am most grateful to Frank for his time and interest.

In addition, I am most grateful to all in Workshop D at EuroPLoP 2003 for their many varied and useful comments concerning the pattern, their support and their suggestions for improvement.