Applet Mode

https://github.com/threerings/getdown/wiki/Applet-Mode

——————————————————————————————————————————————————————————

如何以Applet模式运行Getdown。

以签名Applet模式运行Getdown，并下载和运行应用是可能的，这样可以提供一种”in the web browser“的体验。甚至可以让Getdown在同一个JVM（Getdown运行的JVM）中运行应用，允许应用占据Getdown窗口，这样可以提供一个非常像applet的体验。

Signing

因为Getdown必须以签名applet运行，这样它才有权限写入用户的文件系统并运行一个单独的JVM，所以你必须使用一个code signing certificate来签名getdown-client.jar文件。

Getdown是一个通用的启动机制，因此需要使用同样的签名来签Getdown的元数据，否则Getdown可以被任何人以你的签名运行任意程序，这是很糟糕的。

注意Getdown的签名必须是RSA，而不是DSA，用keytool生成签名时默认是DSA，确保传入-keyalg rsa参数。

Applet tag

以applet模式运行Getdown需要创建applet标签，包含基本的元数据，部分元数据会与getdown.txt文件中的重复，以允许applet启动更快一点，并提供更好的用户UI。

下面是applet标签的例子：

<object height="253" width="424" type="application/x-java-applet;version=1.5"
        archive="http://myapp.com/client/getdown-client.jar">
  <param name="archive" value="http://myapp.com/client/getdown-client.jar"/>
  <param name="code" value="com.threerings.getdown.launcher.GetdownApplet"/>
  <param name="appname" value="myapp"/>
  <param name="appbase" value="http://myapp.com/client/"/>
  <param name="bgimage" value="http://myapp.com/client//background.png"/>
  <param name="errorbgimage" value="http://myapp.com/client/background_error.jpg"/>
  <param name="ui.status" value="30, 60, 364, 80"/>
  <param name="ui.status_text" value="FFEC48"/>
  <div class="nojava">You must first install Java to play this game in your browser!</div>
</object>

大部分applet标签是标准的，包括属性width, height, type, archive, code等，Getdown特有的参数如下：

appname

用于决定应用数据被存储的目录名称的标识，随操作系统不同而不同

• Windows Vista: %HOME%\AppData\LocalLow\myapp\
• Windows XP, etc.: %HOME%\Application Data\myapp\
• Mac OS: $HOME/Library/Application Support/myapp/
• Linux: $HOME/.getdown/myapp/


appbase

与getdown.txt中的appbase相同，用于下载getdown.txt文件以获得所有其他的应用数据。

bgimage, errorbgimage

These should be fully qualified URLs that reference the same images in the ui.background and ui.error_background configuration values from the getdown.txt file. They are duplicated here so that the applet can immediately display a branded user interface without having to first download the getdown.txt file.

ui.status, ui.status_text

These should contain the same values as those specified in the getdown.txt file. These values are only used if there is a problem downloading the getdown.txt file, at which point Getdown needs to display feedback to the user and needs to know where on the errorbgimage to render that feedback.

jvmargN and appargN

You can augment the jvmarg and apparg configuration in getdown.txt with applet parameters (which can be dynamically generated when the user requests the page that contains the <applet> tag).

To do so, simply add jvmargN or appargN <param> tags with increasing values for N. For example:

<object ...>
  <param name="jvmarg0" value="-Xmx256M"/>
  <param name="jvmarg1" value="-Dsun.java2d.opengl=true"/>
  <param name="apparg0" value="--username"/>
  <param name="apparg1" value="someusername"/>
</object>

Note that the jvmarg and apparg configuration specified in the applet tag will appear after the jvmarg and apparg configuration from the getdown.txt file, on the command line.

Signature File

除了要对getdown-client.jar文件签名外，还必须为digest.txt生成签名文件，这可以在生成digest.txt的同时完成。很简单，提供你的Keystore的路径、密码、以及使用的key的别名给Ant的<digest>任务：

<taskdef name="digest" classname="com.threerings.getdown.tools.DigesterTask"
         classpathref="getdown.classpath"/>
<property file="certificate.properties"/>
<digest appdir="${app_dir}" keystore="${sign.keystore}" storepass="${sign.storepass}"
        alias="${sign.alias}"/>

就像你看到的一样，我们推荐你保存敏感的元数据信息到单独的属性文件中，以确保它不会被提交到版本管理系统中，或者泄露给外部的团体，certificate.properties包含下面的数据

sign.keystore = /path/to/keystore.dat
sign.storepass = s3cr3t
sign.alias = mycompanyalias

这样将会生成digest.txt.sig文件，必须放在digest.txt文件同目录。applet将会下载该文件来校验digest.txt文件的内容，如果不能找到digest.txt.sig文件，或者签名不匹配，applet将拒绝运行程序。

因为digest.txt包含了组成应用的所有代码和资源的加密散列值，这意味着别人不可能使用你签名过的getdown-client.jar去做任何除运行你签名过的应用的其他事情。

注意每次更新应用后都必须生成新的digest.txt.sig文件，以及新的digest.txt文件。

Signing getdown-client.jar

Signing the getdown-client.jar file is easily accomplished using the signjar Ant task (which is included with the standard Ant distribution). Here is an example:

<property file="certificate.properties"/>
<signjar keystore="${sign.keystore}" alias="${sign.alias}" storepass="${sign.storepass}">
  <fileset dir="${app_dir}" includes="getdown-client.jar"/>
</signjar>

We assume you have a certificate.properties file configured as described above.

Ensuring User Has Java Plugin

Running Getdown as an applet is predicated on the user having at least Java 1.5 installed on their computer and properly configured as a browser plugin. The applet tag we have shown above should trigger the process of installing the Java plugin if the user does not already have it installed.

Note that we only require JDK 1.5 in our <object> tag above, you may wish to require JDK 1.6, or you may want to use Getdown's support for running intself in a 1.5 JDK and then automatically downloading and installing a 1.6 (or newer) JDK as a part of the application download process. See the documentation on getdown.txt for details.