Task javaLibrary
Build a Java library.
A library is constructed from Java source files, compiled Java source files (class files), and JARs.
Source files intended for inclusion in the library are provided in the form of package structured directory trees. Multiple source trees can be specified.
JDK releases
Ordinarily, all sources in a library are compiled against a single JDK release, which may be specified using the
release attribute. The selected JDK release defines the
Java language level that the compiler expects, the JDK API that the files are compiled
against, and the class file version of the class files produced by the compiler.
In unusual cases, multiple source trees can be provided that specify different JDK releases. As each specified release corresponds to a different class file version, the ability to specify multiple releases is useful only if the library can ensure that the classes that are loaded are compatible with the Java runtime that the library is running on (see below for one possible technique).
Currently, the most common situation is a library that supports JDK 8 and later, but uses some JDK 8 specific APIs when running on JDK 8 and uses JDK 9+ APIs when running on JDK 9+. The recommended structure for such a library is to define three source trees:
- One tree for code that uses JDK 8 specific APIs. This tree specifies JDK release 8.
- One tree for code that uses JDK 9+ specific APIs. This tree specifies JDK release 9.
- One tree for all other code. This tree does not specify a JDK release, but it is implicitly compiled against JDK 8 because the task itself specifies JDK 8.
This structure is motivated by the fact that the JDK 8 specific APIs are considered internal APIs. For this reason,, a source tree that declares JDK release 8 is compiled with access to the internal APIs, but other source trees are compiled without access to the internal APIs (even though they are compiled against JDK 8).
This task does not support the construction of multi-release JARs. The recommended technique for ensuring that only classes that are supported on the running JDK are loaded is to use reflection to load JDK-specific classes. For client access, the JDK specific classes probably should subclass a common abstract base class that is not JDK specific or support a common interface that is not JDK specific.
Properties
| Property | Description | Type |
| install.local.repo | Boolean property. If true, the library is installed in the local repo as a SNAPSHOT release. | String |
| java.release | A property that specifies the default JDK release, if no valid release is specified for a source tree. | String |
| javac | A property that specifies the path to the java compiler. If undefined, standard locations are searched for the compiler. | String |
| compile.debug | Boolean property. If true, javac is run in debug mode. | String |
| bootclasspath8 | The boot class path to use when compiling for JDK 8. This path is required to allow access to internal APIs. | String |
Parameters accepted as attributes
| Attribute | Description | Type | Required? |
| classpath | Specify the library name. | String | Yes. |
| classpathRef | Specify source trees and Java libraries required for compilation and/or inclusion in a library or application. | Reference | No. If not specified, nested classpath elements must be used. |
| manifest | Specify a file to be used as the JAR Manifest. | File, Manifest | No. |
| optionalManifest | Specify a file to be used as the JAR Manifest. No error is issued if the file does not exist. | File | No. |
| dist | Specify the directory where the basic JAR should be installed. | File | No. If not specified, a basic JAR will not be created. |
| expandedDist | Specify the directory where the expanded JAR should be installed. | File | No. If not specified, an expanded JAR will not be created. |
| expandedName |
Specify the basic name of the expanded JAR file to create. The name should not include the ".jar"
suffix.
|
String | No. If not specified, a library name will be used. |
| codeSigningKey | Specify the key to use for code signing the JAR file. | String | No. If not specified, the JAR file will not be code signed. |
| mavenCoordinates | Specify the Maven repo coordinates to associate with this library. This attribute is currently unused. | String | No. |
| buildRoot | Specify the build directory for this build. Subdirectories of the build directory may be used to store results of the build, unless specific directories have been configured. | File | No. |
| release |
Specify the default JDK release number. This attribute is used for sources for which no explicit
release has been defined.
The JDK release number determines Java language level used to compile Java sources, the associated JDK API that the sources may use, and the class file version number of the generated class files. |
String | No. If not specified, the default release of the Java compiler is used. |
Parameters accepted as nested elements
Task ...
Nested tasks are performed after compilation and before packaging the library contents in a JAR. Nested tasks can be used to create JNI based native libraries, which require header files produced by Java compiler for native Java methods.
Currently, only JNI tasks are supported.