1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="../../style.css" rel="stylesheet" type="text/css"/>
<title>JNLPAppletLauncher Home</title>
<link href="../../SocialCoding/logo_symbol_finals/website_final_blue_favicon_symbol_16x16pel.ico" rel="shortcut icon"/>
</head>
<body>
<div id="container">
<div id="header">
<div id="slogan">JNLPAppletLauncher</div>
<div id="logo"><a href="http://jogamp.org/"><img src="../../images/jogamp_symbols/website_final_blue_jogamp_346x70pel.png" alt="JogAmp Symbol"/></a></div>
</div>
<div id="menu">
<ul>
<li><a href="../../">Home</a></li>
<li><a href="../../gluegen/www/">Gluegen</a></li>
<li><a href="../../joal/">JOAL</a></li>
<li><a href="../../jogl/">JOGL</a></li>
<li><a href="../../jocl/">JOCL</a></li>
<li><a href="../../wiki/">Wiki</a></li>
<li><a href="../../blog/">Blogs</a></li>
<li><a href="../../forum.html">Forums</a></li>
</ul>
</div>
<div id="main">
<div id="sidebar">
</div>
<div id="text">
<h1>JNLPAppletLauncher</h1>
<h2>Overview</h2>
<p>
<!-- NOTE: to regenerate the text for this web page, copy the class
javadoc for the JNLPAppletLauncher and run an emacs macro over it
to remove the leading " *"s. -->
The JNLPAppletLauncher is a general purpose JNLP-based applet
launcher class for deploying applets that use extension libraries
containing native code. It allows applets to use extensions like
Java 3D, JOGL, and JOAL very easily, with just a few additional
parameters to the <code><applet></code> tag, on Java SE
versions as far back as 1.4.2.
<p>
Like Java Web Start, the JNLPAppletLauncher uses an extension's
.jnlp file to locate the native resources for a given extension.
The applet developer only needs to specify the platform-independent
.jar files containing the .class files for the extension. The
platform-specific "nativelib" .jar files are downloaded
automatically from the same server that hosts the extension's Java
Web Start binaries.
<p>
Extensions that support JNLPAppletLauncher include Java 3D, JOGL,
and JOAL. More can be added without needing to modify the
JNLPAppletLauncher. See the section below on <a
href="#MODIFYING">modifying extensions to work with the
JNLPAppletLauncher</a>.
<h2> How to Deploy Applets Using the JNLPAppletLauncher </h2>
<p>
The <code>applet-launcher.jar</code> file containing the
JNLPAppletLauncher class must be signed with the same certificate
as the extension's native resources, for example "sun microsystems,
inc.". The user will receive a security dialog and will be prompted
to accept the certificate for the JLNPAppletLauncher. The applet
being deployed may be either signed or unsigned; if it is unsigned,
it runs inside the security sandbox, and if it is signed, the user
receives a security dialog to accept the certificate for the applet
(in addition to the applet-launcher jar, if it is signed by a
different entity).
<p>
The steps for deploying such applets are straightforward. First,
the <code>archive</code> parameter to the applet tag must contain
<code>applet-laucher.jar</code>, the extension .jar files, and any
jar files associated with your applet. See the section on <a
href="#ORGANIZING">organizing jar files</a> for more details.
<p>
Second, the name of your applet's main class and a textual
description must be specified via the applet tag parameters
<code>subapplet.classname</code> and
<code>subapplet.displayname</code>.
<p>
Finally, the URLs for the extension .jnlp files being used must be
specified as parameters. The <code>jnlpNumExtensions</code>
parameter indicates the number of JNLP files that are referenced,
and for <code>n</code> such files, their URLs are passed in as
parameters <code>jnlpExtension1</code> ...
<code>jnlpExtension[n]</code>.
<h2><a name="ORGANIZING">Organizing Jar Files</a></h2>
<p>
Traditionally, applets are specified with a codebase and an archive
parameter, the latter which is a list of jar files relative to that
codebase. The codebase is optional and defaults to the directory on
the web server containing the HTML document which contains the
applet tag. See the documentation for the <a
href="http://java.sun.com/j2se/1.4.2/docs/guide/misc/applet.html">applet
tag</a>.
<p>
It is not well documented, but at least in the Sun JRE at least as
far back as Java SE 1.4.2, it is possible to use absolute URLs in
the applet tag's archive parameter. This functionality works on all
major operating systems: Windows, Mac OS X, Linux, and Solaris.
This means that you can pull code resources from multiple web
servers, not just one, in similar fashion to Java Web Start and its
extension mechanism. (The security implications are that each
unsigned piece of code downloaded from a separate server receives
sandboxed permissions to connect back to that server; if there are
multiple pieces of unsigned code on the stack during execution of
the program then the permissions will be the intersection of all of
those on the stack, implying that no programmatic network
connections back to the web server(s) will be allowed. See the <a
href="http://java.sun.com/sfaq/">Applet Security FAQ</a> for more
details.)
<p>
This capability means that your applets can refer directly to
extensions like Java 3D and JOGL hosted on Sun's web servers
without having to duplicate their jar files on your web server.
<p>
To use this capability effectively with the JNLPAppletLauncher, you
need to pull in at least three primary pieces of code: the applet
launcher itself, your applet's code, and the Java code for the
extension, or extensions, your applet depends on. (Remember that
the JNLPAppletLauncher's primary function is to automatically
download the native code associated with these extensions, and not
the Java code for these extensions.)
<p>
You might choose to specify the codebase of your applet to point to
your web server's directory containing the jar files of your
applet, and specify absolute URLs to the
<code>applet-launcher.jar</code> and the extension jar files. Or
you might decide to point the codebase to the server which hosts
the applet launcher and specify all of the other resources,
including your applet, with absolute URLs. Or you might decide to
use all absolute URLs in your archive tag with no codebase. The
techniques are basically equivalent. We recommend either pointing
the codebase to the directory containing your applet's jars, using
relative URLs for your applet, and using absolute URLs for all
other resources; or using all absolute URLs.
<p>
Alternatively, you can re-host the jar files and/or JNLP files and
nativelib jars for the extensions you use on your own web
server. This has the advantage that your applet will connect to
fewer web servers upon startup, but has the disadvantages of
requiring additional maintenance on your part and not automatically
receiving updates to the extensions when they are published.
<p>
<b>Note</b> that if you are planning to call into your applet from
JavaScript that there are some <a
href="#SCRIPTING">scripting-related caveats</a> that you need to be
aware of.
<p>
The <code>jnlpExtension</code> parameters passed to the
JNLPAppletLauncher must be specified with absolute URLs.
<p>
The <a href="#EXAMPLES">examples</a> show how to use the
JNLPAppletLauncher in a few different scenarios.
<h2>The codebase_lookup parameter</h2>
<p>
This applet parameter was not well documented until <a
href="http://java.sun.com/javase/6/docs/technotes/guides/plugin/developer_guide/special_attributes.html#codebase">recently</a>,
but it disables certain legacy behavior of the Java Plug-In. Before
the introduction of jar files, applets used to host their class
files and resources as flat files on the web server. Once jar files
were introduced, it was possible to improve the efficiency of
resource loading for applets, but (apparently) not without breaking
compatibility. An applet can specify the parameter
<pre>
<param name="codebase_lookup" value="false">
</pre>
<p>
to improve efficiency of its loading if it does not rely on
fetching flat files from the web server off the codebase.
We recommend setting this parameter.
<h2>Applets using the OpenGL(r) 3D API</h2>
<p>
Applets using the OpenGL 3D graphics API, for example through JOGL
or Java 3D, may encounter robustness issues on the Windows platform
because Sun's Java 2D implementation on Windows uses Microsoft's
DirectDraw API. DirectDraw and OpenGL are incompatible at the
driver level.
<p>
As a workaround for this problem, the JNLPAppletLauncher supports
disabling the use of DirectDraw. Currently this can only be done on
a global basis, for all applets, but doing so is unlikely to slow
down other non-3D applets significantly.
<p>
Specifying the applet parameter
<pre>
<param name="noddraw.check" value="true">
</pre>
<p>
will cause the applet launcher, when run on Windows, to check to
see whether DirectDraw is enabled and, if so, will prompt the user
with a dialog box asking to disable it. A browser restart is
required if the setting is changed.
<p>
If the dialog box is undesirable in a given situation, you can
force the noddraw check to always disable DirectDraw with the two
applet parameters:
<pre>
<param name="noddraw.check" value="true">
<param name="noddraw.check.silent" value="true">
</pre>
<p>
In this case it will not be obvious to the end user that a browser
restart might be required for best robustness, but you could
potentially document the need to try restarting the browser in case
of instability.
<h2><a name="SCRIPTING">Scripting Support</a></h2>
<p>
The JNLPAppletLauncher supports interaction with the sub-applet via
the <code>getSubApplet()</code> method. Calling this method from
JavaScript will return the subordinate applet with which you can
then interact via JavaScript.
<p>
There are currently some scripting-related caveats associated with
<a href="#ORGANIZING">pulling jar files from multiple locations</a>
for a particular applet. In particular, it appears that the
LiveConnect security model on Mac OS X in the Safari browser
prohibits JavaScript from one domain from communicating with Java
code (such as an applet) downloaded from another domain. This is
correct according to older versions of the LiveConnect
specification, although some more recent implementations of
LiveConnect allow this, restricting the privileges of such calls in
other ways.
<p>
The workaround for this problem seems to be to host the
<code>applet-launcher.jar</code> on your web site if you need to
talk to your applet from JavaScript. Your applet's jars will likely
also need to be hosted from the same web server. If you talk to
extension APIs in your <code>archive</code> tag directly from
JavaScript, you may find it necessary to host those jars on your
web server as well.
<p>
From a practical standpoint, most applet developers using
JavaScript with the JNLPAppletLauncher will only need to re-host at
most <code>applet-launcher.jar</code> on their web site.
<h2><a name="EXAMPLES">Examples</a></h2>
<p>
An applet using JOGL as an extension. Note that this example does
not specify a codebase, instead specifying all of its archive tag
elements with absolute URLs (split here for readability; in a real
applet tag they must be all on one line). Note also the use of the
<code>noddraw.check</code> parameter to disable the use of
DirectDraw since using JOGL implies the use of OpenGL.
<pre>
<applet code="org.jdesktop.applet.util.JNLPAppletLauncher"
width=600
height=400
archive="http://jogamp.org/deployment/util/applet-launcher.jar,
http://jogamp.org/deployment/webstart/nativewindow.all.jar,
http://jogamp.org/deployment/webstart/jogl.all.jar,
http://jogamp.org/deployment/webstart/gluegen-rt.jar,
http://jogamp.org/deployment/webstart/jogl-demos.jar">
<param name="codebase_lookup" value="false">
<param name="subapplet.classname" value="demos.applets.GearsApplet">
<param name="subapplet.displayname" value="JOGL Gears Applet">
<param name="noddraw.check" value="true">
<param name="progressbar" value="true">
<param name="jnlpNumExtensions" value="1">
<param name="jnlpExtension1"
value="http://jogamp.org/deployment/webstart/jogl-core.jnlp">
<param name="java_arguments" value="-Dsun.java2d.noddraw=true">
<param name="jnlp_href" value="applet-gears.jnlp">
</applet>
</pre>
<p>
An applet using both JOGL and JOAL as extensions. Note again that
all code resources are specified with absolute URLs. In this
example the unsigned applet pulls in code from both
<code>jogl-demos.jar</code> and <code>joal-demos.jar</code>. Note
again the use of the <code>noddraw.check</code> parameter.
<pre>
<applet code="org.jdesktop.applet.util.JNLPAppletLauncher"
width=600
height=400
archive="http://jogamp.org/deployment/util/applet-launcher.jar,
http://jogamp.org/deployment/webstart/nativewindow.all.jar,
http://jogamp.org/deployment/webstart/jogl.all.jar,
http://jogamp.org/deployment/webstart/gluegen-rt.jar,
http://jogamp.org/deployment/webstart/jogl-demos.jar,
http://download.java.net/media/joal/webstart/joal.jar,
http://download.java.net/media/joal/webstart/joal-demos.jar">
<param name="codebase_lookup" value="false">
<param name="subapplet.classname" VALUE="demos.applets.GearsJOALApplet">
<param name="subapplet.displayname" VALUE="JOGL / JOAL Gears Applet">
<param name="noddraw.check" value="true">
<param name="progressbar" value="true">
<param name="jnlpNumExtensions" value="2">
<param name="jnlpExtension1"
value="http://jogamp.org/deployment/webstart/jogl-core.jnlp">
<param name="jnlpExtension2"
value="http://download.java.net/media/joal/webstart/joal.jnlp">
</applet>
</pre>
<h2> Locations of Standard Extensions </h2>
<p>
This section describes how to set up the <code>archive</code> and
<code>jnlpExtension</code> parameters for a few standard
extensions.
<h4>JNLPAppletLauncher</h4>
<p>
The master jar file for the JNLPAppletLauncher is located at the following URL:
<pre>
http://jogamp.org/deployment/util/applet-launcher.jar
</pre>
<p>
This jar needs to be added to your archive parameter.
<h4>JOGL</h4>
<p>
JOGL 1.1.1-rc3 and later support the JNLPAppletLauncher. You will
need to add the following URL to your archive parameter:
<pre>
http://jogamp.org/deployment/webstart/nativewindow.all.jar
http://jogamp.org/deployment/webstart/jogl.all.jar
</pre>
<p>
Because JOGL depends on the GlueGen runtime, you will also need to
add the following URL to your archive parameter:
<pre>
http://jogamp.org/deployment/webstart/gluegen-rt.jar
</pre>
<p>
Finally, add the following to one of your
<code>jnlpExtension</code> parameters:
<pre>
http://jogamp.org/deployment/webstart/jogl-core.jnlp
</pre>
<p>
Note that the jogl.jnlp extension will automatically pull in the
native code associated with the GlueGen runtime, so you don't have
to separately refer to the gluegen-rt.jnlp file.
<h4>JOAL</h4>
<p>
JOAL 1.1.1 and later support the JNLPAppletLauncher. You will need
to add the following URL to your archive parameter:
<pre>
http://jogamp.org/deployment/webstart/joal.jar
</pre>
<p>
Because JOAL, like JOGL, depends on the GlueGen runtime, you will
also need to add the following URL to your archive parameter:
<pre>
http://jogamp.org/deployment/webstart/gluegen-rt.jar
</pre>
<p>
(If you are using both JOGL and JOAL, you only need to refer to
gluegen-rt.jar once in your archive parameter.)
<p>
Finally, add the following to one of your
<code>jnlpExtension</code> parameters:
<pre>
http://jogamp.org/deployment/webstart/joal.jnlp
</pre>
<p>
Note that the joal.jnlp extension will automatically pull in the
native code associated with the GlueGen runtime, so you don't have
to separately refer to the gluegen-rt.jnlp file.
<h2><a name="MODIFYING">Modifying Your Extension To Work With The JNLPAppletLauncher</a></h2>
<p>
If you are the author of an extension like JOGL which requires some
native code, with only a simple code change you can make your
extension work with the JNLPAppletLauncher. Simply add the
following method somewhere in your code:
<pre>
private static void loadLibraryInternal(String libraryName) {
String sunAppletLauncher = System.getProperty("sun.jnlp.applet.launcher");
boolean usingJNLPAppletLauncher =
Boolean.valueOf(sunAppletLauncher).booleanValue();
boolean loaded = false;
if (usingJNLPAppletLauncher) {
try {
Class jnlpAppletLauncherClass =
Class.forName("org.jdesktop.applet.util.JNLPAppletLauncher");
Method jnlpLoadLibraryMethod =
jnlpAppletLauncherClass.getDeclaredMethod("loadLibrary",
new Class[] { String.class });
jnlpLoadLibraryMethod.invoke(null, new Object[] { libraryName });
loaded = true;
} catch (ClassNotFoundException ex) {
System.err.println("loadLibrary(" + libName + ")");
System.err.println(ex);
System.err.println("Attempting to use System.loadLibrary instead");
} catch (Exception e) {
Throwable t = e;
if (t instanceof InvocationTargetException) {
t = ((InvocationTargetException) t).getTargetException();
}
if (t instanceof Error)
throw (Error) t;
if (t instanceof RuntimeException) {
throw (RuntimeException) t;
}
// Throw UnsatisfiedLinkError for best compatibility with System.loadLibrary()
throw (UnsatisfiedLinkError) new UnsatisfiedLinkError().initCause(e);
}
}
if (!loaded) {
System.loadLibrary(libraryName);
}
}
</pre>
<p>
and wherever you would call <code>System.loadLibrary()</code> (from
within an <code>AccessController.doPrivileged()</code> block) to
load your extension's native code, call the above
<code>loadLibraryInternal</code> method instead.
<p>
Note again that because the <code>applet-launcher.jar</code> and
the nativelib jars for all extensions must currently be signed with
the same certificate, this implies that you must resign both the
applet launcher as well as any other extensions your applet relies
on (unless yours is a Sun-standard extension and can be signed with
Sun's code signing certificate).
<h2>Acknowledgments</h2>
<p>
The JNLPAppletLauncher was developed by Kevin Rushforth, Kenneth
Russell, and Chien Yang. It is based on the earlier
JOGLAppletLauncher developed by Lilian Chamontin.
</div> <!-- text -->
</div> <!-- main -->
<div id="footer">
<div id="footer_left">
<span>JogAmp.org</span>
by <a href="http://jogamp.org">http://jogamp.org</a> is licensed under a <br/>
<a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 License</a>.
</div>
</div>
</div> <!-- container -->
</body>
</html>
|
