JNLP ファイルの構文

この章では、次のトピックについて説明します。

• はじめに
• 例
• JNLP の要素
  • jnlp 要素
  • information 要素
  • related_content 要素
  • security 要素
  • resources 要素
  • application-desc 要素
  • applet-desc 要素

はじめに

このリリースで使用している形式は、「Java Network Launching Protocol & API Specification (JSR-56) version 1.5」に指定されている形式と同じです。このガイドでは、JNLP ファイルでもっともよく使われる要素について説明しています。この形式の完全な説明については、仕様を参照してください。

JNLP ファイルは XML ドキュメントです。以下に、JNLP ファイルの完全な記述例を示します。

例

<?xml version="1.0" encoding="utf-8"?>
<!-- JNLP File for SwingSet2 Demo Application -->
<jnlp
  spec="1.5+"
  codebase="http://my_company.com/jaws/apps"
  href="swingset2.jnlp">
  <information>
    <title>SwingSet2 Demo Application</title>
    <vendor>Sun Microsystems, Inc.</vendor>
    <homepage href="docs/help.html"/>
    <description>SwingSet2 Demo Application</description>
    <description kind="short">A demo of the capabilities 
of the Swing Graphical User Interface.</description>
    <icon href="images/swingset2.jpg"/>
    <icon kind="splash" href="images/splash.gif"/>
    <offline-allowed/> 
    <association>
      <mime-type="application-x/swingset2-file"/>
      <extensions="swingset2"/> 
    </association>
    <shortcut online="false">
      <desktop/>
      <menu submenu="My Corporation Apps"/>
    </shortcut>
  </information>
  <information os="linux">   
    <title> SwingSet2 Demo on Linux </title>
    <homepage href="docs/linuxhelp.html">
  </information>
  <security>
      <all-permissions/>
  </security>
  <resources>
    <j2se version="1.4.2+" java-vm-args="-esa -Xnoclassgc"/>
    <jar href="lib/SwingSet2.jar"/>
  </resources>
  <application-desc main-class="SwingSet2"/>
</jnlp> 

この例は、このドキュメントの基本構造を示したものです。ルート要素は jnlp ですが、この要素には、4 つのサブ要素 information、security、resources、および application-desc を定義できます。さらに、Java Web Start はアプレットの起動もサポートしています。その場合、applet-desc 要素 を使用します。これらの要素について、以下で詳しく説明します。

JNLP の要素

jnlp 要素

spec 属性: この属性が 1.0 以上でないと、このリリースで正しく動作しません。デフォルト値は「1.0+」です。したがって、通常はこの属性を省略してもかまいません。 このバージョンは、バージョン 1.0 と 1.5 の両仕様をサポートしていますが、以前のバージョンでは 1.0 しかサポートされていません。 spec="1.5+" を指定する jnlp ファイルは、このバージョンで動作しますが、以前のバージョンの Java Web Start では動作しません。

codebase 属性: JNLP ファイルの href 属性に指定された相対 URL はすべて、この URL を基準として処理されます。

href 属性: これは、JNLP ファイル自体の格納場所を示す URL です。

information 要素

title 要素: アプリケーションの名前。

vendor 要素: アプリケーションベンダーの名前。

homepage 要素: 単一の属性 href を含みます。これは、アプリケーションのホームページを示す URL です。この要素は、Java アプリケーションキャッシュビューアが、アプリケーションの詳細情報を含む Web ページにユーザをリダイレクトする際に使用されます。

description 要素: アプリケーションに関する短い description。description 要素は省略可能です。kind 属性は、description の用途を定義します。指定可能な値は、次のいずれかです。

• one-line: アプリケーションへの参照をリストまたは表の 1 行に表示する場合に、この description が使用されます。
• short: アプリケーションへの参照を表示する際に 1 段落分のスペースが取れる場合に、この description が使用されます。
• tooltip: アプリケーションへの参照をツールヒント内に表示する場合に、この description が使用されます。

個々の種類に対して指定可能な description 要素は、1 つだけです。kind 属性を含まない description 要素は、デフォルト値として使用されます。したがって、Java Web Start が short の種類の description 要素を必要としているが、それが JNLP ファイル内に指定されていなかった場合、属性を含まない description 要素のテキストが使用されます。

description 要素に含まれるテキストは、プレーンテキストでなければなりません。HTML タグなどを含む形式はサポートされていません。

