Source Code Packaging
The Apache MyFaces project provides a number of different "artefacts":
MyFaces Core (JSF specification implementation)
- Trinidad (currently under development)
The Shared Module
MyFaces Core and Tomahawk have quite a lot of "utility" classes in common. It would not be good software engineering for each project to maintain its own copy of these classes, as bugfixes and enhancements would need to be applied separately to each. The "shared" code is therefore stored in the source code repository as a separate "module".
This module can be found in svn at: * http://svn.apache.org/repos/asf/myfaces/shared/
In versions of MyFaces-Core/Tomahawk up to 1.1.1, the shared code was built as a a separate jarfile that must be present in the classpath in order to use either MyFaces Core or Tomahawk. Unfortunately this had a number of drawbacks, the most serious being that only versions of Core and Tomahawk that use the same version of the shared library can be deployed together. If a user wants to upgrade to a newer release of Tomahawk to fix a bug, then they must upgrade to the matching version of the shared lib - which then means upgrading to the matching version of Core too. It also meant that the MyFaces project effectively had to release Core and Tomahawk at the same time (ie tie their release cycles together).
To resolve this, releases of MyFaces-Core and Tomahawk 1.1.2 or later pre-process the code in the shared module at compile time; the package "org.apache.myfaces.shared" becomes either "org.apache.myfaces.shared_impl" (for Core) or "org.apache.myfaces.shared_tomahawk". The resulting classes are then included directly into the core or tomahawk jarfile, removing the need for an extra "shared" jarfile. This allows versions of Core and Tomahawk to be mixed without conflicts over shared code versions, and allows different release cycles for Core and Tomahawk.
The shared module has its own version numbers; see the version element in the pom.xml file for the shared module. Note that the shared module version numbers are independent of the version numbers of Core or Tomahawk releases (though of course a new "release" of the shared module only occurs when a release of a project that depends on it is performed.
Versions of Core and Tomahawk then declare a dependency on a specific version of the shared module. See the pom.xml file for the relevant Core or Tomahawk release to see what version of the shared library it uses.
In the future, other MyFaces projects (eg Tobago/Trinidad) might also depend on the "shared" module if there is sufficient common code to make this worthwhile.
Core package structure
The JSF specification defines exactly what classes are permitted within the javax.faces package, and exactly what methods and members those classes have. It is explicitly forbidden for any other classes, methods or members to be present (the code will not pass the JSF spec tests).
The core code is therefore split into two parts: an "api" module that complies with the above requirement, and an "impl" module that provides implementation classes that "support" the api implementation. The impl code provides much of the actual behaviour of the MyFaces core, but is not expected to be directly accessed by user code (at least not code that is intended to be portable to other JSF implementations).
This split does lead to some odd code in the api module in some cases.