Sun Microsystems, Inc.Java Software

Support Readiness DocumentforJava Servlet Development Kit(JSDK) 2.0,with 2.1 Addendum

Sun Microsystems, Inc.Java Software901 San Antonio RoadPalo Alto, CA 94303U.S.A.

Support Readiness DocumentforJava Servlet Development Kit(JSDK) 2.0

Revision: 2.0Release Date: August, 1998

Sun Microsystems, Inc.Java Software901 San Antonio RoadPalo Alto, CA 94303U.S.A.

Copyright 1998 by Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, California 94303All rights reserved.

This product or document is protected by copyright and distributed under licenses restricting itsuse, copying, distribution, and decompilation. No part of this product or document may bereproduced in any form by any means without prior written authorization of Sun and itslicensors, if any.

RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject torestrictions of FAR 52.227-14(g)(2)(6/87) and FAR 52.227-19(6/87), or DFAR 252.227-7015(b)(6/95) and DFAR 227.7202-3(a).

Sun, Solaris, Java, JDK, JavaServer, JDBC, and JavaBeans are trademarks, registeredtrademarks, or service marks of Sun Microsystems, Inc. in the United States and othercountries.

THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIESOF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

Production Note: This book was written in FrameMaker 5.0 for Solaris by Sarah Brehm, HollyHedeman and Lisa Walker, and updated by Lisa Walker.

Table of Contents

Preface iv

1.0 Java Servlet Development Kit (JSDK) Overview 11.1 Using Servlets 21.2 Servlet API Details 3

1.2.1 Package javax.servlet 31.2.2 Package javax.servlet.http 3

1.3 Changes to the Servlet API 31.3.1 New Interfaces 31.3.2 New Classes 41.3.3 New Methods 41.3.4 Name Changes Since Java Web Server 1.1 Beta 4

1.4 The Servlet Runner (servletrunner ) 51.5 Loading and Invoking Servlets 6

1.5.1 Loading Servlets 61.5.2 Invoking Servlets 6

1.6 Product Distribution 61.6.1 Downloading the JSDK 61.6.2 Licensing 7

1.7 Localization and Internationalization 7

2.0 JSDK Requirements and Dependencies 72.1 System Requirements and Dependencies 7

2.1.1 Disk Space Needed to Install the JSDK 72.1.2 Supported Hardware Platforms; Required Boards or Peripherals 72.1.3 Recommended Amount of Memory 7

2.2 Software Requirements and Dependencies 72.2.1 Operating Systems and Versions Supported 7

2.3 Product Compatibility 82.3.1 Interoperability With Existing Third-Party Software 82.3.2 Backward/Forward Compatibility With Other Releases 82.3.3 Versions 8

3.0 JSDK Installation 83.1 Pre-Installation Considerations 8

SUN MICROSYSTEMS, INC. i

Table of Contents

ful

3.1.1 JDK Must be Installed and Working 83.1.2 Estimated Time Needed to Install 8

3.2 Installation Details 83.2.1 Default Installation Path 83.2.2 Changes to System Files 83.2.3 Directories Created During Installation 9

3.3 Tutorial: Download and Install the JSDK 93.3.1 Solaris 93.3.2 Microsoft Windows 95 and Windows NT 10

3.4 Post-Install Considerations 10

4.0 JSDK Configuration 104.1 Environment Variables 10

4.1.1 PATH to JSDKbin Directory 104.1.2 CLASSPATH Environment Variable 104.1.3 JAVA_HOME Environment Variable (Solaris Only) 11

4.2 Setting the Port for Servlet Runner 114.3 Stopping the Servlet Runner 114.4 Post-Installation Considerations: Verifying Success

Installation 114.4.1 Tutorial: Test the JSDK Installation by Starting the Servlet Runner

(Solaris) 114.4.2 Tutorial: Test the JSDK Installation by Starting the Servlet Runner

(Win32) 12

5.0 JSDK Deinstallation 125.1 How to Deinstall the JSDK 12

5.1.1 Solaris 125.1.2 Windows 95 or Windows NT 4.0 12

5.2 Common Problems With Deinstallation 125.2.1 Windows NT Registry Entries Not Deleted 12

5.3 Estimated Time Needed to Deinstall 135.4 Files Left Over After Deinstallation 13

6.0 Working with Servlets and the JSDK 136.1 Writing a Servlet 13

6.1.1 Tutorial: Creating the Example Servlet 136.2 Testing a Servlet With the Servlet Runner (servletrunner ) 15

6.2.1 Tutorial: Starting the Servlet Runner and Testing Your Servlet 15

7.0 Troubleshooting 167.1 Common User Errors 167.2 Troubleshooting Tips & Tricks 16

7.2.1 Netstat 167.2.2 Ping 167.2.3 Telnet 167.2.4 Getting Servlets to Use Other Classes 167.2.5 Bug Information 17

SUN MICROSYSTEMS, INC. ii

Table of Contents

8.0 Product Support and Reference Information 178.1 Information on the Web 178.2 Documentation in the JSDK Download 178.3 Mailing List 17

Addendum A: JSDK 2.1 A-1

SUN MICROSYSTEMS, INC. iii

p-gi-de fortion,

pro- in

hen,

re

alic

ular

n in

hen

h as

e

ted

Preface

This document provides support readiness information for the Java Servlet Develoment Kit. The goal of Support Readiness Documents (SRDs) is to help support enneers prepare to support Java Software products. SRDs are not designed to provicomprehensive product training (see the product documentation or Sun Educationthis). Instead, they focus on issues immediately relevant to support, such as installaconfiguration, and common user problems.

Document Format Options: PDF and PostScript

TheJava Servlet Development Kit SRDcan be viewed in PostScript or PDF format. ThePDF version of the document allows navigation via a table of contents frame, and vides the benefit of live cross references and web links. Text that is underlined andblue, such as the URL in this paragraph, are clickable links in the PDF version of tdocument. Although the blue color and underlining appear in the PostScript versiothere are no live links when viewing that version.

Typographic Conventions

This document uses the following type conventions:

• The names of commands, files, Java™ objects, Java classes, and directories ashown inregular monospace font .

• Text that is a placeholder to be replaced with a real name or value appears in ittype; for example:% unzip jsdt-1.4.zip -d destination directory.

• The names of menu items, buttons, windows, and keyboard keys appear in regfont with initial capitals, such as the Enter key.

• URLs that are clickable web links in the PDF version of the document are showblue, underlined monospace font, as inhttp://java.sun.com . Although the bluecolor and underlining appears in the PostScript version, there are no live links wviewing that version.

• URLs that are not clickable web links are shown in regular monospace font, sucjsdt://stard:5555/socket/Session/chatSession.

• Cross-references to other sections of the Java Servlet Development Kit SRD arshown in regular font but are blue and underlined, as in,See Section1.0, “ Over-view.” In the PDF version of the document, these are clickable links to the indica

