Product Manager

Intent

Provide a framework to which to migrate unmanaged code. Help isolate clients from semantically different technologies. Control "unmanaged" code in a more managed fashion.

Problem

When building a business services framework in .NET, unless you are lucky, you will have to support some form of legacy services (e.g., DLLs, COM components , or any unmanaged code). It is strange having to refer to existing COM components as legacy. This is especially true because COM+ is still used with .NET. However, when dealing with unmanaged pieces of code, more care should be given. Whether it is an existing framework that you are migrating from or some other third-party application that you must integrate, this issue will be there. The trick is not figuring out the bridging technology upon which to call these legacy services but how to still provide a clean design. How does one design a set of managed .NET code when some of those services will be using unmanaged services? How does one isolate the client from knowing or caring that the services it requests are actually being handled by unmanaged code?

For starters, abstracting a calling client from the back-end business services will help. This will isolate the technical differences apparent only in the object bridging those services. Those who have used the Abstract Factory (GoF) or Strategy Pattern (GoF) should be very comfortable with this design approach. The Product Manager takes a step further by combining these patterns (so to speak) to form a design that will not only provide a standard contract upon which to call any back-end business service but also a level at which to isolate any code that will act as the "bridge" between managed and unmanaged code. The main controller of any services exposed by either managed or unmanaged code is the client of the Product Manager. This client takes the form of a fa §ade object in our example. Here, in the PaymentFacade, we control which product to instantiate and, using contracted methods on each product, ask the Product Manager to execute the requested service (Figure 4.5). The PaymentFacade object acts as the controller to the ProductManager. It interacts only with the "contracted" interface provided by this abstract base class. All of the common business implementation code for this design is located in the ProductManager base class. Any of the product-specific implementation code resides in the child classes of the Product Manager. Specifically, code to handle unmanaged versus managed semantics will be located in these child classes.

Figure 4.5. Product Manager implementation class diagram.

For example, let's say you wish to use XML schemas to describe each underlying packet that is passed from object to object. Each packet can also be passed into each product class. To provide such a feature, the designer may wish to store that schema in a database and load a packet from that schema. This is something you will see in Chapters 5 and 6. Retrieving that schema from the database will be done in the same exact way, no matter which product child class the controller is talking to. Hence, this is some of the common code we are referencing. All the controller needs to know is that a schema must be retrieved to hydrate a packet. The common code for retrieving this schema can be easily placed in an abstract parent ProductManager class. This is part of the code common to both unmanaged and managed code. Each product child object merely has to override methods that provide the base ProductManager class with the key to use to retrieve these schemas. All the database logic code still resides in the base class of the abstract ProductManager parent. Code specific to each product resides in the child product classes. This is object orientation 101. The difference is that all product-specific code to call unmanaged or unmanaged code remains in the child classes. The unmanaged product child class still benefits from any of this common code while still isolating the controller from any the differences through the use of the abstract parent.

For a product that must bridge older technologies such as a COM component, a product child class simply acts as the calling proxy to the underlying COM code. Using the model below, a CreditCard product acts as a normal client to the COM proxy code generated with the .NET/COM interoperability tools. Any COM-specific package or unpackaging occurs in this CreditCard product object. The CreditReport object is a standard common language runtime (CLR)-managed object. It can call other .NET help objects or be self-contained; it doesn't matter. The point is, neither the client nor even the controller class know or care that the back-end business functions running may be unmanaged code. This design also provides the unmanaged code access to common managed services. All in all, this pattern allows common .NET-friendly code to be shared in an abstract base class while isolating product-specific code in the derived product child classes.

Forces

Use the Product Manager Pattern when:

• Migrating old business services into a new technology platform.

• Bridging COM services from a .NET framework.

• Calling semantically different business services from a single interface, such as when using some form of "factory" pattern (e.g., Abstract Factory, Chained Service Factory, etc.).

• You want to leverage common code yet isolate technology-specific code from a common caller.

Structure

Figure 4.6. Product Manager generic class diagram.

Consequences

1. Isolate technology-specific implementation details . When building a framework that will employ calling unmanaged code, most likely there will be technology-specific nuances that will be included, for example, if the unmanaged code provides business services that would initially take too long to migrate fully over to the unmanaged world. The best solution would be to leverage off those services from the managed code. Typically, this is done with a bridge or proxy. Doing so may incorporate technology-specific details. However, that should not affect the "managed" architecture. If these unmanaged services were to be COM+ components, there may be some technology-specific attributes. These could include those that control transaction semantics or other COM+-specific attributes. Abstracting these details will help isolate calling clients and help decouple technology semantics within a framework aimed at creating managed-friendly semantics. The abstraction can be easily implemented using an interface implementation contract defined by the managed framework. Taking it a step further, an abstract class (ProductManager) can then be created to house common code that both managed and unmanaged products can share. All technology-specific code can then reside in the derived product classes, isolating the Controller Class (Fa §ade, in our example) from implementation details.

2. Provide a migration path to the new .NET framework . Fully reengineering legacy business services is a luxury most development teams do not have. Leveraging those business services as much as possible usually is the best answer. Providing a migration path to the "new managed world" then seems to be the best architectural solution. By isolating technology details as mentioned in the previous consequence, the Product Manager provides a migration path to this managed world. External legacy services can then be incorporated into the architecture by deriving themselves by an abstract parent class that may contain managed code common to all services. The derived product class can then simply act as a client to the external services, as any other client would act if it were not implemented using managed code. The designer can then slowly migrate functionality to this derived product class without affecting common code.

