Codebase Determination

Java Rich Internet Applications Guide > Applet Developer's Guide > Codebase Determination

The following topics are covered:

Codebase Computation Rules
- Examples
Best Practices

Codebase Computation Rules

In a JNLP file, the codebase is an optional parameter to the <jnlp> tag. It is used both to locate resources described in that JNLP file, as well as to find the JNLP file itself. For technical reasons, Java Web Start is not able to refresh the contents of the JNLP file from the server unless an absolute codebase is specified.

A codebase is always provided by the browser, either because it was explicitly specified, or implicitly obtained from the location of the HTML document. This allows relative URLs to be used in JNLP files, which is very useful for moving an entire tree of content from one server to another.

JNLP files reference other JNLP files in a tree structure. The root JNLP file for a JNLP applet is referenced by an <applet> tag. The applet tag's codebase helps define the location of the root JNLP file.

The rules for codebase computation are as follows:

If an absolute codebase is specified in the JNLP file, it is used. This is required for backward compatibility reasons.
If the JNLP codebase is not specified, the directory containing the JNLP file is used.
Otherwise, merge the JNLP's codebase into the directory containing the JNLP file.

In simple Java terms, this can be expressed as

   URL new_codebase = new URL(current_jnlp_dir, current_jnlp_codebase);

This codebase computation is not an extension of JSR-56. JSR-56 does not restrict the codebase to be absolute, and therefore it may be relative.

Examples

Example 1:

   this JNLP's location:   http://someserver.example.com/this.jnlp
   this JNLP's codebase:   http://www.example.com/test/
   resulting codebase for
     parsing this JNLP:    http://www.example.com/test/

Example 2:

   this JNLP's location:   http://www.example.com/test2/this.jnlp
   this JNLP's codebase:   <none>
   resulting codebase for
     parsing this JNLP:    http://www.example.com/test2/

Example 3:

   this JNLP's location:   http://www.example.com/this.jnlp
   this JNLP's codebase:   codebasedir
   resulting codebase for
     parsing this JNLP:    http://www.example.com/codebasedir

Example 4:

Relative paths are used to refer to each nested JNLP, just as in a tree of HTML files.

   www.example.com/html/my_applet.html
     refers to: my_applet.jnlp
     codebase:  www.example.com/html

     my_applet.jnlp:
       codebase not specified
       inherits "www.example.com/html"
       references JNLP extension "jogl/jogl.jnlp"

     jogl/
       jogl.jnlp
       codebase not specified
       inherits "www.example.com/html/jogl"
         (the directory containing jogl.jnlp)
       references gluegen-rt/gluegen-rt.jnlp

       gluegen-rt/
         gluegen-rt.jnlp
         codebase not specified
         inherits "www.example.com/html/jogl/gluegen-rt"
           (the directory containing gluegen-rt.jnlp)

Best Practices

We recommend either:

Leaving the codebase empty for both the main or extension JNLP file, allowing the referencing JNLP file or <applet> tag to implicitly specify the codebase.
Specifying an absolute URL for the codebase of any main or extension JNLP file.