SUN MICROSYSTEMS, INC. iv

ion,

section. Although the blue color and underlining appears in the PostScript versthere are no live links when viewing that version.

• New terms and book titles appear initalic type.

SUN MICROSYSTEMS, INC. v

Java Servlet Development Kit (JSDK) Overview

n-rs and

nd

rit-

rt toby the

et run-

ciated

nto ar ownr or

n beto the

ifferGUI)

Java Servlet Development Kit (JSDK)

1.0 Java Servlet Development Kit (JSDK) Overview

The Java™ Servlet Development Kit (JSDK) 2.0, in conjunction with the JDK™, cotains all the pieces necessary for implementing servlets on Java-based web serveany web servers or servlet engines that implement the Java Servlet API. The JSDKincludes an implementation of the Java Servlet API, a servlet engine for running atesting servlets, thejavax.servlet andsun.servlet package sources, API docu-mentation forjavax.servlets , and example code to help developers get started wing servlets.

For a more thorough overview of servlets, please read theJava Servlet API White Paper(http://java.sun.com/features/1997/aug/jws1.html ).

The Java Servlet Development Kit is designed to allow the addition of servlet suppoany Java-based web server. Please note that most of the servers that are supportedJSDK are also supported by commercial products which also implement the ServlAPI. Wherever possible, it is recommended that you use a commercial product forning servlets in a production environment.

Servlets provide a Java-based solution that addresses the problems currently assowith doing server-side programming, including inextensible scripting solutions andplatform-specific APIs. Servlets are Java server-side modules which fit seamlessly iJava-based server’s framework. The JSDK 2.0 is used by developers to create theiservlets. Developers using the JSDK don’t have to worry about the particular serveplatform being used with their servlets.

Servlets are objects that conform to the Java Servlet API, therefore the servlets caplugged into any Java-based server. Servlets are to the server side what applets areclient side: object bytecodes that can be dynamically loaded off the network. They dfrom applets in that they are faceless objects—without a graphical user interface (component. They serve as platform-independent, dynamically loadable, pluggablehelper bytecode objects on the server side that can be used to dynamically extendserver-side functionality.

SUN MICROSYSTEMS, INC. 1 of 18

Java Servlet Development Kit (JSDK) Overview

a-ually.

ripts. notGIerverr type.

eic

. Java

es

topltipleoes

e in

TMLpartta-

hro-enc-

achould

loadarti-g to

Note that the JavaServlet Development Kit is different from the JavaServer™ Toolkit.The JavaServer Toolkit is a source code product for writing servers that is sold seprately from the Java Web Server and the Servlet Toolkit. The Java Web Server is actwritten using the JavaServer Toolkit, and extended with servlets by using the JSDK

The JSDK 2.0 is a separate download from the Java Web Server.

1.1 Using Servlets

• Java Servlets are a good replacement for CGI (Common Gateway Interface) scJava Servlets can be much less resource-intensive than CGI programs, and dohave any of the maintainability problems inherent in scripting languages. Also, Cscripts are platform specific, whereas Java Servlets are platform-independent sextensions, both in the sense of hardware and operating system, and web serve

• Java Servlets are ideally suited to be the implementation of the middle tier in ththree-tier model for enterprise solutions. Servlets can serve as the business log

which connects to SQL (Structured Query Language) databases via the JDBC™database access API, while Java applets can handle the user interface.

• A servlet bean is a servlet that adheres to the JavaBeans™ design pattern for gettingand setting properties. A servlet bean has all the benefits of a regular Java beanbeans can also be integrated into existing servlets or .jhtml files. These would bebeans with no user interface.

• Java Servlets can be used for dynamic HTML generation via Server Side Includ(SSIs). The HTML will be created and placed in the.html file only when the webpage is accessed.

• Session tracking is a mechanism for building a sophisticated, stateful model onof the Web's stateless protocol. It can maintain state and user identity across mupage requests. It can also construct a complex overview of user behavior that gbeyond reporting of user hits.

Session tracking interfaces and interfaces specific to HTTP session tracking arthe javax.servlet.http package.

• A simple servlet can process data which was POSTed over HTTPS using an Hform, passing data such as a purchase order with credit card data. This would beof an order entry and processing system, working with product and inventory dabases and perhaps an online payment system.

• Since servlets handle multiple requests concurrently, the requests can be syncnized with each other to support collaborative applications such as online confering.

• A community of active agents could be defined which would share work among eother. The code for each agent would be loaded as a servlet, and the agents wpass data to each other.

• One servlet could forward requests to other servers. This technique can balanceamong several servers which mirror the same content. Or it could be used to ption a single logical service between several servers, routing requests accordintask type or organizational boundaries.

SUN MICROSYSTEMS, INC. 2 of 18

Java Servlet Development Kit (JSDK) Overview

to

-

rvletuage.

ble

hot-

1.2 Servlet API Details

JSDK 2.0, in conjunction with the JDK 1.1 or higher, contains all that is necessary write, test, and run servlets. The kit includesservletrunner for testing servlets, thejsdk.jar file containing thejavax.servlet andsun.servlet packages for theAPI and thejavax.servlet source and API documentation. There is no API documentation for thesun.servlet package.

Below is a short description of thejavax packages included in the JSDK. This API,which is supported by most web servers that support Java and many third party seengines, allows developers to create servlets written in the Java programming langJavaDoc-style documentation for thejavax packages included in the JSDK can befound atfile:/ path_to_jsdk/JSDK/doc/apidoc/packages.html , wherepath_to_jsdk is the directory in which you installed the JSDK.

1.2.1 Package javax.servlet

• Contains theServlet interface; within theServlet interface are the methodinitwhich creates the servlet, and the methodservice(ServletRequest, Servle-tResponse) which carries out a single request from a client. The simplest possiservlet implements this method.

• ContainsServletRequest andSerlvetResponse interfaces which are for get-ting data from a client to a servlet, and to a client from a servlet, respectively

• ContainsServletInputStream abstract class which is used byServletRe-quest to get data from a client

• ContainsServletOutputStream abstract class which is accessed viaServlet-Response to return data to the client

• ContainsGenericServlet class which implements theServlet interface; serv-lets are easy to write by just subclassingGenericServlet

1.2.2 Package javax.servlet.http

• ContainsHttpServlet abstract class which simplifies writing HTTP servlets;HttpServlet is a subclass ofGenericServlet , and containsdoGet anddoPost methods which perform the HTTPGET andPOST operations

• ContainsHttpServletRequest andHttpServletResponse which allow theservlet to manipulate HTTP protocol-specified header information

1.3 Changes to the Servlet API

The following are the latest additions to the Java Servlet API. These additions areupwardly compatible for servlet developers. They will, however, affect developers wwrite servers that load and use their own servlets, and developers who write servleembedding engines.

1.3.1 New Interfaces

• javax.servlet.http.HttpSessionBindingListener

• javax.servlet.http.HttpSessionContext

SUN MICROSYSTEMS, INC. 3 of 18

Java Servlet Development Kit (JSDK) Overview

• javax.servlet.SingleThreadModel

1.3.2 New Classes

• javax.servlet.http.HttpSessionBindingEvent

1.3.3 New Methods

• HttpServletRequest class

public abstract javax.servlet.http.Cookie getCookies() [];

public abstract javax.servlet.http.HttpSession getSession();

public abstract String getRequestedSessionId();

public abstract boolean isRequested SessionIdValid();

public abstract boolean isRequestedSessionIdFromUrl();

public abstract boolean isRequestedSessionIdFromCookie();

• HttpServletResponse class

public abstract void addCookie(javax.servlet.http.Cookie);

public abstract String encodeUrl(String url);

public abstract String encodeRedirectUrl(String url);

• HttpServlet class

protected void doDelete(HttpServletRequest req, HttpServletRe-sponse resp)

protected void doOptions(HttpServletRequest req, HttpServletRe-sponse resp)

protected void doPut(HttpServletRequest req, HttpServletResponseresp)

protected void doTrace(HttpServletRequest req, HttpServletResponseresp)

1.3.4 Name Changes Since Java Web Server 1.1 Beta

• HttpServletRequest class

getHttpSession → getSession

isRequestedSessionIdFromURL → isRequestedSessionIdFromUrl

• HttpServletResponse class

encodeURL → encodeUrl

encodeRedirectURL → encodeRedirectUrl

• HttpSession class

getSessionID → getId

SUN MICROSYSTEMS, INC. 4 of 18

Java Servlet Development Kit (JSDK) Overview

nlent:

st.e

tion

getSessionValue → getValue

getSessionValueNames → getValueNames

invalidateSession → invalidate

isNewSession → isNew

putSessionValue → putValue

removeSessionValue → removeValue

• HttpSessionBindingListener class

sessionValueBound → valueBound

sessionValueUnbound → valueUnbound

• HttpSessionContext class

getSessionIds → getIds

1.4 The Servlet Runner ( servletrunner )

The Servlet Runner (servletrunner ) can be used to test servlets if you don’t have aactual server or just want the lower overhead of using the Servlet Runner. It is equivato usingappletviewer to test applets. The command to start the Servlet Runner is

servletrunner -d servlet-dir

The argumentservlet-dir specifies the directory containing the servlets you want to teThe default directory is the current directory, so if the servlet you are testing is in thcurrent directory then no arguments need to be specified. In addition, the followingoptions are recognized by the Servlet Runner, along with the default values if the opis not used:

• -p port – port number to listen on (8080)

• -b backlog – backlog parameter for accepting new connections (50)

• -m max – maximum number of connection handlers (100)

• -t timeout – connection timeout in milliseconds (5000)

• -d dir – servlet directory (current directory)

• -r root – document root directory (current directory)

• -s filename – servlet properties file (servletdir/servlets.properties , whereservletdir is the directory specified with the-d option)

• -v generate verbose output (off)

SeeSection4.4, “Post-Installation Considerations: Verifying Successful Installation,”for details on how to configure and start the Servlet Runner.

The Servlet Runner (servletrunner ) does not work with JDK 1.2 beta 3.

SUN MICROSYSTEMS, INC. 5 of 18

Java Servlet Development Kit (JSDK) Overview

the

d

the

the

ass

erv-e

ool).

s).