icon 要素: GIF 形式または JPEG 形式のイメージファイルへの HTTP URL を含みます。これらのアイコンは、次の場合にアプリケーションを表現するために使用されます。

• アプリケーション起動時に Java Web Start がアプリケーションをユーザに表示する際
• Java アプリケーションキャッシュビューア内
• デスクトップショートカット内

ダウンロード中は 64x64 のアイコンが表示され、Java アプリケーションキャッシュビューア内とデスクトップショートカット内では 32x32 のアイコンが使用されます。Java Web Start は、アイコンのサイズ変更を必要に応じて自動的に行います。

省略可能な属性 width と height を使えば、イメージのサイズを指定できます。

省略可能な属性 kind="splash" を icon 要素内に指定すれば、そのイメージがアプリケーション起動時の「スプラッシュ」画面用だと示すことができます。 JNLP ファイルに kind="splash" 属性を持つアイコン要素が含まれていない場合、Java Web Start は information 要素の他の項目を使用してスプラッシュ画面を構築します。

JNLP ファイル内に icon イメージが 1 つも存在しなかった場合、スプラッシュイメージは、JNLP ファイルから取得されたアプリケーションのタイトルとベンダーで構成されます。

JNLP ファイルの icon 要素を追加または変更したあと初めてアプリケーションを起動する際には、以前のスプラッシュイメージが表示されます。2 回目以降のアプリケーション起動では、新しいスプラッシュイメージが表示されます。

offline-allowed 要素: 省略可能な offline-allowed 要素は、オフラインでのアプリケーション起動を許可するかどうかを示します。

offline-allowed が指定されている場合、Java アプリケーションキャッシュビューアでアプリケーションをオフラインで起動できます。またアプリケーションをオフラインで起動するショートカットを作成できます。

アプリケーションをオフラインで起動した場合、更新のチェックは行われません。また、API 呼び出し BasicService.isOffline() は true を返します。

また、offline-allowed 要素は、Java Web Start がアプリケーションの更新をチェックする方法も制御します。この要素が指定されていない場合 (つまり、アプリケーションをオンラインで実行する必要がある場合)、Java Web Start は常に、更新版があるかどうかをチェックしたあとでアプリケーションを起動します。更新版が見つかった場合は、その新しいアプリケーションをダウンロードおよび起動します。したがって、ユーザが実行するアプリケーションが常に最新版であることが保証されます。ただし、オフラインの場合、アプリケーションを実行することはできません。

offline-allowed が指定されている場合も、Java Web Start は更新版があるかどうかをチェックします。ただし、アプリケーションがダウンロード済みであった場合、そのチェック処理は数秒でタイムアウトになります。タイムアウトになった場合、キャッシュ済みのアプリケーションが代わりに起動されます。サーバとの接続がある程度高速であれば、たいていは最新版のアプリケーションが実行されるはずですが、保証はありません。ただし、アプリケーションはオフラインで実行できます。

shortcut 要素: 省略可能な shortcut 要素を使用すると、アプリケーションのデスクトップの統合に対する優先性を示すことができます。shortcut 要素とそのサブ要素は、JNLP Client が使用する可能性のあるヒントを提供します。shortcut 要素には省略可能な online 属性と、2 つのサブ要素 desktop、menu が含まれます。

association 要素: 省略可能な association 要素は、オペレーティングシステムに特定の拡張子のプライマリハンドラとして、また特定の MIME タイプとしての登録を行いたい JNLP クライアントへのヒントです。association 要素には必ず拡張子と MIME タイプ属性が割り当てられます。

related-content 要素: 省略可能な related-content 要素は、README ファイル、ヘルプページ、登録ページへのリンクなどの関連コンテンツの追加要素を、JNLP Client へのヒントとして説明します。アプリケーションは、このコンテンツをデスクトップ統合に含めるように要求します。related-content 要素には、href と title の必須属性が割り当てられています。次の 2 つのサブ要素のいずれかを割り当てることもできます。

• description 要素: 関連コンテンツの簡単な説明
• icon 要素: JNLP Client がユーザへの関連コンテンツを識別するために使用するアイコン

security 要素

各アプリケーションはデフォルトで、アプレットのサンドボックスに類似した、制限されたランタイム内で実行されます。 security 要素を使えば、無制限のアクセス権限を要求できます。

all-permissions 要素が指定された場合、アプリケーションはクライアントマシンとローカルネットワークに対する完全なアクセス権を持ちます。完全なアクセス権を要求するアプリケーションでは、すべての JAR ファイルに署名する必要があります。アプリケーションの初回起動時に、ユーザは証明書への同意を求められます。

