Adobe 38000382 - Macromedia JRun - Mac User manual

JRun SDK Guide
sdk.book Page i Wednesday, April 17, 2002 2:28 PM

Trademarks
Afterburner, AppletAce, Attain, Attain Enterprise Learning System, Attain Essentials, Attain Objects for Dreamweaver, Authorware,
Authorware Attain, Authorware Interactive Studio, Authorware Star, Authorware Synergy, Backstage, Backstage Designer, Backstage
Desktop Studio, Backstage Enterprise Studio, Backstage Internet Studio, ColdFusion, Design in Motion, Director, Director
Multimedia Studio, Doc Around the Clock, Dreamweaver, Dreamweaver Attain, Drumbeat, Drumbeat 2000, Extreme 3D, Fireworks,
Flash, Fontographer, FreeHand, FreeHand Graphics Studio, Generator, Generator Developer's Studio, Generator Dynamic Graphics
Server, JRun, Knowledge Objects, Knowledge Stream, Knowledge Track, Lingo, Live Effects, Macromedia, Macromedia M Logo &
Design, Macromedia Flash, Macromedia Xres, Macromind, Macromind Action, MAGIC, Mediamaker, Object Authoring, Power
Applets, Priority Access, Roundtrip HTML, Scriptlets, SoundEdit, ShockRave, Shockmachine, Shockwave, Shockwave Remote,
Shockwave Internet Studio, Showcase, Tools to Power Your Ideas, Universal Media, Virtuoso, Web Design 101, Whirlwind and Xtra
are trademarks of Macromedia, Inc.andmay be registered inthe United States or in other jurisdictions including internationally. Other
product names, logos, designs, titles, words or phrases mentioned within this publication may be trademarks, servicemarks, or
tradenames of Macromedia, Inc. orother entities and may be registered in certain jurisdictions including internationally.
This product includes code licensed from RSA Data Security.
This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for
the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia
provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any
responsibility for the content on those third-party sites.
Apple Disclaimer
APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED
COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
THEEXCLUSIONOFIMPLIEDWARRANTIESISNOT PERMITTEDBYSOMESTATES.THEABOVEEXCLUSIONMAY
NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY BE OTHER
RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE.
Copyright © 1999–2002 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated,
or converted to any electronic or machine-readable form in whole or in part without prior written approval of Macromedia, Inc.
Part Number ZJR40M600
First Edition: May 2002
Macromedia, Inc.
600 Townsend St.
San Francisco, CA 94103
sdk.book Page ii Wednesday, April 17, 2002 2:28 PM

iii
CONTENTS
ABOUT THIS BOOK . . . . . . . . . . . . . . . . . . . . . . . . . . . VII
Developer resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
About JRun documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Printed and online documentation set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Accessing online documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Contacting Macromedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
CHAPTER 1 Introduction to the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . 1
About the JRun SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Getting the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
SDK/retail differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
SDK file group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Core components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
JRun components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
JRun source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
JRun installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
SDK documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
CHAPTER 2 JRun Installer Overview . . . . . . . . . . . . . . . . . . . . . . . . 9
Installer overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Configuring JRun during installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Custom software requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
User input during installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Setting ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Setting the JMC username and password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Working with JRun licenses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Installing multiple instances of JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Building a customized version of JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Building JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Choose components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Setting the language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Setting the platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Setting the destination directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
CHAPTER 3 Windows JRun Installers. . . . . . . . . . . . . . . . . . . . . . . .17
sdk.book Page iii Wednesday, April 17, 2002 2:28 PM

