MACROMEDIA JRun 4 Getting Started Manual

Getting Started

with JRun

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. and may be registered in the 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. or other 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. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY 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 © 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 ZJR40M200

Acknowledgments

Project Management: Randy Nielsen Writing: Rosemary Marano Editing: Linda Adler and Noreen Maher

First Edition: May 2002

Macromedia, Inc. 600 Townsend St. San Francisco, CA 94103

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Part I Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

CHAPTER 1 Welcome to JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

About JRun. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

Benefits of server-side Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

Benefits of using J2EE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

J2EE standards compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

JRun architectural model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

JRun features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8

Development tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Dreamweaver MX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Using JRun with your Java IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Installing the Enterprise Deployment Wizard in your Java IDE . . . . . . . . . . . . . . . . . . . .13

What to do next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14

CHAPTER 2 JRun Programming Model . . . . . . . . . . . . . . . . . . . . . . 15

Enterprise application architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Enterprise application design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

J2EE application architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

JRun support for the three-tier model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

JRun programming environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

JRun servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Using JRun servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Starting and stopping JRun servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Installed JRun servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Web servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

JRun Web Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

JRun support for J2EE applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

About web applications and JRun. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

iii

About EJBs and JRun. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

About enterprise resource adapters and JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

About enterprise applications and JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

CHAPTER 3 Introduction to J2EE . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

J2EE environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

J2EE platform technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Communication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

J2EE APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

EJB 2.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

Java Database Connectivity 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Java Servlet 2.3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

JavaServer Pages 1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Java Message Service 1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Java Transaction API 1.0 and Java Transaction Service. . . . . . . . . . . . . . . . . . . . . . . . . . .34

JavaMail 1.2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

JavaBeans Activation Framework 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Java API for XML 1.1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

J2EE Connector API 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Java Authentication and Authorization Service 1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Java Naming and Directory Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Common Object Request Broker Architecture compliance. . . . . . . . . . . . . . . . . . . . . . . .36

Additional resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

CHAPTER 4 Using Servlets and JSP . . . . . . . . . . . . . . . . . . . . . . . . . 37

Using Java Servlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Invoking servlets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Servlet benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

Creating servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

JRun support for servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

JRun support for JSPs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Servlets and JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

HTTP requests and responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

Writing results back to the client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

Using servlet filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

Using event listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

Handling exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

Maintaining page context information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

Working with sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44

Tracking an application’s context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44

Accessing configuration information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

Writing servlets in Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

Writing servlets as JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

CHAPTER 5 Introduction to EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

EJB Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

The parts of an EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

Container services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

iv Contents

EJB types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Session beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Entity beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50

Message-driven beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Using EJB in JRun. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

Stubless deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

Deployment options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

EJB clustering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

XDoclet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

The Enterprise Deployment Wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

CHAPTER 6 Developing Web Applications . . . . . . . . . . . . . . . . . . . . 55

Introduction to web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

The benefits of web applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

Comparing web applications and enterprise applications . . . . . . . . . . . . . . . . . . . . . . . . .56

Using web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57

About the web application directory structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

The deployment descriptor (web.xml) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Web applications, JRun servers, and web servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

Application mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

Developing web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62

Creating a web application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62

Adding web application components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62

Deploying web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Deploying a web application across a cluster. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Packaging a web application for deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66

Part II Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

LESSON 1 Servlet Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Setting up the development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

Getting started with JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71

Adding a JRun server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72

Deploying the tutorial enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

Adding JDBC data sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Compass Travel J2EE application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

Coding the logon servlet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82

What’s next?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82

LESSON 2 JSP Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Creating a home page JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

Compass Travel tutorial application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

Accessing a JavaBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

What’s next?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

LESSON 3 EJB Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

C o n t e n t s v

Using EJBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90

Invoking an EJB from a JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91

Booking a trip reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

Examining the code for the reservation EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

Examining the code for the credit card EJB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94

Examining the code for the order EJB: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

Tutorial lessons summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

What’s next?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

LESSON 4 Web Services Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Using JRun web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

TravelNet web services application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Setting up the development environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

Getting started with JRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Adding a JRun server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Deploying the TravelNet enterprise application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104

Authoring a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

Generating WSDL from a published web service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Generating a web service proxy client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

Creating and using a JSP-based proxy client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

vi Contents

ABOUT THIS BOOK

Getting Started with JRun is for anyone using JRun to develop applications consisting of Java Servlets, JavaServer pages, Enterprise JavaBeans, and Web Services. Part I of this book provides a general introduction to JRun and J2EE. Part II contains tutorials to show you how to build a simple J2EE application. In the tutorial lessons, you add a JRun server and write the code for servlets, JSPs, JavaBeans, and EJBs.

This preface 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........................................................................................xiv

vii

Developer resources

Macromedia, Inc. is committed to setting the standard for customer support in developer 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 /http://www.macromedia.com/products/

jrun//a

JRun Online Forum

http://webforums.macromedia.com/jrunhtt

p://webforums.macromedia.com/jrun/a

Developer Resources

http://www.macromedia.com/desdev/devel oper/http://www.macromedia.com/desdev/

developer//a

JRun Support Center

http://www.macromedia.com/support/jrunh

ttp://www.macromedia.com/

support/jrun/a

Tr a i n i n g

http://www.macromedia.com/support/traini ng/http://www.macromedia.com/support/

training//a

Detailed product information on JRun and related topics.

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.

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.

Professional support programs that Macromedia offers.

Information about classes, on-site training, and online courses offered by Macromedia.

Macromedia Alliance

http://www.macromedia.com/partners/http

://www.macromedia.com/partners//a

viii About This Book

Connection with the growing network of solution providers, application developers, resellers, and hosting services creating solutions with JRun.

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:

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

JRun SDK Guide Provides information to OEM/ISV customers and

JRun Quick Reference Provides brief descriptions and syntax for JavaServer

Online Help Provides JMC users with usage notes, procedures, and

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 running JRun:

jrun_root/docs/dochome.htm. JRun_root is the directory into which you installed JRun.

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.

Describes how to assemble and deploy the components of a J2EE application.

advanced users who embed, customize, or use the APIs in JRun.

Pages (JSP) directives, actions, and scripting elements.

concepts.

About JRun documentation ix

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

Java Server Pages Application Development

http://www.moreservlets.comMore

Servlets and JavaServer Pages/a

http://www.coreservlets.comCore

Servlets and JavaServer Pages/a

Java Servlet Programming, Second

Edition

http://www.servletguru.comJava

Servlets Developer’s Guide/a

Drew Falkman Macromedia Press, 2001 ISBN: 0789726009

Scott M. Stirling, et al. Sams, 2000 ISBN: 067231939X

Marty Hall Prentice Hall PTR, 2001 ISBN: 0130676144

Marty Hall Prentice Hall PTR, 2000 ISBN: 0130893404

Jason Hunter and William Crawford O'Reilly & Associates, 2001 ISBN: 0596000405

Karl Moss McGraw-Hill/Osborne Media, 2002 ISBN: 0-07-222262-X

http://www.sourcestream.comInside

Servlets: Server-Side Programming for the Java Platform, Second

Edition/a

Web Development with JavaServer Pages

Enterprise Java Servlets Jeff Genender

Advanced JavaServer Pages David Geary

x About This Book

Dustin R. Callaway Addison-Wesley, 2001 ISBN: 0201709066

Duane K. Fields and Mark A. Kolb Manning Publications Company, 2000 ISBN: 1884777996

Addison-Wesley, 2001 ISBN: 020170921X

Prentice Hall, 2001 ISBN: 0130307041

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

http://www.middleware-company.c omMastering Enterprise JavaBeans,

Second Edition/a

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

Server-Based Java Programming Te d N ew ar d

Subrahmanyam Allamaraju, et al Wrox Press, 2001 ISBN: 1861005377

Manning Publications Company, 2000 ISBN: 1884777716

Other resources xi

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#blueprintsh

ttp://java.sun.com/j2ee/download.html#blueprints/a )

Building Java Enterprise Systems with J2EE

J2EE: A Bird's Eye View (e-book) Rick Grehan

Java Message Service Richard Monson-Haefel and David Chappell

J2EE Connector Architecture and Enterprise Application Integration

Building Web Services with Java: Making Sense of XML, SOAP, WSDL and UDDI

Architecting Web Services William L. Oellermann Jr.

Paul Perrone and Venkata S.R. “Krishna” .R. Chaganti

Sams, 2000 ISBN: 0672317958

Fawcette Technical Publications, 2001 ISBN: B00005BAZV

O’Reilly and Associates, 2001 ISBN: 0596000685

Rahul Sharma, et al Addison-Wesley, 2001 ISBN: 0201775808

Sim Simeonov, Glen Daniels, et al Prentice Hall, 2002 ISBN: 0672321815

Apress, 2001 ISBN: 1893115585

Online resources

Java Servlet API http://java.sun.com/products/servlethttp://java.sun.co

JavaServer Pages API http://java.sun.com/products/jsphttp://java.sun.com/p

Enterprise JavaBeans API http://java.sun.com/products/ejb/http://java.sun.com/

Java 2 Standard Edition API http://java.sun.com/j2se/http://java.sun.com/j2se//a

Servlet Source http://www.servletsource.comhttp://www.servletsourc

JSP Resource Index http://www.jspin.comhttp://www.jspin.com/a

xii About This Book

m/products/servlet/a

roducts/jsp/a

products/ejb//a

e.com/a

Server Side http://www.theserverside.comhttp://www.theserversid

e.com/a

Dot Com Builder http://dcb.sun.comhttp://dcb.sun.com/a

Servlet Forum http://www.servletforum.com/http://www.servletforum

.com/a

Other resources xiii

Contacting Macromedia

Corporate headquarters

Technical support Macromedia offers a range of telephone and web-based

Sales Toll Free: 888.939.2545

Macromedia, Inc. 600 Townsend Street San Francisco, CA 94103

Tel: 415.252.2000 Fax: 415.626.0554

http://www.macromedia.com www.macromedia.com/a

Web:

support options. Go to

http://www.macromedia.com/support/http://www.macromedia

.com/support//a for a complete description of technical support services.