in-

1.5 Loading and Invoking Servlets

1.5.1 Loading ServletsLoading servlets is a function of the server or tool that invokes the servlet, thereforeexact way a servlet is loaded is server- or tool-dependent.

In the case ofservletrunner , servlets are loaded from the servlet directory specifieby the-d option. Servlets are run byservletrunner by calling them in your browser.When servlets are updated,servletrunner does not automatically reload them.

In the case of the Java Web Server, a servlet invoker is a servlet that invokes theser-vice method on a named servlet. The invoker servlet is used to load servlets fromserver_root/servlets/ directory. All other servlets are loaded through an internalmapping. If the servlet is not already loaded in the server, then the invoker first loadsservlet (either from local disk or from the network) and then invokes theservicemethod. As with applets, local servlets in the server can be identified by just the clname. In other words, if a servlet name is not absolute, it is treated as local.

Servlets can be loaded into the Java Web Server from three places:

• From a directory that is on theCLASSPATH. TheCLASSPATHof the Java Web Serverincludesserver_root/classes/ which is where the system classes reside.

• From theserver_root/servlets/ directory. This isnot in the server’sCLASS-PATH. A custom classloader is used to create servlets from this directory. New slets can be added, existing servlets can be recompiled, and the server will noticthese changes.

• From a remote location. For this a codebase likehttp://nine.eng/classes/foo/ is required in addition to the servlet’s classname. (This example must first be configured with the Java Web Server AdminT

1.5.2 Invoking ServletsServlets can be invoked by a client in the following ways:

• The client (browser) can ask for a document that is served by the servlet.

