This page documents an idea on how to improve the java alternatives system. A proof of concept has been implemented.

= Problem =

All java related tools such as java, javac, javadoc are symlinks are handled by the alternatives system. Neither the non-privileged user nor the Debian packager can easily override which JVM should be used. There is some support for overriding in the java-wrappers package but the implementation is not very Debianish. That is why we will introduce sensible tools to the java-common package.

= Use Cases =

== Basic Usage ==

{{{sensible-java}}}, {{{sensible-javac}}}, {{{sensible-javadoc}}}, ... will just run {{{java}}}, {{{javac}}}, and {{{javadoc}}} by default but you can change it by specifying {{{JAVA_HOME}}}:
{{{
JAVA_HOME=/usr/lib/jvm/default-java
export JAVA_HOME
sensible-java ...
}}}
You get more flexibility with {{{JAVA_FLAVOR}}}:
{{{
JAVA_FLAVOR="default /usr/lib/jvm/java-6-sun"
export JAVA_FLAVOR
sensible-javac ...
}}}
which is a space separated list of codenames or absolute directory names of candidates for {{{JAVA_HOME}}}. {{{JAVA_FLAVOR}}} will be ignored if {{{JAVA_HOME}}} is specified. Some examples for the codenames are:
 * {{{default}}} which points to default-java
 * {{{sun}}} which will try openjdk-6, sun-java6, and sun-java5
 * {{{gcj}}} which points to gcj
The complete list can be found in {{{/etc/java/jvm.list}}} and will be documented later.

The sensible commands will fall back to the alternatives system in case no valid {{{JAVA_HOME}}} can be found. -- '''IRC discussion:''' failing is probably a better idea


== Setting up CLASSPATH ==

The contruction of the {{{CLASSPATH}}} can be simplified by specifying
{{{
JAVA_LIBS="item1 item2 item3"
}}}
where each item can be
 * a relative filename of a JAR file in {{{/usr/share/java/}}},
 * an absolute filename, or
 * an absolute directory name that contains jar files.
The {{{.jar}}} extension is optional for filenames and will be added
automatically. All JAR files will be added to the {{{CLASSPATH}}} in lexical
order for the directory case. An explicitely specified CLASSPATH has priority
over {{{JAVA_LIBS}}}.

== Advanced Usage ==

The program {{{sensible-java-home}}} can be used to improve existing shell
wrappers. Just add a line like
{{{
JAVA_FLAVOR=default
JAVA_LIBS="hello-impl hello-api"
export JAVA_FLAVOR JAVA_LIBS
eval $(sensible-java-home java javac javadoc)
}}}
to the top of the wrapper. That will insert the following code into the wrapper:
{{{
JAVA_HOME=/usr/lib/jvm/default-java
JAVA_CMD=/usr/lib/jvm/default-java/bin/java
JAVAC_CMD=/usr/lib/jvm/default-java/bin/javac
JAVADOC_CMD=/usr/lib/jvm/default-java/bin/javadoc
CLASSPATH=/usr/share/java/hello-impl:/usr/share/java/hello-api
export JAVA_HOME JAVA_CMD JAVAC_CMD JAVADOC_CMD CLASSPATH
}}}
The arguments to {{{sensible-java-home}}} are optional and default to java; {{{sensible-java-home}}} finds a {{{JAVA_HOME}}} that is valid for all specified commands.

== Ant Support ==

The line
{{{
eval $(sensible-java-home java javac)
}}}
will be added to the
{{{ant}}} wrapper and allows you to set {{{JAVA_FLAVOR}}} and {{{JAVA_LIBS}}}
before calling {{{ant}}}.

== Makefile Usage ==

You can beautify {{{debian/rules}}} without including helper fragments:
{{{
export JAVA_FLAVOR = default
export JAVA_LIBS = hello-impl hello-api

build-indep:
	sensible-javac ...
	ant
}}}

= Implementation Details =

The individual sensible commands are simple symlinks to
{{{sensible-java-home}}} which are implemented in dash compatible shell
scripts. Unit tests might use something more advanced like python doctests. An
environment variable {{{JAVA_DEBUG}}} will enable debugging output.


----
CategoryJava