You can make postings to the JRun Support Forum (http://webforums.macromedia.comhttp://webforums.macrom edia.com/a) at any time.

Te l: 61 7. 21 9. 2 1 00 Fax: 617.219.2101

E-mail:

mailto:sales@macromedia.comsales@macromedia.com/a

Web:

http://www.macromedia.com/store/http://www.macromedia.c

om/store//a

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: 617.219.2102 E-mail:

mailto:oemsales@macromedia.comoemsales@macromedia.c

om/a Web:

http://www.macromedia.com/software/jrun/oemhttp://www.m

acromedia.com/software/jrun/oem/a

xiv About This Book

PART I

Introduction

This part contains an introduction to JRun and J2EE.

Welcome to JRun..........................................................................................................3

JRun Programming Model........................................................................................15

Introduction to J2EE..................................................................................................29

Using Servlets and JSP............................................................................................ 37

Introduction to EJB .....................................................................................................47

Developing Web Applications ................................................................................55

CHAPTER 1

Welcome to JRun

This chapter contains an overview of Macromedia JRun and JRun architecture. It describes many of the features and tools that you use during application development and deployment. It also includes a description of different types of JRun users and pointers to the JRun documentation where each type of user can find additional information.

Contents

• About JRun............................................................................................................. 4

• J2EE standards compliance......................................................................................6

• JRun architectural model......................................................................................... 7

• JRun features........................................................................................................... 8

• Development tools................................................................................................. 13

• What to do next .................................................................................................... 14

About JRun

JRun is a complete Java application server for developing and deploying reliable, scalable, and secure server-side Java 2 Enterprise Edition (J2EE) applications. JRun supports the latest industry standards for developing applications composed of Java Servlets, JavaServer pages (JSP), Enterprise JavaBeans (EJB), Java Message Service (JMS), Macromedia Flash files, HTML pages, images, and other resources.

JRun supports a variety of Windows and UNIX platforms. Its open design lets JRun work with a variety of existing web servers, including Apache, Microsoft Internet Information Server (IIS), Netscape Enterprise Server (NES), Netscape iPlanet, and Zeus. With JRun, you can deploy websites with dynamically generated content on almost any platform.

JRun connects to a web server using a plug-in mechanism unique to each web server: Netscape Server API (NSAPI) for Netscape, Internet Server API (ISAPI) for Microsoft IIS, and the Apache 1.3 and 2.0 Dynamic Shared Object (DSO) interfaces for the Apache web server. However, you do not need to have a separate web server to develop and deploy applications using JRun. JRun provides its own built-in web server.

For more information, see Installing JRun.

Benefits of server-side Java

Java Servlets, JSPs, and EJBs are all examples of server-side Java—that is, Java code that executes on an application server rather than on a web client.

Server-side Java has many important features that make it extremely useful for developing web server applications, including the following:

• Consistent Java features You can guarantee that your server supports the features

of Java that are required by your application.

• Up-to-date Java technologies As the Java standard continues to evolve, your

server-side application can immediately take advantage of new Java features, regardless of the compliance level of clients.

• Control over the Java Virtual Machine (JVM) Your server runs the JVM that you

require for your application.

Server-side Java lets you completely realize the Java “write once, run anywhere” goal. The full capabilities of the language are available to you with no limitations or restrictions. Because these applications run on the server, you can also control the platform, the operating system, and every aspect of the environment in which your application runs.

With complete control over your environment, you can develop on one platform and deploy on another with confidence that your application will run properly on both platforms.

4 Chapter 1 Welcome to JRun

Benefits of using J2EE

The J2EE platform represents a single standard for implementing and deploying multitier, enterprise applications. J2EE applications take advantage of Java’s inherent portability and can be run on all platforms supported by JRun.

J2EE offers a number of benefits for application programmers, including the following:

• Rich set of standard APIs and services

• High performance

• Integration with backend infrastructure, such as Relational Database Management

Systems (RDBMS) and Enterprise Information Systems (EIS)

• Industry support, including third party tools and Application Programming

Interfaces (APIs)

JRun is standardized on the latest J2EE platform specifications, highlighted in the following section.

About JRun 5

J2EE standards compliance

Macromedia JRun is a J2EE-compliant application server. JRun passed the J2EE Compatibility Test Suite (CTS) and delivers the full capabilities of the most recent Sun J2EE 1.3 platform specification. The following table describes the many enhancements and new features in the 1.3 specification:

Feature Description

EJB 2.0 Provides enhancements that simplify the development of distributed

components.

• Container Managed Persistence (CMP) 2.0 lets developers build

portable applications that are database-independent and free of database access code.

• Introduces a standard, database-independent EJB query language

(EJBQL).

• Introduces local interfaces to efficiently invoke an EJB component

residing on the same computer as the calling application.

Message Driven Beans (MDB)

J2EE Connector Architecture (JCA) 1.0

JSP 1.2 Supports several additions to the JSP API, including the following:

A part of the EJB 2.0 specification, combines the asynchronous benefits of the Java Message Service (JMS) with EJB. MDBs are message listeners that run in the EJB container and can use container services, such as security and transactions.

Defines a standard architecture that supports integration of J2EE servers with enterprise information systems, such as Enterprise Resource Planning (ERP) systems, mainframe transaction processing systems, and legacy database systems.

• Two new tag types, IterationTag and TryCatchFinallyTag.

• An XML syntax for JSP pages (JSPX), which makes it easier to

automate the authoring of JSP pages.

• A number of enhancements to Tag Library Descriptors (TLD) that

improve portability, and better support authoring tools.

Servlet 2.3 Introduces the following two important new features:

• Application events Useful for application initialization code and

can replace preloaded servlets in some cases.

• Filters Allow pre- and post-processing of servlet requests.

Java APIs for XML Processing (JAXP) 1.1

Supports the latest XML development features, including a pluggable architecture for adding your choice of XML parser or XSL processor into the server and overriding the default components that JRun includes.

Java Message Service (JMS) 1.0

Java Authentication and Authorization Service (JAAS)

6 Chapter 1 Welcome to JRun

Lets J2EE application components create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous.

Provides a way for a J2EE application to authenticate users and enforce access controls in a modular fashion.

For detailed information on the J2EE platform, see Chapter 3, “Introduction to J2EE”

on page 29.

JRun architectural model

JRun has a service-based architecture, a modular design that contains pluggable services (components) in a core server backbone.

The server backbone facilitates communication among all components or services that plug into it. It provides a core set of services that are shared across all the components and features of the server. The backbone provides flexibility through its ability to accommodate various services. Services extend the core server by adding functionality, independently of each other.

In JRun, the core server backbone is the server kernel. The services are JRun server features, as the following figure shows:

The JRun architecture is based on Java standards, including the following:

• Java Management Extensions (JMX) Specifications for managing Java

environments. JMX defines the architecture and APIs for a scalable system that you can integrate with existing management systems.

• Java Naming & Directory Interface (JNDI) A standard mechanism for Java-based

applications to access application components and server resources across a distributed computing environment.

• XML An open, cross-platform formatting standard used for storing information

about the state of a JRun service.

JRun is built on a JMX service-based architecture, and uses JMX to provide flexible and dynamic management and administration. JMX is an emerging Java standard for management and customization.

JRun implements its features and functionality (for example, EJB container, web container, and logging) as JMX services (called MBeans), plugged into the JRun kernel. You can manage these services through the JMX-enabled JRun Management Console (JMC) or other JMX-enabled management tools.

JRun architectural model 7

Because services are independent of each other and can be restarted individually, the JRun service-based architecture ensures high application availability. It also provides a highly customizable and easily extensible platform. You can unplug unneeded services to avoid the overhead of unused functionality. Administrators, advanced developers, and Original Equipment Manufacturers (OEMs) can also create their own custom services (MBeans) and plug them into the JRun kernel. All JRun services can take advantage of the clustering capabilities built into the JRun kernel.

For more information on JRun architecture, see JRun Administrator’s Guide.

JRun features

JRun 4 provides many new and changed features, including the following:

• Dynamic deployment of J2EE components

• Dynamic servlet and class reloading and compilation

• Dynamic creation of database tables for entity beans

• JRun Server Tags (JST)

• JRun Management Console (JMC)

• Web Server Configuration tool

• Clustering

• Security

• Enterprise Deployment Wizard

• XDoclet integration

• Pointbase database server

• JDBC Drivers

• Sample applications

• Web services

Dynamic deployment of J2EE components

JRun provides auto deploy and hot deploy features for dynamic deployment of web applications, EJBs, enterprise applications, and enterprise resource adapters from Java archive files or expanded directories. When you copy a J2EE module archive file or directory to a deploy directory (jrun_root/servers/jrun_server, by default), JRun automatically deploys the module in a running server or deploys it the next time the server starts. The deployment is dynamically updated when you modify a module archive file or deployment descriptor. For more information, see JRun Assembly and Deployment Guide.

Dynamic servlet and class reloading and compilation

You can configure JRun to dynamically recompile and reload servlets, JSPs, servlet helper classes, and JSP helper classes when a servlet or JSP is called. When the compile and reload features are enabled, JRun dynamically recompiles and reloads a servlet when it is called. JRun also dynamically recompiles and reloads classes in the WEB-INF/classes directory, and tag library classes when they are called by a servlet or JSP. This feature is disabled by default.

8 Chapter 1 Welcome to JRun

You enable dynamic compiling and reloading by creating a WEB-INF/jrun-web.xml file that contains the following text, setting the reload and compile values to false or true:

<jrun-web-app> <reload>true</reload> <compile>true</compile> </jrun-web-app>

For more information, see JRun Assembly and Deployment Guide.

Dynamic creation of database tables for entity beans

When you deploy an entity bean, and its required database tables do not yet exist, JRun can generate them for you when you have configured the appropriate Java Database Connectivity (JDBC) data source in JRun. For more information, see JRun Programmer’s Guide.

JRun Server Tags (JST)

JST technology supports JSP 1.2 and recursion. JST lets you write custom JSP tags using JSP syntax, rather than the custom tag handler API. Recursion allows a JST to call itself.

JRun Management Console (JMC)

The redesigned, JMX-enabled JMC provides an easy-to-use, intuitive graphical user interface for managing your local and remote JRun servers. Using the JMC, you can create servers, define clusters, manage applications, and implement security based on JAAS. For additional information, see the JMC online Help.

Web Server Configuration tool

JRun provides native connectors for most major web servers. Using the Web Server Configuration tool, you can connect one or more web servers to each JRun server. The Web Server Configuration tool, a stand-alone tool, does not require JRun on the web server host. For information on connecting JRun to an external web server, see Installing

JRun. For more information on understanding web server connectors, see JRun Administrator’s Guide.

Clustering

JRun provides enterprise-level server clustering for maximum reliability and scalability. Clustering is built into the web server connectors and the JRun kernel:

• At the web server connector level, clustering enables load balancing and automatic

failover between the web server and the web containers. In-memory session replication ensures that state information is preserved if the web server fails over to another web container in the cluster.

• At the kernel level, clustering enables load balancing and automatic failover for

clusterable server objects, such as EJBs, JNDI trees, or any clusterable custom service. The object state (for example, the state of a stateful EJB) is automatically replicated in an optimized manner to provide the highest level of reliability while maintaining performance. JRun servers use the JINI technology to dynamically locate their peers

JRun features 9

Security

in the cluster, eliminating the risk inherent to a single point of failure. For more information, see JRun Administrator’s Guide.

JRun supports the JAAS 1.0 specification, which includes the following levels of security:

• JRun administration security JRun uses JAAS as the security framework. JAAS is

a set of packages that lets JRun authenticate users and enforce access controls in a modular fashion. The default JAAS security module provides an XML-based security management (jrun-users.xml). JAAS provides a pluggable mechanism that lets you customize the system to integrate with existing authentication user stores, such as LDAP or a relational database. In addition, you can write custom security modules based on the JAAS specification.

JRun includes a JDBC-based login module and an LDAP-based login module, which perform authentication and authorization using information stored in a relational database or an LDAP directory. JRun also supplies a login module for users and groups from Windows domains. For more information, see JRun Administrator’s Guide or the JMC online Help.

• Web application security To address security issues that involve web applications,

the Java Servlet API specification defines an authentication mechanism to control client access to resources within a web application. Web application security guarantees that only authorized web clients have access to the resources on a website. For more information on web application security, see JRun Administrator’s Guide.

• EJB security JRun provides a configurable mechanism for implementing EJB

security, as defined in the EJB specification. In the deployment descriptor, you specify the users or roles allowed to access each bean method. You can specify the type and content of user information to be verified, what composes a role, and how authentication occurs. This flexibility can accommodate security schemes that you might already have in place. For more information on EJB security, see JRun Administrator’s Guide.

Enterprise Deployment Wizard

JRun includes the Enterprise Deployment Wizard for developing, packaging, and deploying EJBs. Using its Swing-based graphical user interface, you can create any type of EJB, or edit the deployment descriptor of existing EJBs, package them into JAR files, and deploy them on JRun. In particular, the object-relational mapping capabilities of the Enterprise Deployment Wizard let you streamline the entity bean development process.

The Enterprise Deployment Wizard runs as a stand-alone tool, or as a plug-in on top of an Java Integrated Development Environment (IDE).

To start the Enterprise Deployment Wizard, run jrun_root/bin/jrunwizard.exe (Windows) or jrun_root/bin/jrunwizard (UNIX).

To install the Enterprise Deployment Wizard in an IDE, open a console window to the jrun_root/lib directory and issue the following command:

java -jar jrunwizard-installer.jar

For a list of currently supported IDEs, see the Release Notes.

10 Chapter 1 Welcome to JRun

The Enterprise Deployment Wizard features a context-sensitive online Help system. For usage information, see the online Help.

XDoclet integration

JRun provides integration with XDoclet, a popular open-source Java utility that greatly simplifies the development of J2EE modules (such as EJBs, servlets, and custom tags) by letting you maintain your component metadata using Javadoc-style tags in a single source file.

For example, to create an EJB, you traditionally have to maintain four different files: the home interface, the remote or local interface, the implementation class, and the deployment descriptor. Using XDoclet, you only maintain a single source file (the implementation class) that you annotate with special Javadoc tags, that indicate how the auxiliary files should be built. JRun senses modifications to the source file and automatically builds the auxiliary files (such as interfaces and deployment descriptors). For more information, see JRun Programmer’s Guide.

Pointbase database server

JRun includes a restricted version of the PointBase Server Database Management Software (DBMS). This is an all-Java database used with the JRun sample applications. You can use this database server for your evaluation and development work. For more information on the PointBase database, see the PointBase documentation, located in jrun_root/pointbase/docs. (jrun_root is the directory into which you installed JRun.)

JDBC Drivers

JRun embeds type 4 JDBC database drivers that provide connectivity to all major databases.

Sample applications

The samples JRun server contains a variety of applications that illustrate a number of coding techniques. The following table describes the samples applications that are included with JRun:

Application Description

Compass travel A simple online travel agent trip reservation system. This

TravelNet An online travel agent that sells trips from Compass travel. This

application illustrates JSP, servlet, and EJB programming and is delivered as an enterprise application in an open-directory structure. Compass travel uses the compass database, accessing it through the compass data source, which you can view through the JMC. For companion tutorial lessons, see Part II, Tutorials.

application illustrates JSP and web services programming, and is delivered as an enterprise application in an open-directory structure. For companion tutorial lessons, see Lesson 4, “Web

Services Tutorial” on page 97.

JRun features 11

Application Description

World music An e-commerce application that sells music. This application also

contains an admin module. The world music application illustrates many common design patterns using JSP, servlet, and JavaBean programming. The world music sample application uses the worldmusic database, accessing it directly through JDBC.

Web services Programming techniques used in JRun web services

programming.

Web services

Programming techniques

Flash gateway Flash movies and Flash Gateway adapters, which illustrate how to

SmarTicket A Java Blueprints J2ME application. The SmarTicket application

Java PetStore A Java Blueprints J2EE application that shows how to use the

Programming techniques described in this book. The techniques application uses the samples database, accessing it through the samples data source, which you can view through the JMC.

write Flash applications that communicate with JRun.

illustrates how the J2EE platform interoperates with the Java 2 Micro Edition (J2ME) platform to create enterprise applications that serve mobile client devices, such as cell phones, two-way pagers, and palmtops.

The SmarTicket application uses the smarticket database, accessing it through the smarticket data source, which you can view through the JMC.

capabilities of the J2EE 1.3 platform to develop a typical e-commerce application, which can take and process orders and credit card information, manage user logins, shipping information, and shopping cart sessions.

JRun lets you publish and consume web services. Web services provide platform- and location-independent computing using XML and standard Internet protocols such as HTTP. By allowing previously incompatible applications to interoperate over the web, regardless of language, platform, or operating system, web services create new business opportunities and help companies adapt to changing business relationships. For example, a Microsoft .NET component can communicate with a J2EE component, such as an Enterprise JavaBean (EJB).

Using JRun, you can reuse existing Java code as a web service, or write new code specifically to publish as a web service. You also can create object- and tag-based clients that can invoke methods on remote web services, even when those services reside on non-Java platforms.

The JRun web services implementation is built on Apache Axis, the third generation of the Apache Software Foundation’s Simple Object Access Protocol (SOAP) engine. For more information, see JRun Programmer’s Guide.

For more information on JRun 4 features, see the Release Notes in jrun_root/ relnotes.htm.

12 Chapter 1 Welcome to JRun

Development tools

Macromedia provides development tools (available separately) to work with JRun. Additionally, you can use JRun with your Java IDE.

Dreamweaver MX

Dreamweaver MX is an HTML editor for visually designing and managing websites and JSPs created with JRun. Dreamweaver MX increases JSP developer productivity with the following coding tools and features:

• Visual programming Accelerate development with powerful two-way visual

programming tools integrated with transparent source editing.

• HTML design Includes all the functionality of Macromedia HomeSite, the

award-winning HTML design tool.

• JavaScript Debugger

• Code editors Code view and Code inspector that let you edit JavaScript, XML,

and other text documents.

Using JRun with your Java IDE

You can fully integrate JRun with your Java IDE. When setting up your IDE to work with JRun, you specify the following:

• The class containing the JRun server main method: jrunx.kernel.JRun, contained

in jrun_root/lib/jrun.jar

Note: The jrun_root directory is the directory into which you installed JRun.

• The working directory: jrun_root/bin

• The JAR files needed in the JRun runtime classpath: All the JAR files located in

jrun_root/lib and jrun_root/servers/lib

Note: The JRun JDBC drivers are included in the jrun_root/lib/jrun.jar file and require no special attention.

• The command-line arguments passed to the JRun server main method:

start [jrun_server]

Note: Before starting JRun inside your IDE, stop the JRun server on your computer. Otherwise, port conflicts arise with the running server, and JRun will not start inside your IDE.

Installing the Enterprise Deployment Wizard in your Java IDE

To install the Enterprise Deployment Wizard in an IDE, open a console window to the jrun_root/lib directory and issue the following command:

java -jar jrunwizard-installer.jar

For a list of currently supported IDEs, see the Release Notes. The Enterprise Deployment Wizard features a context-sensitive online Help system. For

usage information, see the online Help.

Development tools 13

What to do next

The remaining chapters in Part I provide a general introduction to JRun and J2EE. These chapters include the following:

• Chapter 2, “JRun Programming Model” on page 15

• Chapter 3, “Introduction to J2EE” on page 29

• Chapter 4, “Using Servlets and JSP” on page 37

• Chapter 5, “Introduction to EJB” on page 47

• Chapter 6, “Developing Web Applications” on page 55

All JRun users should be familiar with the information in these chapters. Part II contains tutorials to show you how to build a simple J2EE application. In the

tutorial lessons, you add a JRun server and write the code for servlets, JSPs, JavaBeans, and EJBs. You learn how to combine these elements to produce a flexible and scalable J2EE application. In the last tutorial lesson, you use web services to access data in a JRun sample application.

The following table shows the books to read after the introductory chapters, depending on your role in developing and deploying JRun applications:

Role Description For more information

All JRun developers Performs common development tasks

including application monitoring, debugging, and authentication.

System administrator Responsible for installing and

administrating JRun in a production environment, starting and stopping JRun, and adding and removing applications.

JSP developer Creates JSPs that generate dynamic

content that is returned to clients. These JSPs can reference Java Servlets, custom tag libraries, or JavaBeans.

Java Servlet and tag library developer

EJB developer Creates reusable components used by

Application deployer Packages JRun applications for

Develops servlets in Java, and also develops custom tag libraries used in JSPs.

Java Servlet and JSP developers.

deployment or resale.

JRun Administrator’s Guide

JRun Programmer’s Guide

JRun Assembly and Deployment Guide

14 Chapter 1 Welcome to JRun

CHAPTER 2

JRun Programming Model

JRun is a complete Java application server for developing and deploying J2EE enterprise applications. This chapter describes the JRun programming model, the major components of JRun, and JRun support for J2EE enterprise applications.

Contents

• Enterprise application architecture......................................................................... 16

• JRun programming environment........................................................................... 19

• JRun servers........................................................................................................... 20

• Web servers............................................................................................................ 25

• JRun support for J2EE applications ....................................................................... 26

Enterprise application architecture

The standards for enterprise application development on the web are based on the J2EE specification. JRun supports the J2EE application model and provides a runtime environment for executing enterprise applications.

Enterprise application design

Enterprise applications share several common design goals, including the following:

• Extensibility and maintainability It should be easy to add and maintain new

functionality.

• Scalability, portability, and availability Many enterprise applications must scale to

support thousands of users. A portable application reduces the risk of vendor lock-in and system obsolescence. High availability ensures uninterrupted access to enterprise data and business functions.

• Code reuse Code developed for an application must be reusable within the

application and, ideally, in other applications as well.

• Interoperability An enterprise application must be able to interoperate with other

systems, using their services and providing services to them, particularly existing information assets, including legacy systems.

• Focus on implementing business logic Developers must focus on writing code to

address business issues and minimize time spent dealing with system mechanisms.

For more information on application design patterns, see JRun Programmer’s Guide. Dividing an enterprise application into tiers supports an enterprise application’s design

goals with layers that separate differing design and implementation concerns, such as information persistence, application functionality, and user interaction. The next section explains the roles of the tiers in a J2EE application and describes the technologies available in each tier.

For more information on J2EE, see Chapter 3, “Introduction to J2EE” on page 29.

J2EE application architecture

By definition, J2EE applications are multitiered. Each tier brings specific benefits to the application design. A tiered architecture provides natural access points for integration with existing and future systems. J2EE applications divide their functionality across several tiers or functional layers, each of which serves a specific purpose. This model divides the functionality of a business website into discrete components that can be implemented independently from each other. Typically, multitier applications have the following characteristics:

• Client tier User interaction and data capture occur in the client tier. Client tier

programs translate user actions and input into server requests, and format server responses; for example, using a browser to access the middle tier over an HTTP connection, such as the Internet. Included in this tier are any applets that execute on the client’s machine.

16 Chapter 2 JRun Programming Model

• Middle tier The business logic of a website. The middle tier contains both the

presentation logic (web tier) and the business rules (EJB tier) that define a website. You use JRun to implement applications for the middle tier.

− Web tier Makes application functionality available on the web. It accesses data

and business functionality from other tiers and often encapsulates some user interaction control. In web service scenarios, other applications take the place of the client programs, accessing a J2EE application through its web tier.

− EJB tier Provides portable, scalable, available, and high-performance access to

enterprise data and business rules. It offers object persistence and access to business logic implemented as EJBs. Other tiers access server-side enterprise bean instances using the Java Remote Method Invocation (RMI) API.

• Data tier Integrates a J2EE application with other enterprise information systems.

The data tier provides data storage and other information services to the J2EE application. Databases, enterprise resources planning systems, mainframe transaction processors, legacy systems, and enterprise integration technologies usually reside in the data tier. Other tiers access the data tier with a driver supporting the JDBC API, and access non-database EIS resources with J2EE connector extensions, CORBA, or vendor-specific proprietary protocols.

The following figure shows a three-tier application model:

This three-tier architecture offers the following advantages to website developers:

• The tiers, or even components of the tiers, can be distributed across multiple

hardware systems to improve system scalability and performance.

• The middle tier shields clients from the complexities of accessing the enterprise data

store.

• EJBs provide a secure, component solution that can be reused by multiple

applications to share access to enterprise data. EJBs can be accessed by web applications, or web clients can access them directly.

• The component architecture lets you distribute application development across your

development group. For example, JSP developers are typically concerned with information presentation rather than with implementing business rules. Conversely, EJB developers are concerned with data access and manipulation, but not with presentation.

Enterprise application architecture 17

JRun support for the three-tier model

You use JRun to implement J2EE applications for the middle tier of the three-tier model. JRun completely supports the latest industry standards for developing enterprise applications composed of the following:

• Java Servlets Java Servlets are server-side components written in Java that let you

add custom functionality to a web server. Servlets are ideally suited for web-based applications because they support the HTTP request and response model and let you access the EJB components used for data access and manipulation. For more information on creating servlets, see Chapter 4, “Using Servlets and JSP” on page 37.

• JavaServer Pages JavaServer Pages (JSPs) let you create servlets from text files

containing a combination of HTML and scripting code. When a client requests a JSP, the page is translated into a Java Servlet. The scripting portion of a JSP lets you present dynamic content back to the client. In addition, you can access servlets, custom tag libraries, and EJBs from JSPs. For more information on creating JSPs, see

Chapter 4, “Using Servlets and JSP” on page 37.

• Enterprise JavaBeans EJBs let you develop and deploy reusable Java components

containing your business logic. The EJB specification defines a software component model whereby you can deploy server-side application logic (enterprise beans) using EJB-compliant application servers. JRun EJB support includes transaction and object persistence, and a security service to control bean access. For more information on creating EJBs, see Chapter 5, “Introduction to EJB” on page 47.

JRun lets you combine your business logic, implemented as EJBs, with presentation logic, implemented as web applications, into a single J2EE application. The web applications use servlets and JSPs to access the business logic contained within EJBs to deliver dynamic content back to a web client.

18 Chapter 2 JRun Programming Model

JRun programming environment

JRun lets you develop dynamic J2EE applications that include servlets, JSPs, and EJBs. Your applications can be hosted by a third-party web server, such as IIS or Apache, or by the integrated JRun Web Server (JWS).

The following figure shows a system using JRun to develop and deploy applications:

This figure shows the four main components of a JRun system:

• JRun server Provides the necessary services and web services to process J2EE

applications containing servlets, JSPs, and EJBs. You can create multiple JRun servers on a single system. As part of installing and configuring JRun, you can configure a connector for your web server to communicate with the JRun Connection Module within the server. For more information on web server connectors, see JRun Administrator’s Guide.

• Web server Receives a client request and delivers a response containing web

content. This content can be static web pages, or dynamically generated by a Java Servlet or a JSP processed by JRun. You can connect one or more web servers to a single JRun server, and vice versa. The previous figure shows example web servers that you can use with JRun. For a complete list of supported web servers, see Installing JRun.

JRun also provides its own built-in web server, the JWS. The JWS is a full-featured, fast, and lightweight all-Java web server that you can use to develop, test, and deploy web applications without loading or configuring a third-party web server.

• Enterprise application Comprises web applications and EJBs.

− Web application The Java Servlet specification defines a web application as

being composed of servlets, JSPs, static content such as HTML pages, images, and any other application resources. A JRun server can support multiple web applications mapped to different URLs. For example, JRun installs a samples JRun server that hosts several sample applications.

JRun programming environment 19

− EJB JRun provides a runtime environment for EJB components. The EJB

• Web services JRun lets you publish and consume web services, which are

distributed software components that provide platform- and location-independent computing, using XML and standard Internet protocols such as HTTP. Using JRun, you can reuse existing Java code as a web service or write new code specifically to publish as a web service. You also can create object- and tag-based clients that can invoke methods on remote web services, even when those services reside on non-Java platforms, such as Microsoft .NET.

The following sections contain detailed descriptions of these components.

JRun servers

A JRun server provides the services necessary for a web server to process J2EE applications containing servlets, JSPs, and EJBs. The JRun server runs in its own process outside any web server process. Running the JRun server in a separate process offers the following advantages:

• Increased stability of the web server

• The ability to start and stop a web server independently of JRun

• The ability to modify an application without restarting the web server

• The ability for a single JRun server to communicate with multiple web servers

specification defines a software component model whereby you can deploy server-side application logic (enterprise beans) using EJB-compliant application servers. The JRun EJB container provides automation of services, including component lifecycle, naming, transaction management, messaging, resource management, security, distribution, state management, and persistence.

A single installation of JRun supports multiple JRun servers. One reason to create multiple JRun servers is to isolate applications within the processes of separate computers. For example, each JRun server has associated with it a single Java Virtual Machine (JVM) that executes all servlets, JSP pages, and EJBs for that server. The JVM, also known as a JRE, is the software implementation of a CPU. It contains everything necessary to run programs written for the Java platform. By deploying applications on multiple JRun servers, and therefore, in their own JVMs, you can prevent one application from adversely affecting another. Additionally, you can define classpaths, data sources, EJBs, and other resources for each application at the server level.

Another reason to execute applications on different JRun servers is that each JRun server can implement its own user-authentication mechanism or set of user-authentication rules. Thus, you can take advantage of a particular server’s authentication settings. For more information on authentication, see JRun Administrator’s Guide.

Using JRun servers

JRun provides utilities to start, stop, and perform other functions on the JRun servers. This section describes these utilities for the different JRun platforms.

20 Chapter 2 JRun Programming Model

Windows services considerations

A JRun server responds to requests only after it is started. During JRun installation on a Windows NT or 2000 system, you can configure JRun as a Windows NT service. If you choose services, JRun starts all three servers when you start your Windows NT or 2000 system. Services run as system processes rather than as user processes. You can start, stop, and restart JRun using the Service Control Panel found in Start > Programs > Administrative Tools > Services. If JRun is running on a Windows platform other than Windows NT or 2000, or a UNIX platform, you must manually start each JRun server after starting your system. If you do not run JRun as a service, it runs as an application.

For more information on starting and stopping a JRun server, see JRun Administrator’s Guide or the JMC online Help.

Starting and stopping JRun servers

You can start and stop JRun servers using the following techniques:

• JRun server launcher

• Command line

Using the JRun server launcher

The JRun server launcher is a Java Swing application that you can use to start, restart, and stop JRun servers. You execute the launcher by running the jrun.exe file (Windows) or the jrun executable (UNIX), in the jrun_root/bin directory. The launcher contains buttons to start, restart, and stop JRun servers.

1(Windows) Select Start > Programs > Macromedia JRun 4 > JRun Launcher.

The JRun Launcher window appears:

2 Select a JRun server and click Start, Stop, or Restart.

JRun servers 21

Using the command line

You can start and stop JRun using the jrun.exe and jrun shell script command-line utilities. Use the following syntax:

jrun {options} {server-name}

The following table describes the options:

Option Description

-start Starts JRun.

-stop Stops JRun.

-restart Restarts JRun.

-status Displays status information for all JRun servers or for a specified

-nohup Starts JRun in a separate process.

JRun server.

-config

path-to-jvm.config

-version Displays the JRun version number (primarily for OEM use).

-build Displays the JRun build number (primarily for OEM use).

-info Displays additional information (primarily for OEM use).

Installed JRun servers

During installation, JRun creates three servers: admin, default, and samples. JRun also creates a JWS for each JRun server. The following figure shows the configuration of the admin and default servers:

Specifies a path to the JVM configuration file. Overrides the default, jrun_root/bin/jvm.config, to determine the JVM configuration.

22 Chapter 2 JRun Programming Model

This figure differs from the previous JRun system figure because it shows a process view of JRun—that is, it shows the services that run within each of the JRun server processes. As the figure shows, the JWS associated with each server runs within that server’s process.

When you install JRun, it dynamically assigns a web server port number that is not in use, starting at the default location. The following table lists the default JWS port locations for the JRun servers:

JRun server Default JWS port number

admin 8000

default 8100

samples 8200

You find the web server port settings in the following locations:

• The JRun Launcher, under Web Port

• The JMC Welcome page, in the Available Servers table, under HTTP port

• The jrun_server/SERVER-INF/jrun.xml file, in the following lines:

Admin server

Default server

For more information on JRun ports, see JRun Administrator’s Guide.

The admin JRun server executes all the administrative applications shipped with JRun, including the JRun Management Console (JMC). You are not limited to running the JMC on this server or at this port location.

You access the JMC application by making HTTP requests to an application resource just as you would for any web application. Therefore, the admin server requires that its associated JWS be running to handle these requests.

By default, the JWS associated with the admin server responds to HTTP requests received over port 8000. Requests to this port number have the following form http://localhost:8000. For example, use the following URL to connect to the JRun Management Console http://localhost:8000.

Additionally, (Windows only) you can open the JMC by selecting Start > Programs > Macromedia JRun 4 > JRun Management Console.

The default JRun server provides the necessary services for you to develop, test, and deploy servlets, JSPs, EJBs, and web applications. The JWS associated with the default server responds to HTTP requests received over port 8100. Requests to this port number have the following form http://localhost:8100.

JRun servers 23

By default, when a JRun server starts, the corresponding JWS also starts. However, to configure a third-party web server to communicate with the default JRun server, see Installing JRun.

Samples server

The samples server hosts the following JRun sample applications at

http://localhost:8200:

Application Description

Compass travel A simple online travel agent trip reservation system. This

TravelNet An online travel agent that sells trips from compass travel. This

application illustrates JSP and web services programming and is delivered as an enterprise application in an open-directory structure. For companion tutorial lessons, see Lesson 4, “Web

Services Tutorial” on page 97.

World music An e-commerce application that sells music. This application also

Web services Programming techniques used in JRun web services

programming.

Programming techniques

Flash gateway Flash movies and Flash Gateway adapters, which illustrate how to

SmarTicket A Java Blueprints J2ME application. The SmarTicket application

Java PetStore A Java Blueprints J2EE application that shows how to use the

Programming techniques described in this book. The techniques application uses the sample database, accessing it through the samples data source, which you can view through the JMC.

write Flash applications that communicate with JRun.

The SmarTicket application uses the smarticket database, accessing it through the smarticket data source, which you can view through the JMC.

24 Chapter 2 JRun Programming Model

Web servers

JRun extends a web server to enable it to process J2EE applications that deliver dynamic content generated by servlets, JSPs, and EJBs hosted by the JRun server. Because a web server acts as a client that communicates with JRun, the web server must establish a connection to JRun. JRun provides a native server connection module responsible for making the connection to the web server.

A native server connection module, or connector, is compiled for the specific web server, hardware architecture, and operating system. JRun has connectors for NSAPI, ISAPI, and Apache 1.3 and 2.0 DSO interfaces, supporting NES, IIS, and Apache web servers for each JRun supported hardware architecture and operating system.

You can connect one or more web servers to each JRun server. In a typical deployment environment, you connect a web server to the JRun server that processes your applications. The following figure shows a single web server connected to a single JRun server:

When a request is made for an application resource, the connector on the web server opens a network connection to the JRun connection module residing within the JRun server. The connection module serves as a transparent communicator and translates the request from the connector to the JRun server. The JRun server handles the request and sends its reply to the connection module service. For example, each JRun server listens to a different network port number for requests from a web server. In the previous example, the default JRun server listens to port 51000.

JRun provides several additional parameters for tuning the connection between a web server and a JRun server. For more information on the connection and tuning parameters, see JRun Administrator’s Guide.

JRun Web Server

JRun provides a ready-to-use Java web server that lets you begin developing J2EE applications even if you do not have an existing web server. This means your development team can create, test, and debug servlets using the built-in JRun Web Server (JWS), and then deploy them on your production server with guaranteed compatibility.

The JWS is an HTTP Version 1.0 server. In most cases, you will use a third-party web server with JRun on a live website.

Web servers 25

JRun support for J2EE applications

JRun completely supports the latest industry standards for developing J2EE applications, including the following J2EE modules:

• Web applications

• EJBs

• Enterprise resource adapters

• Enterprise applications

JRun lets you deploy J2EE modules from expanded directories or from archive files. The following table lists these components and files:

Component Archive file

web application WAR (.war file)

EJB JAR (.jar file)

enterprise resource adapters RAR (.rar file)

enterprise applications EAR (.ear file)

In a production environment, you deploy archive files for greater portability; whereas during development, expanded directories provide greater flexibility and ease-of-use.

The following figure shows the components in a J2EE enterprise application:

Prior to deploying a component, you must package its constituent parts in the appropriate directory structure, and create the component’s deployment descriptor. Each component has a deployment descriptor. A deployment descriptor is an XML file that describes the component. For example, an EJB deployment descriptor declares transaction attributes and security authorizations for an enterprise bean. Because this information is declarative, you can change it without requiring modifications to the bean’s source code. At runtime, the J2EE server reads the information and acts upon the bean accordingly.

26 Chapter 2 JRun Programming Model

In addition to the standard deployment descriptors, JRun creates JRun-specific deployment descriptor files for web applications, EJBs, resource adapters, and J2EE client applications that let you configure features that are unique to JRun. JRun-specific deployment descriptor names are made up of the corresponding standard deployment descriptor filenames preceded by the prefix jrun-.

For more information, see JRun Assembly and Deployment Guide and JRun Administrator’s Guide.

About web applications and JRun

As defined by the Java Servlet specification, a web application is a collection of servlets, JSPs, HTML pages, images, and any additional resources required by a web application. Because JRun supports the Java Servlet specification for web applications, you can develop a web application using JRun and deploy that application on any other web application server that supports this specification.

A configuration of a web application is defined by the contents of the web.xml file, which is the standard web application deployment descriptor file. This file contains all information required by an application server to execute the application. In addition to web.xml, JRun creates a JRun-specific deployment descriptor file, jrun-web.xml, in which you can specify JRun-specific behaviors, such as enabling or disabling dynamic servlet compilation and reloading.

When you distribute a web application, you can distribute it as the expanded directory structure, or you can distribute it as a single, compressed file called a Web ARchive (WAR) file. A WAR file contains the complete directory structure and all the files that define the application.

For more information on distributing web applications, creating WAR files, and deploying web applications, see Chapter 6, “Developing Web Applications” on page 55. Also, see JRun Assembly and Deployment Guide and JRun Programmer’s Guide.

About EJBs and JRun

EJBs provide a component architecture for building distributed, component-based applications. The architecture requires that an application server support enterprise-level features, such as transactions, security, and lifecycle management.

Because JRun provides full support for entity, session, and message-driven EJBs, you can develop and deploy robust solutions for business needs.

JRun provides two utilities that help you develop, package, and deploy EJBs:

Enterprise Deployment Wizard

You use the Enterprise Deployment Wizard to create EJB template code and deployment descriptors and deploy EJBs on a JRun server. The Enterprise Deployment Wizard can also generate CMP specifications in an entity bean deployment descriptor and supports the 1.1 and 2.0 CMP specifications. The wizard runs as a stand-alone tool or you can install it in your Java Integrated Development Environment (IDE). For more information, see JRun Assembly and Deployment Guide or the Enterprise Deployment Wizard online Help.

JRun support for J2EE applications 27

XDoclet (for EJBs and web applications)

JRun provides integration with XDoclet, a popular open-source tool that generates EJB interfaces and deployment descriptors based on special Javadoc comments in an enterprise bean implementation source file. You can also use XDoclet to generate web application deployment descriptors and JSP tag library descriptors based on comments in servlet or tag library source files.

JRun extends XDoclet to support the JRun-specific deployment descriptors, and provides automatic compilation and deployment. For more information, see JRun Programmer’s Guide.

About enterprise resource adapters and JRun

A resource adapter is a J2EE component that implements the J2EE connector technology for a specific EIS. The resource adapter provides a standard API through which a J2EE application communicates with an EIS resource that is outside of the J2EE server.

The JCA architecture defines a set of contracts that a resource adapter must support to plug into a J2EE product; for example, transactions, security, and resource management, that are managed by the JRun server.

The resource adapter provider creates the standard deployment descriptor file, ra.xml. You use jrun-ra.xml when you require more than one managed connection, to specify the resource adapter’s JNDI name, configuration properties, security information, and connection pool settings.

About enterprise applications and JRun

An enterprise application consists of one or more J2EE modules and an enterprise application deployment descriptor, application.xml, packaged in an EAR file or an expanded directory.

JRun completely supports the J2EE application model and provides a runtime environment for executing enterprise applications. J2EE enterprise applications are based on standardized, modular components, to which JRun provides a complete set of services and handles many details of application behavior automatically, such as transaction management, lifecycle management, and resource pooling.

JRun facilitates enterprise application development and deployment by providing the following features:

• You can deploy an enterprise application EAR file or expanded directory.

• JRun automatically deploys J2EE modules that are located in the server’s deploy

directory.

• JRun dynamically detects changes to J2EE modules in the deploy directory and

redeploys them.

For more information on developing and deploying enterprise applications, see JRun Programmer’s Guide and JRun Assembly and Deployment Guide.

28 Chapter 2 JRun Programming Model

CHAPTER 3

Introduction to J2EE

This chapter familiarizes you with the Java 2 Platform, Enterprise Edition (J2EE) and its related technologies.

Contents

• J2EE environment................................................................................................. 30

• J2EE platform technologies ................................................................................... 31

• J2EE APIs.............................................................................................................. 33

• Additional resources............................................................................................... 36

J2EE environment

The J2EE platform represents a single standard for implementing and deploying multitier enterprise applications. Typically, such applications are configured as a client tier to provide the user interface, one or more middle tiers that provide client services and business logic for an application, and a data tier consisting of backend enterprise information systems (EIS) that provide data management.

The following figure shows the tiers and some of the components and services that make up a typical J2EE environment:

Distributed applications consist of distinct components running in separate runtime environments, usually on different platforms connected through a network. Typical distributed applications are two-tier (client-server), three-tier (client-middleware-server), and multitier (client-multiple middleware-multiple servers).

The tiers have the following characteristics:

• Client tier Supports a variety of client types, both outside and inside of corporate

firewalls. Clients can run on desktops, laptops, PDAs, cell phones, and other devices. Client-side user interfaces can use HTML and Java applets. J2EE also supports stand-alone Java application clients.

• Middle tier Supports client services through web containers (includes Java Servlets

and JSPs) and business logic components and services through the EJB container. The middle tier resides on the J2EE server.

• Data tier Supports access to existing information systems through standard APIs.

The data tier includes enterprise infra-structure systems, such as enterprise resource planning (ERP), mainframe transaction processing, database systems, and other legacy information systems.

30 Chapter 3 Introduction to J2EE

J2EE platform technologies

The J2EE platform specifies technologies to support multitier enterprise applications. These technologies fall into the following three categories:

• Components Developers use component technologies to create the essential parts

of an enterprise application: the user interface and the business logic. You develop components as reusable modules that you can share among multiple enterprise applications.

• Containers Containers provide application components with J2EE system-level

services. Containers let you customize components to use the resources available in the environment in which they are deployed.

• Communication Since most enterprise applications require access to existing

resources, the J2EE platform supports APIs that provide access to database, transaction, naming and directory, messaging services, and legacy applications. The J2EE platform also provides technologies that enable communication between clients and servers and between collaborating objects hosted by different servers.

Components

A J2EE component is a self-contained functional software unit that is assembled into a J2EE application with its related classes and files and communicates with other components.

Containers

The J2EE platform supports the following types of components:

Component Includes

Client Web browsers, applets, and applications (optionally JavaBeans, but

not considered a J2EE component)

Web Java Servlets, JSPs, (optionally JavaBeans, but not considered a

J2EE component)

Business EJBs (session, entity, and message-driven beans)

Before a component can be executed, it must be assembled into a J2EE application and deployed into its container. Containers are standardized runtime environments that provide specific component services, such as life cycle management, security, deployment, and runtime services. Each type of container (EJB, web, JSP, servlet, applet, and application client) also provides component-specific services.

The assembly process involves specifying container settings for each component in the J2EE application and for the application itself. Container settings customize the underlying support provided by the J2EE server, including services such as security checks, transaction management, Java Naming and Directory Interface (JNDI) lookups, and remote connectivity. You specify application behavior at assembly or deployment time with deployment descriptors. Deployment descriptors are text files that specify component behavior in terms of well-defined XML tags.

J2EE platform technologies 31

For more information on J2EE application assembly and deployment, see JRun Assembly and Deployment Guide.

Containers provide all application components with the J2EE platform Application Programming Interfaces (APIs). For detailed descriptions of the APIs, see “J2EE APIs” on

page 33.

Communication

Communication technologies provide mechanisms for communication between clients and servers and between collaborating objects hosted by different servers. The J2EE specification requires support for the following types of communication technologies:

• Internet protocols Includes Transport Control Protocol over Internet Protocol

• Remote Method Invocation (RMI) protocols

• Object Management Group (OMG) protocols Includes the Common Object

• Messaging technologies Includes Java Message Service (JMS), JavaMail, and

• Data formats Includes HTML, image files in two formats, GIF and JPEG, JAR

(TCP/IP), Hypertext Transfer Protocol (HTTP) 1.0, and Secure Socket Layer (SSL)

3.0.

Request Broker Architecture (CORBA) technologies, Java Integration Definition Language (IDL), and RMI over Internet Inter-ORB Protocol (IIOP).

JavaBeans Activation Framework (JAF).

files, class files (compiled Java files), and XML.

The next section contains more information on the J2EE APIs.

32 Chapter 3 Introduction to J2EE

J2EE APIs

J2EE builds on the existing technologies in the Java 2 Platform, Standard Edition (J2SE). J2SE includes the base Java support and various libraries with support for applets and applications. A J2EE compliant application implements both the J2EE and J2SE APIs.

The following figure shows the technologies included with J2EE:

EJB 2.0

The following sections describe the J2EE platform specifications.

The EJB architecture is a server-side technology for developing and deploying components containing the business logic of an enterprise application. Enterprise JavaBeans components, called enterprise beans, are scalable, transactional, and secure.

An enterprise bean is a body of code with fields to implement modules of business logic. Enterprise beans are building blocks that you can use alone or with other enterprise beans to execute business logic on a J2EE server.

Enterprise beans are hosted by an EJB container. In addition to standard container services, an EJB container provides a range of transaction and persistence services and access to the J2EE service and communication APIs.

The EJB 2.0 specification defines three types of enterprise beans: session beans, entity beans, and message-driven beans (MDB). For more information on EJBs, see Chapter 5,

“Introduction to EJB” on page 47.

J2EE APIs 33

Java Database Connectivity 2.0

The Java Database Connectivity (JDBC) API is a standard Java extension for data access that lets Java programmers code to a unified relational database API. By using JDBC, you can issue SQL statements and process database results from Java programming language methods. Clients program to the JDBC API, which is implemented by a JDBC Driver, an adapter that can communicate with a particular database in a proprietary way.

The JDBC API has two parts: an application-level interface used by the application to access a database, and a service provider interface to attach a JDBC driver to the J2EE platform.

Java Servlet 2.3

Java Servlet technology lets you define HTTP-specific servlet classes. A servlet class extends the capabilities of servers that host applications accessed by way of a request-response programming model. Although servlets can respond to any type of request, they are commonly used to extend the applications hosted by web servers.

For more information on servlets, see Chapter 4, “Using Servlets and JSP” on page 37.

JavaServer Pages 1.2

JavaServer Pages (JSP) technology lets you put snippets of servlet code directly into a text-based document. A JSP page is a text-based document that contains two types of text: static template data which can be expressed in any text-based format such as HTML, WML, and XML, and JSP elements that determine how the page constructs dynamic content.

For more information on JSPs, see Chapter 4, “Using Servlets and JSP” on page 37.

Java Message Service 1.0

The Java Message Service (JMS) API is a messaging standard that allows J2EE application components to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous. By passing messages asynchronously, a process can be offline when a message is initially sent and respond to messages whenever it is convenient.

Java Transaction API 1.0 and Java Transaction Service

A transaction is a unit of work that makes a set of guarantees about its execution. For example, one guarantee is that any code executing within the scope of a transaction is all executed or not executed at all. Transactions are required to maintain a consistent system state. They allow multiple users to modify the same data, yet each is isolated from the others.

The J2EE architecture provides a default auto commit to handle transaction commits and rollbacks. An auto commit means other applications viewing data will see the updated data after each database read or write operation. However, if your application performs two separate database access operations that depend on each other, you use the

34 Chapter 3 Introduction to J2EE

Java Transaction API (JTA) to demarcate where the entire transaction, including both operations, begins, rolls back, and commits.

To facilitate transactions, J2EE has two APIs: JTA and Java Transaction Service (JTS). JTA is a high-level transaction interface that your applications use to control transactions. JTS is a set of low-level transaction interfaces that EJBs use behind the scenes (your client code does not directly interact with JTS). One of the main advantages of EJBs is that the EJB container manages transactions declaratively, with no transaction logic required in the code.

JavaMail 1.2

The J2EE platform includes the JavaMail API with a JavaMail service provider that application components can use to send Internet mail. J2EE includes JavaMail to support applications such as e-commerce websites for its ability to send order confirmations and other user feedback. The JavaMail API has two parts: an application-level interface used by the application components to send mail, and a service provider interface.

JavaBeans Activation Framework 1.0

The JavaBeans Activation Framework (JAF) provides standard services to determine the type of an arbitrary piece of data, encapsulate access to it, discover the operations available on it, and create the appropriate JavaBeans component to perform those operations. JavaMail uses JAF.

Java API for XML 1.1

XML is a language for representing and describing text-based data so the data can be read and handled by any program or tool that uses the XML API. For example, a J2EE application can use JAXP to produce reports, and different companies that receive the reports can handle the data in a way that best suits their needs. One company might put the XML data through a program to translate the XML to HTML so it can post it on the web and another company might read the XML data into its J2EE application for processing.

J2EE Connector API 1.0

J2EE supports integration with existing enterprise information systems (EIS) through connectors called resource adapters. A resource adapter is a vendor-specific bridge that links an existing system to J2EE.

J2EE tools vendors and system integrators use the J2EE Connector API (JCA) to create resource adapters that support access to legacy systems that can be plugged into any J2EE product. A resource adapter is a software component that lets J2EE application components access and interact with the underlying resource manager. Because a resource adapter is specific for a resource manager, there is typically a different resource adapter for each type of database or EIS.

The JCA architecture defines a set of contracts that a resource adapter must support to plug into a J2EE product; for example, transactions, security, and resource management.

J2EE APIs 35

Java Authentication and Authorization Service 1.0

Java Authentication and Authorization Service (JAAS) provides a way for a J2EE application to authenticate and authorize a specific user or group of users. JAAS is a Java programming language version of the standard Pluggable Authentication Module (PAM) framework that extends the Java 2 platform security architecture to support user-based authorization.

Java Naming and Directory Interface

Java Naming and Directory Interface (JNDI) is a standard for naming and directory services. Applications rely on JNDI for looking up distributed components (EJBs) and other resources (such as data sources, resource adapters, JavaMail, and JMS) across a network. JNDI is a key technology in the JRun architecture.

Common Object Request Broker Architecture compliance

J2EE supports two Common Object Request Broker Architecture (CORBA)-compliant technologies: JavaIDL and RMI-IIOP.

CORBA is a unifying standard for writing distributed object systems. The standard is completely neutral with respect to platform, language, and vendor and incorporates a variety of important technologies useful for advanced middleware development, cross-language support, and legacy integration.

Java Integration Definition Language

You use Java Integration Definition Language (IDL) to define interfaces to remote CORBA objects. The interfaces are independent of operating systems and programming languages. Java IDL also lets distributed objects use the full range of CORBA services. J2EE is fully compatible with CORBA.

Java Remote Method Invocation and RMI-IIOP

Java Remote Method Invocation (RMI) is a mechanism for invoking methods remotely on other computers. It allows interprocess communication and provides other communication-related services. RMI-IIOP is a portable extension of RMI that uses the Internet Inter-ORB Protocol (IIOP) as a communications protocol. IIOP is also necessary for integration of J2EE applications with CORBA systems.

Additional resources

For more information on J2EE resources, see “Developer resources” on page viii and

“Other resources” on page x.

36 Chapter 3 Introduction to J2EE

CHAPTER 4

Using Servlets and JSP

This chapter introduces servlet development using Java and JSPs. It highlights concepts and objects common to both environments. It includes sample code for a Java Servlet and a JSP, as well as a summary of changes in the servlet API.

Contents

• Using Java Servlets ................................................................................................. 38

• Servlets and JSPs.................................................................................................... 41

• Writing servlets in Java .......................................................................................... 45

• Writing servlets as JSPs .......................................................................................... 46

Using Java Servlets

Java Servlets are server-side components written in Java that let you add custom functionality to a web server. A servlet runs on a web server and features high performance, database connectivity, stability, and security.

Unlike CGI scripts, which are often written in C++ and Perl for a specific web server implementation, servlets are written in Java and, therefore, include all the benefits of the Java programming language, including portability—the “write once, run anywhere” feature of Java.

Servlets are ideally suited for web-based applications because they support the HTTP request/response protocol. The following figure shows the basic processing model of a Java Servlet:

As you can see in this figure, the web server receives the HTTP request, determines that the request references a servlet, and forwards the request to the servlet engine, which invokes the appropriate servlet. The servlet processes the request and returns a response that the web server then forwards back to the client.

You can use servlets to write sophisticated applications without being encumbered by the complexities and platform-specific behaviors of a specific web server implementation. The servlet API supports the building blocks of a web application, such as HTML, form data, request headers, and cookies.

Invoking servlets

A client invokes a servlet by referencing a URL, as it would any web resource. The fact that a URL references a servlet is transparent to the web client.

Typically, a client invokes a servlet in one of the following ways:

• By accessing a JavaServer Page JavaServer Pages (JSPs) are a combination of

HTML and scripting code (typically written in Java or JavaScript). The first time a client accesses a JSP file, JRun translates the file into Java source code, compiles the source-code into a Java Servlet, and then loads and executes the servlet. The web server forwards any HTML output from the servlet back to the web client.

Subsequent client accesses to the JSP file are very efficient because the servlet executable remains in memory. This means JRun can reference the servlet image in memory, and bypass the compile and load steps.

• By directly referencing a URL that is mapped to a servlet The servlet remains in

memory, and subsequent calls to the servlet reference the memory image.

38 Chapter 4 Using Servlets and JSP

Servlet benefits

Servlets offer many benefits to web developers over existing server-side application development technologies. Some of these benefits are associated with the Java programming language and others are associated with servlet technology. This section discusses several benefits of using servlets and Java.

Benefits of using servlets

Servlet technology offers the following benefits to web developers:

• Security Because servlets are invoked through the web server, your business logic

cannot be directly exposed to the client. In addition, servlets are isolated from each other so that an error in one servlet cannot corrupt any other servlet.

• Performance One of the biggest differences between existing server-side

applications, such as CGI, and servlets is performance. A servlet is loaded once when it is called. The servlet remains in memory and is not reloaded until it changes. A modified servlet can be reloaded without restarting the web server or application.

In addition, servlets are multithreaded and run within the process of the servlet server. A process context switch is not required to handle each servlet request.

• Portability Using JRun, servlets adhere to the industry-standard servlet

specification and are portable to any other web server that supports the servlet standard or uses JRun. Portability is important for servlet vendors because they do not have to maintain a different version of the servlet for different web servers and server platforms.

• Stability Servlets execute outside the process of the web server. Therefore, if a

servlet produces an error, only the process executing the servlet is affected; the web server process is isolated and is not affected.

• State persistence Multiple invocations of the servlet can share static or persistent

information. This lets you share information between multiple users or within a session.

Benefits of using Java

Some of the most important benefits of servlets are a result of their being implemented in the Java programming language. Because servlets take advantage of the inherent portability of Java, they can run on all web servers and server platforms supported by JRun.

Java offers a number of benefits for application programmers, including the following:

• Application portability

• Object-oriented programming

• Simplified programming model

• Multithreading support

• Automatic garbage collecting

Because you develop your servlets using Java or JavaServer Pages, you receive the additional benefits of the Java programming language.

Using Java Servlets 39

Creating servlets

JRun provides two methods for creating servlets: writing Java programs and writing JSPs. When you write Java programs, you have full access to the data-processing capabilities and benefits of Java. Typically, you use Java to write servlets that perform complex data manipulation such as database access.

You can also create servlets from JSPs, which are a type of server-side scripting that combines HTML and scripting code. JSPs provide access to the full power of the Java programming language, but use a simple mechanism to embed Java code within HTML code. They are often used to implement servlets that produce HTML results returned directly to a client browser.

This book describes both methods of servlet creation.

JRun support for servlets

One of the primary reasons to use JRun to work with servlets is that not all web servers have implemented servlet functionality. JRun extends your web server to handle servlets.

Even if your web server has the capability to run servlets, the server’s implementation of the servlet standard might be specific to that server or the hardware platform hosting the server. JRun offers a completely portable servlet solution. You can use any servlet that you write using JRun on any other web server that uses JRun, or any web server that supports the J2EE servlet standard. JRun supports the Java Servlet 2.3 specification, which introduces two important features: servlet event listeners and filters.

JRun also provides a ready-to-use Java web server that you can use to develop servlets, even if you do not have access to an existing web server. You can create, test, and debug servlets using the built-in JRun Web Server, and then deploy them on your production server with guaranteed compatibility.

JRun support for JSPs

JRun support for JSPs includes all the capabilities of page compilation as defined by the Java web server and the current JSP 1.2 specification. JRun provides the following features:

• Complete compatibility with JSP 1.2 specification

• Full support for the JSP <jsp:useBean> tag

• Support for extending JSPs for true object-oriented page design

• Support for recursive dependent file compiling

• Support for presentation templates

• Support for all Java Virtual Machines (JVMs) and Java compilers

The JSP 1.2 specification includes the following additions:

• Two tag types: IterationTag and TryCatchFinallyTag

• An XML syntax for JSP pages (JSPX), which makes it easier to automate the

authoring of JSP pages

• A number of enhancements to Tag Library Descriptors (TLD) that improve

portability and better support authoring tools

For more information, see JRun Programmer’s Guide.

40 Chapter 4 Using Servlets and JSP

Servlets and JSPs

With JRun, you can create server-side Java applications using servlets and JSPs. Because JRun translates JSPs into servlets, many of the objects available to native servlets (as follows) are also available natively to JSPs:

• HTTP requests and responses

• Output

• Filters

• Event Listeners

• Exceptions

• PageContext

• Sessions

• Context (application)

• Configuration information

• Application deployment (for example, WAR files and DTDs)

The following pages introduce these objects. For detailed information about using these objects, see JRun Programmer’s Guide.

HTTP requests and responses

Servlets are invoked when an HTTP request references the servlet, either directly as a Java Servlet, or indirectly as a JSP file. Servlets access the information stored within the HTTP request, process the information, and return results to the client as part of an HTTP response. The following figure shows the anatomy of a HTTP request and response:

HTTP requests contain information sent to the servlet from the client. For example, if the servlet is invoked by a form, the servlet must access the form data stored in the request before processing. The form data might contain login information used to verify a user, registration information written to a database, or information about a product added to a user’s shopping cart.

You can access HTTP request information in the following ways:

• In a Java Servlet, use the javax.servlet.HttpServletRequest object, which

defines methods that you can use to access the information stored within the request.

• In a JSP, use the implicit JSP object request. You can use the same methods with the

request object as you can with the

javax.servlet.HttpServletRequest object.

Servlets and JSPs 41

Servlets answer a request by constructing an HTTP response and sending that response back to the client. Within your servlet, you access the HTTP response to write information within the response that is sent back to the client.

You can access HTTP response information in the following ways:

• In a Java Servlet, use the javax.servlet.HttpServletResponse object, which

defines methods for accessing the information stored within the response.

• In a JSP, use the implicit JSP object response. You can use the same methods with

the response object as you can with the object.

The HTTP response includes an output stream for sending results back to the client.

Writing results back to the client

With servlets, you can return dynamic content to the requesting client. That output is generated based on information passed to the servlet or on information that the servlet calculates. For example, a servlet can use a passed form attribute (accessed using the request object) to return formatted database data. Alternatively, if the application has a method of maintaining user preferences, the servlet might set the display color of the browser based on stored preference information.

You return information through the HTTP response, in the following ways:

• Servlets use the javax.servlet.HttpServletResponse object’s PrintWriter or

ServletOutputStream interfaces. These interfaces include println and print

methods, which let you write to the output stream.

• JSPs use the implicit JSP object out. The out object also includes println and

print methods.

javax.servlet.HttpServletResponse

Using servlet filters

The Servlet 2.3 specification introduces servlet filters, which give you access to the HTTP request and response objects for pre- and post-processing. Filters process request objects before they get to the server, or process response objects after they leave the server and before they are returned to the client. You can also invoke filters in a chain so that one filter can pass the request or the response to another in the chain, and so on. You can use filters to do the following tasks:

• Take flow-control logic out of web application components.

• Examine and modify the request object before the server receives it from the client.

• Examine and modify the response object before the client receives it from the server.

• Change the content of the response.

For more information on using filters, see JRun Programmer’s Guide.

42 Chapter 4 Using Servlets and JSP

Using event listeners

One of the major new features of the Java Servlet 2.3 specification is the addition of servlet event listeners. The specification provides listener classes for web applications. Also known as event handlers, event listeners provide call-back methods that JRun calls when certain events occur. Event listeners help you manage disparate elements of the web application and track state changes in the ServletContext and HttpSession objects.

There are two basic types of servlet event listeners that watch the activity of the ServletContext and HttpSession objects. Each type has a listener interface and an attribute listener interface, as the following table shows:

Servlet object Associated listener interfaces

ServletContext ServletContextListener

HttpSession HttpSessionListener

You use event listeners for a number of common tasks, including the following:

• Logging

• Managing sessions

• Tracking application server resources

ServletContextAttributeListener

HttpSessionAttributeListener

For more information on using event listeners, see JRun Programmer’s Guide.

Handling exceptions

Exceptions are errors detected within your servlet. Exceptions can occur when JRun translates a JSP to a Java class file, or when the servlet executes.

You represent exceptions in the following ways:

• In a Java Servlet, an exception is represented by an instance of the

javax.servlet.ServletException class.

• In a JSP, you reference an exception using the exception object.

Maintaining page context information

The JSP pageContext object provides a mechanism for storing information that is local to the JSP. JRun creates a new pageContext object for each page request; the object is created when the page is invoked, and destroyed when the page completes. Methods of the pageContext object let you access information about the JSP and perform other actions.

Java Servlets have no equivalent object.

Servlets and JSPs 43

Working with sessions

HTTP is a stateless protocol. A web server receives a request, sends a response, then terminates the connection to the client. The web server does not maintain information about the client, so it cannot determine when another request comes from the same client. This inability to track clients and their navigation through a website makes it difficult to do any complex transactions on a website.

However, JRun supports a session object, which you can use to track a user during the entire interaction with the web server. With the session object, you can track users as they shop for items or send registration or preference information. You can also eliminate the need for users to re-enter information every time that they connect to your site. A session object gives you a single location to store and retrieve information throughout a user’s connection to your website.

In a simple implementation, your application might retain the user name; in a secure implementation, your application might retain the user name and password; in an e-commerce system, your application might maintain the shopping cart. In applications that do not use the Servlet API, you typically store session information using an application-specific storage mechanism and return a key value to the browser through a hidden form field or a cookie. Subsequent requests use this key value to look up the previously stored session information.

Cookies are stored on the server and referenced with a session ID that is passed back and forth between the client and the server. Cookies are a general mechanism used by server-side applications to store information in individual browsers. The server-side application can retrieve cookies stored in a browser. With cookies, your web application can create specific variables for each browser. Such variables might include a user name or the last-accessed date. If you enable session tracking through cookies, JRun creates a session-tracking cookie named jsessionid (you can control the cookie name through the JMC). Cookies provide a persistence mechanism that you can use to compensate for the HTTP protocol stateless nature.

You can access session information in the following ways:

• In a Java Servlet, use the javax.servlet.http.HttpSession object.

• In JSPs, use the implicit JSP session object.

Tracking an application’s context

You use the context object to store information about your application and to share information among the various components of the application.

For example, your application might consist of multiple servlets (written in Java and as JSPs), HTML pages, and other server-side components. To let components of the application communicate, you can use the application context object to store and retrieve the information. Information available through the context object includes the following:

• Attributes passed to the request

• Initialization parameters

• MIME type

• Version information

• Path information

44 Chapter 4 Using Servlets and JSP

You can access application information in the following ways:

• In a Java Servlet, use the javax.servlet.ServletContext object.

• In a JSP, use the implicit JSP application object.

Accessing configuration information

JRun passes configuration information to a servlet when it is initialized. This configuration information includes name-value pairs, which describe initialization parameters, and the servletConfig object, which describes the context within which the servlet is running.

You can access configuration information in the following ways

• In a Java Servlet, use the javax.servlet.ServletConfig object.

• In a JSP, use the implicit JSP config object.

Writing servlets in Java

The following example shows the complete source code for a functioning Java Servlet:

import java.io.*; import javax.servlet.*; import javax.servlet.http.*;

public class SimpleServlet extends HttpServlet {

public void doGet(ServletRequest req, ServletResponse resp)

throws IOException, ServletException {

resp.setContentType("text/html"); PrintWriter out = resp.getWriter(); out.println("<html><head><title> SimpleServlet Output "); out.println("</title></head><body>"); out.println("<h1> SimpleServlet Output </h1>"); out.println("</body></html>");

}

In contrast to JSPs, you must compile servlets before they can be tested or deployed. When requested, this servlet outputs text containing HTML tags back to the client.

Although this servlet is relatively simple, it does show the basic form and structure of a Java Servlet.

For tutorial exercises on writing servlets, see Lesson 1, “Servlet Tutorial” on page 69.

Writing servlets in Java 45

Writing servlets as JSPs

The previous section includes an example of a servlet written in Java. JRun also supports a second method for developing servlets that relies less on Java coding: JSPs. JSPs let you create servlets from text files containing a combination of HTML and scripting code.

The scripting code within a JSP is a combination of JSP syntax and, typically, JavaScript (a subset of ECMAScript) or Java. For more information on JSP syntax and on choosing your scripting language, see JRun Programmer’s Guide.

When a JSP file is requested for the first time, JRun translates it into a Java source file and then compiles the file into a Java class file. So, you can create servlets without writing a line of Java code. Because the runtime image of a JSP file is a Java class file, the web server cannot distinguish between a file created in Java and one created as a JSP.

JSP files can also call other servlets written in Java or implemented as JSP files. The following example shows a simple JSP that writes “

Hello World” to the browser

screen five times:

<html> <head> <title>Greetings</title> </head> <body>

<% for(int i=0;i<5;i++) { %> <h1>Hello World!</h1> <% } %>

</body> </html>

A JSP filename ends in the extension .jsp. JRun recognizes requests for JSPs and translates the JSP into a Java Servlet for execution. For more information on developing JSPs, see JRun Programmer’s Guide.

46 Chapter 4 Using Servlets and JSP

CHAPTER 5

Introduction to EJB

This chapter describes fundamental Enterprise JavaBean (EJB) elements and concepts and JRun-specific EJB features. JRun Programmer’s Guide explains these features in detail.

Contents

• EJB Overview........................................................................................................ 48

• Container services..................................................................................................49

• EJB types...............................................................................................................49

• Using EJB in JRun................................................................................................. 52

EJB Overview

EJBs provide an architecture for building distributed, component-based, enterprise-level Java 2 Platform, Enterprise Edition (J2EE) applications. Enterprise JavaBeans components, called enterprise beans, are scalable, transactional, and secure. EJBs written using only features in the EJB specification are portable to other J2EE application servers.

Enterprise beans are hosted by an EJB container. In addition to standard container services, an EJB container provides a range of transaction and persistence services, and access to the J2EE service and communication application programming interfaces (APIs). The EJB container handles the complexity of lower-level services, such as component life cycle, state management, persistence, multithreading, connection pooling, transaction management, and security.

For more information, see “Container services” on page 49. An application server that supports EJBs lets Java developers concentrate on

implementing the business logic of an enterprise application as reusable components. The EJB programming model is best suited for experienced server-side Java developers who understand the EJB API. JRun simplifies EJB development by providing functionality such as stubless, open-directory deployment, the Enterprise Deployment Wizard, and XDoclet support. For information, see “Using EJB in JRun” on page 52.

The parts of an EJB

The following table describes the parts of an EJB:

Part Description

Home interface Provides methods that control EJB lifecycle operations, including

Component interface Defines the business methods that are exposed to EJB clients.

Bean implementation Contains the methods that perform business logic. Also contains

Deployment descriptor

For more information, see JRun Programmer’s Guide.

creating, removing, and locating an EJB instance. There are two types of home interfaces:

• Remote home Used by remote clients.

• Local home Used by clients running on the same JRun

server.

There are two types of component interfaces:

• Remote Used by remote clients.

• Local Used by clients running on the same JRun server.

callback methods that EJB developers implement as necessary.

Specifies the declarative semantics that describe an EJB and the services it requires.

48 Chapter 5 Introduction to EJB

Container services

The EJB specification requires that EJB containers support a variety of services, each of which provides advanced functionality that EJBs can use with little or no coding in the EJB. The following table describes EJB container services:

Service Description

EJB types

Lifecycle management

Session management

Transaction A transaction is a unit of work that must be executed in one piece. Every

Security EJB supports authentication and role-driven access control. JRun 4

JRun automatically increases and decreases the number of available bean instances in proportion to the current server load.

JRun maintains state for stateful session beans (through passivation and activation callback methods) and entity beans (through entity-bean callback methods).

element of the unit must succeed in order for the transaction to succeed. EJB provides an architecture for two types of transaction management:

• Container-managed transactions (CMT) When you use CMT, the

container begins and commits or rolls back transactions on behalf of the bean.

• Bean-managed transactions (BMT) When you use BMT, you have

complete control over transactions. You can manage transactions from the client or, in the case of session beans, from the bean itself.

features a security system based on Java Authentication and Authorization Service (JAAS).

The EJB specification defines three types of enterprise beans: session beans, entity beans, and message-driven beans (MDB). These types are described in the following sections. For more information, see JRun Programmer’s Guide.

Session beans

You use session beans to manage business logic in your application. You often use session beans to coordinate interactions between EJBs and perform complex manipulations to accomplish tasks, such as generating prices of products, interacting with an ATM, or booking a trip reservation.

There are two types of session beans:

• Stateless session beans

• Stateful session beans

Stateless session beans

Stateless session beans do not maintain a conversational state. A single-request business process is one that does not require state to be maintained. Stateless session beans can accommodate these types of single-request business processes.

Stateless session beans are particularly useful in the session-entity facade pattern. A facade is a high-level interface that masks lower-level subsystems. Stateless session beans can

Container services 49

provide a high-level interface facade to business processes, in which session bean methods perform a unit of work, calling one or more methods in one or more entity beans.

For more information, see JRun Programmer’s Guide.

Stateful session beans

You can perform some business processes in a single business request, such as computing the price of goods or verifying a credit card account. Other business processes are more drawn out and last across multiple requests and transactions. For example, on an e-commerce website, adding items to an online shopping cart spans multiple method requests. The business process must track the user’s state from request to request. Stateful session beans maintain a conversational state on behalf of a client. If a stateful session bean changes during a method invocation, that same state is available to the client on the following invocation.

When used in a clustered environment, JRun supports failover by maintaining stateful session-bean state across the cluster.

For more information, see JRun Programmer’s Guide.

Entity beans

Entity beans represent objects that persist through a server shutdown. The data representing an instance of an entity bean is typically stored in rows and tables of a relational database, which you access using a JDBC data store. These tables can also span multiple databases.

BMP

CMP

There are two types of entity bean persistence:

• Bean-managed persistence (BMP) The entity bean implementation manages

persistence by coding database access and update statements in callback methods.

• Container-managed persistence (CMP) The container uses specifications made

in the deployment descriptor to perform database access and update statements automatically.

In BMP, the developer manages persistence by coding the appropriate database update code in callback methods. For example, the and the

For more information, see the

ejbFindByPrimaryKey method locates a database row using the primary key.

CreditCard and Reservation EJBs in the compass-ear

ejbUpdate method updates the database,

directory of the samples server.

In CMP, the container manages persistence by automatically synchronizing the bean with the database at certain points in the lifecycle. With CMP, your bean implementation coding is simpler and can focus on the business logic.

The EJB 2.0 specification requires that application servers support EJB 1.1 CMP and EJB 2.0 CMP.

50 Chapter 5 Introduction to EJB

Support for EJB 2.0 CMP

EJB 2.0 features major revisions to CMP, including the following:

• The EJB implementation class is defined as an abstract class.

• Persistence is managed using EJB query language (EJBQL).

• Relationships let you maintain relationships between entity beans.

• CMP beans can use select methods in addition to finder methods.

CMP enhancements are a major feature of EJB 2.0. In addition to using the resources and examples in this book, you should consult one of the trade press books that discusses EJB 2.0. The preface of this book includes a list of these books.

For more information on EJB 2.0 support, see JRun Programmer’s Guide.

Support for EJB 1.1 CMP

EJB 1.1 CMP support in JRun 4 is different from CMP support in earlier versions of JRun. Previously, you specified persistence information using environment entries in the

ejb-jar.xml file. In JRun 4, you provide persistence information using elements in the jrun-ejb-jar.xml file. These elements tell the EJB container how to perform

persistence management for the appropriate persistence actions, such as store, load, findByPrimaryKey, and so on.

Note: JRun 4 also supports the automatic deployment of JRun 3.1-style CMP beans.

For more information on EJB 1.1 support, see JRun Programmer’s Guide.

Message-driven beans

A message-driven bean (MDB) acts as a JMS message listener. MDBs are different from session beans and entity beans because they have no remote, remote home, local, or local home interfaces. They are similar to other bean types in that they have a bean implementation, they are defined in the ejb-jar.xml file, and they can take advantage of EJB features such as transactions, security, and lifecycle management.

Like session beans, MDBs are responsible for coordinating tasks involving other session and entity beans. A major difference between a message-driven bean and a session bean is how they are accessed. A session bean provides a remote interface that defines which methods you can invoke, whereas, a message-driven bean does not. A message-driven bean subscribes to or listens for specific asynchronous messages; it responds by processing the message and managing the actions other beans take in response to those messages.

The main advantage that MDBs have over simple JMS message consumers is that the EJB container can instantiate multiple MDB instances to handle multiple messages simultaneously.

For more information on MDB, see JRun Programmer’s Guide.

EJB types 51

Using EJB in JRun

This section describes features and functionality unique to the JRun EJB architecture.

Stubless deployment

One of the main JRun EJB features is stubless deployment. There is no JRun EJB deployment tool. You compile the EJBs, package them in a JAR file (optional), copy the compiled EJB interfaces to the client, and define this location in the client classpath. The JRun instance proxy handles the functionality formerly managed by the stubs.

Deployment options

JRun provides a flexible EJB deployment model that makes it easy to develop and deploy beans. The following table describes the features of this deployment model:

Deployment feature Description

Hot deploy If hot deploy is enabled, you can deploy an EJB by copying its JAR

file or directory structure into a deploy directory. By default, the JRun server root directory is set for hot deployment. To test this feature, start the samples JRun server and copy an EJB to the jrun_root/servers/samples directory.

When hot deploy is enabled, the JRun deployer detects changes to the EJB deployment descriptor and automatically redeploys the bean.

Additionally, when enabled, this feature deploys EJBs created for other application servers, including the Sun reference implementation and JRun 3.1.

Run from JAR or open directory

EJB clustering

When running EJBs in a JRun server that is part of a cluster, JRun enables load balancing and failover, ensuring high performance and reliability.

JRun also enables EJB clustering by default. To disable EJB clustering, set the

cluster-home and cluster-object elements in the jrun-ejb-jar.xml file to false.

Note: JRun does not enable EJB clustering for local beans.

For more information see JRun Administrator’s Guide.

JRun can run your EJB from a JAR file or from an open directory structure. When the JRun deployer finds a META-INF/ejb-jar.xml file, it deploys the EJBs specified in the file. Running from an open directory structure is particularly useful during the EJB development cycle because it eliminates many steps in the traditional EJB deployment and redeployment process.

52 Chapter 5 Introduction to EJB

XDoclet

JRun provides integration with XDoclet, an open source tool that generates code and deployment descriptors for EJBs, web applications, and JSP tag libraries. Many application servers are adding support for XDoclet and EJBs that are written using basic XDoclet tags, which are portable across servers.

For EJBs, you can use XDoclet to do the following tasks:

• Generate required EJB callback methods for a bean implementation using an abstract

class containing business methods as input.

• Generate remote, local, home, and local home interfaces from a bean implementation

class.

• Generate a deployment descriptor.

To control the processing performed by XDoclet, you use a combination of jrun.xml attributes and Javadoc-style comments in the bean implementation.

For more information on using XDoclet with an EJB, see JRun Programmer’s Guide.

The Enterprise Deployment Wizard

The JRun Enterprise Deployment Wizard streamlines the process of developing and deploying EJBs. Using its Swing-based graphical user interface, you can create any type of EJB, or edit the deployment descriptor of existing EJBs, package them into JAR files, and deploy them to JRun. In particular, the object-relational mapping capabilities of the Enterprise Deployment Wizard let you streamline the entity bean development process.

The Enterprise Deployment Wizard runs as a stand-alone tool, or as a plug-in on top of an IDE.

To start the Enterprise Deployment Wizard, run jrun_root/bin/jrunwizard.exe (Windows) or jrun_root/bin/jrunwizard (UNIX).

To install the Enterprise Deployment Wizard in an IDE, open a console window to the jrun_root/lib directory and issue the following command:

java -jar jrunwizard-installer.jar

For a list of currently supported IDEs, see the Release Notes. The Enterprise Deployment Wizard features a context-sensitive online Help system.

Refer to the online Help for usage information.

Using EJB in JRun 53

54 Chapter 5 Introduction to EJB

CHAPTER 6

Developing Web Applications

This chapter describes the structure of a web application and how JRun processes a web application and the resources in it. It also describes how to create, package, and deploy a web application.

Contents

• Introduction to web applications ........................................................................... 56

• About the web application directory structure ....................................................... 58

• Web applications, JRun servers, and web servers.................................................... 60

• Developing web applications ................................................................................. 62

• Deploying web applications................................................................................... 65

Introduction to web applications

A web application consists of servlets, JSPs, HTML pages, images, a standard deployment descriptor, optionally, JavaBeans and custom tag classes, and other resources, known as web components. You place these resources in a standard, predefined directory structure so that you can deploy them on any web application server.

This section describes the important features and benefits of web applications.

The benefits of web applications

The Java Servlet 2.3 specification defines web applications. The specification offers the following advantages:

• Standard definition for representing a web application, including the application

directory structure and other information required for defining the application.

• Standard definition for deploying a web application on an application server. A web

application written for an application server is guaranteed to be portable to any other application server that adheres to the Java Servlet specification.

• Relative links to reference application resources within the application. Because web

applications should not use absolute references, the location of an application on an application server is not important. Therefore, you can deploy a web application in a different directory or URL, or on a different server, from where it was developed.

JRun fully implements the web application architecture described in the Java Servlet 2.3 specification. You can develop a web application using JRun and deploy the application on any other web application server that supports this specification. JRun also completely supports the latest industry standards for developing enterprise-level J2EE applications, so your web applications can take advantage of and interoperate with enterprise-level J2EE resources and components.

Comparing web applications and enterprise applications

Enterprise applications are composed of one or more J2EE modules, typically web applications, resource adapters, and EJBs. The standards for enterprise application development on the web are based on the J2EE specification. JRun supports the J2EE application model and provides a runtime environment for executing enterprise applications.

An enterprise application also includes an enterprise application deployment descriptor, application.xml, typically packaged in a single, compressed file called a Enterprise ARchive (EAR) file.

For more information, see “Enterprise application architecture” on page 16. A web application is a subset of an enterprise application. However, you can deploy

standalone web applications. The configuration of a web application is defined by the contents of the web.xml file,

which is the standard web application deployment descriptor file. This file contains all information required by an application server to execute the application.

56 Chapter 6 Developing Web Applications

When you distribute a web application on JRun, you can distribute it as the expanded directory structure, or you can distribute it as a single, compressed file called a Web ARchive (WAR) file. A WAR file contains the complete directory structure and all the files that define the application.

For more information on developing and deploying web and enterprise applications, see

“Developing web applications” on page 62 and “Deploying web applications” on page

65. Also, see JRun Programmer’s Guide and JRun Assembly and Deployment Guide.

Using web applications

A single JRun server can support multiple web applications. Web applications can reference resources in other applications on the same server and share common resources. Sharing lets web applications access resources, such as EJBs and database driver classes, that many applications commonly use.

Web applications can also share data using a database or an EJB. For example, an e-commerce website can consist of several applications. Customers of this type of website can be identified by a login name and password. Then each web application uses the login name to access information in a shared database about that customer, such as shopping cart information, payment history, and address.

As you develop web applications, you must decide whether to divide applications between multiple JRun servers, use a single JRun server to host all of your applications, or to define a cluster of servers to handle them. A cluster is a set of servers that provide a single system image and manage application load and server load across the servers that participate in the cluster. For more information on clusters, see JRun Administrator’s Guide.

One reason to create multiple JRun servers is to isolate applications within the processes of separate Java Virtual Machines (JVMs). The JVM, also known as a JRE, is the software implementation of a CPU. It contains everything necessary to run programs written for the Java platform. Each JRun server has associated with it a single JVM that executes all servlets, JSP pages, and EJBs for that server. By deploying applications on multiple JRun servers, and, therefore, in their own JVMs, you can prevent one application from adversely affecting another. Additionally, you can define classpaths, data sources, EJBs, and other resources for each application at the server level.

Another reason to execute web applications in different JRun servers is that each JRun server can implement its own user-authentication mechanism or set of user-authentication rules. By executing applications in different JRun servers, you can take advantage of the server authentication settings. For more information on authentication, see JRun Administrator’s Guide.

Introduction to web applications 57

About the web application directory structure

The following figure shows the directory structure of a web application:

The application root directory, web_app in the figure, functions as the document root for serving application files. The web_app directory is often the WAR filename. This directory includes JSPs and HTML pages that you develop as part of a web application. For example, for a web application located at jrun_root/servers/jrun_server/web_app, the default welcome file is typically located at jrun_root/servers/jrun_server/web_app/index.html. jrun_server is the directory name of a JRun server and web_app is the name of a directory corresponding to the name of a web application hosted by the server.

Web applications must conform to the following directory structure:

Directory Description

Web_app Contains the WEB-INF directory and all files that must be

accessible to the client request, such as JSPs, HTML pages, cascading style sheets, images, and JavaScript files. You can place these files directly in the web application root directory or in subdirectories that do not use the reserved name WEB-INF.

WEB-INF (Required) Contains the classes and lib directories, the standard

web application deployment descriptor (web.xml), and possibly a JRun-specific deployment descriptor (jrun-web.xml).

This directory is not part of the public document tree of the application; that is, you cannot directly serve any file contained in this directory, or any of its subdirectories, to a client.

WEB-INF/classes Contains servlets, other Java classes, and associated resources that

are not packaged in Java ARchive (JAR) files.

WEB-INF/lib Contains servlets, other Java classes, and associated resources that

are contained within JAR or ZIP files. This subdirectory includes any JAR files that contain tag libraries.

58 Chapter 6 Developing Web Applications

Directory Description

WEB-INF/jsp Contains the files generated by JRun when translating a JSP.

WEB-INF/sessions Contains serialized JRun sessions used by the default session

persistence mechanism.

Enterprise applications conform to a similar directory structure as web applications. The application root directory, web_app, is often the EAR filename. The enterprise application deployment descriptor, application.xml, is located in the jrun_root/servers/jrun_server/web_app/META-INF directory.

Your web application is not limited to the directories and subdirectories listed above. You can add directories to the application for items such as Flash SWF files, HTML files, images, and other application resources. These directories constitute the public document tree for the web application for resources accessed directly by a client. For more information on adding directories to the application, see “Adding directories” on

page 62.

The deployment descriptor (web.xml)

A web application is defined by the contents of the WEB-INF/web.xml file, which is also called the deployment descriptor. A deployment descriptor is an XML file that contains configuration information used by the application for execution on an application server. The Java Servlet specification defines the contents of web.xml, so it is not specific to JRun. All platforms that support J2EE-compliant web applications, recognize and interpret the contents of a web.xml file.

You use the web.xml file to define the following types of configuration and deployment information for a web application:

• Servlet initialization parameters

• Session configuration

• Servlet and JSP definitions

• Servlet and JSP URL mappings

• MIME-type mappings

• Welcome file list

• Error pages

• Filters

• Event handlers

• Tag libraries

• Security information

• Resources, such as data sources and JMS connection factories

In addition to containing information about a web application, a web.xml file can also contain reference information about EJBs accessed by the web application. The standard deployment descriptors for web applications and EJBs have common elements for environment entries, EJB references, resource references, and security roles.

About the web application directory structure 59

In addition to the standard deployment descriptors, you can use the following JRun-specific deployment descriptor files:

• WEB-INF/jrun-web.xml Contains web application elements that are specific to the

JRun application server. This deployment descriptor lets you set a context-root for the web application, enable and disable automatic servlet compilation and reloading, set virtual paths, configure servlet session persistence and cookies, and set values for JNDI names.

• SERVER-INF/default-web.xml Has the same structure as the standard web.xml

file, but it applies settings to all the web applications in a JRun server. Contains default values for each web application web.xml file. This file includes definitions and mappings for global servlets, used internally by JRun.

You can edit the web.xml file using a standard text editor or an XML editor. JRun lets you specify additional elements in the jrun-web.xml and default-web.xml files. For a complete list of all properties in the standard web.xml file, see the Java Servlet 2.3 specification. For more information on JRun-specific deployment descriptors, see JRun Assembly and Deployment Guide.

Web applications, JRun servers, and web servers

One of your tasks when developing a web application is to deploy your application on a JRun server.

Mappings

Note: Do not deploy a web application on the admin JRun server; you use it primarily to administer JRun servers.

A JRun server can contain multiple web applications, enterprise applications, or a combination of both.

To assign client requests to the different web applications hosted by a JRun server, you map each web application to respond to a different URL pattern. In this way, the JRun server can forward the request to the appropriate web application.

JRun uses the following types of mappings when determining the file to return in response to a request:

Mapping Purpose

Application mapping Associate the web application’s context root with the physical

directory that contains the application.

Servlet mapping Associate a servlet with a URL mapping (such as MyServlet), a

prefix (such as /servlet), or suffix (such as .jsp) within the context root.

Welcome file mapping Define web application behavior if a request does not match

existing application or servlet mappings. Usually the welcome file mapping associates files with the index.html or other default page. For example, index.html and index.jsp in jrun_root/servers/default/SERVER-INF/default-web.xml.

60 Chapter 6 Developing Web Applications

Each web application running in a JRun server can have one context root mapping and multiple servlet mappings. You can define the context root in the jrun-web.xml file or let JRun substitute one for you. JRun determines the context root in the following order:

1 Checks the /WEB-INF/jrun-web.xml file for a context root mapping. 2 If the WAR file is uncompressed, JRun uses the WAR file root directory name. For

example, if the WAR file is deployed in the jrun_root/servers/samples/worldmusic-war/ directory, JRun uses worldmusic-war as the context root.

3 If the WAR file is compressed, JRun uses the WAR filename, minus the “.war”

extension. For example, if the web application is contained in techniques.war, JRun uses “techniques” as the context root.

To use web applications in an optimal manner, you must understand how JRun uses application mappings and servlet mappings to handle requests for HTML files, JSPs, and servlets. The following table describes the mappings that the JRun configuration files define:

Configuration file Mappings

default-web.xml Servlet, filter, and welcome file mappings.

Settings in the default-web.xml file apply to all web applications on this JRun server.

web.xml Servlet and filter mappings.

jrun-web.xml Virtual path mappings and optional application

application.xml Application mapping (context-root) for the web

Application mappings

An application mapping relates a context path to the name and directory path of a web application. The context path specifies the path prefix associated with a web application mapping. For a default application (rooted at the base of the web server URL namespace), the context path is an empty string. For a nondefault application, the context path starts with a forward slash (/) but does not end with one. For example, /compass maps request URLs that include /compass to the compass application.

For more information on understanding application mappings, see JRun Programmer’s Guide.

mapping (context-root) for stand-alone web applications (WAR files).

applications in an enterprise application (EAR file).

Web applications, JRun servers, and web servers 61

Developing web applications

This section describes how to create a web application, and then describes how to add resources and components to the web application.

Creating a web application

JRun provides an empty web application on the default JRun server that you can use for developing web applications. The web application root directory is jrun_root/servers/default/default-ear/default-war. JRun creates the basic directory structure of the application, a web.xml file with the minimal information in it, and an application URL mapping. You can begin developing servlets, JSPs, and EJBs and place them in the default-war directory structure.

In addition, when you create a JRun server using the JMC, JRun creates a default web application on that server. You use the same rules to add content to the default application as you do to any web application. For more information on adding resources to a web application, see “Adding web application components” on page 62.

Adding web application components

A complete web application can be composed of servlets, JSPs, HTML pages, Flash (.swf) files, images, tag libraries, JavaBeans, Enterprise JavaBeans, and other application resources. As part of developing a web application, you add these components to the directory structure of the application.

The following sections describe how to add components to a web application:

• “Adding directories,” on page 62

• “Adding HTML pages,” on page 63

• “Adding JSPs,” on page 63

• “Adding Java Servlets,” on page 63

• “Using the ServletInvoker,” on page 64

• “Adding tag libraries,” on page 64

• “Adding EJBs,” on page 64

• “Adding additional resources,” on page 65

Adding directories

The directory structure of a web application defines at least one subdirectory named WEB-INF. For a description of this directory, see “About the web application directory

structure” on page 58.

However, many web applications contain directories in addition to WEB-INF under the application root directory. As long as the additional directories do not contain .class or JAR files that must be included in the application classpath, adding a subdirectory to the application root requires no special action other than creating the directory.

For example, you commonly place image files in a directory named images under the application root directory. Another common directory is an include directory for any files shared by more than one application resource.

62 Chapter 6 Developing Web Applications

Adding HTML pages

The application root directory functions as the document root for serving application files. Add HTML pages for your application under the application root, or in any subdirectory of the application root except under the WEB-INF directory. For example, for a web application located at jrun_root/servers/jrun_server/web_app, you could include the default welcome file at jrun_root/servers/jrun_server/web_app/index.html.

Adding JSPs

JSPs contain a combination of HTML and scripting code. When a client first requests a JSP (.jsp file), the page is translated into a Java source code file (.java file) and compiled into a Java class file (.class file). For more information on creating JSPs, see Chapter 4,

“Using Servlets and JSP” on page 37.

To add a JSP to a web application, you copy the JSP to the application root directory or to any directory under the application root except those directories under WEB-INF.

Note: In JRun, the files generated in response to a request for a JSP are written to the WEB-INF/jsp directory.

Adding Java Servlets

Java Servlets are represented by a .class file. The procedure for adding a servlet to a web application depends on where you store the servlet. Typically, you store the servlet in one of the following locations:

• .class file in WEB-INF/classes or a subdirectory of WEB-INF/classes (reflecting a

Java package name)

• .class file in a JAR file in WEB-INF/lib

You include the directories WEB-INF/classes and WEB-INF/lib in the web application classpath; all .class and JAR files in these directories are reloadable.

An important concept is knowing how JRun serves up servlets. By definition, application servers cannot directly serve files from the WEB-INF directory or from any subdirectory of WEB-INF. However, servlet .class files typically go in WEB-INF/classes, a subdirectory of WEB-INF/classes, or WEB-INF/lib, within a JAR file. The following procedure describes how servlets serve data back to the client:

To add a servlet to an application:

1 Copy the servlet .class file, or a JAR file containing the servlet .class file, to the

appropriate directory:

• .class file in WEB-INF/classes

• JAR file in WEB-INF/lib

2 Define the servlet in the web.xml or default-web.xml file:

a Create a servlet element in web.xml. b Create a servlet URL mapping in web.xml.

A servlet mapping associates a servlet with a URL pattern.

Developing web applications 63

When a request URI has a servlet path that matches a specified URL pattern, JRun invokes the associated servlet. If you do not explicitly define a servlet, you can use the /servlet implicit mapping to request a servlet that you store in the WEB-INF/classes directory.

Using the ServletInvoker

JRun provides an implicit servlet mapping of /servlet to the general-purpose invocation mechanism for servlets that are not explicitly defined in the web.xml or default-web.xml files. To reference an undefined servlet, specify /servlet in the request URL, as follows: http://localhost:webserver:portnumber/web_app/servlet/servlet-class-name

Note: Do not include .class in the servlet class name.

You do not have to define servlet elements explicitly to process a servlet. The

ServletInvoker servlet creates a temporary servlet registration using the servlet class

name. You use the

for security and performance reasons, define explicit servlet definitions and mappings for all of your servlets and override the default production systems.

Adding tag libraries

The JavaServer Pages specification describes a framework for tag libraries. Tag libr a rie s let developers encapsulate sets of related functionality within a set of custom tags. JSPs can then use these tags to take advantage of the functionality built into the libraries. For example, you can create a library of tags for simplifying database access, performing e-commerce operations, re-writing URLs, or transforming XML.

ServletInvoker servlet, a

ServletInvoker servlet mostly during development and testing. However,

ServletInvoker mapping in your

Adding EJBs

A tag library consists of one or more actions, called tags or custom tags. Each action performs processing, as coded in an associated Java tag handler class. You define the functionality (including attributes) of a custom tag, code the tag handlers, and define each custom tag in the Tag Library Descriptor (TLD) file.

A deployable tag library incorporates tag handlers, a TLD file, Tag Extra Information (TEI) classes, and other supporting classes into a JAR file. This JAR file is typically located in the web application WEB-INF/lib directory.

For more information on tag libraries, see JRun Programmer’s Guide.

In order for a web application to access an EJB, the EJB must be deployed on the JRun server hosting the web application, or on a JRun server accessible to the web application.

For information on developing and deploying EJBs on JRun, see “Introduction to EJB”

on page 47.

64 Chapter 6 Developing Web Applications

Adding additional resources

Resources that you can add include image directories, JavaBeans, and class files for resources such as database drivers. When adding these resources to a web application, you must place them in the correct location in the web application directory structure. If the resource is represented by a .class or JAR file, it must be located in a directory included in the web application classpath (typically WEB-INF/classes or WEB-INF/lib).

Deploying web applications

JRun provides auto deploy and hot deploy features for dynamic deployment of web applications, enterprise applications, and other J2EE modules, such as EJBs and enterprise resource adapters, from the following module archive files or expanded directories:

• Web application (WAR file or directory)

• Enterprise application (EAR file or directory)

• Enterprise JavaBean (JAR file or directory)

• Enterprise resource adapter (RAR file or directory)

When you copy a module archive file or expanded directory to a deploy directory (jrun_root/servers/jrun_server, by default), JRun automatically deploys the application or module, if the server is running, or deploys it the next time you start the server. The deployment is dynamically updated when you modify a module archive file or deployment descriptor.

In a production environment, it is best to deploy archive files for greater portability. During development, deploying expanded directories provides the greatest flexibility and ease-of-use. For more information, see JRun Assembly and Deployment Guide.

Deploying a web application across a cluster

JRun also automatically deploys a web application across a server cluster when it detects an archive file in a cluster deploy directory. This feature does not support deploying expanded directories. The default cluster deploy directory is jrun_root/servers/jrun_server/SERVER-INF/cluster, but you can change the directory through the JMC or the jrun.xml file. When you use the JMC to deploy an application to a cluster, JRun copies the archive file to a cluster deploy directory on one of the clustered servers. The server must be running for web application deployment and synchronization across the cluster.

You must ensure that the web application resources, defined in the jrun_server/SERVER-INF/jrun-resources.xml, such as JMS destinations, JMS connection factories, JDBC data sources, and JavaMail sessions, are present or accessible on each server in the cluster.

For more information about JRun clusters, see JRun Administrator’s Guide.

Deploying web applications 65

Packaging a web application for deployment

Prior to deploying a web application, you must create the application deployment descriptors and package its parts in the appropriate directory structure.

Although there are many ways to prepare a web application for deployment, the basic web application deployment procedure includes the following steps:

1 Create a staging directory tree containing the JSPs, HTML files, images, and other

referenced files that must be accessible by the user’s web browser. To easily identify the directory as a web application directory, use a directory name

that ends with -war. Maintain the original directory structure of referenced files.

2 In the staging directory, create a directory called WEB-INF. 3 In the WEB-INF directory, create directories called classes and lib. 4 Copy the application servlets and any other unarchived class files to the

WEB-INF/classes directory.

5 If the web application uses JSP tag libraries, copy any tag libraries packaged in a JAR

file to the WEB-INF/lib directory. Copy any unarchived tag library classes to the WEB-INF/classes directory.

When deployed inside a JAR file, a TLD file must be in the META-INF directory or a subdirectory of the META-INF directory. When deployed directly to a web application, the TLD file must be in the WEB-INF directory or a subdirectory of it.

6 Place the web application deployment descriptor, web.xml and optionally,

jrun-web.xml, in the WEB-INF directory.

7 To prepare the web application for a production environment, package it in a WAR

file using the following jar utility command from the top level of the staging directory:

jar cvf web_app.war

where web_app is the web application name.

For more information, see JRun Assembly and Deployment Guide.

66 Chapter 6 Developing Web Applications

PART II

Tutorials

Part II contains tutorials to show you how to build a simple J2EE application. In the tutorial lessons, you add a JRun server and write the code for Java Servlets, JSPs, JavaBeans, and EJBs. You learn how to combine these elements to produce a flexible and scalable J2EE application. In the final tutorial lesson, you use web services to access data in a JRun sample application.

Servlet Tutorial.............................................................................................................69

JSP Tutorial.................................................................................................................. 83

EJB Tutorial ..................................................................................................................89

Web Services Tutorial................................................................................................ 97

LESSON 1

Servlet Tutorial

The following tutorial lessons show you how to develop, deploy, and run a simple J2EE application consisting of servlets, JavaServer Pages (JSPs), JavaBeans, and Enterprise JavaBeans (EJBs).

In this lesson, you set up the development environment, add a JRun server for the tutorial, and deploy the tutorial template application. In the first procedure, you code the logon servlet that provides the business logic to validate the user ID and password.

Contents

• Setting up the development environment .............................................................. 70

• Getting started with JRun...................................................................................... 71

• Deploying the tutorial enterprise application......................................................... 75

• Compass Travel J2EE application .......................................................................... 80

• Summary............................................................................................................... 82

Setting up the development environment

Before beginning the tutorial lessons, ensure that you set up your development environment.

To set up the development environment:

1 Install the following software:

Software Requirements

Web se rver

Text editor

JRun 4

• JRun-supplied web server (JWS)

• Supported external web server (optional)

• Any text editor

• Java integrated development environment (IDE)

• HTML editor, such as Macromedia Dreamweaver MX

For the system requirements, see

Installing JRun.

2 The tutorial files are located in the jrun_root/docs/tutorialfiles directory, referred to as

tutorial_root.

3 (Optional) Set up your Java IDE to work with JRun.

For more information, see “Using JRun with your Java IDE” on page 13.

70 Lesson 1 Servlet Tutorial

Getting started with JRun

Begin working with JRun by starting the admin JRun server.

To start the admin JRun server, do one of the following:

• Use the JRun command-line utility, from the jrun_root/bin directory (jrun_root is the

directory into which you installed JRun):

jrun -start admin

• (Windows only) Select Start > Programs > Macromedia JRun 4 > JRun Launcher.

Select the admin server, and click the Start button.

The admin JRun server must be running in order to use the JRun Management Console (JMC). You use the JMC for the initial tutorial procedures: adding a JRun application server and defining a JDBC data source.

To start the JRun Management Console:

1 Start the JMC in one of the following ways:

• Open a web browser and enter the following URL:

http://localhost:8000

Note: This procedure assumes that you are connecting to the JMC on the default JWS port 8000. If not, substitute 8000 with the admin web server port number, which you can find in the jrun_root/servers/admin/SERVER-INF/jrun.xml file, in the following lines:

Getting started with JRun 71

• (Windows only) Select Start > Programs > Macromedia JRun 4 > JRun

Management Console.

The JMC login window appears:

2 Enter your user name and password, and click Login.

Note: You set your user name and password during JRun installation. For information, see Installing JRun.

The JRun home page appears:

In the next section, you use the JMC to add a JRun server for the tutorial application.

Adding a JRun server

During installation, JRun creates three servers: admin, default, and samples. The admin server using the JMC. When adding or removing JRun servers, be aware that the servers require unique ports. For more information on understanding JRun ports, see JRun Administrator’s Guide.

hosts the JMC, by default. The next section describes how to add a JRun server

72 Lesson 1 Servlet Tutorial

You might add a JRun server for the following reasons:

• Many organizations build sites that are comprised of multiple web applications. By

having multiple JRun servers you can isolate these web applications. If one JRun server stops responding or must be restarted, the other servers and their applications remain running.

• You might also want to logically separate your JRun servers by type of user. For

example, having production, QA, and admin JRun servers can help organize your development workflow.

• The JMC lets you easily establish and manage server clusters. JRun automatically

deploys applications to all members of the cluster and provides connector-based load balancing and failover services to ensure high availability for your web servers and JRun servers.

In the following procedure, you add a JRun server for the tutorial application.

To add a JRun server:

1 In the top menu bar of the JMC, click Create New Server.

The Creating a New JRun Application Server window appears:

Getting started with JRun 73

2 Keep the default Host Name (localhost), enter the JRun Server Name for the tutorial

application, tutorial, and the JRun Server Directory (added automatically when you enter the server name, {jrun.home}/servers/tutorial):

The server creation process replaces the symbolic variable {jrun.home} with the directory in which you installed JRun.

3 Click Create Server.

The Port Settings window appears:

Note: Make a note of the web server port number. You use it to access the compass tutorial application on the tutorial server.

4 Keep the default port settings, and click Finish.

74 Lesson 1 Servlet Tutorial

5 After the JMC refreshes, you see the tutorial server listed in the Available Servers table

on the JMC home page and in the left pane.

Start

6 Start the tutorial server by clicking its start icon.

The server status changes from Stopped to Running.

Deploying the tutorial enterprise application

An enterprise application contains web applications and EJBs. You typically distribute an enterprise application as a single, compressed enterprise archive (EAR) file. The EAR file contains the complete directory structure and all the files that define the application.

In JRun, you deploy an EAR file in one of the following ways:

• Auto deploy Place the EAR file in an autodeploy directory on the target server. The

default autodeploy directory is jrun_root/servers/jrun_server. The name of the JRun server on which you are deploying the application is tutorial.

• JMC deploy In the JMC, click the JRun server name in the left pane to access the

server deployments window. Click the Add button in the Enterprise Applications table, browse to, or enter the path to the EAR file, and click Deploy.

Additionally, JRun lets you deploy an enterprise application from an open directory structure. Typically, you use this method during application development.

In the next procedure, you auto deploy the compass tutorial application open directory on the tutorial server. Then you use the JMC to add a JDBC data source and verify the connection to the database.

To deploy the tutorial application files:

1 Copy the compass-ear directory from tutorial_root. 2 Paste the compass-ear directory in jrun_root/servers/tutorial.

Deploying the tutorial enterprise application 75

In the JMC, you see the compass tutorial application deployed on the tutorial server:

Tutorial application

The following figure shows the JRun directory structure, expanded beneath the tutorial server, containing the deployed tutorial (compass) enterprise application:

jrun_root

Adding JDBC data sources

Using the JMC, you can add, remove, edit, and test JDBC data sources. The JMC provides an interface to the data source settings and will fill in most drivers and URLs for you.

In the next procedure, you use the JMC to create a data source for the tutorial application.

tutorial jrun_server

76 Lesson 1 Servlet Tutorial

To add a new JDBC data source:

1 In the left pane in the JMC, expand the tutorial server menu, expand Resources, and

click JDBC Data Sources. The JDBC Data Sources window appears:

2 In Data Source Name, enter compass. Select Pointbase Server in the Database Driver

drop-down list box. Click Add. The Data Source Settings window appears.

3 Enter compass as the Database Name, change the Server Port to 9292, and enter

PBPUBLIC in the User Name, Password, and Verify Password fields.

Deploying the tutorial enterprise application 77

4Click Submit.

The compass data source is added in the JDBC Data Sources table:

5 Start the compass (tutorial) database:

• (Windows) Open the jrun_root/pointbase directory and double-click on

compassdb.bat.

• (Linux/UNIX) Run the compassdb shell script.

6 Restart the tutorial server in one of the following ways:

• In the JMC, click the Restart icon next to the tutorial server.

• In the JRun Launcher, select the tutorial server, and click the Restart button.

7 Verify the connection to the compass database by clicking the verify icon next to the

compass JDBC data source:

Verify

You get a confirmation message.

78 Lesson 1 Servlet Tutorial

8 Verify the application deployment by opening a web browser to the following URL:

http://localhost:8101/compass/logon.jsp

Note: Use 8101 or the web server port number that JRun assigned when you created the tutorial server.

View the tutorial application login page:

In subsequent tutorial lessons, you code the application pages and business logic, including logging in, accessing trip data, and booking a trip.

Deploying the tutorial enterprise application 79

Compass Travel J2EE application

The Compass Travel tutorial application lets users browse adventure trip descriptions, booking information, and make trip reservations. You use HTML, servlets, JSPs, Java Beans, and EJBs to create the static and dynamic portions of the application.

Coding the logon servlet

A servlet is a server-side Java program that extends the functionality of a web server. You can use servlets to apply dynamic content and logic to HTML pages. Typically, you use Java to write servlets that perform complex data manipulations, such as database access.

You must compile servlets before you can test or deploy them. In JRun, when you modify the source code for a servlet in the WEB-INF/classes directory, JRun automatically recompiles and reloads the servlet when it is called (this behavior is enabled by default).

In the next procedure, you code the logon servlet. It validates the user ID and password provided by the user in logon.jsp. If the login is valid, home.jsp appears. Otherwise, LogonError.htm appears. This procedure shows how to write a servlet that accesses a database.

To code the logon servlet:

1 Open a text editor or Java IDE and copy and paste the following code:

package compass; import javax.servlet.*; import javax.servlet.http.*; import java.io.*; import java.sql.*; import javax.sql.DataSource; import javax.naming.InitialContext;

public class Logon extends HttpServlet {

private String validLogonPage; private String invalidLogonPage;

public void init() throws ServletException {

/*Read initialization parameters in web.xml:

- validLogonPage specifies which page to go to if the logon is valid.

- invalidLogonPage specifies which page to go to if the logon is invalid. Using this technique, we don't have to hardcode page names in the Servlet, and the Servlet is more reusable. */

validLogonPage = getInitParameter("validLogonPage"); if (validLogonPage==null) throw new ServletException

("web.xml error: init parameter 'validLogonPage' not found"); invalidLogonPage = getInitParameter("invalidLogonPage"); if (validLogonPage==null) throw new ServletException

("web.xml error: init parameter 'invalidLogonPage' not found"); } protected void doPost(HttpServletRequest request, HttpServletResponse response)

throws ServletException, IOException { String userId = request.getParameter("userId"); String password = request.getParameter("password");

80 Lesson 1 Servlet Tutorial

String firstName="";

String lastName="";

String sql= "SELECT password, first_name, last_name FROM user WHERE user_id=?";

Connection connection=null; PreparedStatement ps=null; ResultSet rs=null; boolean validLogon=false; try {

InitialContext ctx=new InitialContext();

DataSource ds=(DataSource) ctx.lookup("compass");

connection=ds.getConnection();

ps=connection.prepareStatement(sql);

ps.setString(1, userId);

rs = ps.executeQuery();

if (rs.next()) {

if (password.equals(rs.getString("password"))) {

validLogon=true; firstName=rs.getString("first_name"); lastName=rs.getString("last_name");

}

} } catch (Exception e) {

System.out.println(e);

throw new ServletException(e); } finally {

try {

rs.close(); ps.close(); connection.close();

} catch (Exception e) {

System.out.println(e);

} }

if (validLogon) {

HttpSession session = request.getSession();

session.setAttribute("userId", userId);

session.setAttribute("firstName", firstName);

session.setAttribute("lastName", lastName);

response.sendRedirect(validLogonPage); } else {

response.sendRedirect(invalidLogonPage); }

} }

2 Save the file as Logon.java in jrun_root/servers/tutorial/compass-ear/compass-war/

WEB-INF/classes/compass. In the next step, you enable dynamic servlet and class compiling and reloading.

Compass Travel J2EE application 81

3Copy the following code and save it as jrun_root/servers/tutorial/compass-ear/

compass-war/WEB-INF/jrun-web.xml:

<?xml version="1.0" encoding="ISO-8859-1"?> <jrun-web-app> <reload>true</reload> <compile>true</compile> </jrun-web-app>

4 Restart the tutorial server in one of the following ways:

• In the JMC, click the Restart icon next to the tutorial server.

• In the JRun Launcher, select the tutorial server, and click the Restart button.

5 Open a web browser to the following URL:

http://localhost:8101/compass/logon.jsp

6 Enter a registered user ID and password in the Logon fields.

Note: There are two users defined in the compass database: john (password: john) and mary (password: mary).

7 Click the Logon button.

If the login is valid, a blank Adventure Trips home page appears:

Summary

What’s next?

In this lesson, you set up the development environment for writing a J2EE application using JRun. You used the JMC to add a JRun server for the tutorial, deployed the tutorial template application, and defined a JDBC data source for it.

To get started in the tutorial application, you coded the logon servlet which accesses the compass database to validate your user ID and password. After successfully logging in, you see the Compass Adventure Trips home page.

In the next lesson, you add JSP code to the Compass Adventure Trips home page. For details, see Lesson 2, “JSP Tutorial” on page 83.

82 Lesson 1 Servlet Tutorial

LESSON 2

JSP Tutorial

In this lesson, you code JavaServer Pages (JSPs) that comprise the body of the Compass Travel tutorial application. You build a JSP with embedded Java code to access database information and develop a JSP that uses a JavaBean.

Contents

• Creating a home page JSP......................................................................................84

• Accessing a JavaBean.............................................................................................. 86

• Summary............................................................................................................... 88

Creating a home page JSP

JSPs let you create dynamic pages containing a combination of HTML, Java, and scripting code. JSPs deliver high performance because the first time that a client requests a JSP, the page is translated into a Java Servlet and compiled. At runtime, you execute the compiled servlet.

Compass Travel tutorial application

In the Compass Travel tutorial application, you can browse adventure trip descriptions, booking information, and make trip reservations. You use HTML, servlets, JSPs, JavaBeans, and Enterprise JavaBeans (EJBs) to create the static and dynamic portions of the application.

To get started with the tutorial lessons, see Lesson 1, “Servlet Tutorial” on page 69. In this chapter, you add JSP code to the tutorial home page and use JSPs to access a JavaBean that retrieves information from a database.

In the home page of the tutorial application, home.jsp, you code the following JSP elements:

• JSP directives to define page-wide attributes and insert text into a JSP page.

• JSP scripting elements to query a database and define statements evaluated on the

server before sending the page output to the client.

Home.jsp displays a list of trips a customer can book. This lesson shows how to build a JSP with embedded Java code to access database information.

To add JSP code to the Compass Adventures home page:

1 In a text editor or a Java IDE, open the file home.jsp located in jrun_root/servers/

tutorial/compass-ear/compass-war.

2 Where indicated by comments in the file, add the following code:

• JSP page import directive

<%@ page import="java.sql.*,javax.sql.*,javax.naming.*"%>

• JSP include action which calls the header and welcome pages

<jsp:include page="header.jsp" flush="true"/> <jsp:include page="welcome.jsp" flush="true"/>

• JSP include directive to insert the footer file text

<%@ include file="footer.htm"%>

• JSP scriptlet code to query a database for information about adventure trips

<% java.text.NumberFormat nf = java.text.NumberFormat.getCurrencyInstance(); String sql="SELECT trip_id, name, teaser, price FROM trip"; Connection connection=null; Statement stmt=null; ResultSet trips=null;

try {

InitialContext ctx=new InitialContext();

DataSource ds=(DataSource) ctx.lookup("compass");

connection=ds.getConnection();

84 Lesson 2 JSP Tutorial

stmt=connection.createStatement();

trips=stmt.executeQuery(sql);

while (trips.next()){ %>

<!--output the trip information (notice that tripID is used for the link but

name is what displays)-->

<tr>

<%=trips.getString("name") %></a></td> <td class="contentBG"><%=trips.getString("teaser") %></td> <td class="contentBG"><%=nf.format(trips.getDouble("price")) %></td>

</tr> <%

}

} catch (Exception e) {

out.println(e);

} finally {

connection.close();

}

3 Save home.jsp and open a web browser to the following URL:

http://localhost:8101/compass/home.jsp

Note: Use 8101 or the web server port number that JRun assigned when you created the tutorial server (see page 74).

A table containing adventure trip information appears:

The next section shows you how to develop a JSP that uses a JavaBean.

Creating a home page JSP 85

Accessing a JavaBean

A JavaBean is a particular type of a Java class that conforms to a set of design standards specified in the JavaBean API. A JavaBean does not inherit from any particular base class or interface but must provide methods for accessing its properties. A JavaBean is different from an EJB.

Within Java technology, some of the ways that you can use JavaBeans include the following examples:

• A JSP or servlet instantiates a bean and invokes its methods directly.

• A JSP employs the useBean action to get and set JavaBean properties and optionally,

invokes its methods directly.

In the following tutorial procedure, a JSP accesses a JavaBean that encapsulates the business logic to retrieve data from a database. You code a JSP action to instantiate and reference a JavaBean that retrieves detailed trip information.

In this procedure, you use the following JSP actions:

Element name Purpose

jsp:useBean Defines an instance of a JavaBean

jsp:setProperty Sets the value of one or more JavaBean properties

jsp:getProperty Writes the value of the bean property as a string to the page output

In tripdetail.jsp, you instantiate the

TripBean JavaBean and use it to access detailed

information about a selected trip.

To instantiate a JavaBean:

1Open the file tripdetail.jsp located in jrun_root/servers/tutorial/compass-ear/

compass-war.

2 Where indicated in the file, add the following JSP code:

<jsp:useBean id="trip" scope="session" class="compass.TripBean"/> <jsp:setProperty name="trip" property="tripId"/>

3 Review the jsp:getProperty code, which outputs the trip name, description, price,

start date, and end date.

The

TripBean JavaBean provides the data access logic to retrieve information about a

trip from the database. This tutorial lesson shows an example of application partitioning and role separation in

J2EE application development. The web developer builds the user interface in the JSP and does not need to know Java. The Java developer writes the business logic and need not be concerned about how the page looks. This lesson also demonstrates how to use the

useBean, setProperty, and getProperty tags.

The next procedure shows how to write a JavaBean that is used in a JSP.

86 Lesson 2 JSP Tutorial

MACROMEDIA JRun 4 Getting Started Manual

Specifications and Main Features

Frequently Asked Questions

User Manual