Each subsystem that is used by other subsystems provide two ways for other subsystems to use them:
- The Facade class
- The use of Facade class is not wide spread in ArgoUML. This is because ArgoUML is traditionally built as a whole and no subsystems were clearly defined.
- A Facade class provides the most common functions other subsystems want to do when using that subsystem to reduce the need of having to use anything else but the Facade class. The Facade class should be very much more stable than the subsystem itself. Methods in the Facade should change very slowly and only be removed after several months (and one stable release) of deprecation.
- The Facade class is documented in the class file itself (as javadoc) and the more complex picture (if needed) is documented in the wiki page of the subsystem.
- An API with calls to public or protected methods.
Traditionally, the subsystems in ArgoUML communicate through public methods and public variables and the subsystems, as defined by the responsibilities, are spread over several packages setting aside the Java visibility rules. For this reason it is not well-known or documented what public methods form part of a subsystem's API and what public methods are internal to a subsystem. For this reason, always exercise extreme caution when changing the signature of a public method. (See Section 7.2, “When Committing to the Repository”.) CategoryFix: Resolve this reference.
- In order to improve things, make it very clear when encountering and understanding the purpose of a public method or class, if it is part of the subsystem's API or not (by improving the javadoc for that method or class).
- Try to help in moving the public API methods and classes from wherever, to the subsystem's directory/package using the proper deprecation procedure.
- In order not to worsen things, always add new API classes and methods in the subsystem's directory/package.
- This way of communicating is still to be used when it is not convenient to use the Facade for a specific use of that subsystem.
Notice that the Facade is normally a part of the API or a simplified version of the API.
For each subsystem X in ArgoUML that uses the subsystem Y, the designer of the subsystem X must decide if he wants to use the API of Y when using the subsystem Y (putting a set of import org.argouml.Y.internals.blabla.*; statements in each file of subsystem X that uses subsystem Y) or use the Facade class of subsystem Y (putting only one import org.argouml.Y.YFacade; in each file in the subsystem X that uses subsystem Y).
The API solution makes subsystem X depend on subsystem Y meaning that when we change the API of the subsystem Y we must also change subsystem X. The facade calls solution doesn't make the subsystem X depend on the API of subsystem Y but just the Facade of subsystem Y.
The choice between the usage of the API or the Facade shall be stated in the Cookbook's description of subsystem X in the list of used subsystems.