Package com.zfabrik.components.java

## Interface IJavaComponent

-     public interface IJavaComponent

  Client interface of a Java component. I.e. any Java component provides an implementation of this interface when looked up.

  A Java component is declared by using the component type `com.zfabrik.java` (see also `IComponentDescriptor.COMPONENT_TYPE`)

  Java components generally serve Java type definitions to other components, for example Web applications.

  One important defaulting mechanism applies to Java components: By convention, other component types that require or support an implementation, for example a Web application will use `JavaComponentUtil` to identify a Java component that is used to load types from. Given a project `com.acme.myproject`, the default Java component to look for is `com.acme.myproject/java`, i.e. the project name with an appended "/java". Components within the project use the private loader of that Java component by convention.

  See also `IComponentsRepository` for a typical component repository layout.

  In most cases Java components do hold Java resources, e.g. Java source files or JAR libraries. In some cases all types required are provided elsewhere, so that the project itself does not hold any Java resources. In that case a Java component does not require a folder structure but may be specified only a set of properties defining references to other Java components.

  The folder structure of Java components assigns meaning to the following files and 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.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` 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`. 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

  The following properties can be used in the component descriptor:

  java.publicReferences
    Points to other java components whose 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".

    Alternatively this reference points to a `com.zfabrik.files` component that must have a bin folder that will be included into this java component's java resources. The files resource may also have a `src` folder that will be copied befor compilation into the public interface in `src.api` or `src`.

    See also `JavaComponentUtil.fixJavaComponentName(String)`

  java.privateReferences
    Points to other java components whose 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".

    Alternatively this reference points to a `com.zfabrik.files` component that must have a bin folder that will be included into this java component's java resources. The files resource may also have a `src` folder that will be copied befor compilation into the public interface in `src.impl` or `private/src`.

    See also `JavaComponentUtil.fixJavaComponentName(String)`

  java.testReferences
    When running in development mode, the test references add to the private references of the component. Test references are meant to satisfy the dependencies of types and other definitions defined in `src.test`, `bin.test`. When not running in development mode, this setting will be ignored.
  java.nobuild
    A Java component specifying `true` as the value of this component property will be ignored by the compilation mechanism (as it will be in javadoc generation).
  java.compile.order
    The compile order must be defined in java components that also contain non-java sources, e.g. `scala`, or require special handling like apsect weaving. This property can be omitted for pure java components, otherwise one has to define all compilers in the right order - e.g: `scala, java`
  Author:
    hb

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `IJavaComponent.Part` | A Java component is constructed from three different aspects, that are either publicly shared, privately used for implementation, or only available in development mode for testing.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `COMPILE_ORDER` | The compile order must be defined in java components that also contain non-java sources e.g.
    `static java.lang.String` | `DEFAULT_CLASSPATH_PATTERN` | Default inclusion pattern for classpath computation of the component.
    `static java.lang.String` | `NOBUILD` | A Java component specifying `true` as the value of this component property will be ignored by the compilation mechanism (as it will be in javadoc generation).
    `static java.lang.String` | `PRIINCS` | 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.
    `static java.lang.String` | `PRIREFS` | 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.
    `static java.lang.String` | `PRIVATE_CLASSPATH_PATTERN` | Custom inclusion pattern for classpath computation of the impl section.
    `static java.lang.String` | `PRIVATE_COMPILE_ORDER` | Specific override of compile order for the implementation part of a Java component.
    `static java.lang.String` | `PUBINCS` | 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.
    `static java.lang.String` | `PUBLIC_CLASSPATH_PATTERN` | Custom inclusion pattern for classpath computation of the API section.
    `static java.lang.String` | `PUBLIC_COMPILE_ORDER` | Specific override of compile order for the API part of a Java component.
    `static java.lang.String` | `PUBREFS` | Points to another java component whose public types will be shared with this one (and maybe others).
    `static java.lang.String` | `TEST_CLASSPATH_PATTERN` | Custom inclusion pattern for classpath computation of the test section.
    `static java.lang.String` | `TEST_COMPILE_ORDER` | Specific override of compile order for the test part of a Java component.
    `static java.lang.String` | `TESTINCS` | 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.
    `static java.lang.String` | `TESTREFS` | 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 also `Foundation.MODE`) is set to "development".
    `static java.lang.String` | `TYPE` | Type constant for Java components.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `JavaComponentClassLoader` | `getPrivateLoader()` | Retrieve the private implementation's loader of this Java component.
    `JavaComponentClassLoader` | `getPublicLoader()` | Retrieve the public interface's loader of this Java component.
    `java.io.File` | `getRuntimeResources()` | Unlike the originally provided Java component repository resources made accessible via `IComponentsRepository.retrieve(String)`, due to compilation the runtime resources are the result of one or more compilation operations.

