Z2 Java components intro » History » Revision 10
Revision 9 (Henning Blohm, 21.09.2012 11:17) → Revision 10/13 (Henning Blohm, 21.09.2012 11:21)
h1. An introduction to Z2 Java components
The one, probably most essential component type, is that of Java components. Per se, modules in Z2 are not "Java modules" (unlike in OSGi for example). From its underlying model, Java code is handled like any other component resource. There is however important conventions that do make Java components special.
Java components play an important role in Z2 modularization, as re-use of code is one of the driving motivations for modularization. Z2 offers a moderately sophisticated way of re-use via inclusion or class loading delegation that is still simple enough that typical Java and Java EE approaches still work without painful adaptations and that you can - in many cases - ignore the more complex, problematic situations.
h2. Conventions
A majority of component types imply the presence of some implementation code or "class path stored" resources: A Web application may require some Servlet implementation or a Tag Library. A Datasource names a JDBC implementation class, a Spring application context needs to find Bean implementation types.
Therefore Z2 implements a module level convention (and this is actually the only place that the module granularity matters) that is used by component types to identify "the default source of implementation code":
bq. Given a component *<module>/<name>*, when requiring to retrieve implementation types, look for the Java component *<module>/java*.
That convention is implemented in "JavaComponentUtil":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/components/java/JavaComponentUtil.html and used all over the place.
Part of that convention is that components in the module use the implementation or "private" loader of the module's Java component to look for types or class path resources. That is, components in the module are privileged to refer to implementation code that may not be visible to components of other modules (see also "IJavaComponent":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/components/java/IJavaComponent.html).
This technically slim convention makes modules a place to implement encapsulation and information hiding.
h2. API and Implementation
Z2 supports a separation of *API* definitions, i.e. Java types or class path resources that may be referenced from other Java components, and *implementation* types or class path resources that are hidden from other Java components. This is reflected in the folder structure of Java components. You do however have the choice of ignoring this separation by using an "API vs. Implementation"-indifferent folder structure that behaves as if everything is an API.
Before explaining the details of the folder structure, here is some rational:
Ideally modules implement some coherent set of functions hat are exposed via interfaces that hide implementation details. Within the module implementation types may do however seen fit best to implement the promised interfaces. By hiding the implementation from direct access by other modules, the module contract is required to be restricted to the exposed interfaces and you reserve the freedom to modify the implementation without breaking your module's contract.
Another aspect that is in reality at least as important is that APIs effectively (in reality) imply a transitive closure that spans everything needed by the API. Without a clean separation of API and implementation, you do effectively expose also 3rd party implementations used in your implementation which can easily become a major headache due to version conflicts and accidental re-use by users of your API.
There are reasons to not separate API and implementation in a module however. For example:
* You have an extremely pure or small setup in which there is no possibility of version conflicts or accidental re-use
* You separate on the module level, i.e. some modules are pure API modules, while other modules are pure implementation modules, and you do not care about hiding
We do generally recommend to split API from implementation and use the corresponding folder structure, even some folders stay empty.
On top of API and implementation, Z2 Java components support test code. Test code is part of the component's implementation code if and only if Z2 runs in development mode (i.e. the system property *com.zfabrik.mode* is set to development)
h2. Java component folder structure
Typically, Java components are defined in a folder *<module name>/java*. In the rare case that a Java component does not provide definitions on its own, a Java component can be declared as *<module name>/java.properties*. The folder structure of Java components assigns meaning to the following folders:
|z.properties|The component descriptor. Typically this looks like
com.zfabrik.component.type=com.zfabrik.java
java.publicReferences=<java component 1>, <java component 2>,...
java.privateReferences=<java component n>, <java component n+1>,... |
|src.api|Public type definitions that will be compiled and exposed so that they are visible by other Java components. See PUBREFS.|
|bin.api/lib|JAR libraries to be added to the public types of the Java Component.|
|bin.api/classes|Pre-compiled Java code, i.e. .class files and other resources to be added to the public types of the Java Component.|
|src| Equivalent to src.api and may be combined |
|bin/lib| Equivalent to bin.api/lib and may be combined |
|bin/classes| Equivalent to bin.api/classes and may be combined |
|src.impl|Type definitions that will be compiled and made available for use within the project (see above) but will not be exposed to other Java components. See PRIREFS.|
|bin.impl/lib|JAR libraries to be added to the private types of the Java Component.|
|bin.impl/classes|Pre-compiled Java code, i.e. .class files and other resources to be added to the private types of the Java Component.|
|src.test|Type definitions that will be compiled and made available for use just like the types defined in src.impl. In contrast to src.impl, the source files in src.test will be ignored unless the runtime runs in development mode, that is the system property "Foundation.MODE":http://www.z2-environment.net/javadoc/com.zfabrik.core.api!2Fjava/api/com/zfabrik/util/runtime/Foundation.html#MODE is set to "development".|
|bin.test/lib|JAR libraries to be added to the private types of the Java Component iff running in development mode.|
|bin.test/classes|Pre-compiled Java code, i.e. .class files and other resources to be added to the private types of the Java Component iff running in development mode.|
Java components may "include" components of type *com.zfabrik.files* and *com.zfabrik.java*. This can be useful for libraries that cannot be shared by just re-using the classes but instead require to be used within the using component's context, e.g. to load classes by name that would not be within the library's scope. This is true for older versions of the Spring framework for example.
Files components may be included as API or impl provisioning depending on the reference used. The included source files or pre-compiled binaries are expected to comply to the following folder structure:
|src| Source files that require compilation before execution.|
|bin/lib|JAR libraries|
|bin/classes|Pre-compiled Java code, i.e. .class files and other resources |
h2. Referencing and including Java resources from other modules
Via the following component properties, re-use of Java definitions from other Java components can be controlled:
|java.publicReferences|Points to other another java components component whose public types will be shared with this one (and maybe others).
Everything referenced as public reference will be visible to the public interface of the referencing component as well as to all referencing the referencing component. In other words: References are transitive. In particular, anything required to compile the public types of a Java component must be referenced via this reference property.
Components may be specified as a comma-separated list. Component names that have no "/" will be defaulted by appending "/java". |
|java.publicIncludes|Points to com.zfabrik.files or com.zfabrik.java components that must have a bin (or alternatively a bin.api, for Java components) folder that will be included into this java component's public java resources. The component may also have a src (or alternatively src.api, for Java components) folder that will be copied before compilation into src.api. |
|java.privateReferences|Points to other another java components component whose public types will be shared with this one (and maybe others) Nothing referenced as private reference will be automatically exposed to the public interface of the referencing component nor to other components. Anything needed to compile the private types of a Java component, must be referenced as a public reference, be part of the public types of that component, or be referenced via this reference property.
In other words: The private types automatically see the public types and transitively anything referenced publicly as described above. In addition, to use more types in the "private implementation section" of a Java component, types that will not be exposed to referencing components, use this reference property.
Components may be specified as a comma-separated list. Component names that have no "/" will be defaulted by appending "/java". |
|java.privateIncludes|Points to com.zfabrik.files or com.zfabrik.java components that must have a bin (or alternatively a bin.api, for Java components) folder that will be included into this java component's private java resources. The component may also have a src (or alternatively src.api, for Java components) folder that will be copied before compilation into src.impl. |
|java.testReferences|Points to another java component whose public types will be shared with this one (and maybe others) if the execution mode, as defined by the system property Foundation.MODE is set to "development". Test references extend the private references. In conjunction with the tests source folder this allows to add test code and corresponding dependencies that will be ignored by the runtime unless running in development mode. |
|java.testIncludes|Points to com.zfabrik.files or com.zfabrik.java components that must have a bin (or alternatively a bin.api, for Java components) folder that will be included into this java component's test java resources. The component may also have a src (or alternatively src.api, for Java components) folder that will be copied before compilation into src.test. |
The following picture illustrates the relationships established via references and includes:
!java.png!
h2. Classloading in Z2
h2. Java component configuration
Configuration properties of Java components:
|_. Name |_. Values |
|com.zfabrik.component.type|com.zfabrik.java|
|java.publicReferences|Points to another java component whose public types will be shared with this one (and maybe others). Everything referenced as public reference will be visible to the public interface of the referencing component as well as to all referencing the referencing component. In other words: References are transitive. In particular, anything required to compile the public types of a Java component must be referenced via this reference property. Components may be specified as a comma-separated list. Component names that have no "/" will be defaulted by appending "/java".|
|java.publicIncludes|Points to com.zfabrik.files or com.zfabrik.java components that must have a bin (or alternatively a bin.api, for Java components) folder that will be included into this java component's public java resources. The component may also have a src (or alternatively src.api, for Java components) folder that will be copied before compilation into src.api.|
|java.privateReferences|Points to another java component whose public types will be shared with this one (and maybe others) Nothing referenced as private reference will be automatically exposed to the public interface of the referencing component nor to other components. Anything needed to compile the private types of a Java component, must be referenced as a public reference, be part of the public types of that component, or be referenced via this reference property. In other words: The private types automatically see the public types and transitively anything referenced publicly as described above. In addition, to use more types in the "private implementation section" of a Java component, types that will not be exposed to referencing components, use this reference property. Components may be specified as a comma-separated list. Component names that have no "/" will be defaulted by appending "/java".|
|java.privateIncludes|Points to com.zfabrik.files or com.zfabrik.java components that must have a bin (or alternatively a bin.api, for Java components) folder that will be included into this java component's private java resources. The component may also have a src (or alternatively src.api, for Java components) folder that will be copied before compilation into src.impl.|
|java.testReferences|Points to another java component whose public types will be shared with this one (and maybe others) if the execution mode, as defined by the system property (see Foundation.MODE} is set to development. Test references extend the private references. In conjunction with the tests source folder this allows to add test code and corresponding dependencies that will be ignored by the runtime unless running in development mode.|
|java.testIncludes|Points to com.zfabrik.files or com.zfabrik.java components that must have a bin (or alternatively a bin.api, for Java components) folder that will be included into this java component's test java resources. The component may also have a src (or alternatively src.api, for Java components) folder that will be copied before compilation into src.test.|
|java.compile.order|The compile order must be defined in java components that also contain non-java sources - e.g. scala. This property can be omitted for pure java components, otherwise one has to define all compilers in the right order - e.g: scala, java|
h2. References
* http://www.z2-environment.eu/v21doc#javaComponents