3. Leverages common managed code for managed calling proxies to unmanaged code (that's a mouthful) . Building a proxy to unmanaged code should also provide access to the common architecture code to which Product Manager objects have access. By implementing an abstract base class and placing all common managed code here (the ProductManager), the managed proxy to the unmanaged code will, through inheritance, still have access to it. This will promote leveraging as much of the new architecture as possible, even when calling legacy services such as COM components.

Participants

• Fa §ade (PaymentFacade) ” "Controller" class that acts as a client to the Product Manager. The fa §ade, in this case, speaks only "Product Manager language." This simply means only public interfaces exposed by the Product Manager and implemented by the specific products will be callable from the fa §ade.

• ProductManager (Same name as implementation) ” The abstract base class for each product object in the design. There can be a Product Manager for each category of product. This contains the standard interface "contract" (abstract functions) that must be implemented by each derived product class. It also contains all code common to all products in the class tree.

• ConcreteProduct (CreditReport) ” Contains all code for the business logic on the managed code side. This can be self-contained or it may aggregate other downstream business objects. It must implement all abstract members of the ProductManager to conform to the Product Manager's contract.

• ConcreteDelegate (CreditCard) ” Contains all code for the business logic on the unmanaged code side. This usually acts as the gateway to the external service or unmanaged code. It must also implement all abstract members of the ProductManager to conform to the Product Manager's contract.

• ManagedProduct (CreditCustomer) ” Optional helper class used to implement the managed business code fully.

• UnmanagedProduct (CreditCardCOMProxy) ” This represents either the proxy code or the third-party services. In the case of calling COM components, this is the generated proxy code (using tblimp.exe utility or VS.NET). Whether a generated proxy or third-party library, this is any unmanaged code that the architecture wishes to leverage.

Implementation

One of the benefits of implementing the Product Manager pattern is its general applicability. Like similar patterns, such as Abstract Factory and Factory Method, this pattern can be applied to many scenarios through the architecture. There can be several difference Product Manager abstract classes. If the designer so chooses, there can be a single common Product Manager class from which to derive all product classes. The ProductManager class can be driven directly from a GUI-based client or from another business object, such as a controller or fa §ade. In our example, we use a Fa §ade object to manage the ProductManager abstract class. The PaymentFacade participates in the creation of the appropriate Product class (CreditCard and CreditReport, both derived from ProductManager). Because each Product class derives and implements the "contract" for the Product Manager, the fa §ade calls only those interfaces exposed by the ProductManager abstract class (e.g., Execute()), as shown in Listing 4.4.

Listing 4.4 Product Manager Factory Method implementation.

 public Packet Execute(Packet oPacket) {       ProductManager oProdMan;     switch (oPacket.Type)       {           case CREDIT_CARD_TYPE:               oProdMan = (ProductManager) new CreditCard(oPacket);               break;           case PMConstants.CHECK_TYPE:               oProdMan = (ProductManager) new CreditReport(oPacket);               break;           default:               oProdMan = null;               break;       }       return oProdMan.Execute();     } 

In essence, this code is acting as another factory on each product. In addition, it is calling the established "strategy" style interface to invoke the action on the product (see the Strategy Pattern section from the GoF). Once invoked, the product is able to disseminate the action by either further delegating the call or by handling the invoked business function immediately. In the "eyes" of the Execute() statement above, only the signature of the Product Manager is known. The fact that CreditCard is delegating to the proxy COM wrapper is unknown. Both CreditCard (forwards to unmanaged code) and CreditReport (forwards to managed code) look the same to the fa §ade in this scenario. When Execute() is finally called on the CreditReport object, it looks something like as shown in Listing 4.5.

Listing 4.5 Product Manager delegation implementation.

 public override Packet Execute()     {           Packet oPacketOut;           switch (Packet.Action)           {                 case AUTHORIZE_ACTION:                       oPacketOut = Authorize();                       break;                 case CAPTURE_ACTION:                       oPacketOut = Capture();                       break;                 case GET_PRODUCT_SCHEMA_ACTION:                       oPacketOut = GetProductSchema();                       break;                 default:                       oPacketOut = null;                       break;           }           return oPacketOut; } 

Here you see that, like the Fa §ade object, the Execute method of the CreditCard product simply determines (by using another property of the packet) which business function this should delegate to. If the packet requests an "authorization," this will call a local method, Authorize(). Authorize() will delegate to a proxy object that was generated via tblimp.exe. The authorization will actually occur in unmanaged code, and the CreditCard product object is simply acting as a client to that code. This not only provides a migration path from COM services already written, but it also isolates the controller or Fa §ade object from knowing when this is handled in unmanaged or managed code. The Authorize() method looks something like this (Listing 4.6):

Listing 4.6 Sample Product Manager worker implementation.

 public Packet Authorize()     {           Packet oPacketOut = new Packet();           // COM Proxy object           COMAuthorizer oAuthorizer = new COMAuthorizer();           // .. build COMPacket from Packet           oAuthorizer.DoOp(COMPacket, null);           // .. build Packet from returned COMPacket           return oPacketOut;     } 

Implementing the other product object, CreditReport in our example, is exactly the same. The difference is that CreditReport contains all managed code. CreditReport and CreditCard can each leverage common code contained in the abstract ProductManager. However, both can still contain technology-specific implementation details hidden from the outside world.

Related Patterns

• Factory Method (GoF)

• Chained Service Factory (Thilmany)

• Unchained Service Factory (Thilmany)

• Virtual Proxy (Grand)

• Abstract Factory (GoF)

• Strategy (GoF)

Challenge 4.2

What other kind of products could utilize the Product Manager besides what is shown here?

See Chapter 6 on Product X to see (pages 296 “303).