• The servlet can be invoked through servlet tags with Server Side Includes (SSI

• The servlet can be invoked by calling the servlet withserver_host_name: port/servlet/ Servlet_Name, after placing it in the servletsdirectory.

• The servlet can be invoked by using it in a filter chain.

1.6 Product Distribution

JSDK 2.0 is available from Sun for Solaris™, and for Microsoft Windows 95 and Wdows 95 (also referred to collectively as Win32).

1.6.1 Downloading the JSDKThe JSDK is not available on CD-ROM, but is available for downloading fromhttp://java.sun.com/products/java-server/servlets/index.html .

SUN MICROSYSTEMS, INC. 6 of 18

JSDK Requirements and Dependencies

lat-

vlets.nfor-

l-

KB.

B.

uent

2.0

and

For the Solaris platform, the download file is a tar file. For the Microsoft Windows pform, the download file is a self-extracting file.

1.6.2 LicensingJSDK 2.0 can be downloaded at no charge for development of Java compatible serIn addition, the Servlet APIs may be embedded into any server at no charge. For imation about other kinds of licensing, see Sun’s Licensing page athttp://java.sun.com/nav/business/index.html .

1.7 Localization and Internationalization

JSDK 2.0 supports internationalization. Servlets written with JSDK 2.0 can be locaized.

2.0 JSDK Requirements and Dependencies

2.1 System Requirements and Dependencies

2.1.1 Disk Space Needed to Install the JSDK

Solaris

The Solaris download is about 300 KB. When installed, the JSDK directory is 645

Microsoft Windows

The Win32 download is about 950 KB. When installed, the JSDK directory is 640 K

2.1.2 Supported Hardware Platforms; Required Boards or PeripheralsJSDK 2.0 is supported on any hardware platform running the JDK 1.1 and subseqJDK versions. No additional boards or peripherals are needed.

2.1.3 Recommended Amount of MemoryThe JSDK requires minimal memory. Other applications that you may use with theJSDK should mandate the amount of memory, not the JSDK itself.

2.2 Software Requirements and Dependencies

2.2.1 Operating Systems and Versions SupportedAny platform that supports JDK 1.1 and subsequent releases is supported by JSDK.The JSDK 2.0 can be downloaded fromhttp://java.sun.com/products/java-server/servlets/ in formats recognizable by the following platforms:

• Solaris 2.5.1 with ISS patches or higher (Solaris X86 is not officially supported does not run SSL)

• Microsoft Windows NT 4.0

• Microsoft Windows 95 (supported for development, but not for deployment)

SUN MICROSYSTEMS, INC. 7 of 18

JSDK Installation

ers,vers.run on

rs

andn of

rking

Note: You should have at least JDK 1.1 when developing servlets. For up-to-date infor-mation on whether your target platform supports JDK 1.1, please contact the platform'svendor.

2.3 Product Compatibility

2.3.1 Interoperability With Existing Third-Party SoftwareThe Java Servlet API is being adopted or has already been adopted by many servincluding Sun’s Java Web Server, Netscape servers, Microsoft IIS, and Apache SerBecause the Java Servlet API is being adopted by these servers, Java Servlets cana variety of servers. Sun does not provide support for these third-party servers.

Seehttp://java.sun.com/products/java-server/servlets/environments.html for a list of servers supporting the Java Servlet API, and servesupporting the Java Servlet API by using the JSDK.

2.3.2 Backward/Forward Compatibility With Other ReleasesThere have been a number of changes made to the Servlet API since releases 1.01.0.1, some compatible with 1.0 and 1.0.1 and some not. For a detailed descriptiothese changes, please seeSection1.3, “Changes to the Servlet API.”

2.3.3 Versions

• JSDK 1.0, 1.0.1 – previously available, but no longer distributed

• JSDK 2.0 – available now

3.0 JSDK Installation

3.1 Pre-Installation Considerations

3.1.1 JDK Must be Installed and WorkingBe sure the JDK 1.1 or a subsequent release is installed on your machine and in wocondition.

3.1.2 Estimated Time Needed to InstallIt takes less than 5 minutes to install the JSDK.

3.2 Installation Details

3.2.1 Default Installation Path

• Solaris – There is no default installation path

• Microsoft Windows – The default installation path isC:\

3.2.2 Changes to System Files

• Solaris – There are no changes made to system files during installation

SUN MICROSYSTEMS, INC. 8 of 18

JSDK Installation

ese

Ifile.d

• Microsoft Windows NT – Changes are made to the registry during installation; thchanges are related to InstallShield

3.2.3 Directories Created During Installation

Solaris

These directories are created in a directory calledJSDK2.0 on Solaris

• bin – contains Servlet Runner executable (servletrunner )

• lib – contains JSDK JAR file

• doc – contains servlet tutorial andapidoc directory for API documentation

• examples – contains sample servlets and source code

• src – javax.servlet class sources

Microsoft Windows

These directories are created in a directory calledJsdk2.0 on Windows

• bin – contains Servlet Runner executable (servletrunner.exe )

• lib – contains JSDK JAR file

• doc – contains servlet tutorial andapidoc directory for API documentation

• examples – contains sample servlets and source code

• src – javax.servlet class sources

3.3 Tutorial: Download and Install the JSDK

3.3.1 Solaris

1. Download the JSDK compressed tar file from the JSDK web site:http://java.sun.com/products/java-server/servlets/ . The file iscalled jsdk20-solaris2-sparc.tar.Z.

2. Move the compressed tar file to the directory where you want to install theJSDK software. The JSDK directory will be created within this directory.

3. Uncompress the tar file. Enter:

% uncompress jsdk20-solaris-sparc.tar.Z

The tar file is now ready to be installed.

4. Install the contents of the tar file. Enter:

% tar -xvf jsdk20-solaris-sparc.tar

This creates a directory called JSDK2.0 , which contains the product release.

5. After you have finished installing the JSDK you can delete the tar file if you wish.you don’t have to delete it for space reasons, it makes sense to keep it for a whThen if you have to reinstall for some reason, you don’t have to do the downloaagain.

SUN MICROSYSTEMS, INC. 9 of 18

JSDK Configuration

e

ifp ithe

viron-

s-

r

3.3.2 Microsoft Windows 95 and Windows NT

1. Download the JSDK self-extracting file from the JSDK web site:http://java.sun.com/products/java-server/servlets/ . The file iscalledjsdk20-win32.exe .

2. Double-click on the icon for the self-extracting file and follow the instructions in thSetup program to install the JSDK in a directory location on your hard disk. Bydefault, Setup installs the JSDK inC:\Jsdk .

3. After you have finished installing the JSDK you can delete the downloaded file you wish. If you don’t have to delete it for space reasons, it makes sense to keefor a while. Then if you have to reinstall for some reason, you don’t have to do tdownload again

3.4 Post-Install Considerations

Check that the directoryJSDK2.0 contains the directories listed inSection3.2.3,“Directories Created During Installation.”

4.0 JSDK Configuration

4.1 Environment Variables

Environment variables can give developers problems, so this section covers the enment variables that the JSDK uses.

4.1.1 PATH to JSDK bin Directory

You can temporarily add the JSDKbin directory to your search path for the current sesion by typing the following in a C shell on Solaris platforms:

% setenv PATH / path_to_JSKD_directory/JSDK2.0/bin:${PATH} (on Solaris)

or typing the following at a command prompt on Windows platforms

C> set PATH=C:\Jsdk\bin;%PATH% (on Win32)

You can permanently add the JSDKbin directory to your search path by following theinstructions below for your platform:

• Solaris – In your.cshrc file (or other shell configuration file) set thePATHvariableto include the JSDKbin directory.

• Windows NT – Add the path to JSDKbin to your path environment variable undeControl Panel→ System→ Environment.

• Windows 95 – Open theautoexec.bat file and add the path to JDSKbin to yourPATH environment variable.

4.1.2 CLASSPATHEnvironment VariableThe JSDK comes with two class packages which must be added to yourCLASSPATH

before you can develop servlets. The easiest way to do this is to include

SUN MICROSYSTEMS, INC. 10 of 18

JSDK Configuration

prob-

ouServ-the

sec-.

e of

/path_to_jsdk/JSDK2.0/lib/jsdk.jar in yourCLASSPATH. You need JDK 1.1 orsubsequent releases in yourCLASSPATH as well.

4.1.3 JAVA_HOME Environment Variable (Solaris Only)When trying to startservletrunner , you may get the following message:

Error: Cannot find Java runtime in search path. Please setJAVA_HOME.

because the your path does not include the JDK. There are two ways to correct thelem:

• Add the JDK path to the path statement in your.cshrc file or other shell config-uration file; for example, the addition of/usr/local/java/jdk1.1.6/solaris/bin in the statement below:

set path=($path /usr/local/bin:/usr/dist/exe:/usr/local/casta-net/tuner/bin:/usr/local/java/jdk1.1.6/solaris/bin)

• Add a statement to your.cshrc file or other shell configuration file to set theJAVA_HOME environment variable; for example,

setenv JAVA_HOME /usr/local/java/jdk1.16/solaris

Note: The addition to the path statement takes you to thebin level of the JDK whereastheJAVA_HOME variable includes one level abovebin .

4.2 Setting the Port for Servlet Runner

The default port for the Servlet Runner is 8080. Use the-p option if you want to specifya different port. Note that the default port for the Java Web Server is also 8080. If yhave the Java Web Server running using that port, you will not be able to start the let Runner with the default port as well. Either change the Web Server port or use switch to change the Servlet Runner port.

4.3 Stopping the Servlet Runner

Stop the Servlet Runner by typing Control-C in the command window where youstarted it. On Solaris, you can also kill the process java sun.servlet.http .

4.4 Post-Installation Considerations: Verifying Successful Installation

To test your setup and ensure that it works correctly, start the Servlet Runner. Thistion steps through how to start the Servlet Runner on Solaris and Win32 platforms

4.4.1 Tutorial: Test the JSDK Installation by Starting the Servlet Runner (Solaris)This tutorial just tests your installation to make sure that Servlet Runner works. Usservletrunner is explained in more detail inSection6.0, “Working with Servletsand the JSDK.”

1. Add the JSDKbin directory to your search path. SeeSection4.1.1,“PATHto JSDKbin Directory” for details.

% setenv PATH / path_to_JSDK_directory/JSDK2.0/bin:${PATH}

2. Start the Servlet Runner.

SUN MICROSYSTEMS, INC. 11 of 18

JSDK Deinstallation

e of

ine.

outor’s

% servletrunner -v

The-v option (verbose) will give you startup information including what port theServlet Runner is using.

4.4.2 Tutorial: Test the JSDK Installation by Starting the Servlet Runner (Win32)This tutorial just tests your installation to make sure that Servlet Runner works. Usservletrunner is explained in more detail inSection6.0, “Working with Servletsand the JSDK.”

1. Add the JSDKbin directory to your search path.

C> set PATH=C:\Jsdk\bin;%PATH%

2. Start the Servlet Runner

C> servletrunner -v

The -v option (verbose) will give you startup information including what port theServlet Runner is using.

Note: It is not a good idea to start the Servlet Runner by double-clicking on theserv-letrunner icon because then you cannot specify a directory to run servlets from. Forthis tutorial it is not an issue, since we just want to see if it runs. When you are ready totest servlets, however, you will want to either startservletrunner from the directorycontaining your servlet or specify that directory using the-d option when you startservletrunner from the command line.

5.0 JSDK Deinstallation

5.1 How to Deinstall the JSDK

5.1.1 SolarisThe JSDK does not have a deinstall script to remove the JSDK files from your mach

To remove the JSDK files manually and deinstall the JSDK, type:

% rm -r JSDK2.0

5.1.2 Windows 95 or Windows NT 4.0

1. Open the Control Panel.

2. Click on Add/Remove Programs.

3. Highlight the JSDK entry in the window and click on Add/Remove.

5.2 Common Problems With Deinstallation

5.2.1 Windows NT Registry Entries Not DeletedWindows NT stores its configuration information in a database called the Registry.Sometimes registry entries will be left over after installation, and could interfere if yreinstall. The Registry is not intended for user-level access, it is a system administratool. See the Windows NT online help for more information.

SUN MICROSYSTEMS, INC. 12 of 18

Working with Servlets and the JSDK

llyhe

ave,

to add

thetory

-

To check for registry entries after deinstallation:

1. Start the registry editor by typingregedt32 at a command prompt.

2. Go to the HKEY_LOCAL_MACHINE panel.

3. Check the following for JSDK entries, and delete the JSDK key only:

SYSTEM/ControlSet001/Services/

SYSTEM/ControlSet002/Services/

SYSTEM/CurrentControlSet/Services/

4. During installation a key is also created in SOFTWARE/JavaSoft/ but this is usuadeleted without any problem when you use Add/Remove programs to remove tsoftware.

5.3 Estimated Time Needed to Deinstall

It should take less than 5 minutes to deinstall the JSDK.

5.4 Files Left Over After Deinstallation

• Solaris – No files left after deinstallation

• Windows – When you use Add/Remove Programs to deinstall in Windows, you hto manually remove any files and directories that were created after installationsince Add/Remove Programs will not remove them

6.0 Working with Servlets and the JSDK

As we discussed earlier, servlets can be written using the JSDK and can be used functionality to your server.

6.1 Writing a Servlet

In order to write a servlet you need to use the Servlet API. The documentation for Servlet API is part of the JSDK download and can be accessed from your local direcat URL file:/ path_to_jsdk/JSDK2.0/doc/apidoc/packages.html or athttp://jserv.java.sun.com/products/java-server/documentation/webserver1.1/apidoc/packages.html .

6.1.1 Tutorial: Creating the Example ServletUsing theSimpleServlet.java file located in /path_to_jsdk/JSDK2.0/exam-ples/ continue through the following steps.

1. Open theSimpleServlet.java file in any text editor. You should see the following Java code (this is only the code portion of the.java file so your example willlook slightly different):

import java.io.*;

import javax.servlet.*;

import javax.servlet.http.*;

SUN MICROSYSTEMS, INC. 13 of 18

Working with Servlets and the JSDK

r

e of

public class SimpleServlet extends HttpServlet {

public void doGet (

HttpServletRequest request,

HttpServletResponse response

) throws ServletException, IOException

{

PrintWriter out;

String title = "Simple Servlet Output";

// set content type and other response header fields first

response.setContentType("text/html");

// then write the data of the response

out = response.getWriter();

out.println("<HTML><HEAD><TITLE>");

out.println(title);

out.println("</TITLE></HEAD><BODY>");

out.println("<H1>" + title + "</H1>");

out.println("<P>This is output from SimpleServlet.");

out.println("</BODY></HTML>");

out.close();

}

}

Note: In this example, theservice method provided by superclassHTTPServlet iscalled every time the servlet is accessed. It writes “This is output from SimpleServlet”to the response, which causes the phrase “This is output from SimpleServlet” to appearon the display of the browser accessing the servlet.

2. Change the name of the classSimpleServlet to your own name or something thatis unique to you (for example,class HollyServlet extends HttpServlet ).

3. Change the text in the lineout.println("<P>This is output from Sim-pleServlet") to something recognizable by you. This will be the output of youservlet throughout the rest of the tutorials.

4. Save the file with same name that you changed your class name to in the first lincode (e.g. with the example change made in Step 2, the file should be saved asHol-lyServlet.java ). You can save the file to any directory you choose.

5. Compile this new file using thejavac command. This should result in a.classfile, a complete servlet which you will use in the following tutorials.

SUN MICROSYSTEMS, INC. 14 of 18

Working with Servlets and the JSDK

the

er-

is

Note: When compiling, don't forget to include thejavax.servlet.* package inyour CLASSPATH. The easiest way to do this is to includepath_to_jsdk/JSDK2.0/lib/jsdk.jar in yourCLASSPATH. You need the JDK 1.1or higher in yourCLASSPATH as well.

6.2 Testing a Servlet With the Servlet Runner ( servletrunner )

The standard way to invoke a servlet in any server is with a URL like the following:

/servlet/ servlet-name/ path-info?query-args

The name of the servlet isservlet-name and is the class name of the servlet,path-info isoptional path information for the servlet, andquery-args is optional query string argu-ments for the servlet.

For example, if you had started the Servlet Runner on hosteno within the directorysamples containing sample servlets, then from any browser you could runSnoopS-ervlet with the following URL:

http://eno:8080/servlet/SnoopServlet/foo/bar?a=z

This will invokeSnoopServlet with path info/foo/bar and query stringa=z .SnoopServlet will echo the request headers and query string arguments back to client.

Note: Remember that the default port for the Servlet Runner is 8080.

6.2.1 Tutorial: Starting the Servlet Runner and Testing Your Servlet

1. First, add the JSDKbin directory to your search path if you have not done soalready. (The command for Solaris shells other than C shell may be slightly diffent.)

% setenv PATH / path_to/JSDK2.0/bin:${PATH} (on Solaris)

or

C> set PATH=C:\Jsdk2.0\bin;%PATH% (on Win32)

2. Start the Servlet Runner (servletrunner ).

% servletrunner -d path_to_servlet -v (on Solaris)

or

C> servletrunner -d path_to_servlet -v (on Win32)

Wherepath_to_servlet is the path to the directory where your.class file resides.Another option is tocd into the directory where your.class file resides and thenstart the Servlet Runner. Remember that the default port for the Servlet Runnerport 8080, so if your Java Web Server is still running on this port, you will get anerror when you try the step below.

Note: Aside from the verbose startup information, you will not see any confirmationthat the Servlet Runner has started. The cursor will just blink in the terminal window.

3. Invoke your servlet using a browser.

SUN MICROSYSTEMS, INC. 15 of 18

Troubleshooting

of

fterer

ara-xam-

ent

nt to

t

roto-

e

ither

Type the path to invoke your servlet in the text field for URLs (see the beginningSection6.2, “Testing a Servlet With the Servlet Runner (servletrunner )” fordetails).

You should see the text that you changed in your servlet before you compiled.

7.0 Troubleshooting

7.1 Common User Errors

• Because there is no clear communication that the Servlet Runner has started ausing theservletrunner command, people do not realize that the Servlet Runnhas started. Suggest using the-v option when they startservletrunner .

• People sometimes misunderstand that servlets work on the request/response pdigm. They expect a socket to open between their servlet and a database, for eple.

• People sometimes misunderstand that the Servlet Runner will not serve documfiles, just servlets—it is not a server. Why is there a-r option to specify a documentdirectory? Some methods in the JSDK require a document root, so you may waset it so a particular servlet can run.

• The Servlet Runner requires that the JDK be installed.

7.2 Troubleshooting Tips & Tricks

7.2.1 Netstat

To see if a port is bound, typenetstat -a in a terminal window. This will give you alist of all sockets currently active. The-a option means it will include those that are juslistening.

7.2.2 Ping

Typeping localhost in a terminal window. If that doesn’t work, there are networkproblems that need to be solved before you try to run the server.

7.2.3 Telnet

To rule out your browser as the cause of problems, manually simulate the HTTP pcol:

1. Type telnet localhost port.

2. Type get / HTTP/1.0 and press Enter twice.

3. This will give you the raw HTML of the top web page. If this works, you know thproblem points toward the browser, not the server.

7.2.4 Getting Servlets to Use Other ClassesIf you are having problems getting your servlets to use other classes, you can do eof the following:

• put the other classes in the servlet directory (NOT on theCLASSPATH)

• put the servlet with the other classes in another directory (on theCLASSPATH)

SUN MICROSYSTEMS, INC. 16 of 18

Product Support and Reference Information

t

7.2.5 Bug InformationFor bug information on this product, do a search for JSDK athttp://developer.java.sun.com/developer/bugParade

8.0 Product Support and Reference Information

8.1 Information on the Web

The main site for the Java Server Product family can be found athttp://jserv.javasoft.com/products/java-server/index.html . Beloware URLs for specific information.

• Java Servlet Development Kit (JSDK) Page –http://jserv.java.sun.com/products/java-server/servlets

• Servlet Tutorial – http://jserv.javasoft.com/products/java-server/documentation/webserver1.1/servlets/servlet_tutorial.html

• Servlet API Documentation – http://jserv.javasoft.com/products/java-server/documentation/webserver1.1/apidoc/packages.html

• Servlet Environments – http://jserv.java.sun.com/products/java-server/servlets/environments.html

• Servlet FAQ – http://jserv.javasoft.com/products/java-server/documentation/webserver1.1/servlets/servlets_faq.html

• Servlet API White Paper –http://java.sun.com/features/1997/aug/jws1.html

• Java Web Server Page – http://jserv.java.sun.com/products/java-server/webserver/index.html

• JavaServer Documentation – http://jserv.java.sun.com/products/java-server/documentation/index.html

• Java Web Server and JSDK FAQs –http://jserv.java.sun.com/products/java-server/faq/index.html

8.2 Documentation in the JSDK Download

• Servlet Tutorial –file:/ path_to_JSDK/JSDK2.0/doc/servlet_tutorial.html

• JavaDoc Servlet API documentation –

file:/ path_to_JSDK/JSDK2.0/doc/apidoc/packages.html

8.3 Mailing List

Users can join the Java Web Server mailing list,jserv-interest , by sending email tolistserv@javasoft.com with the message body ofsubscribe jserv-inter-est user_email_address. The user can also join the mailing list from the web page a

SUN MICROSYSTEMS, INC. 17 of 18

Product Support and Reference Information

nd to

http://jserv.java.sun.com/products/java-server/lists.html . Themailing list can be used to monitor current issues that other users are discussing aask questions.

An archive of messages from thejserv-interest list is available athttp://hplbwww.hpl.hp.com/people/ak/archives/jeeves/ . This site isnot a Sun Microsystems site.

SUN MICROSYSTEMS, INC. 18 of 18

elop-.

Addendum A: JSDK 2.1

1.0 JSDK 2.1 Overview

Java Servlet Development Kit (JSDK) 2.1 contains a simple Servlet engine for deving and testing servlets, thejavax.servlet package sources, and API documentationJSDK 2.1 is a full reference implementation of the JSDK API 2.1 specification.

JSDK 2.1 is 100% pure Java and Y2K compliant.

1.1 Changes and New Features in Version 2.1

This section contains new features and major changes since JSDK 2.0.

1.1.1 New Classes

• javax.servlet.RequestDispatcher

1.1.2 New Methods

• javax.servlet.ServletContext

getAttributeNames()

getContext(java.lang.String uripath)

getMajorVersion()

getMinorVersion()

getRequestDispatcher(java.lang.String urlpath)

getResource(java.lang.String path)

getResourceAsStream(java.lang.String path)

removeAttribute(java.lang.String name)

setAttribute(java.lang.String name java.lang.Object object)

• java.servlet.ServletRequest

getAttributeNames()

setAttributeNames(java.lang.String key, java.lang.Object o)

• java.servlet.GenericServlet

SUN MICROSYSTEMS, INC. A-1 of 9

JSDK 2.1 Overview

s

od

log(java.lang.String message, java.lang.Throwable t)

• java.servlet.ServletException

ServletException(java.lang.String message, java.lang.ThrowablerootCause)

ServletException(java.lang.Throwable rootCause)

• java.servlet.http.HttpSession

setMaxInactiveInterval()

1.1.3 Changed Methods

• java.servlet.ServletContext

log(Exception exception String msg)

changed to

log(java.lang.String message, java.lang.Throwable throwable)

1.1.4 Deprecated Interfaces

• javax.servlet.http.HttpSessionContext – deprecated for security reason

1.1.5 Deprecated Methods

• javax.servlet.http.HttpServletRequest.isRequestedSessionIdFro-mUrl – use methodisRequestedSessionIdFromURL instead

• javax.servlet.ServletContext.getServlet – This method was originallydefined to retrieve a servlet from aServletContext . In this version, this methodalways returns null and remains only to preserve binary compatibility. This methwill be permanently removed in a future version of the Java Servlet API.

• javax.servlet.ServletContext.getServletNames – This method wasoriginally defined to return anEnumeration of all the servlet names known to thiscontext. In this version, this method always returns an emptyEnumeration andremains only to preserve binary compatibility. This method will be permanentlyremoved in a future version of the Java Servlet API.

• javax.servlet.ServletContext.getServlets – This method was origi-nally defined to return anEnumeration of all the servlets known to this servletcontext. In this version, this method always returns an empty enumeration andremains only to preserve binary compatibility. This method will be permanentlyremoved in a future version of the Java Servlet API.

• log(java.lang.Exception exception, java.lang.String msg) – Dep-recated. Uselog(String message, Throwable throwable) instead.

• javax.servlet.ServletRequest.getRealPath(java.lang.Stringmsg) – Usejava.servlet.ServletContext.getReal-Path(java.lang.String msg) instead.

• javax.servlet.http.HttpServletRequest.isRequestSessionIdFro-mUrl – Deprecated. Usejavax.servlet.http.HttpServletRequest.isRe-questSessionIdFromURL instead.

SUN MICROSYSTEMS, INC. A-2 of 9

Product Distribution

nd

per-

spec-

t isrvlet

l-

nrma-

• javax.servlet.http.HttpServletResponse.encodeUrl(String url) -Usejavax.servlet.http.JttpServletResponse.encodeUrl(Stringurl) instead.

• javax.servlet.http.HttpServletResponse.setStatus(int sc,java.lang.String sm) – Deprecated because of ambiguous meaning. To sean error with a description page, usejavax.servlet.http.HttpServletRe-sponse.sendError(int sc, String msg).

• javax.servlet.http.HttpSession.getSessionContext - Deprecatedwith no replacement method

1.1.6 Configuration File ChangesThe JSDK configuration files have changed significantly. To set general server proties, such as port and hostname, edit thedefault.cfg file in the installation directoryof the JSDK. To edit servlet mappings, mime types and other properties, edit the retive files ininstallation_directory/webpages/WEB-INF .

1.1.7 Servlets Directory LocationThe servlets directory is located atinstallation_directory/webpages/WEB-INF/servlets .

1.1.8 Automatic Servlet ReloadingAutomatic servlet reloading is not operational in this release of the JSDK. If a servlereplaced with an updated version while the server is running, clients running the sewill not get the updated version.

1.2 Localization and Internationalization

JSDK 2.1 supports internationalization. Servlets written with JSDK 2.1 can be locaized.

2.0 Product Distribution

JSDK 2.1 can be downloaded fromhttp://java.sun.com/products/servlet/index.html at no charge for development of Java compatible servlets. Iaddition, the Servlet APIs may be embedded into any server at no charge. For infotion about other kinds of licensing, see Sun’s Licensing page athttp://java.sun.com/nav/business/index.html .

3.0 Requirements and Dependencies

3.1 System Requirements and Dependencies

3.1.1 Disk Space Needed to Install JSDK 2.1Note this is the disk space needed toinstall, not to download. The size of the downloadis listed inSection4.1, “Name and Size of Download Files”.

• Microsoft Windows – 1.12 MB

SUN MICROSYSTEMS, INC. A-3 of 9

Downloading JSDK 2.1

d

and

lets.

sses.1 as

r-

• Unix – 1.21 MB

3.2 Software Requirements and Dependencies

3.2.1 OS and Versions SupportedJSDK 2.1 supports the following operating systems:

• Microsoft Windows 95, Windows 98 and Windows NT

• Solaris 2.6

JSDK 2.1 works on Linux and Macintosh, although these are not officially supporteplatforms.

JSDK 1.2 supports the following versions of the JDK:

• JDK 1.1.x – JDK 1.1.8 is recommended

• Java2 SDK 1.2.x

3.2.2 Other Software RequirementsJava2 SDK is not included in the JSDK download, therefore it must be downloadedinstalled separately.

3.3 Product Limitations

Automatic servlet reloading is not operational in this release of the JSDK.

3.4 Product Compatibility

3.4.1 Interoperability with Existing Sun and Third-Party SoftwareSeehttp://java.sun.com/products/servlet/runners.html for an up-to-date list of software that conforms to the servlet API specification and will run serv

3.4.2 Backward and Forward Compatibility With Other VersionsPrograms writetn using JSDK 2.1 can be run with version 2.0, as long as no new claor methods are used. Programs written using version 2.0 can be run with version 2long as no methods which have been removed are used. SeeSection1.1,“ChangesandNew Features in Version 2.1” for a list of new, removed and deprecated classes, intefaces, and methods..

4.0 Downloading JSDK 2.1

4.1 Name and Size of Download Files

Some general tips on downloading from Sun can be found onhttp://java.sun.com/feedback/faq/downloading.html

SUN MICROSYSTEMS, INC. A-4 of 9

Installing JSDK 2.1

m

4.2 Steps to Download

JSDK 2.1 can be downloaded fromhttp://java.sun.com/products/servlet/index.html .

4.2.1 Unix Download

1. In the “Download JSDK Software” section, select UNIX (Solaris and others) frothe “Choose a Platform” pull-down. Click continue.

2. Read the license agreement and click Accept.

3. Click “FTP download” or any of the 3 alternate sites.

4. From the “Save As” window, storejsdk2_1-solsparc.tar.Z in a directorywhere you would like thejsdk directory to reside.

4.2.2 Windows Download

1. In the “Download JSDK Software” section, select “Windows 95/NT” from the“Choose a Platform” pull-down. Click continue.

2. Read the license agreement and click Accept.

3. Click “FTP download” or any of the 3 alternate sites.

4. From the “Save As” window, storejsdk2_1-win.zip in any directory.

5.0 Installing JSDK 2.1

5.1 Pre-Installation Considerations

5.1.1 Java2 SDK RequirementsJava2 SDK must be installed and working. Thejava program included in the SDKmust be included in the user’s path.

5.1.2 Disk SpaceMake sure there is enough disk space; seeSection3.1.1, “Disk Space Needed to InstallJSDK 2.1”.

5.1.3 Estimated Time Needed to InstallInstallation takes less than five minutes to complete.

Platform File Name Size

Solaris jsdk2_1-solsparc.tar.Z 466387 bytes

MS Windows jsdk2_1-win.zip 375128 bytes

SUN MICROSYSTEMS, INC. A-5 of 9

Installing JSDK 2.1

les

-

5.2 Installation Details

5.2.1 Default Installation Path

• Solaris –current directory/jsdk2.1

• Microsoft Windows – c:\unzipped\jsdk2.1

5.2.2 Changes to System FilesThere are no changes to system files on any platform.

5.2.3 Directories Created at InstallationThe jsdk2.1 directory created at installation contains the following

• default.cfg – default configuration file for the server

• etc – directory containing Java code to start theHttpServer

• examples – directory containing example servlets, including source code, html fiand property files

• LICENSE or LICENSE.TXT – text file containing license agreement

• README or README.TXT –text file containing changes to the JSDK, troubleshooting, and instructions on running the servlets withservletrunner

• server.jar – archive file containing classes and files necessary for running aserver

• servlet.jar – archive file containing classes in theservlet package

• src – directory containing source code forjavax.servlet

• startserver , startserver.bat – startup script forservletrunner

• stopserver , stopserver.bat – shutdown script to stopservletrunner

• webpages – directory containingdocs , a directory containing JSDK documenta-tion in HTML format, andWEB-INF, a directory containing the servlet directory andservlet properties files

5.3 How to Install JSDK 2.1

5.3.1 Unix Installation

1. In a terminal window, type the following command to unzip the file.

Unix prompt% gunzip jsdk2_1-solsparc.tar.Z

This creates a tar file calledjsdk2_1-solsparc.tar .

2. In a terminal window, type the following command to unarchive the JSDK.

Unix prompt% tar -xvf jsdk2_1-solsparc.tar

This creates thejsdk2.1 directory.

3. The tar file can be deleted now.

5.3.2 Windows InstallationThe download file is in zip format, so use the program WinZip to unarchivejsdk2_1-win.zip

SUN MICROSYSTEMS, INC. A-6 of 9

JSDK 2.1 Uninstall

t

ter-

d

ghtck-

K).i-