resources 要素

resources 要素を使えば、Java クラスファイル、ネイティブライブラリ、システムプロパティなど、アプリケーションの一部となるあらゆるリソースを指定できます。 リソース定義を、特定のオペレーティングシステム、アーキテクチャ、またはロケールに限定することも可能です。それには、os、arch、locale の各属性を使用します。

resources 要素に指定可能なサブ要素は、jar、nativelib、j2se、property、package、extension の 6 つです。この開発者ガイドでは、package 要素と extension 要素については説明しません。詳細については、「Java Network Launching Protocol & API Specification (JSR-56) version 1.5」を参照してください。

jar 要素には、アプリケーションのクラスパスに含める JAR ファイルを指定します。 次に例を示します。

  <jar href="myjar.jar"/>

jar ファイルは、ClassLoader オブジェクトを使って JVM 内にロードされます。 jar ファイルには通常、特定のアプリケーションのコードを含む Java クラスが格納されますが、アイコンや設定ファイルなど、その他のリソースを格納することも可能です。そうしたリソースを取得するには、getResource メカニズムを使用します。

nativelib 要素には、ネイティブライブラリを含む JAR ファイルを指定します。 次に例を示します。

    <nativelib href="lib/windows/corelib.jar"/>

JNLP クライアントは、JAR ファイルのルートディレクトリ (/) 内にある各ファイルエントリを、System.loadLibrary メソッドを使って実行中のプロセス内にロードできることを確認する必要があります。 各エントリには、適切な命名規約 (Windows の場合は *.dll、Solaris/Linux の場合は lib*.so) に準拠した、プラットフォームに依存する共有ライブラリを含める必要があります。 System.loadLibrary への呼び出しを実際に行うのは、アプリケーションの役目です。

ネイティブライブラリは通常、特定のオペレーティングシステムやアーキテクチャに特化した resources 要素内に含まれます。 次に例を示します。

    <resources os="SunOS" arch="sparc">
        <nativelib href="lib/solaris/corelibs.jar"/>
    </resources>

jar リソースと nativelib リソースは、デフォルトですぐにダウンロードされます。つまり、アプリケーションが起動される前にダウンロードされ、アプリケーションを実行する JVM からローカルで利用できる状態になります。 jar 要素と nativelib 要素では、リソースを lazy として指定することもできます。 これは、アプリケーションの起動前にクライアントシステムにリソースをダウンロードする必要がないことを意味しています。

download 属性を使えば、リソースのダウンロードをすぐに行うか、またはあとで行うかどうかを制御できます。 次に例を示します。

    <jar href="sound.jar" download="lazy"/>
    <nativelib href="native-sound.jar" download="eager"/>

j2se 要素には、アプリケーションがサポートする Java 2 SE Runtime Environment (JRE) のバージョンと、Java 仮想マシンへの標準パラメータを指定します。複数の JRE が指定されている場合は、それは、サポートされている JRE の優先リストを示しており、もっとも優先順位の高いバージョンが最初に指定されています。次に例を示します。

       <j2se version="1.3" initial-heap-size="64m" max-heap-size="128m"/>
       <j2se version="1.4.2+" href="http://java.sun.com/products/autodl/j2se" java-vm-args="-esa -Xnoclassgc"/>

version 属性は、デフォルトで Java 2 プラットフォームのプラットフォームバージョン (仕様バージョン) を参照します。現時点で定義されているプラットフォームバージョンは、1.2、1.3、1.4 および 1.5 です (通常、プラットフォームバージョンには、マイクロバージョン番号（たとえば 1.4.2）は含まれない)。

正確な製品バージョン (実装バージョン) を、href 属性を使用して指定することもできます。たとえば、1.3.1_07、1.4.2、または 1.5.0-beta2 のようになります。以下のように指定します。

<j2se version="1.4.2" href="http://java.sun.com/products/autodl/j2se"/

または

<j2se version="1.4.2_04" href="http://java.sun.com/products/autodl/j2se"/>

プラットフォームバージョンが指定された場合 (つまり、href 属性が指定されなかった場合)、Java Web Start は、インストール済みの非 FCS (マイルストン) の JRE を、要求に一致するものとみなしません。次に例を示します。

<j2se version="1.4+"/>

