Appendix 5: Complete Example—Deploying Java Media Framework as Java Extension

This section covers the following topics:

Introduction

This is a complete, working example showing how to deploy a single jar file from Java Media Framework (JMF) as a Java Extension. The example uses SimplePlayerApplet.java and jmf.jar to play an .avi media file. It uses the raw installation method for installating a repackaged and signed version of jmf.jar called s_my_jmf.jar. Normally there are other jar files that are installed with JMF, but for SimplePlayerApplet.java only the functionality in jmf.jar is required.

For simplicity sake, this example makes the following assumptions:

Creating the jar File to Be Installed

In this case there is no installer. All you need to do is obtain the required jar file, jmf.jar, that needs to be downloaded and copied into <jre_location>/lib/ext. Plug-in, in conjunction with the extension mechanism in the JRE, handles the installation (downloading and copying of the file) for you.

You can get jmf.jar by downloading the cross-platform installation zip file jmf-2_1_1a-alljava.zip from http://java.sun.com/products/java-media/jmf/2.1.1/download.html. Along with other jar files, the zip file contains jmf.jar, which you can extract from the zip.

Once you have obtained jmf.jar, you will want to extract jmf.jar itself into some directory, say C:\plugin\extensions\workspace1. Here you will want to delete the META-INF directory, as the manifest.mf file contains signing information that you do not want.

Next you need to create your own manifest file for the new jar file to be based on jmf.jar. The manifest file that we create we call jmf_manifest. It will be provided as input to the jar tool. Here is what is used in this example:

Extension-Name: javax.media.s_my_jmf
Specification-Vendor: Sun Microsystems, Inc
Specification-Version: 2.1
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc
Implementation-Version: 2.1.1

First we will jar the files in jmf.jar and rename the result my_jmf.jar. Then we will sign the result and call it s_my_jmf.jar.

In order to jar the files in workspace1 with our new manifest file jmf_manifest, we cd to the locations of workspace1, then we use the jar tool in the SDK as follows:

C:\plugin\extensions\workspace1>C:\j2sdk1.4.0\bin\jar cmf jmf_manifest my_jmf.jar *.class codecLib com javax jmapps

Note that codecLib, com, javax, and jmapps are subdirectories that must be jar'd as well *.class.

In this example we use the jarsigner tool to sign the new jar file.

Assuming that we have a Thawte keystore called thawte.p12 located in C:\plugin\keystores with the same password, mypass, for both storepass and keypass, and storetype is "pkcs12" and the keystore alias is "Sun Microsystems Inc.'s Thawte Consulting cc ID", then we can sign my_jmf.jar as follows, creating a signed jar file called s_my_jmf.jar:

C:\plugin\extensions\workspace1>C:\j2sdk1.4.0\bin\jarsigner -keystore C:\plugin\keystores\thawte.p12 -storepass mypass -keypass mypass -storetype "pkcs12" -signedjar s_my_jmf.jar my_jmf.jar "Sun Microsystems Inc.'s Thawte Consulting cc ID"

We can verify the new signed jar file as follows:

C:\plugin\extensions\workspace1>C:\j2sdk1.4.0\bin\jarsigner -verify s_my_jmf.jar

We now have a signed jar file with the proper manifest.mf file for raw installation.

Next we need to create the applet jar file.


Creating the Applet jar file

The applet consists of a single file, SimplePlayerApplet.class, that can be used to playback a media file. The source code for the applet can be viewed here. What we need to do is create a manifest file called for the the applet, which we will call applet_manifest, jar the applet with the manifest, then sign the result..

The applet applet_manifest is as follows:

Extension-List: s_my_jmf 
s_my_jmf-Extension-Name: javax.media.s_my_jmf 
s_my_jmf-Specification-Version: 2.1 
s_my_jmf-Implementation-Version: 2.1.1
s_my_jmf-Implementation-Vendor-Id: com.sun 
s_my_jmf-Implementation-URL: http://java.sun.com/products/plugin/extensions/examples/jmf/s_my_jmf.jar

Note that the above manifest says that the extension jar, s_my_jmf.jar, can be downloaded from the java.sun.com web server at http://java.sun.com/products/plugin/extensions/examples/jmf

If the SimplePlayerApplet.class and applet_manifest are located in C:\plugin\workspace2, we can jar the applet with the manifest with the following command:

C:\plugin\extensions\workspace2>C:\j2sdk1.4.0\bin\jar cmf applet_manifest my_SimplePlayerApplet.jar *.class