iv Contents
Overview of Windows installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Windows Installer environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Non-Windows Installer environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Customizing JRun installers with Windows Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
About merge modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Working with merge modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Merge module list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Working with InstallShield Developer 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Determining merge module location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Connecting a merge module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Using Windows Installer on the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Using the Windows Installer wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
CHAPTER 4 Platform-Independent JRun Installers . . . . . . . . . . . 27
About files for custom installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
Using BIN files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
BIN file list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
BIN file properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
CHAPTER 5 Embedding JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Connecting to external web servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Silently running the Web Server Configuration tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Including the Web Server Configuration tool in the installer . . . . . . . . . . . . . . . . . . . . . .33
Working with web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Hiding JSP source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Adding web applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Removing web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Hiding the JMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Rebranding JRun tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Rebranding the Web Server Configuration tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
Rebranding the JRun Launcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Rebranding the JMC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
JMC source code overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Creating a custom JRun interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Hiding the JMC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Deploying applications outside the JRun directory structure . . . . . . . . . . . . . . . . . . . . . .44
Using exit handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
JRunExitHandler interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Exit handler example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Exit codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
CHAPTER 6 Using the JMC Custom Tag Library . . . . . . . . . . . . . 47
Extracting the JMC custom tag library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Strategies for working with the JMC custom tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Finding services, classes, and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Using the service and server attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Using the mbean attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Understanding offline properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Using the errorId attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Using the type and id attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
sdk.book Page iv Wednesday, April 17, 2002 2:28 PM

C o n t e n t s v
JMC custom tags reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
add. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
addOfflinePropertyValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
checkServer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
getConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
getOfflineProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
getOfflinePropertyValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
getProperty. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
getServer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
getServersOnHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
invoke. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
isRemoteServer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
removeAllOfflinePropertyValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
setOfflineProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
setProperty. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
CHAPTER 7 JRun APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Using the JRun API Javadocs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
JRun APIs overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Command-line tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Using GetControlPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Using migrate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Using Base64 encoder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Using the Web Server Configuration tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Using jrun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Using jrunsvc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Using JSPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Using XMLScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Using Java2WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Using WSDL2Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
JRun executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
CHAPTER 8 JRun Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Service architecture (JMX). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Creating services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Basic JRun services: extending ServiceMBean and ServiceAdapter . . . . . . . . . . . . . . . . . .82
Service naming convention. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Service composition: extending ServicePartitionMBean and ServicePartition . . . . . . . . . .82
Creating services using jrun.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Creating services programmatically. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Custom service example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Accessing JRun services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
JNDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Service convenience methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
JMX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
sdk.book Page v Wednesday, April 17, 2002 2:28 PM

vi Contents
Adding JRun service security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Loading MBeans through MLETs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
CHAPTER 9 Editing XML Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Editing XML files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Tools for editing XML files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Understanding the XML metadata classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Using XML metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Finding metadata classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
XML metadata example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
sdk.book Page vi Wednesday, April 17, 2002 2:28 PM

vii
ABOUT THIS BOOK
The JRun SDK Guide is for OEMs and advanced users of Macromedia JRun. This book
assumes that you are comfortable using JRun and understand the XML configuration
files.
This chapter tells you how to access JRun and Macromedia resources, such as websites,
documentation, and technical support.
Contents
•Developer resources.............................................................................................. viii
•About JRun documentation.................................................................................... ix
•Other resources........................................................................................................ x
•Contacting Macromedia....................................................................................... xiii
sdk.book Page vii Wednesday, April 17, 2002 2:28 PM

viii About This Book
Developer resources
Macromedia, Inc. is committed to setting the standard for customer support indeveloper
education, documentation, technical support, and professional services. The
Macromedia website is designed to give you quick access to the entire range of online
resources. The following table shows the locations of these resources:
Resource Description
Information on JRun
http://www.macromedia.com/products/
jrun/
Detailed product information on JRun and
related topics.
JRun Online Forum
http://webforums.macromedia.com/jrun
Access to experienced JRun developers
through participation in the Macromedia
Online Forums, where you can post messages
and read replies on many subjects relating to
JRun.
Developer Resources
http://www.macromedia.com/desdev/
developer/
All of the resources that you need to stay on
the cutting edge of JRun development,
including online discussion groups,
Component Exchange, Resource Library,
technical papers, and more.
JRun Support Center
http://www.macromedia.com/
support/jrun
Professional support programs that
Macromedia offers.
Tr ai n i ng
http://www.macromedia.com/support/
training/
Information about classes, on-site training,
and online courses offered by Macromedia.
Macromedia Alliance
http://www.macromedia.com/partners/
Connection with the growing network of
solution providers, application developers,
resellers, and hosting services creating
solutions with JRun.
sdk.book Page viii Wednesday, April 17, 2002 2:28 PM

