Last weeks were very busy here in Oracle. JavaOne 2012 is next week. Come
to see us there!
Meanwhile i'd like
to quickly update you on recent developments in the area of packaging tools. This is an area of ongoing development for the team, and we are continuing
to refine and improve both the tools and the process. Thanks
to everyone who shared experiences and suggestions with us. We are listening and fixed many of reported issues. Please keep them coming as comments on the blog or (even better) file issues directly
to the JIRA.
In this post i'll focus on several new packaging features added in JDK 7 update 10:
Self-Contained Applications: Select Java Runtime
to bundle
Self-Contained Applications: Create Package without Java Runtime
Self-Contained Applications: Package non-JavaFX
application
Option
to disable proxy setup in the JavaFX launcher
Ability
to specify codebase for WebStart
application
Option
to update existing jar file
Self-Contained Applications: Specify
application icon
Self-Contained Applications: Pass parameters on the command line
All these features and number of other important bug fixes are available in the developer preview builds of JDK 7 update 10 (build 8 or later). Please give them a try and share your feedback!
Self-Contained Applications: Select Java Runtime
to bundle
Packager tools in 7u6 assume current JDK (based on java.home property) is the source for embedded runtime. This is useful simplification for many scenarios but there are cases where ability
to specify what
to embed explicitly is handy. For example IDE may be using fixed JDK
to build the project and this is
not the version you want
to bundle into your
application.
To make it more flexible we now allow
to specify location of base JDK
explicitly. It is optional and if you do not specify it then current JDK will be used (i.e. this change is fully backward compatible).
New 'basedir' attribute was added
to <fx:platform> tag. Its value
is location of JDK
to be used. It is ok
to point
to either JRE inside
the JDK or JDK top level folder. However, it must be JDK and not JRE as we need
other JDK tools for proper packaging and it must be recent version of
JDK that is bundled with JavaFX (i.e. Java 7 update 6 or later).
Here are examples (<fx:platform> is part of <fx:deploy> task):
<fx:platform basedir="${java.home}"/>
<fx:platform basedir="c:\tools\jdk7"/>
Hint: this feature enables you
to use packaging tools from JDK 7 update
10 (and benefit from bug fixes and other features described below)
to create
application package with bundled FCS version of JRE 7 update 6.
Self-Contained Applications: Create Package without Java Runtime
This may sound a bit puzzling at first glance. Package without embedded Java Runtime is not really self-contained and obviously will not help with:
Deployment on fresh systems. JRE need
to be installed separately (and this step will require admin permissions).
Possible compatibility issues due
to updates of system runtime.
However, these packages are much much smaller in size. If download size
matters and you are confident that user have recommended system JRE
installed then this may be good option
to consider if you want
to improve user experience for install and launch.
Technically, this is implemented as an extension of previous feature.
Pass empty string as value for 'basedir' attribute and this will be
treated as request
to not bundle Java runtime, e.g.
<fx:platform basedir=""/>
Self-Contained Applications: Package non-JavaFX
application
One of popular questions people ask about self-contained applications -
can i package my Java
application as self-contained application? Absolutely.
This is true even for tools shipped with JDK 7 update 6. Simply follow steps for creating
package for Swing
application with integrated JavaFX content and they will work even if your
application does not use JavaFX. What's wrong with it? Well, there are few caveats:
bundle size is larger because JavaFX is bundled whilst it is not really needed
main
application jar needs
to be packaged
to comply
to JavaFX packaging requirements(and this may be not trivial
to achieve in your existing build scripts)
javafx
application launcher may not work well with startup logic of your application (for example launcher will initialize networking stack and this may void custom networking settings in your
application code)
In JDK 7 update 6 <fx:deploy> was updated
to accept arbitrary
executable jar as an input. Self-contained
application package will be created preserving input jar as-is, i.e. no JavaFX launcher will be embedded. This does not help with first point above but resolves other two.
More formally following assertions must be
true for packaging
to succeed:
application can be launched as "java -jar YourApp.jar" from the command line
mainClass attribute of <fx:application> refers
to application main class
<fx:resources> lists all resources needed for the
application
To give you an example lets assume we need
to create a bundle for
application consisting of 3 jars:
dist/javamain.jar
dist/lib/somelib.jar dist/morelibs/anotherlib.jar
where javamain.jar has manifest with Main-Class: app.Main Class-Path: lib/somelib.jar morelibs/anotherlib.jar
Here is sample ant code
to package it:
<target name="package-bundle">
<taskdef resource="com/sun/javafx/tools/ant/antlib.xml"
uri="javafx:com.sun.javafx.tools.ant"
classpath="${javafx.tools.ant.jar}"/>
<fx:deploy nativeBundles="all"
width="100" height="100"
outdir="native-packages/" outfile="MyJavaApp">
<info title="Sample project" vendor="Me"
description="Test built from Java executable jar"/>
<fx:application id="myapp" version="1.0"
mainClass="app.Main" name="MyJavaApp"/>
<fx:resources>
<fx:fileset dir="dist">
<include name="javamain.jar"/>
<include name="lib/somelib.jar"/>
<include name="morelibs/anotherlib.jar"/>
</fx:fileset>
</fx:resources>
</fx:deploy>
</target>
Option
to disable proxy setup in the JavaFX launcher
Since JavaFX 2.2 (part of JDK 7u6) properly packaged JavaFX applications have proxy settings initialized according
to Java Runtime configuration settings.
This is handy for most of the
application accessing network with one
exception. If your
application explicitly sets networking
properties (e.g. socksProxyHost) then they must be set before
networking stack is initialized. Proxy detection will initialize
networking stack and therefore your custom settings will be ignored.
One way
to disable proxy setup by the embedded JavaFX launcher is
to pass
"-Djavafx.autoproxy.disable=true" on the command line. This
is good for troubleshooting (proxy detection may cause significant
startup time increases if network is misconfigured) but not really user friendly.
Now proxy setup will be disabled if manifest of main
application jar has "JavaFX-Feature-Proxy" entry with value "None". Here is simple example of adding this entry using <fx:jar> task:
<fx:jar destfile="dist/sampleapp.jar">
<fx:application refid="myapp"/>
<fx:resources refid="myresources"/>
<fileset dir="build/classes"/>
<manifest>
<attribute name="JavaFX-Feature-Proxy" value="None"/>
</manifest>
</fx:jar>
Ability
to specify codebase for WebStart
application
JavaFX applications do not need
to specify codebase (i.e. absolute location where
application code will be deployed) for most of real world deployment scenarios. This is convenient as
application does not need
to be modified when it is moved from development
to deployment environment.
However, some developers want
to ensure copies of their
application JNLP
file will redirect
to master location. This is where codebase is
needed.
To avoid need
to edit JNLP file manually <fx:deploy> task now accepts optional codebase attribute. If
attribute is not specified packager will generate same no-codebase files
as before.
If codebase value is explicitly specified then generated JNLP files
(including JNLP
content embedded into
web page) will use it. Here is an example:
<fx:deploy width="600" height="400"
outdir="Samples"
codebase="http://localhost/codebaseTest"
outfile="TestApp">
....
</fx:deploy>
Option
to update existing jar file
JavaFX packaging procedures are optimized for new
application that can use ant or command line javafxpackager utility. This may lead
to some redundant steps when you add it
to your existing build process.
One typical situation is that you might already have a build procedure that produces executable jar file with custom manifest. To properly package it as JavaFX executable jar you would need
to unpack
it and then use javafxpackager or <fx:jar>
to create jar again (and you need
to make sure you pass all important details from your custom manifest).
We added option
to pass jar file as an input
to javafxpackager and <fx:jar>. This simplifies integration of JavaFX packaging tools into
existing build process as postprocessing step. By the way, we are looking for ways
to simplify this further. Please share your suggestions!
On the technical side this works as follows. Both <fx:jar> and
javafxpackager will attempt
to update existing jar file if this is the
only input file. Update process will add JavaFX launcher classes and update the jar manifest with JavaFX attributes. Your custom attributes will be preserved. Update could be performed in place or result may be saved
to a different file.
Main-Class and Class-Path elements (if present) of manifest of input jar file will be used for JavaFX
application unless they are explicitly overriden in the packaging command you use. E.g. attribute mainClass of <fx:application> (or -appclass in the javafxpackager case) overrides existing Main-Class in the jar manifest. Note that class specified in the Main-Class attribute could either extend JavaFX
Application or provide static main() method.
Here are examples of updating jar file using javafxpackager:
Create new JavaFX executable jar as a copy of given jar file javafxpackager -createjar -srcdir dist -srcfiles fish_proto.jar -outdir dist -outfile fish.jar
Update existing jar file
to be JavaFX executable jar and use test.Fish as main
application class javafxpackager -createjar -srcdir dist -appclass test.Fish -srcfiles fish.jar -outdir dist -outfile fish.jar
And here is example of using <fx:jar>
to create new JavaFX executable jar from the existing fish_proto.jar:
<fx:jar destfile="dist/fish.jar">
<fileset dir="dist">
<include name="fish_proto.jar"/>
</fileset>
</fx:jar>
Self-Contained Applications: Specify
application icon
The only way
to specify
application icon for self-contained
application using tools in JDK 7 update 6 is
to use drop-in resources.
Now this bug is resolved and you can also specify icon using
<fx:icon> tag. Here is an example:
<fx:deploy ...>
<fx:info>
<fx:icon href="default.png"/>
</fx:info>
...
</fx:deploy>
Few things
to keep in mind:
Only default kind of icon is applicable
to self-contained applications (as of now)
Icon should follow platform specific rules for sizes and image format (e.g. .ico on Windows and .icns on Mac)
Self-Contained Applications: Pass parameters on the command line
JavaFX applications support two types of
application parameters: named and unnamed (see the API for
Application.Parameters).
Static named parameters can be added
to the
application package using
<fx:param> and unnamed parameters can be added using
<fx:argument>. They are applicable
to all execution modes including standalone applications.
It is also possible
to pass parameters
to a JavaFX
application from a
Web page that hosts it, using <fx:htmlParam>. Prior
to JavaFX 2.2, this was only supported for embedded applications.
Starting from JavaFX 2.2, <fx:htmlParam> is applicable
to Web
Start applications also. See JavaFX
deployment guide for more details on this.
However, there was no way
to pass dynamic parameters
to the
self-contained
application. This has been improved and now native
launchers will delegate parameters from command line
to the
application code. I.e.
to
pass parameter
to the
application you simply need
to run it as "myapp.exe somevalue" and then use getParameters().getUnnamed().get(0)
to get "somevalue".