1. Start WinZip and choose to use the Wizard.

2. Choosejsdk2_1-win.zip from the list of zip files and click Next.

3. Enter a directory name where you want the jsdk to reside, otherwise the defauldirectoryc:\unzipped\jsdk2_1-win will be used.

4. Select Unzip Now.

5. Select Close to exit WinZip.

6. The zip file can be deleted now.

6.0 JSDK 2.1 Uninstall

6.1 Pre-Uninstall Considerations

6.1.1 Estimated Time Needed to UninstallLess than 5 minutes is needed to uninstall JSDK 2.1.

6.2 How to Uninstall JSDK 2.1

6.2.1 UnixThere is no script to remove JSDK 2.1, therefore use the following command from aminal window to delete JSDK 2.1.

Unix prompt% rm -r path_to_JSDK/jsdk2.1

6.2.2 WindowsThere is no executable to remove JSDK 2.1, therefore select the jsdk2.1 folder anselect Delete under the file menu.

7.0 Key File Descriptions

List and explain the function of: most common files used by product that a user miutilize or modify, configuration files, most used binaries (daemons, bin files) and paages.

8.0 Using JSDK 2.1

In order to run the JSDK it is necessary to have installed a compliant Java2 SDK (JDYou must also have thejava program available in your path (set using the PATH envronment variable). More information can be found at

http://java.sun.com/products/jdk .

SUN MICROSYSTEMS, INC. A-7 of 9

Bug Information

and

docu-

8.0.1 Starting the Server

To run the server that comes with the JSDK, there is a Unix based Korn Shell Scripta Windows based Batch File provided in the installation directory of the JSDK. Tostartup the server on Unix:

Unix prompt% cd installation_directory

Unix prompt% startserver

To start up the server on Windows

Windows prompt> cd installation_directory

Windows prompt> startserver

Once the server is running, you can use any web browser to browse

http://localhost:8080

and you will be browsing pages served from the server. You can read the JavaDocmentation for thejavax.servlet packages as well as see some examples.

8.0.2 Stopping the Server

To stop the server, use the following commands:

Unix prompt% stopserver

Windows prompt > stopserver

9.0 Bug Information

To view bug information on this product, do a search for JSDK athttp://developer.java.sun.com/developer/bugParade

10.0 Tuning and Troubleshooting

10.1 Common User Questions

A third-party FAQ is available at the following web site.

http://www.purpletech.com/java/servlet-faq .

10.2 Known Bugs and Their Workarounds

10.2.1 IssuesKnown issues with JSDK 2.1 can be found athttp://java.sun.com/products/servlet/knownIssues.html

SUN MICROSYSTEMS, INC. A-8 of 9

Reference Information

ce”small

10.2.2 Out of Environment Space ErrorOn a Windows 95 or Windows 98 machine you may see an “Out of Environment Spaerror message when starting the server. This is caused by Windows providing too a space for environment variables. Do the following to work around this limitation:

1. Close the MS-DOS window (the error can corrupt its CLASSPATH variable) inwhich you attempted to start the server.

2. Open a new MS-DOS window.

3. Click on the MS-DOS icon at the top-left of the window.

4. Select the Properties option.

5. Click on the Memory tab.

6. Adjust the Initial Environment drop-down box from Auto to 2816.

7. Click OK.

8. Start the server by typingstartserver at the prompt.

11.0 Reference Information

11.1 Technical Documentation

• installation_directory /jsdk2.1/webpages/docs/api/overview-summary.html – JSDK API documentation included in the installation

• http://java.sun.com/products/servlet – Sun’s main JSDK page

• http://java.sun.com/products/servlet/external-resources.html– list of external sources for servlet technology

11.2 Additional References

To subscribe to the external JSDK mailing list, send a message tolist-serv@java.sun.com with the following message body:

subscribe servlet-interest your full email address

SUN MICROSYSTEMS, INC. A-9 of 9