About JRun documentation ix
About JRun documentation
JRun documentation provides support for all JRun users, including JSP developers,
servlet developers, EJB client developers, EJB bean developers, and system
administrators. The printed and online versions are organized to let you quickly locate
the information that you need. JRun online documentation is provided in HTML and
Adobe Acrobat formats.
Printed and online documentation set
The JRun documentation set consists of the following titles:
Accessing online documentation
All JRun documentation is available online in HTML and Adobe Acrobat formats. To
access the documentation, open the following file on the server that is running JRun:
jrun_root/docs/dochome.htm. Jrun_root is the directory into which you installed JRun.
In addition, the JRun SDK contains a special set of Javadocs that describe the JMC
classes. You can access the JMC Javadocs from the sdk_root/docs/jmc-javadocs directory.
Macromedia provides online versions of all JRun books as Adobe Acrobat Portable
Document Format (PDF) files. The PDF files are included on the JRun CD and
installed in the JRun /docs directory, although they are an optional part of the
installation. You can access them by clicking the Product Documentation link on the
JRun Management Console Welcome window.
Book Description
Installing JRun Describes installing and configuring JRun.
Getting Started with JRun Provides a J2EE overview, concepts, and tutorials for
JSPs, servlets, EJBs, and web services.
JRun Administrator’s Guide Describes how to integrate a JRun server into an
existing environment.
JRun Programmer’s Guide Describes how to use JRun to develop JSPs, servlets,
custom tags, EJBs, and web services.
JRun Assembly and Deployment
Guide
Describes how to assemble and deploy the
components of a J2EE application.
JRun SDK Guide Provides information to OEM/ISV customers and
advanced users who embed, customize, or use the
APIs in JRun.
JRun Quick Reference Provides brief descriptions and syntax for JavaServer
Pages (JSP) directives, actions, and scripting elements.
Online Help Provides JMC users with usage notes, procedures, and
concepts.
sdk.book Page ix Wednesday, April 17, 2002 2:28 PM

x About This Book
Other resources
You can consult the following resources for more information on topics described in
JRun documentation.
Books
Servlets, JavaServer Pages, and Tag Libraries
JRun Web Application Construction
Kit
Drew Falkman
Macromedia Press, 2001
ISBN: 0789726009
Java Server Pages Application
Development
Scott M. Stirling, et al.
Sams, 2000
ISBN: 067231939X
More Servlets and JavaServer Pages Marty Hall
Prentice Hall PTR, 2001
ISBN: 0130676144
Core Servlets and JavaServer Pages Marty Hall
Prentice Hall PTR, 2000
ISBN: 0130893404
Java Servlet Programming, Second
Edition
Jason Hunter and William Crawford
O'Reilly & Associates, 2001
ISBN: 0596000405
Java Servlets Developer’s Guide Karl Moss
McGraw-Hill/Osborne Media, 2002
ISBN: 0-07-222262-X
Inside Servlets: Server-Side
Programming for the Java Platform,
Second Edition
Dustin R. Callaway
Addison-Wesley, 2001
ISBN: 0201709066
Web Development with JavaServer
Pages
Duane K. Fields and Mark A. Kolb
Manning Publications Company, 2000
ISBN: 1884777996
Enterprise Java Servlets Jeff Genender
Addison-Wesley, 2001
ISBN: 020170921X
Advanced JavaServer Pages David Geary
Prentice Hall, 2001
ISBN: 0130307041
sdk.book Page x Wednesday, April 17, 2002 2:28 PM

