z2-Environment

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": 

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. 

This technically slim convention makes modules a place to implement encapsulation and information hiding.

h2. API and Implementation

h2. Classloading in Z2

h2. Referencing and including Java resources from other modules

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