Basic Hierarchy Example

This section describes the elements of the generated and required handcrafted class hierarchy for a basic entity class named MyClass, which does not make use of inheritance or code packages.

The UML representation of the generated Java classes of the entity class MyClass would show the following four classes:

• <PackageName>.intf.MyClass
• <PackageName>.base.MyClass
  • Implements, or realizes, the intf class.
  • It is the super class.
• <PackageName>.impl.MyClass
  • A subclass of the base class.
  • Contains any required (non-generated) handcrafted methods.
• <PackageName>.fact.MyClassFactory
  • A subclass of the impl class.
  • Returns an instance of the intf class.

Thus, there are four Java classes corresponding to the entity class in the UML model. Three of the classes have the same name as the class in the model, the fourth has the same name with the word Factory appended.

A further description of the classes are as follows:

1. <ProjectName>.intf.MyClass

   This is a generated Java interface class containing all the public methods for the class.

   The other classes in the hierarchy - either generated or handcrafted - will be required to provide implementations for these methods.

2. <ProjectName>.base.MyClass

   This is a generated abstract Java class which implements the interface contained in the intf version of the file. It contains the following:

   • The implementations of data access methods (i.e. stereotyped methods of entity classes) and connector methods.
   • Abstract method declarations for exit point methods.

     This is to ensure that the developer is forced to provide implementations for the exit points.

   • Abstract method declarations for methods declared protected in the model.

     This is to ensure that the developer is forced to provide implementations for these methods without having to expose them in the interface (intf layer) for the class.

3. <ProjectName>.impl.MyClass

   This class is supplied by the developer and always inherits from the corresponding base version.

   It should be declared abstract to ensure that the class cannot be instantiated directly - the class should only be instantiated using the factory mechanism. (See below.)

   In this class the developer must provide implementations for all the methods declared in the class in the model for which an implementation was not produced by the generator.

   While this class inherits from a generated class, it contains only handcrafted code and no generated code. This is so that there is no risk of developer code overwriting generated code, or generated code overwriting developer code.

4. <ProjectName>.fact.MyClassFactory

   This is a generated Java class containing one static method: newInstance(). This method creates instances of the class and is the only means by which entity, facade and process classes should be instantiated.

   Since a factory creates all instances of objects, it can also be used to:

   • transparently create and return a customized version of the class requested. See Replacing the Superclass. Pre-existing code which used the original version of the class does not need to be changed.
   • transparently create and return a proxy class of the requested class. The proxy class wraps the requested class (using the Java 1.3 Dynamic Proxy mechanism) and captures detailed tracing information for all interactions with the class.

The following code sample shows how an instance of MyClass is created. Note that the return type of MyClassFactory. newInstance is sample.intf.MyClass.

// Use the factory to create an instance:
sample.intf.MyClass myObject =
        sample.fact.MyClassFactory.newInstance();