Project: www.peterbuettner.de/projects/shelljar
This document: www.peterbuettner.de/projects/shelljar/specification.html
State: work in progress.
Last change: 18. August 2003
Purpose:
An Icon which may be used by the gui shell for the jar file.
Like the fileicons in the windows explorer or kde konqueror.
The icon is in a subfolder '/shell-meta-inf/icons' and is named 'icon.ico'. The format is the windows icon-format. It may contain alpha-channel icons.
Purpose:
This small text (about ~100 chars) may be used by the shell for tooltips,
subtitles or similar. It may be combined by the shell with other info like
filedate, filesize etc.
The description is stored as text items in the file '/shell-meta-inf/description'. There may be different languages in this file. The data for one language is stored in one item.
An example for some languages:
default=Default language description en=English description de=German description en_US=English description in US variant.
The language/sublanguage codes are the common java ones. If a 'lang_SUB' enty is not found 'lang' is used. If a suitable entry is not found the one named 'default' is used, if this doesn't exists no description is used.
Purpose:
Version is more technical info, but understandable by end users. Items as
'version', 'company', 'copyright'. Since it is more technical, there is only one
version for all languages.
The version is stored as text items in the file '/shell-meta-inf/version'. It consists of a unlimited number of items. There are some predefined names which should be preferred, but you can use any name you find conveniant. Here an example:
Version=4.0.1234.1 Description=The special purpose library Copyright=(c) Megacompany 2003 Company= Internalname= Originalname= Productname= Language=
Purpose:
Deposition of various start options, as usual they may be totaly ignored by a platform, see
them as 'nice to have'.
The file is named '/shell-meta-inf/startoptions' and contains text items. Every item may switch on some behavior/capabilities. The name is the option. List of options follows:
Purpose:
If one starts the java program with filenames as parameters, this 'commandline'
may be limited by the operating system (e.g: Win2k: ~2000, Win95: ~500 chars). Now a jar can define
an option 'org.jarshell.start.filenames' so that the jar may be called with the name of one
temporary file which contains those parameters.
The temporary file has to be deleted by the java program.
The file is a Binary String List. Each filename is one entry.
Be prepared to find any chars in filenames.
The jar is started 'normally', without parameters, but with a defined System.property:
org.jarshell.start.filenames=TempFileName
Note that this construct may not always used by your plattform. It works e.g. on windows if the
user drops files on the jar or 'send files' to a jar in the 'SendTo-Folder', but
any other process who want to start a jar has to work this out itself (maybe there will be
some helper function in the shellextension dll).
The plattform may not implement this feature at all. In this case e.g. files dropped on a
jar in the Windows explorer are appended to the commandline when starting the jar.
Purpose:
See org.jarshell.start.filenames, but this is for urls.
Urls like: 'http:', 'ftp:', 'mailto:', 'news:', 'file:', ...
The temporary file has to be deleted by the java program. The file is a Binary String List. Each url is one entry. Be prepared to find any chars. The value of this option may restrict used url types:
org.jarshell.start.urls=file,http
but this restriction may be ignored by the shell.
The jar is started 'normally' without parameters, but with a defined System.property:
org.jarshell.start.urls=TempFileName
Purpose:
This is a helper for other options which read data from a filename.
With this option, the data may be transfered via stdin to the java program.
If 'org.jarshell.start.stdin' is defined, the jar signals it is also able to read the data from stdin. If the plattform is unable to provide this, the option is ignored. Else the corresponding System.property is defined to the value '-' and not TempFileName
org.jarshell.start.urls=- or org.jarshell.start.filenames=-
Be aware that a plattform may be unable to display the full unicode range, or not even more than the ASCII range. The length of displayed data may be limited, \t and \n may be displayed or ignored (seen as whitespace). You probably know which platforms are targets for your application (desktop, mobile PCs like Palm, mobile phones) and can limit the used space and requirements. The versioninfo e.g. may do it without full unicode text.
Purpose is easy transfer of a list of strings without \t\r\n\0 mess, easy and fast machine readable.
BSL consits of Multiple StringEntries.
A StringEntry is a 4-byte length value (high byte first), followed by the utf-8 coded String.
The end of a BSL may be marked by an 0 length value (== a 4 byte zero), but in some
context where empty Strings are used, the number of Entries may be contextdependent (e.g. filesize).
Binary String List ::= {StringEntry} [EndMarker]
StringEntry ::= LengthValue StringUtf8
LengthValue ::= '4-byte unsigned int, high byte first' // value is length of the encoded String (follows)
StringUtf8 ::= 'utf-8 encoded String' // no end marker char
EndMarker ::= '4 bytes all 0x00'
There will be portable code for reading the icon-format which delivers data in the bmp format (windows bitmap). This format is mostly easy to read, and i hope there already exists tested portable code.
Later, there may be other icons, specially named for themes or different gui shell like 'icon-kde.ico' 'icon-gnome.ico'
There will be java classes to read the info (at least the text info) from a java program. Maybe some Swing classes to show the versioninfo.
| Name | Description |
|---|---|
| Version | should be in the form 'a.b.c.d'. a..d are numbers |
| Description | different from the info above in description, here more technical like 'xyz plugin for uvw Editor' |
| Copyright | e.g.: 'Copyright (C) 2003 Mysoft Company', or from Mozilla.exe: 'License: MPL 1.1/GPL 2.0/LGPL 2.1' |
| Company | e.g. 'Mysoft, Germany' |
| Productiondate | Format: 'YYYY-MM-DD', the shell may Display this in the users preferred format |
| Productname | This jar may be part of a bigger product. |
| Originalname | The name of the file on delivery like 'myapp.jar' |
| Internalname | e.g.: 'appstarter', 'synctool' |
| Language | like: 'German', 'English', 'Neutral', 'Multi',... |
| mailto, http, news, support-phone, ... | Urls for contact and support. |
More suggestions for predefined names please!