This document:

Shell & jar metainfo

Purpose of this specification is to enhance the shell interaction with java programs. Therefore developers may store some extra infos into a jar. This data is optional, the program has to be able to work without it.
Some general information about storing that extra data is described at the end of this document.

Current specification

State: work in progress.
Last change: 18. August 2003

Metainfo components


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.


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.


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:

Description=The special purpose library
Copyright=(c) Megacompany 2003

The list of predefined names.

Start options

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:

Start Option: org.jarshell.start.filenames

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


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.

Start Option: org.jarshell.start.urls

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:


but this restriction may be ignored by the shell.

The jar is started 'normally' without parameters, but with a defined


Start Option: org.jarshell.start.stdin

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 is defined to the value '-' and not TempFileName



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.

General data format and storage

Data storage

  1. All data is stored in files below the path '/shell-meta-inf/' inside the jar file.
  2. Filenames consist of ASCII-chars (between 0x20 and 0x80) but only lowercase chars, they are case sensitive.
  3. Textcontent
    1. Any textcontent is stored in utf-8 charset.
    2. The literal '\t' is translatetd to TAB; '\n' is translated to the plattform line-separator; '\\' becomes '\'; and any other combination stays unmodified ('\x' -> '\x').
    3. If a file consists of more than one line (see as: 1 Line is 1 record) the lines are separated by any combination of #13 or #10 with any length (e.g.: #10 #13 #13 #10 is one separator). #xx means the binary value xx in the textfile
    4. The linelength is unlimited.
    5. Text items is textcontent with items in the form 'name=value'
      1. Each item is on it's single line
      2. Names are casesensitive
      3. Values may be omitted. In this case the value of a name may be set to a special text, which depends on the context.

Other data structures

Binary String List (BSL)

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'

Textual info

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.


Predefined names for version

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'
Copyrighte.g.: 'Copyright (C) 2003 Mysoft Company', or from Mozilla.exe: 'License: MPL 1.1/GPL 2.0/LGPL 2.1'
Companye.g. 'Mysoft, Germany'
ProductiondateFormat: 'YYYY-MM-DD', the shell may Display this in the users preferred format
Productname This jar may be part of a bigger product.
OriginalnameThe name of the file on delivery like 'myapp.jar'
Internalnamee.g.: 'appstarter', 'synctool'
Languagelike: 'German', 'English', 'Neutral', 'Multi',...
mailto, http, news, support-phone, ...Urls for contact and support.

More suggestions for predefined names please!