- - ### Field Detail

    - #### TYPE

          static final java.lang.String TYPE

      Type constant for Java components.
      See Also:
        `IComponentDescriptor.COMPONENT_TYPE`, Constant Field Values

    - #### PUBREFS

          static final java.lang.String PUBREFS

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

      See Also:
        `JavaComponentUtil.fixJavaComponentName(String)`, Constant Field Values

    - #### PUBINCS

          static final java.lang.String PUBINCS

      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`.
      See Also:
        Constant Field Values

    - #### PRIREFS

          static final java.lang.String PRIREFS

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

      See Also:
        `JavaComponentUtil.fixJavaComponentName(String)`, Constant Field Values

    - #### PRIINCS

          static final java.lang.String PRIINCS

      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`.
      See Also:
        Constant Field Values

    - #### TESTREFS

          static final java.lang.String TESTREFS

      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 also `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.

      See also `PRIREFS`

      See Also:
        Constant Field Values

    - #### TESTINCS

          static final java.lang.String TESTINCS

      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`.
      See Also:
        Constant Field Values

    - #### NOBUILD

          static final java.lang.String NOBUILD

      A Java component specifying `true` as the value of this component property will be ignored by the compilation mechanism (as it will be in javadoc generation).
      See Also:
        Constant Field Values

    - #### COMPILE_ORDER

          static final java.lang.String COMPILE_ORDER

      The compile order must be defined in java components that also contain non-java sources e.g. `scala` code or that require additional handling by e.g. aspect weaving. Z2 offers a compiler extension mechanism for that purpose. This property defines the order in which compilers will be applied. This property can be omitted for pure java components in that it defaults to `java`. Otherwise one has to define all compilers in the right order - e.g: `scala, java`
      See Also:
        Constant Field Values

    - #### PUBLIC_COMPILE_ORDER

          static final java.lang.String PUBLIC_COMPILE_ORDER

      Specific override of compile order for the API part of a Java component. Otherwise like `COMPILE_ORDER`.
      See Also:
        Constant Field Values

    - #### PRIVATE_COMPILE_ORDER

          static final java.lang.String PRIVATE_COMPILE_ORDER

      Specific override of compile order for the implementation part of a Java component. Otherwise like `COMPILE_ORDER`.
      See Also:
        Constant Field Values

    - #### TEST_COMPILE_ORDER

          static final java.lang.String TEST_COMPILE_ORDER

      Specific override of compile order for the test part of a Java component. Otherwise like `COMPILE_ORDER`.
      See Also:
        Constant Field Values

    - #### DEFAULT_CLASSPATH_PATTERN

          static final java.lang.String DEFAULT_CLASSPATH_PATTERN

      Default inclusion pattern for classpath computation of the component. Only library files matching this pattern will be included into classpath computation by default. This has no effect on the inclusion of .class files.
      See Also:
        Constant Field Values

    - #### PUBLIC_CLASSPATH_PATTERN

          static final java.lang.String PUBLIC_CLASSPATH_PATTERN

      Custom inclusion pattern for classpath computation of the API section. Only library files matching the specified pattern will be included into the respective classpath computation. This has no effect on the inclusion of .class files.
      See Also:
        Constant Field Values

    - #### PRIVATE_CLASSPATH_PATTERN

          static final java.lang.String PRIVATE_CLASSPATH_PATTERN

      Custom inclusion pattern for classpath computation of the impl section. Only library files matching the specified pattern will be included into the respective classpath computation. This has no effect on the inclusion of .class files.
      See Also:
        Constant Field Values

    - #### TEST_CLASSPATH_PATTERN

          static final java.lang.String TEST_CLASSPATH_PATTERN

      Custom inclusion pattern for classpath computation of the test section. Only library files matching the specified pattern will be included into the respective classpath computation. This has no effect on the inclusion of .class files.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getPrivateLoader

          JavaComponentClassLoader getPrivateLoader()

      Retrieve the private implementation's loader of this Java component. When this call completes, the Java component will have been checked and possibly compiled, if needed.

    - #### getPublicLoader

          JavaComponentClassLoader getPublicLoader()

      Retrieve the public interface's loader of this Java component. When this call completes, the Java component will have been checked and possibly compiled, if needed.

    - #### getRuntimeResources

          java.io.File getRuntimeResources()

      Unlike the originally provided Java component repository resources made accessible via `IComponentsRepository.retrieve(String)`, due to compilation the runtime resources are the result of one or more compilation operations. Initially the runtime resources are set as the originally provided resources. Compilation processes may alter these resources as required. The standard Java compilation process only adds compilation results, actual .jar files and does not modify other resources.

      Due to changes in dependency components, compilation processes might be run more than once per actual Java component revision and different runtime instances of z2 may access different runtime resources while sharing one set of repository resources.

      This method provides access to the runtime resources root.