Other resources xi
JavaServer Pages Hans Bergsten
O’Reilly & Associates, 2000
ISBN: 156592746X
JSP Tag Libraries Gal Schachor, Adam Chace, and Magnus Rydin
Manning Publications Company, 2001
ISBN: 193011009X
Core JSP Damon Hougland and Aaron Tavistock
Prentice Hall, 2000
ISBN: 0130882488
JSP: JavaServer Pages (Developer’s
Guide)
Barry Burd
Hungry Minds Inc., 2001
ISBN: 0764535358
Enterprise JavaBeans
Mastering Enterprise JavaBeans,
Second Edition
Ed Roman
John Wiley & Sons, 2002
ISBN: 0471417114
Enterprise JavaBeans, Third Edition Richard Monson-Haefel
O'Reilly & Associates, 2001
ISBN: 0596002262.
Professional EJB Rahim Adatia, et al
Wrox Press, 2001
ISBN: 1861005083
Special Edition Using Enterprise
JavaBeans (EJB) 2.0
Chuck Cavaness and Brian Keeton
Que, 2001
ISBN: 0789725673
Applying Enterprise JavaBeans:
Component-Based Development for
the J2EE Platform
Vlada Matena and Beth Stearns
Addison-Wesley Pub Co, 2000
ISBN: 0201702673
Enterprise Java Programming
Professional Java Server
Programming J2EE 1.3 Edition
Subrahmanyam Allamaraju, et al
Wrox Press, 2001
ISBN: 1861005377
Server-Based Java Programming Te d N e w a r d
Manning Publications Company, 2000
ISBN: 1884777716
sdk.book Page xi Wednesday, April 17, 2002 2:28 PM