Again, we use jarsigner to sign the jar file:

C:\plugin\extensions\workspace2>C:\j2sdk1.4.0\bin\jarsigner -keystore C:\plugin\keystores\thawte.p12 -storepass mypass -keypass mypass -storetype "pkcs12" -signedjar s_my_SimplePlayerApplet.jar my_SimplePlayerApplet.jar "Sun Microsystems Inc.'s Thawte Consulting cc ID"

and we verify it as follows:

C:\plugin\extensions\workspace2>C:\j2sdk1.4.0\bin\jarsigner -verify s_my_SimplePlayerApplet.jar

We now have our signed applet jar file called s_my_SimplePlayerApplet.jar, whose manifest contains the correct information to trigger the installation of the required extension jar file, s_my_jmf.jar if no such file or an older version is found in <jre_location>/lib/ext.

Next we need to create the HTML for the applet.

Creating the HTML for the Applet

We have several choices. We can use the conventional APPLET tag and assume those who visit the page have Java Plug-in version 1.3.1_01 or later installed on their systems. (To use Java Plug-in to launch an applet with the conventional applet tag requires 1.3.1_01 or later.) We can also use the HTML Converter, located in the SDK in the bin directory (<sdk_location>/bin/HtmlConverter.exe) to convert the applet to various forms. Here we have chosen to do both: SimplePlayerApplet-1.html uses the conventional applet form; SimplePlayerApplet-2.html is a converted format for both the OBJECT and EMBED tags that assumes dynamic versioning (clasdid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93") for the OBJECT tag and type="application/x-java-applet;jpi-version=1.4" for the EMBED tag for Plug-in 1.4.2).

The two forms are shown below:

SimplePlayerApplet-1.html

<html>
<head>
<title>SimplePlayerApplet</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<applet code="SimplePlayerApplet.class" archive="s_my_SimplePlayerApplet.jar" width=320 height=300>
<param name="file" value="0720crt1.avi">
</applet>
</body>
</html>

SimplePlayerApplet-2.html

<html>
<head>
<title>SimplePlayerApplet</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<!--"CONVERTED_APPLET"-->
<!-- HTML CONVERTER -->
<OBJECT
     classid = "clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
     codebase = "http://java.sun.com/products/plugin/autodl/jinstall-1_4-windows-i586.cab#Version=1,4,0,0"
     WIDTH = 320 HEIGHT = 300 >
     <PARAM NAME = CODE VALUE = "SimplePlayerApplet.class" >
     <PARAM NAME = ARCHIVE VALUE = "s_my_SimplePlayerApplet.jar" >
     <PARAM NAME = "type" VALUE = "application/x-java-applet;version=1.4">
     <PARAM NAME = "scriptable" VALUE = "false">
     <PARAM NAME = "file" VALUE="0720crt1.avi">

<COMMENT>
<EMBED
     type = "application/x-java-applet;version=1.4"
     CODE = "SimplePlayerApplet.class"
     ARCHIVE = "s_my_SimplePlayerApplet.jar"
     WIDTH = 320
     HEIGHT = 300
     file ="0720crt1.avi"
     scriptable = false
     pluginspage = "http://java.sun.com/products/plugin/index.html#download">
<NOEMBED>

</NOEMBED>
</EMBED>
</COMMENT>
</OBJECT>

<!--
<APPLET CODE = "SimplePlayerApplet.class" ARCHIVE = "s_my_SimplePlayerApplet.jar" WIDTH = 320 HEIGHT = 300>
<PARAM NAME = "file" VALUE="0720crt1.avi">

</APPLET>
-->

<!--"END_CONVERTED_APPLET"-->

</body>
</html>


Note that the media file is 0720crt1.avi.

For this example the following files have been placed on the java.sun.com web server at http://java.sun.com/products/plugin/extensions/examples/jmf:

Testing the Example

You can test the setup by pushing either of the buttons below:

When you point your browser at the URL, the applet jar will first be downloaded and cached; and, if the extension has not already been installed, you will see a Java Security Warming dialog that says: 'The applet requires the installation of optional package "javax.media.s_my_jmf" from http://java.sun.com/products/plugin/extensions/examples/jmf/s_my_jmf.jar'. You will have the options to Grant this session, Deny, or Grant Always. If you grant permission for installation, the extension will be installed in <jre_location>/lib/ext and the applet will run.