On todays GUI oriented operating systems, users are used to launching
applications, view web sites, look at documentation and perform a
variety of other tasks, by simply clicking on an icon on the desktop or
in a menu system located on the desktop. Depending on the operating
system these icons have different names. In this context I will refer to
them collectively as shortcuts.
Apart from actually placing an application on the target system, users
routinely expect an installer to create the necessary shortcuts for the
application as well. For you as application developer, this means that
for a professional appearance of your product you should also
consider creating shortcuts.
In contrast to the general specification of an IzPack installer, the
specification of shortcuts in IzPack requires a little more effort. In
addition, some of the concepts are a bit more complex and there are some
operating system specific issues to observe. Fortunately, you only need
to worry about operating system specifics if you want to deploy your
application to multiple different operating systems. In any case, it
will pay off to spend some time to study this documentation and the
example spec file before you start to implement your own shortcuts.
At the time of this writing (for IzPack version 3.0) IzPack is only
capable of creating shortcuts on the Microsoft Windows operating systems
[Win95 and higher and Win-NT 4.0 and higher]. Other operating systems,
such as Mac and UNIX flavors are not directly supported. However, there
is a special UI that automatically pops up on unsupported systems. It
informs the user about the intended targets of your shortcuts and allows
the user to save this information to a text file. While this is not an
elegant solution, at least it aids the user in the manual creation of
the shortcuts.
If you would like to review what an end user would see if the target
operating system is not supported, you can do the following. Simply
place the tag <notSupported/> in the spec file. This tag requires no
attributes or other data. It must be placed under <shortcuts>, just like
the individual shortcut specifications. Be sure to remove this tag
before getting your application ready for shipment.
We expect other operating systems to be supported in the near future and
as always, contributions are very welcome. At present someone is
actively working on Mac support and Julien wanted to implement a
solution for KDE.
There are a number of things that you must add to the installer to make
it ready for creating shortcuts. Obviously you need to add the panel
responsible for creating shortcuts. This panel is aptly enough called
ShortcutPanel. However, in order for the ShortcutPanel to function
properly a number of additional items are required. These must be added
manually to the installer, because the front-end does not support this
feature yet. In this chapter I will explain which of these items are
required and for what reason.
First, I would like to discuss items that are supplied with IzPack and
only need to be added to the installer. After that, I move on to the
things you have to prepare yourself before you can add them. The way in
which shortcuts are created varies widely among operating systems. In
some cases it is actually possible to do this with pure Java code, while
other systems -such as MS-Windows- require native code to accomplish
this task. The native libraries required for the supported operating
systems are supplied with IzPack but they are not automatically added to
your installer file. You need to list them yourself in the XML file for
the installer. I'll describe later how to do this. At the time of this
writing (for IzPack version 3.0) only MS-Windows is supported. The
native library required for this operating system is called
ShellLink.dll.
Native libraries can be added to the installer by using the
<native> tag. To add the DLL for Windows for example, you just
have to add the following line to the installer XML file:
<native type="izpack" name="ShellLink.dll"/>
For more details about the use of the <native> tag see the
cahpter about the format of the XML file.
You have to supply an extra specification file for the shortcuts that
you want to be created on the target system. This file is required by
the shortcut panel. The format for this spec file is XML. It must be
added to the installer as a resource. The source name of this
specification does not matter, however its name when added to the
installer must be shortcutSpec.xml. This is the name the
ShortcutPanel looks for, do not use a different name and do not a path
to the name! If the specification file can not be found, the
ShortcutPanel will not show at all.
Example
<res src="C:\MyDocuments\Installer\MyShortcutSpec.xml" id="shortcutSpec.xml"/>
This little chapter is not strictly part of the documentation but I have
been asked this question sufficiently often that I think it's worth
explaining right here. It is certainly a natural question to ask. After
all IzPack is an application completely written in Java and primarily
targeted for the installation of Java based programs. So why wouldn't we
try to keep everything pure Java and avoid the use of native code
altogether? There must be some personal preference of the developer
hidden behind this approach you might think. Well, not really, but I
admit at first it seems quite feasible to write it all in Java. On
virtually any operating system or GUI surface around, Shortcuts are
simply files on the local file system. Files can be created and accessed
directly from within Java, so why should there be a need for using
native code?
Well, it turns out that just creating a file is not good enough, it also
needs to have the right content. Shell Links as they are called in
Windows land are binary files. I actually managed to find documentation
on the format. Naturally this was hacker data, you won't get this sort
of thing from Microsoft (by the way: thanks a lot to Jesse Hager for a
smash job!). Armed with this information I tried to create these files
myself in Java. The problem was that the documentation was not entirely
accurate and had some gaps as well. I tried for over a month to get this
to work but finally I had to give up. Even if I would have succeeded, it
would have been a hack, since a shell link requires some information that
is impossible to obtain from within Java. Usually you can successfully
create a shell link by only filling in the bare minimum information and
then ask Windows to resolve the link. Windows then repairs the shell
link. Unfortunately this was only the beginning, soon I encountered a
host of other problems. For one thing, the installer needs to know the
correct directories for placing the links and it turns out they are
named differently in different countries. In addition, there are ways of
manually modifying them, which some people might actually have done. The
only way to place the shortcut files reliably is through accessing the
Windows Registry. Naturally, this operation also required native code.
Same thing with asking Windows to resolve the link... On the bottom
line, at every step and turn you run into an issue where you just need
to use native code to do the trick. So I decided that I would do it the
proper way all the way through. That is in a nutshell the reason why I
used native code to create shortcuts on MS-Windows.
As I am writing this I am at work with a friend to replicate this work
for the Mac and it looks very much like we need to take the same
approach there as well. The various UNIX GUI surfaces on the other hand
seem promising. It might turn out that we can do the job without native
libraries, we will see...
The specification for shortcuts is provided to the ShortcutPanel in the
form of a XML file. At the time of this writing (for IzPack version 3.0)
the front-end has no support for generating this specification. Until a
later version provides front-end support you will have to write the
specification manually. For your convenience, an annotated sample
specification is located in the sample subdirectory of your IzPack
installation. At the beginning you might want to experiment with that
file.
The specification file has only one major section called <shortcuts>.
In this section, two different tags are recognized: <programGroup> and
<shortcut>.
The <programGroup> tag allows you to specify the name of the
menu under which the shortcuts will be grouped. The exact location and
appearance of the program group depends on the specific target system on
which the application will be installed, however you have some influence
on this. Please note that <programGroup> may only appear once
in the specification. If more than one instance occurs, only the first
one will be used. This tag requires two attributes: defaultName
and location. defaultName specifies the name that the
group menu should have on the target system. You should be aware that
the ShortcutPanel will present this name to the user as a choice. The
user can then edit this name or select a group that already exists. As a
result, there is no guarantee that the actual name of the program group
on the target system is identical with your specification.
location specifies where the group menu should show up. There
are two choices: applications and startMenu. If you
use applications, then the menu will be placed in the menu that
is ordinarily used for application shortcuts. If you use
startMenu, the group menu will be placed at the top most menu
level available on the target system. Depending on the target system, it
might not be possible to honor this specification exactly. In such
cases, the ShortcutPanel will map the choice to the location that most
closely resembles your choice.
For each shortcut you want to create, add one <shortcut> tag.
Most details about the shortcut are listed as attributes with this tag.
The following sections describe what each attribute does, which
attributes are optional and which ones are required and what the values
are that are accepted for each of the attributes. Note that all
attributes that have a yes/no choice can also be omitted. Doing so has
the same effect as using a value of no. The shortcut attributes can be
divided into two groups
The following attributes are used to define location:
There are three classes of attributes. Some are required, most are completely optional and some are semi-optional. The set of semi-optional attributes are all the attributes used to define the location of a shortcut. These are semi-optional because for any individual one it is your choice if you want to include it or not. However they are not completely optional. You must specify at least one location. If all were omitted, the instruction would essentially tell the panel that a copy of this shortcut is to be placed at no location. In other words no copy is to be placed anywhere.
name - required
The value of this attribute defines the name that the shortcut will
have. This is the text that makes up the menu name if the shortcut is
placed in a menu or the caption that is displayed with the shortcut if
it is placed on the desktop.
target - required
The value of this attribute points to the application that should be
launched when the shortcut is clicked. The value is translated through
the variable substitutor. Therefore variables such as
$INSTALL_PATH can be used to describe the location.
You should be aware that the use of this tag is likely to change
once other operating systems are supported.
commandLine - optional
The value of this attribute will be passed to the application as command
line. I recommend to work without command line arguments, since these are
not supported by all operating systems. As a result, your applications
will not be portable if they depend on command line arguments. Instead,
consider using system properties or configuration files.
workingDirectory - optional
This attribute defines the working directory for the application at the
time it is launched. I would recommend some caution in relying on this
too heavily if your application should be portable, since this might not
be supported by all operating systems. At this time I don't have enough
information to make a definite statement one way or the other. The value
is translated through the variable substitutor. Therefore variables such
as $INSTALL_PATH can be used to describe the directory.
description - optional
The value of this attribute will be visible to the user when a brief
description about associated application is requested. The form of the
request and the way in which this description is displayed varies
between operating systems. On MS-Windows the description is shown as a
tool tip when the mouse cursor hovers over the icon for a few seconds.
On some operating systems this feature might not be supported but I
think it is always a good idea to include a brief description.
iconFile - optional
The value of this attribute points to the file that holds the icon that
should be displayed as a symbol for this shortcut. This value is also
translated through the variable substitutor and consequently can contain
variables such as $INSTALL_PATH. If this attribute is omitted, no icon
will be specified for the shortcut. Usually this causes the OS to
display an OS supplied default icon. The use of this attribute
is also likely to change once other operating systems are supported.
iconIndex - optional
If the file type for the icon supports multiple icons in one file, then
this attribute may be used to specify the correct index for the icon. I
would also advise against using this feature, because of operating
system incompatibilities in this area. In file formats that do not
support multiple icons, this values is ignored.
initialState - optional
There are four values accepted for this attribute: noShow,
normal, maximized and minimized. If th
target operating system supports this feature, then this value will have
the appropriate influence on the initial window state of the
application. noShow is particularly useful when launch scripts
are used that cause a command window to open, because the command window
will not be visible with this option. For instance on MS-Windows
starting a batch file that launches a Java application has the less than
pretty side effect that two windows show: the DOS command prompt and the
Java application window. Even if the shortcut is configured to show
minimized, there are buttons for both windows in the task bar. Using
noShow will completely eliminate this effect, only the Java
application window will be visible.
programGroup - semi-optional
The value for this attribute can be either yes or no. Any other value
will be interpreted as no. If the value is yes, then a copy of this
shortcut will be placed in the group menu.
desktop - semi-optional
For this attribute the value should also be yes or no. If the value is
yes, then a copy of the shortcut is placed on the desktop.
applications - semi-optional
This is also a yes/no attribute. If the value is yes, then a copy of the
shortcut is placed in the applications menu (if the target operating
system supports this). This is the same location as the applications
choice for the program group.
startMenu - semi-optional
This is a yes/no attribute as well. If the value is yes, then a copy of
the shortcut is placed directly in the top most menu that is available
for placing application shortcuts.
startup - semi-optional
This is also a yes/no attribute. If the value is yes, then a copy of the
shortcut is placed in a location where all applications get automatically
started at OS launch time, if this is available on the target OS.
Usually all shortcuts that are listed will be created when the user
clicks the 'Create Shortcuts' button. However it is possible to control
to some degree if specific shortcuts should be created or not. This is
based on install conditions. By including one or more <createForPack>
tags in the specification for a shortcut, you can direct the
ShortcutPanel to create the shortcut only if any of the listed packs are
actually installed. The 'name' attribute is used to define the name of
one of the packs for which the shortcut should be created. You do not
need to list all packs if a shortcut should always be created. In this
case simply omit this tag altogether.
A word of caution
For any shortcut that is always created, I would recommend to omit this
tag, since I have seen a number of problems related to changing pack
names. You can save yourself some troubleshooting and some Aspirin by
not using this feature if it's not required. On the other hand if you
need it I would advise to be very careful about changing pack names.
Native Libraries
Name of Specification File
shortcutSpec.xml
Specification File Layout
<shortcuts> <programGroup defaultName="Name of the Program Group" location="applications/startMenu"/> <shortcut name="the name" target="the application to launch" commandLine="" workingDirectory="c:\MyWorkingDirectory\data" description="a description for the shortcut" iconFile="the file that contains an icon for the shortcut" iconIndex="0" initialState="noShow/normal/maximized/minimized" programGroup="yes/no" desktop="yes/no" applications="yes/no" startMenu="yes/no" startup="yes/no"> <createForPack name="a pack name"/> <createForPack name="another pack name"/> </shortcut> </shortcuts>
I wrote this section to provide additional information about issues
surrounding the creation of shortcuts. Reading this section is not
necessary to successfully create shortcuts, but it might help you
creating an installation that works more smoothly. In addition, it might
give you some knowledge about operating systems that you don't know so
well. In fact most of the issues described in this section are focused
on differences in operating system specifics.
You should recognize that the desktop is precious real estate for many
people. They like to keep it uncluttered and keep only the things there
that they use on a regular basis. This is not true for everybody and you
might personally think different about this. Still, the fact remains
that a lot of people might have different feelings about it, so you
should not automatically assume that it is ok to place all of your
shortcuts on the desktop proper. While your application is certainly one
of the most important things for you, for your customers it is probably
one of many applications they use and maybe not even the most important
one. Accordingly, placing more shortcut icons there than they feel they
will use on a regular basis and especially doing this without asking for
permission might trigger some bad temper.
It is common practice to create a program group on the application menu
system of the OS and place all shortcuts that go with an application in
that program group. In addition, only one shortcut to the key access
point of the application is placed directly on the desktop. Many
installers first ask for permission to do so, as does the ShortcutPanel
in IzPack.
I would like to recommend that you always create a shortcut in the menu
system, even if your application has only one access point and you are
placing this on the desktop. Note that shortcuts can be placed directly
in the menu, they don't need to be in a program group. There are two
reasons for doing so.
Icons are supplied in image files, usually in some kind of bitmap
format. Unfortunately there is no format that is universally recognized
by all operating systems. If you would like to create shortcuts on a
variety of operating systems that use your own icons, you must supply
each icon in a number of different formats. This chapter discusses icon
file formats used on various operating systems. Fortunately there are
good programs available that allow you to convert between these formats,
so that creating the different files is not much of a problem once the
icons themselves are created.
Microsoft Windows
Windows prefers to use its native icon file format. Files of this type
usually use the extension *.ico. Icon files can hold multiple icons in
one file, which can be useful if the same icon is to be provided in a
number of sizes. The iconIndex attribute in the spec file allows you to
specify which of the icons to use.
Windows also supports the use of bitmap files in the *.bmp format as
icons. Note that this format does not support multiple icons.
I am not a total expert in this area and might have overlooked other file
formats that are supported by Windows. However, I would suggest to test
other formats for compatibility as they might not work all the way back
to Windows 95 or on the NT/non-NT strain. Sticking with one of these two
formats should keep you out of trouble.
Apple
Apple Macintosh systems use the Macintosh PICT format, extension *.pct.
If you are working with an apple system you know a whole lot more about
this format than I do. If you don't but would like to be able to install
your application on a Mac, simply start with any bitmap format that you
feel comfortable to work with. Then find an application that is capable
of converting this format into a *.pct file. I like to use Paint Shop
Pro (PC based), because it provides conversion capabilities among
several dozen different file formats.
UNIX flavors
Sorry folks at this time I have no information available on icon file
formats for the various UNIX GUI frontends. If anyone can provide
additional information the would be most welcome.
So, you thought you could escape the ugly mess of operating system
dependencies at least with the way how your Java application is started?
Sorry but I have just another bad message. The one positive thing is
that here you have a way of escaping, even if doing so has a few less
pretty side effects. At first, I would like to discuss various launching
options you have available on different operating systems. At the end of
the chapter I write about a way to make launching your application OS
independent.
Microsoft Windows
On Microsoft Windows you have a variety of options for launching your
application. Probably the most simple case is directly starting the Java
VM from the command line and typing out all parameters, such as class
path, the class name etc. In principle, this can be placed right in a
shortcut and should work.
A little more elegant solution is to place this in a batch file and have
the shortcut point to this batch file. This will also make it more
likely that users can repair or recreate shortcuts. Recreating shortcuts
with sophisticated command lines is practically impossible.
Another method is less commonly used but just as possible. Implement a
native executable that launches the VM with your Java application. The
VM comes as DLL and is used by java.exe in just the same way.
Clearly, even though the first option is a bit ugly and has some
drawbacks, it is the most portable solution among the three.
Apple
I am currently researching the details for the Mac environment. Expect
an updated chapter with the next release.
UNIX
UNIX provides essentially the same options as Windows. You can simply
use the command line option, you can write a shell script and you can
write a native launcher. Naturally this stuff is in no way compatible
with the equivalent Windows implementations. The native option is even
more problematic in this environment, since the code can not even be
moved from one UNIX platform to another, without recompilation.
OS Independent Launching
So, after all this rather discouraging news, there is actually a
portable way to launch Java applications? You bet! although I have to
admit that it is not necessarily the most pretty way of doing things.
This approach is actually used by IzPack. Package your application in a *.jar file if you don't already do so and make it executable. I am not going into all the details on how exactly to do this, the Java documentation will have to do. You might have noticed that even though the instructions to install IzPack say to type :
java -jar IzPack-install.jar
You can just as well double click on IzPack-install.jar and it will
start up. This procedure will work on all Java supported operating
systems -though you might have to replace double clicking with dropping
the file on the VM. In just the same way, you can make the *.jar file
itself the target of a shortcut.
The one drawback with this approach is that a *.jar file can only have
one main file. So, if you have multiple targets, they need to be
packaged each into a different *.jar file. They can be in one *.jar file
but then you have to start them explicitly, which gets you back to the
problems that I mentioned before. This brings me to the ugly part. If
you have just one target, then you are all set. If you have multiple
targets, you need to create a *.jar file for each of them. In addition,
you have a much harder time setting the classpath, because each of the
*.jar files that contain supporting code must be listed. In fact, at
present there is no way of setting this during the installation, because
IzPack does not yet (version 3.0) support the setting and modification
of environment variables.
Before I start to write a lot about the use of command line arguments
let me state this: If you can avoid using them, do it! Not that there
is anything wrong with command line arguments as such. The issue is
simply that if you want your application to be usable cross platform
(the big Java promise) you should shy away from using command line
arguments. The problem here is that not all operating systems actually
support command line arguments. To be more precise, to my knowledge only
Apple operating systems do not support command line parameters. If you
don't care for running your application on a Mac, then you might not
worry about his at all. If you are interested to support the Mac as
well, read on.
In fact the Mac supports command line parameters in a way. More to the
point, it supports a single parameter that your application should
interpret as the name of a data file to open. You have no way of
supplying this to your application through the command line attribute.
The operating system generates this when the user drops the file on your
application and then passes it as command line argument. That's it. This
same behavior will probably fly well on pretty much any system and
should therefore be an ok implementation.
So what to do if you want to modify program behavior based on runtime
switches? For one thing, you could set system properties accordingly.
The drawback here is the same as with the command line parameters: the
way of setting these might vary between operating systems. The best way
seems to be using a property file that contains the configuration
data.
It has been some time since I wrote this chapter during which a good
number of users had a chance to gather experience. Unfortunately I
never know how many have used it successfully without much difficulty. I
only hear from those that have encountered one problem or another. The
type of problems that I have seen prompted me to write this section,
because I think it will help you in locating most problems that you might
encounter or at least give you some idea where the problem might be
located.
If you see an exception that essentially says that a library can not be
loaded (ShellLink.dll) you have an easy problem to deal with. Your
installer file is probably missing the native tag that adds the Windows
dll to the installer or something with this tag is no quite right. Read
'What to Add to the Installer' for all details on this topic.
Most other problems cause the ShortcutPanel not to show at all during
the installation process. The reason is simply that the ShortcutPanel
skips if it does not know what to do or if it has nothing to do (no
point showing then and confusing the user). The problem is that this is
not always what you intended. In the most simple but not so uncommon
case the ShortcutPanel cannot find the spec file. This can be caused by
a number of reasons. The associated resource tag might be missing in the
installer specification, the target file name might be misspelled (the
name you specify for the id attribute) or the target file name
has a path or package name prepended. Just use
textttshortcutSpec.xml and nothing else, just as described in 'What
to Add to the Installer'. You can always verify if this part is ok by
inspecting the content of the installer *.jar file. The file
shortcutSpec.xml should be located in the directory res. This
inspection can be performed with any zip tool. If the file is not there,
first correct this before proceeding.
If the file is there and the panel does not show you have a problem
within the specification file. In most cases that I have seen, it comes
down to a spelling mistake of an attribute or tag name. You just have to
carefully make sure that everything is spelled correctly. Don't forget
that all names are case sensitive! In a few cases it has also turned out
that required or semi-optional attributes are omitted, so you might want
to verify if all attributes that you need are actually supplied.
If everything is correct up to this point the problem becomes more
elusive. Most likely the panel does not show because it is instructed
not to show. There are be several possible reasons for this. The simple
case is that no location has been specified for the shortcuts in your
installation. This can happen if all five location attributes are
omitted or if all the ones that are listed are set to no.
Remember, you must specify at least one location for every shortcut. If
this is also correct, you might have used the <creatForPack> tag. Review
the details in 'Selective Creation of Shortcuts'. One possibility for
the panel not to show is that based on the packs that are actually
selected for installation no shortcut qualifies for creation. In this
case the panel will not show, this is perfectly normal behavior. More
likely this condition is true because of some accident and not because
it's intended. Make sure the packs that you list for the shortcut are
actually defined in your installation and verify that they are all
spelled correctly. Remember: case matters! Did the ShortcutPanel use to
work in your installation and all of a sudden stopped working? Very
likely you are dealing with the last problem. A package name might have
been modified and the shortcut spec was not adjusted to stay in synch.
Unfortunately one problem has been very persistent and only recently one
user found the reason. The problem occurs when installing on some target
systems where non-English characters are used in the storage path for
the shortcuts. The problem is that these characters don't seem to be
properly translated across the Java Native Interface. This leads to a
situation where the proper path can not be located and the shortcut
creation fails. I write 'some target systems' because it does not fail
everywhere. After much agonizing over this problem, one user found the
solution: The shortcut creation works fine if a Sun virtual machine is
installed, but fails if a version from IBM happens to be installed. So
far I have no solution for this problem but I am trying to find a
workaround the problem.