Composite pattern

Introduction

Compose objects into tree structures to represent part-whole hierarchies. Composite lets clients treat individual objects and compositions of objects uniformly.

Participants:

Component

declares the interface for objects in the composition.
implements default behavior for the interface common to all classes, as appropriate.
declares an interface for accessing and managing its child components.
(optional) defines an interface for accessing a components parent in the recursive structure, and implements it if that's appropriate.
this participant can not be an interface.

Leaf

represents leaf objects in the composition. A leaf has no children.
defines behavior for primitive objects in the composition.
this participant can not be read-only.
this participant can not be an interface.

If the "Add Composite operations to Component" option is checked, then the methods for adding/removing leafs will be defined in the Component interface. This gives you transparency, because you can treat all components uniformly.It costs you safety, because clients may try to do meaningless things like add and remove objects from leaves.

Composite

defines behavior for components having children.
stores child component.
implements child-related operations in the Component interface.
this participant can not be read-only.
this participant can not be an interface.

In the "Attribute vector" field you can specify the name of a Composite's Vector attribute to keep references to Component objects the Composite contains.

In the "getEnumeration method" you can specify the name of a Composite's method returning an enumeration of Component objects the Composite contains.

The "Copy documentation" option controls whether to copy JavaDoc comments from methods in interfaces participating in the pattern to the stubs of these methods made by the pattern in classes implementing such interfaces.

The "Create pattern links" option controls whether to generate additional links which can be used by this pattern later to determine classes and interfaces participating in the pattern. That means that if you selected this option and used the pattern to create a set of classes and interfaces, the pattern invoked for some participant later (via the popup menu item "Choose Pattern...") will automatically find (if it is possible) all other participants and fill in participant fields with their names.

Also, if you applied the pattern with this option on and invoked the pattern via the popup menu item "Choose Pattern..." for some participant later, the pattern will have additional field called "Use selected class as", containing possible roles for the selected element.

This option is very useful when you are planning to change something in the classes/interfaces participating in the pattern. For example, if this option is on and after creation of the classes and interfaces you added several methods to certain interface-participant (and this change must be reflected somehow in other participants), all you have to do is to select this changed interface, invoke the "Choose Pattern..." dialog for this element and select the original pattern. After that the pattern will determine other participants and you will only have to press "Finish". The pattern will modify all other classes and interfaces accordingly to your changes.

Applicability

Use the Composite when

you want to represent part-whole hierarchies of objects.
you want clients to be able to ignore the difference between compositions of objects and individual objects. Clients will treat all objects in the composite structure uniformly.