xii About This Book
Online resources
Designing Enterprise Applications
with the Java 2 Platform, Enterprise
Edition
Nicholas Kassem
Addison-Wesley, 2000
ISBN: 0201702770
(free download at http://java.sun.com/j2ee/
download.html#blueprints)
Building Java Enterprise Systems
with J2EE
Paul Perrone and Venkata S.R. “Krishna” .R.
Chaganti
Sams, 2000
ISBN: 0672317958
J2EE: A Bird's Eye View (e-book) Rick Grehan
Fawcette Technical Publications, 2001
ISBN: B00005BAZV
Java Message Service Richard Monson-Haefel and David Chappell
O’Reilly and Associates, 2001
ISBN: 0596000685
J2EE Connector Architecture and
Enterprise Application Integration
Rahul Sharma, et al
Addison-Wesley, 2001
ISBN: 0201775808
Building Web Services with Java:
Making Sense of XML, SOAP,
WSDL and UDDI
Sim Simeonov, Glen Daniels, et al
Prentice Hall, 2002
ISBN: 0672321815
Architecting Web Services William L. Oellermann Jr.
Apress, 2001
ISBN: 1893115585
Java Servlet API http://java.sun.com/products/servlet
JavaServer Pages API http://java.sun.com/products/jsp
Enterprise JavaBeans API http://java.sun.com/products/ejb/
Java 2 Standard Edition API http://java.sun.com/j2se/
Servlet Source http://www.servletsource.com
JSP Resource Index http://www.jspin.com
Server Side http://www.theserverside.com
Dot Com Builder http://dcb.sun.com
Servlet Forum http://www.servletforum.com
sdk.book Page xii Wednesday, April 17, 2002 2:28 PM

Contacting Macromedia xiii
Contacting Macromedia
Corporate
headquarters
Macromedia, Inc.
600 Townsend Street
San Francisco, CA 94103
Tel: [phone]
Fax: [phone]
Web: http:// www.macromedia.com
Technical support Macromedia offers a range of telephone and web-based
support options. Go to http://www.macromedia.com/support/
for a complete description of technical support services.
You can make postings to the JRun Support Forum
(http://webforums.macromedia.com) at any time.
Sales Toll Free: 888.939.2545
Te l : 6 1 7 . 2 1 9 . 2 1 0 0
Fax: [phone]
E-mail: [email protected]
Web: http://commerce.macromedia.com/purchase/index.cfm
OEM/hosting sales For information about OEM/hosting, such as inquiries
regarding licensing and pricing for product, support, training
and consulting, contact:
Toll Free: 888.939.2545, request OEM Sales Desk extension
2157.
OEM Sales Desk: 617.219.2157
Fax: [phone]
E-mail: [e-mail]
Web: http://www.macromedia.com/software/jrun/oem
sdk.book Page xiii Wednesday, April 17, 2002 2:28 PM

xiv About This Book
sdk.book Page xiv Wednesday, April 17, 2002 2:28 PM

1
CHAPTER 1
Introduction to the SDK
The JRun Software Development Kit (SDK) contains source code, Javadocs, and utilities
for customizing the Macromedia JRun installation. It is primarily intended for OEMs,
ISVs, and advanced JRun users.
Contents
•About the JRun SDK...............................................................................................2
•Software requirements .............................................................................................3
•SDK file group........................................................................................................4
sdk.book Page 1 Wednesday, April 17, 2002 2:28 PM

2 Chapter 1 Introduction to the SDK
About the JRun SDK
The JRun Software Development Kit (SDK) is for OEM/ISV customers and advanced
JRun users who embed, customize, or use the APIs in JRun. In JRun 3.x, the JRun SDK
was called the JRun OEM kit.
Getting the SDK
You can download the JRun SDK from the Macromedia website.
To download the SDK:
1 Download the latest version of the JRun SDK from the following location:
http://www.macromedia.com/go/jrun_sdk
2 Extract the files into a directory on your machine. This book refers to the SDK
directory as sdk_root.
For a description of the contents of the SDK, see “SDK file group” on page 4.
SDK/retail differences
The SDK includes thefollowingcomponents thatare not included in the retail version of
JRun:
•Installer project files for common installation development environments
•Windows merge modules and BIN files for JRun components
•JRun API Javadocs for the jrunx.jmc packages
•build.xml files and JRun filesets for creating a custom installation
•Source code for the following JRun modules:
−JRun Management Console (JMC)
−Connectors
−Windows service
−Launcher
−JAAS Windows login module
−OpenSSL toolkit
The SDK does not include the following files that are included in the retail version of
JRun:
•Standard documentation set
•Core JRun API Javadocs
•JRE
•Samples server
•PointBase sample database
sdk.book Page 2 Wednesday, April 17, 2002 2:28 PM

Software requirements 3
Software requirements
You can use the SDK to compile your own custom connectors, recompile the JMC with
custom functions, or compile your own JRun installer. Depending on what your purpose
is, the SDK has various requirements.
The following table describes the tools that you might need while working with the
SDK:
Tool Used for
C compiler Compiling source code of some JRun components.
Ant Compiling the JMC source and building a custom
installation of JRun.
Cygwin from CYGNUS Building connectors from the JRun source code. For
more information, see http://www.cygnus.com.
InstallShield 7 or later
Wise Solutions 4 or later
Building Windows Installer installation components.
InstallShield 6.2 or earlier
Wise Solutions 3.x or earlier
Building non-Windows Installer components for
installation in Windows.
Install Anywhere (all versions) Building cross-platform installers from the supplied
project files.
JDK 1.3 Using the classes in any JAR file in the jrun_root/lib
directory, such as jrun.jar or xdoclet.jar.
sdk.book Page 3 Wednesday, April 17, 2002 2:28 PM

4 Chapter 1 Introduction to the SDK
SDK file group
The SDK consists of prebuilt filesets, which are installed under the sdk_root directory.
The following table briefly describes these top-level directories:
The following sections describe the contents of these top-level directories in the SDK.
Core components
The sdk_root/filesets/all directory contains the non–platform-specific filesets for JRun,
organized by functional component. You use these filesets if you are preparing a custom
JRun installation in a non-Windows Installer environment. For more information on
creating custom installers, see “Building a customized version of JRun” on page 14.
The following table describes the files in the sdk_root/filesets/all directory of the SDK:
Directory Description
filesets Contains the core components of JRun and localization files.
For more information on the contents of the sdk_root/filesets directory,
see “JRun components” on page 5.
src Contains source code for some components of JRun, including the JMC
and web server connectors.
For more information on the contents of the sdk_root/src directory, see
“JRun source code” on page 6.
docs Contains documentation specific to the SDK.
For more information on the contents of the sdk_root/docs directory, see
“SDK documentation” on page 7.
installers Contains merge modules and BIN files for use in installer development
environments, and the Windows Installer wrapper.
For more information on the contents of the sdk_root/installers directory,
see “JRun installers” on page 6.
Subdirectory Description
core Includes the basic files to run JRun and serve J2EE applications.
Also includes the migration tool, XMLScript, and the JSPC compiler.
default-server Includes all files used by the default JRun server, including the
default application.
flashgateway Contains the files necessary to run the Macromedia Flash Remoting
service that is installed in the retail version of JRun by default.
jmc Includes the files used by the JMC applications. The JMC provides
access to JRun settings through a web-based GUI. In the retail
version, JRun hotdeploys this component as an EAR file.
The source code of the JMC is also included in the sdk_root/src
fileset.
jrunwizard Includes the JRun EJB Deployment Wizard stand-alone tool and
the tool’s GUI installer.
macromedia_drivers Includes the JRun JDBC drivers.
sdk.book Page 4 Wednesday, April 17, 2002 2:28 PM

SDK file group 5
JRun components
The sdk_root/filesets directory contains filesets for all JRun components. It also contains
subdirectories for each supported platform with a binary code base for each of the
following JRun tools:
•JRun EJB Deployment Wizard
•Web Services
•Web Server Configuration tool
The subdirectories contain the compiled classes and resource files, separated into
functional groups. The directories take the following form:
{os_or_language}/{module_name}/{jrun_dirs}
The sdk_root/filesets directory also contains a build.xml file which lets you create a
custom JRun installation using different combinations of modules, OS-specific files, and
language-specific files. You must have Ant to use the build.xml file. For more information
on building a custom version of JRun using the build.xml file, see “Building a
customized version of JRun” on page 14.
The following table describes the files in the sdk_root/filesets directory of the SDK:
webservices Includes all files used to implement Web Services on JRun.
xdoclet Contains files for using the XDoclet XML generation tool with JRun.
Subdirectory Description
Subdirectory Description
all Contains the non–platform-specific filesets for JRun, organized by
functional component.
For more information on the contents of the subdirectories of the
sdk_root/filesets/all directory, see “Core components” on page 4.
alpha-osf1 Contains binaries for the Alpha flavor of UNIX.
english Contains localization files for the English language.
french Contains localization files for the French language.
intel-linux Contains binaries for the Linux platform.
intel-win Contains binaries for the Windows platform.
japanese Contains localization files for the Japanese language.
pa_risc-hpux Contains binaries for the HPUX flavor of UNIX.
ppc-aix Contains binaries for the AIX flavor of UNIX.
sparc-solaris Contains binaries for the Sun Sparc flavor of UNIX.
sdk.book Page 5 Wednesday, April 17, 2002 2:28 PM

6 Chapter 1 Introduction to the SDK
JRun source code
The JRun SDK includes source code for a subset of JRun tools. This gives you the most
granular level of control over the JRun components. The source code is in the
sdk_root/src directory in the SDK.
The following table describes the files in the sdk_root/src directory of the SDK:
Working with the JRun tools’ source code is beyond the scope of this book. However,
some information on working with the JMC source code is included in “Rebranding the
JMC” on page 42.
JRun installers
The SDK includes files for OEMs to build custom JRun installers in the
sdk_root/installers directory. For general information about the JRun installer creation
tools, see Chapter 2, “JRun Installer Overview” on page 9.
The following table describes the subdirectories in the sdk_root/installers directory of the
SDK:
Subdirectory Description
C Contains the source code for the following JRun components:
•Launcher
•Windows services
•JAAS Windows login module
Connectors Contains the source code for web server connectors for the
following web servers:
•Apache
•IIS (including metabase tools for configuration)
•Netscape
Also contains source code for the OpenSSL toolkit.
JMC Contains the source code for the JRun Management Console (JMC)
application.
Subdirectory Description
windows Contains the Windows Installer merge modules for building installers
in the Windows Installer development environments.
Also contains the Windows merge modules that closely correspond
to the JRun components described in “Core components” on page
4. The merge modules can be used with any Windows
Installer-aware application.
For more information about creating a Windows JRun installer, see
Chapter 3, “Windows JRun Installers” on page 17.
all Contains the BIN files that you can use as part of your installer
project. These BIN files closely correspond to the JRun components
described in “Core components” on page 4.
For more information about creating a UNIX JRun installer, see
Chapter 4, “Platform-Independent JRun Installers” on page 27.
sdk.book Page 6 Wednesday, April 17, 2002 2:28 PM