Please note: This documentation is very dated and should be treated as an old draft. Among the major updates as of 8/2005 are a jump from version .6 to .8, the renaming of staging to launcher.

Appendix A. Class Documentation Example and Template

Table of Contents

Facility (Example of Class Documentation)
What Is The Role?
Background Information
How Do I Use This?
Notes
What's Next?
Class Documentation Template
What Is The Role?
Background Information
How Do I Use This?
Notes
What's Next?

Facility (Example of Class Documentation)

What Is The Role?

The class Facility does not specify the interface of the Component that can be bound to it. Rather, it is simply a "marker" that Components can be bound to. Its role is binding a concrete Component, and providing access to it.

Facilities must be stored in the Pyre Inventory, as they use special features of the inventory to automatically bind components, and rely on support architecture to allow the user to override the default component to be bound.

Facilities can specify the default component to be bound to them. However, the client of a facility can override this default with another when they add one to their inventory. Further, the user can override that default from the top level of their script, the input file, or the command line, giving total flexibility.

Background Information

Facilities are a design pattern that enables the assembly of application components at run-time under user control. They are also named abstract application requirements. Components are named engines that satisfy the requirements. Clients or application classes that register that they need a particular service through a Facility can then interact with it according to the interface defined by the base of the Component's hierarchy matching that facility, considered an improvement of the Dependency Injection pattern. As with the Abstract Factory Pattern, this pattern of facilities and components promotes flexibility and reusability. Changing the actual component a client class uses doesn't require changing lots of C classes. You never need to hard wire the creation of a particular Component, you merely specify the abstract interface you expect through a Facility. All you have to do is pass in a different component name through the command line or XML, and you can override the actual component used.

How Do I Use This?

The real power of facilities is in the way they bind components given the name of the component. When a client first accesses a facility, the facility looks up its current component name, and transparently locates that component, and binds that it to itself. Thereafter, the user can access the features of the component through the facility name in their inventory.

This is done using a Facility's binder object. Different binders exist, but the default (and most widely used) type of binder is a script binder. Script binders do the following:

  1. Add a .py to the end of the component name
  2. Locate this file and import it
  3. Run the function in that file with the name of the current facility
  4. Bind what this function returns to the name of the facility

So for this process to work:

  1. Components must follow the naming standard that their file name is their class name.
  2. The file containing a Component class must also define a factory method with the name of the facility they want to bind to.
  3. The above factory method must return something meaningful

Facility offers dynamic control. The application script author provides a specification of application facilities as part of the Application definition and a component to be used as the default. The user can construct scripts that create alternative components that comply with the interface. The end user can configure the properties of the component and select which component is to be bound to a given facility.

Example A.1. Using Facility

Place an example of usage here!

Notes

The Facility system uses some of the bells and whistles of Python. An examination of the facility.Facility, facility.ScriptBinder and inventory.Trait classes are the ones to check out. It all relies on the special _set_ and _get_ methods in Python, and the Inventory being a class contained by the client component.

What's Next?

As an example of use, all GeoFramework codes inherit from the mpi.Application class. The two core facilities this Application provides are:JournalFacility and StagingFacility. The Journal facility is often modified by the individual applications to have more options.