この場合、1.4.1-ea や 1.4.2-beta の JRE がインストールされていても、それらは要求に一致する JRE とはみなされません。Sun Microsystems, Inc. が提供する JRE では、1.3.0 以降、非 FCS (マイルストン) のバージョン文字列にはダッシュ (-) を含めることになっています。

j2se 要素の java-vm-args 属性は、Java の起動時に優先的に使用される仮想マシンの一連の引数を指定します。

<j2se version="1.4+" java-vm-args="-ea -Xincgc"/>

このバージョンでは、次の java-vm-args がサポートされます。

-client
-server
-verbose
-showversion
-esa
-enablesystemassertions
-dsa
-disablesystemassertions
-Xmixed
-Xint
-Xnoclassgc
-Xincgc
-Xbatch
-Xprof
-Xdebug
-Xrs
-XX:+ForceTimeHighResolution
-XX:-ForceTimeHighResolution

また次のいずれかを先頭とする、任意の引数がサポートされます。

-ea:
-enableassertions:
-da:
-disableassertions:
-verbose:
-Xms
-Xmx
-Xss
-XX:NewRatio
-XX:NewSize
-XX:MaxNewSize
-XX:PermSize
-XX:MaxPermSize
-XX:MaxHeapFreeRatio
-XX:MinHeapFreeRatio
-XX:UseSerialGC
-XX:ThreadStackSize
-XX:MaxInlineSize
-XX:ReservedCodeCacheSize

property 要素はシステムプロパティを定義します。これらのプロパティは、System.getProperty、System.setProperties の両メソッドを使って取得できます。この要素では、2 つの属性 name と value を必ず指定する必要があります。次に例を示します。

<property name="key" value="overwritten"/>

jnlp ファイルに設定されるプロパティは、通常は VM が起動してからアプリケーションが呼び出されるまでの間に、Java Web Start により設定されます。「安全」と見なされたプロパティは、Java 呼び出しコマンド行で引数「-Dkey=値」と指定して渡すことができます。

次のプロパティは「安全」と見なされ、次の方法で VM に渡されます。

sun.java2d.noddraw
javaws.cfg.jauthenticator
swing.useSystemFontSettings
swing.metalTheme
http.agent
http.keepAlive

信頼されていないアプリケーションの場合、JNLP ファイルに設定されるシステムプロパティは、これらが安全と見なされる場合、またはプロパティ名が「jnlp.」または「javaws.」で始まる場合にのみ Java Web Start で設定されます。

application-desc 要素

application 要素は、JNLP ファイルの起動対象が、アプレットではなくアプリケーションであることを示します。application-desc 要素には main-class 属性を指定できます。省略可能なこの属性を使えば、アプリケーションのメインクラス (最初に実行すべき public static void main(String argv[]) メソッドを含んでいるクラス) の名前を指定できます。

main-class 属性を省略できるのは、JNLP ファイル内に指定された最初の JAR ファイルに main クラスを含むマニフェストファイルが格納されている場合です。

アプリケーションへの引数を指定するには、1 つまたは複数の入れ子にされた argument 要素を含めます。次に例を示します。

  <application-desc main-class="Main">
    <argument>arg1</argument>
    <argument>arg2</argument>
  </application-desc>

applet-desc 要素

Java Web Start は、Java アプレットの起動をサポートします。このサポートにより、既存コードの Java Web Start への移行が容易になります。

アプレットを起動するには、application-desc 要素の代わりに applet-desc 要素を使用します。次に例を示します。

  <applet-desc
      documentBase="http://..."
      name="TimePilot"
      main-class="TimePilot.TimePilotApp"
      width="527"
      height="428">
    <param name="key1" value="value1"/>
    <param name="key2" value="value2"/>
  </applet-desc>

アプレットを構成する JAR ファイルは、アプリケーションの場合と同じく、resources 要素を使って記述します。documentBase を明示的に指定する必要があるのは、JNLP ファイルが HTML ページに埋め込まれないからです。その他の属性はそれぞれ、特定の HTML アプレットタグ要素に対応します。

code 属性の代わりに main-class 属性が使用されます。 main-class 属性には、Applet クラスの名前 (.class 拡張子は除く) を指定します。 メインの JAR ファイル内の Main-Class マニフェストエントリから Applet クラスが検索可能である場合、この属性を省略してもかまいません。

注: アプレットは、JAR ファイル内にパッケージ化しないと、Java Web Start で正しく動作しません。

その他の役に立つ例については、「JNLP API の使用例」を参照してください。