Java JRun

JRun User s Manual
Version 2.3.3
JRun User Manual s

Version 2.3.3
Allaire Corporation. All rights reserved. This manual, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. The content of this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Allaire Corporation. Allaire Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this book. Except as permitted by such license, no part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Allaire Corporation. JRun and <CF_Anywhere> are trademarks of, and ColdFusion is a registered trademark of, Allaire Corporation. Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Corporation. UNIX is a trademark of Novell Inc. All other products or name brands are the trademarks of their respective holders.
http://www.allaire.com
Table of Contents
Introduction to JRun...................................................................................................... 1
Java: A brief history ........................................................................................................................ 1 Comparing Client-Side Java and Server-Side Java ........................................................................... 1 Server Component Model................................................................................................................ 2 What is JRun? ................................................................................................................................. 3 JRun Architecture ........................................................................................................................... 3 JRun Services.................................................................................................................................. 5
Introduction to Servlets .................................................................................................. 6

Servlets vs. CGI .............................................................................................................................. 6 Extending Web Servers with Servlets .............................................................................................. 7
Servlet Tutorial .............................................................................................................. 8

Part 1 .............................................................................................................................................. 8 Part 2 .............................................................................................................................................10 Part 3 .............................................................................................................................................11 Part 4 .............................................................................................................................................12
JRun Administration.................................................................................................... 15
Starting the JRun Admin Application .............................................................................................16 Selecting a JSM to Configure .........................................................................................................17 Selecting a Service to Configure.....................................................................................................18 Configuring General Settings for a Service .....................................................................................19 Configuring Service Settings for a Service......................................................................................22 JRun Web Server.......................................................................................................................22 JRun Servlet Engine ..................................................................................................................24 General Tab ..........................................................................................................................25 Mappings Tab: Prefix and Suffix Mappings...........................................................................25 Mappings Tab: Servlet Chaining ...........................................................................................28 Aliases Tab ...........................................................................................................................29 Mime Filters Tab ..................................................................................................................31 Multi Home Tab....................................................................................................................32 Session Tracking Tab ............................................................................................................33 Page Compilation Tab...........................................................................................................34 Code Taglets Tab ..................................................................................................................39 Dynamic Taglets Tab ............................................................................................................40 <CF_Anywhere> Tab............................................................................................................41 File Settings Tab ...................................................................................................................45 Configuring General Settings for a JSM..........................................................................................47 General Subtab ..........................................................................................................................47 Java Subtab ...............................................................................................................................48 Performing Remote Administration (JRun Pro Only) ......................................................................50 Starting the Remote JRun Administrator Applet .........................................................................50 Starting the Remote JRun Administrator Application .................................................................51 Registering a Username and Password for Remote JRun Admin.................................................53
Common JRun Tasks ................................................................................................... 55

Using Multiple JSMs......................................................................................................................55 Accessing the Embedded JRun Web Server ....................................................................................56 Developing Custom Services Under JRun.......................................................................................57 Editing Thread Parameters .............................................................................................................61
Contacting Technical Support ..................................................................................... 63 Other Resources ........................................................................................................... 64

JRun User Guide s Version 2.3.3
List of Figures, Tables, and Listings

Figure 1-1: JRun Architecture.................................................................................................................. 4 Figure 1-2: JRun Services Manager Architecture ..................................................................................... 5 Figure 4-1: JRun Folder Contents ..........................................................................................................16 Figure 4-2: JRun Administrator Window: JRun Service Manager Tab...............................................16 Figure 4-3: JSM Configuration Window: Services Tab..........................................................................17 Figure 4-4: General Config Window: Service Info Tab........................................................................19 Figure 4-5: General Config Window: Endpoint Settings Tab, General Subtab ...................................20 Figure 4-6: General Config Window: Endpoint Settings Tab, Tuning Subtab .....................................21 Figure 4-7: Service Config Window (JWS): Service Settings Tab.......................................................22 Figure 4-8: Service Config Window (JWS): Path Settings Tab............................................................23 Figure 4-9: Service Config Window (JSE) ............................................................................................24 Figure 4-10: Service Config Window (JSE): Mappings Tab, Servlet Mappings ....................................26 Figure 4-11: Service Config Window (JSE): Mappings Tab, Servlet Chaining .....................................28 Figure 4-12: Service Config Window (JSE): Aliases Tab .....................................................................29 Figure 4-13: Init Args Editor Window....................................................................................................30 Figure 4-14: Service Config Window (JSE): Mime Filters Tab.............................................................31 Figure 4-15: Service Config Window (JSE): Multi Home Tab ..............................................................32 Figure 4-16: Service Config Window (JSE): Session Tracking Tab, General Subtab..........................33 Figure 4-17: Service Config Window (JSE): Session Tracking Tab, Cookie Subtab ............................34 Figure 4-18: Service Config Window (JSE): Page Compilation Tab....................................................35 Figure 4-19: Service Config Window (JSE): Code Taglets Tab...........................................................39 Figure 4-20: Service Config Window (JSE): Dynamic Taglets Tab .....................................................40 Figure 4-21: Service Config Window (JSE): <CF_Anywhere> Tab .....................................................41 Figure 4-22: <CF_Anywhere> Configuration Window: CF Tags Tab .................................................41 Figure 4-23: <CF_Anywhere> Configuration Window: Web Application Tab, Variables Subtab .......42 Figure 4-24: <CF_Anywhere> Configuration Window: Web Application Tab, Timeout Subtab .........43 Figure 4-25: <CF_Anywhere> Configuration Window: Data Sources Tab.........................................44 Figure 4-26: <CF_Anywhere> Configuration Window: CFForm Applets Tab....................................45 Figure 4-27: Service Config Window (JSE): File Settings Tab.............................................................46 Figure 4-28: JSM Configuration Window: General Tab, General Subtab ..............................................47 Figure 4-29: JSM Configuration Window: General Tab, Java Subtab....................................................48 Figure 4-30: Remote JRun Administrator Login Window: Applet Version............................................51 Figure 4-31: Remote JRun Administrator Login Window: Application Version ....................................52 Figure 5-1: JRun Embedded Web Server Default Home Page..................................................................56 Figure 5-2: Invoking SnoopServlet through the JRun Web Server ...........................................................57
Table 1-1: Features of Server-Side Java ................................................................................................... 1 Table 4-1: JRun Service Names and Ids ..................................................................................................18 Table 4-2: Fields in Service Config Window (JSE): General Tab .........................................................25 Table 4-3: Fields in Service Config Window (JSE): Aliases Tab...........................................................30 Table 4-4: Fields in Service Config Window (JSE): Multi Home Tab....................................................32 Table 4-5: Fields in Service Config Window (JSE): Session Tracking Tab, General Subtab...............33 Table 4-6: Character Encoding Schemes .................................................................................................36 Table 4-7: JRun Administrative Permission Levels..................................................................................54 Listing 2-1: Generic Servlet..................................................................................................................... 7 Listing 2-2: Using a Database Servlet ...................................................................................................... 7 Listing 3-1: Hello World Servlet.............................................................................................................. 8 Listing 3-2: Using the init() Method........................................................................................................10 Listing 3-3: Retrieving Parameters..........................................................................................................11
ii
Listing 3-4: Invoking the Hello World Servlet with <SERVLET> ...........................................................12 Listing 3-5: Hello World Servlet with Page Counter................................................................................12 Listing 4-1: Sun Microsystems JDK1.1.7b Options .................................................................................48 Listing 4-2: Microsoft Command-Line Loader Options ...........................................................................49 Listing 4-3: Example pass.properties File..........................................................................................53 Listing 5-1: Simple HTTP Daemon.........................................................................................................58
iii
Introduction to JRun
Java: A brief history
1
Chapter
This section provides a brief overview of Java and an overview of some of its features. This section is important for readers who have developed server-side web processing applications in other environments such as Perl , Cold Fusion, and Active Server Pages and are wondering why Java and JRun might be a better choice. Although Java may have originally earned its publicity from programs for creating web content on client machines (i.e., applets), Java has become an even more popular and useful language because of its power on server machines. With Java running on servers, the practical limitations of client-side Java disappear. No longer does each individual client need to support Java in order to access its benefits
Comparing Client-Side Java and Server-Side Java

The power of server-side Java becomes evident upon examination of the limitations of clientside Java. Table 1-1 provides a comparison of the features of client-side and server-side Java. Table 1-1: Features of Server-Side Java Capability Consistent Java features Uses latest Java technologies Use Java VM of choice No browser limitations Client irrelevant Client-Side Java Server-Side Java X X X X X
With server-side Java, many, if not all, of the limitations of applets disappear. As a developer, you now have complete control over your Java Virtual Machine (JVM), what features and capabilities you may use, and on what platforms you may run your server-side application.
Server-side Java enables you to completely realize Java write once, run anywhere goal. s The full capabilities of the language are available to you with no limitations or restrictions. If you want to use Microsoft J/Direct technology or Sun RMI technology, you may do so s s without concern for your clientsability to run these applications. Because these applications run on the server, you may also control the platform, the operating system, and every aspect of the environment in which your application runs. Java on the server is a true unifying solution for application development. Because you have complete control over your environment, you may develop on one platform and deploy on another, with confidence that it will run properly on both platforms. Because the interface is handled with DHTML or a similar technology, you have a truly portable system. With the power that server-side Java affords you, including all of the inherent benefits of Java object oriented, strong type-checking, large set of built-in classes, etc. it still has one shortcoming: It lacks a consistent server-side API. A consistent API is needed to use Java as the development platform across all servers and to combine multiple applications together into a larger system. The answer to this problem is Java servlets.
Server Component Model

Servlets are more than just a replacement for server-side programs. They are a true component model for building server-side applications. Servlets have many unique features, but two in particular extend the ability of a server-side system into a component model for server-side applications. These two features are servlet chaining and inter-servlet communications. Servlet chaining is the ability for one servlet output to be piped to the input of another s servlet. This can continue for multiple servlets even servlets from different vendors each working seamlessly together. For example, a spelling-checker servlet could be chained after any other servlet to spell-check the output being sent to the client. Another example might be a language-translation servlet. A servlet that converts English to German could be used to dynamically convert the English output of each servlet into German. Each servlet could be chained first to the spelling-checker servlet and then to the languagetranslation servlet. Each servlet need not know the capabilities of the other; yet they can all work seamlessly together because of a consistent server-side API: the Java Servlet API.
What is JRun?
JRun was first developed in 1997 as software for servlet-enabling web servers. JRun has evolved into a Java server with various capabilities. JRun is a cross-platform Java server that includes an award-winning Java servlet runner, a Java Server Pages (JSPs) compilation engine, and an optional Java web server. JRun enjoys the widest web server compatibility coverage of any servlet engine on the market today. JRun supports Novell Netware, UNIX, LINUX, Windows NT, Windows 95/98, and MacOS. Its simple design allows it to work with a large variety of existing web servers, including Netscape, WebStar, O Reilly WebSite Pro, Microsoft IIS, Microsoft Personal Web Server s (PWS), and Apache. With JRun, you can deploy dynamic web sites on almost any platform.
JRun Architecture
This section describes the architecture of JRun and its main components. Understanding the JRun architecture will enable you to take full advantage of its flexible environment. A core advantage of JRun is its ability to be extended and built upon. The main component of JRun is the JRun Service Manger (JSM). JSM is responsible for loading and initializing services, or protocol-independent components that provide specific capabilities. Three such services are included in JRun: JRun Servlet Engine (JSE) Service: The JSE service is responsible for running and handling Java servlets. JSE allows any service to run servlets. JRun Connector Proxy Service: The JCP service facilitates communication between JSE and any external source (such as a web server or application server). JRun Web Server Service: The JWS service is a fast and lightweight all-Java web server that enables servlets and web pages to run independent of a native web server.
Relationship to the Web Server

JSM runs as its own process, or as an independent entity. The services included within JSM run independently from the web server, or out-of-process. A web server simply acts as a client that talks indirectly to applicable services. The out-of-process model provides several advantages. Servlet developers can now select the type of Java Virtual Machine (JVM) that they want to run with their servlets, independent of the JVM that is supplied by their web server. For example, a servlet developer running Netscape Enterprise Server can choose to run his or her servlets s (including servlets generated from files with the .jsp extension) with Sun or Microsoft s s JVM rather than the JVM included with the Netscape server. (In addition, JRun Pro enables you to run multiple JVMs at the same time.) The out-of-process model includes several additional advantages: increased stability of the web server, the ability to bring a web server up and down independently of JRun, and the ability for a single service (particularly the JSE) to talk to multiple web servers.
Because a web server acts as a client that talks indirectly to the services, in order for a web server to talk to the JSE, it needs to establish some sort of connection. JRun provides and installs a native connector in the web server that is responsible for making the connection from the web server to JSE. When a request is made for a servlet, the native connector opens a socket connection to the JCP service residing within JSM. The JCP service serves as a transparent communicator and translates the request coming from the native connector to the JSE Service. The JSE service handles the request and sends its reply back to the JCP service. The JSE service does not talk through sockets. Instead, it relies on the JCP service to talk through the socket back to the web server. Figure 1-1 illustrates the communication between web servers and the JSE service.
Figure 1-1: JRun Architecture
JRun Services
JRun includes an API allowing advanced developers to create and deploy custom Java services on virtually any platform. These services are managed within the JRun Services Manager (as shown in Figure 1-2). JRun thus provides a simple mechanism for developing and deploying servers across multiple platforms without changing any code. In addition, the JRun Services API handles basic threading and connection management. Figure 1-2: JRun Services Manager Architecture
Custom Service B
Custom Service A
SMTP Service
JRun Servlet Runner
Introduction to Servlets
Servlets vs. CGI
2
Chapter
Common Gateway Interface (CGI) was the dominant interface for extending web servers for years. Because CGI support was built into every web server on the market, CGI was a great choice for development tools and applications that could add dynamic capabilities to a web site. CGI languages included C, C++, and Perl, with Perl being the dominant CGI language. Enter Java. A networked language from the ground up, Java was written specifically to take advantage of the Internet. With built-in support for network sockets, database connectivity, string manipulation, and a host of other features, Java quickly became adopted by developers all over the world as the premier development language. Nevertheless, using Java as a CGI language was still a problem. Most solutions involved creating a new JVM for each request. Much like the Perl interpreter, it was necessary to create a new process for every request to the program. The Java Servlet API was introduced as a means of standardizing the use of Java when used through a web server. Servlets are, in fact, a complete replacement for CGI. Servlets offer many added benefits to the developer, including ease of development, automatic garbage collection, fast throughput and response, inter-servlet communications, and all of the features inherent in Java. One of the main problems with traditional CGI applications is performance. A new process is created each time a CGI application is requested by the client. This behavior can lead to performance problems at popular web sites that handle requests from multiple users. Servlets, on the other hand, handle this process more efficiently. The first time that a servlet is requested, it is loaded into the web server memory space. Subsequent client requests for the s servlet result in calls to the servlet instance in memory. Also, servlets can use threading to process multiple requests efficiently if the JVM embedded in the web server offers thread support, whereas CGI programs are not threaded. Another benefit of servlets over CGI is that servlets are platform-independent, whereas CGI programs are platform-dependent. In addition, a servlet maintains memory of its state once it is loaded by the server. The JVM running on the web server loads the servlet when it is called. CGI programs are stateless because they result in the creation of a new process each time that a request is serviced.
Extending Web Servers with Servlets

By using existing mature server technology, such as web servers, in combination with servlets, developers can write sophisticated applications that hide the complexities and platformspecific behaviors of the particular server implementation. Using servlets, the developer does not need to understand the inner workings of the server. Form data, server headers, cookies, etc. are all handled by the underlying classes of the Java Servlet API. One of the biggest differences between today server-side applications and servlets is performance. A single s JVM runs on the server, and the servlet is loaded once when it is called. The servlet is not loaded again until it changes, and a modified servlet can be reloaded without restarting the server or application. The servlet stays resident in memory and is very fast. Static or persistent information can be shared across multiple invocations of the servlet, allowing you to share information between multiple users. Servlets are also modular; each servlet can perform a specific task and can be tied together. In short, servlets can talk to each other. What does a servlet look like? Listing 2-1 shows the complete source code to a functioning servlet. Listing 2-1: Generic Servlet
Import java.io.*; Import javax.servlet.*; Public class SimpleServlet extends GenericServlet { public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException { ServletOutputStream out = res.getOutputStream() out.println("<HEAD><TITLE> SimpleServlet Output "); out.println("</TITLE></HEAD><BODY>"); out.println("<h1> SimpleServlet Output </h1>"); out.println("</BODY>"); } }
The other powerful capability of servlets is their ability to communicate with each other. That is, one servlet can request the services of another servlet. For example, a servlet that handles database connectivity could be loaded on web server startup; then any subsequent servlet could use the facilities of the database servlet without implementing database code directly. Listing 2-2 shows a portion of code that exemplifies such a behavior. Listing 2-2: Using a Database Servlet
DatabaseServlet dbServlet = (DatabaseServlet) contextgetServlet( Database Servlet ); ResultSet rs = dbServlet.executeQuery( SELECT * From Table );
Listing 2-2 shows how a servlet can request another servlet by name and then execute a method (in this case, an SQL query that returns a ResultSet object). Any servlet could make use of that method.
Servlet Tutorial
3
Chapter
The best way to explain the basics of any programming language and API is with the help of the simplest program that we can develop. In this tutorial, we will develop a HelloWorld program. As we learn more about the Java Servlet API, we will modify the program, ending with a large yet easy-to-modify program that will address all of the basic aspects of the API. At the end of this tutorial, you should have a basic understanding of the API and the tools necessary to develop any servlet.
Part 1
We start our tutorial by examining the program in Listing 3-1. The first lines start by importing all of the necessary packages. The lines that may not be familiar to you are import javax.servlet.* and import javax.servlet.http.*. These items are packages from the Java Servlet API. We import those packages because all servlets need to implement the servlet interface. Listing 3-1: Hello World Servlet
import java.io.*; import javax.servlet.*; import javax.servlet.http.*; public class HelloWorld extends HttpServlet { public void service(HttpServletRequest servReq, HttpServletResponse servRes) throws IOException { ServletOutputStream out = servRes.getOutputStream(); Out.println("Hello World"); } }
Next, we see that the HelloWorld program is extending the HttpServlet class and not the servlet interface that we just mentioned. We are not implementing the servlet interface because the HttpServlet class implements the servlet interface; so we do not need to explicitly implement it. It is a common practice for the servlet developer to extend the GenericServlet or HttpServlet class instead of implementing the servlet interface. Knowing when to extend from GenericServlet or HttpServlet will become clear as we learn more about the Java Servlet API. The service method implemented in the example will be called repeatedly. The first parameter of the service method is an HttpServletRequest object that provides an InputStream so that servlets can read client requests. The second parameter of the service method is an
HttpServletResponse object that provides an OutputStream so that servlets can write a response back to the client. The rest of the program is self-explanatory. At this point, you need to compile the Java code to get your servlet class file. After successfully compiling the code, you need to put the servlet class file in the appropriate directory so that the web server can access it. The HelloWorld example program that we just created is the most basic program that can be created using the Java Servlet API. From this program, we learn that all servlets must implement the servlet interface and that it is customary to extend either the GenericServlet or HttpServlet, both of which implement the servlet interface. Now we will address what happens when a client invokes a servlet. When a client invokes a servlet, the servlet undergoes a three-stage lifecycle: initialization, service, and destroy. During the initialization cycle, the servlet is initialized via the init(ServletConfig) method. At this cycle, it is recommended to allocate all of the resources that the servlet will need throughout its lifecycle because the init(ServletConfig) method only gets called once, thus avoiding the need to allocate expensive resources every time that the servlet is invoked. The service cycle occurs when the servlet handles all incoming requests via the service(), doGet(), or doPost() methods. If you are familiar with the HTTP protocol, or as we continue with the tutorial, it will become clear which method to implement. In our example, we use the service method; but we could have used the doGet or doPost methods (as explained later in this tutorial). The third and final cycle that the servlet undergoes is the destroy cycle. At this cycle, the destroy() method gets called either implicitly or explicitly. Inside the destroy() method, the developer may free all of the allocated resources that the servlet was using during its lifecycle. As soon as the destroy() method gets invoked, the class can be garbage-collected.
Part 2
Now that we know more about the servlet lifecycle, we will rewrite the HelloWorld example program using these methods. Listing 3-2 shows the same example as Listing 3-1, but with the init and destroy methods in place. Listing 3-2: Using the init() Method
import java.io.*; import javax.servlet.*; import javax.servlet.http.*; public class HelloWorld extends HttpServlet { public void init (ServletConfig config) throws ServletException { // This method initializes the servlet and only gets call once. // Allocate all of the servlet resources here. super.init (config); } public void service(HttpServletRequest servReq, HttpServletResponse servRes) throws IOException { ServletOutputStream out = servRes.getOutputStream(); out.println("Hello World"); } public void destroy() { // Once this method is called then any instance of this class can be garbage collected // Here is where all servlets resources can be deallocated. } }
10
Part 3
Up to this point, our example program always outputs the same string value. Obviously, this program is not very helpful. What we really need is a servlet that allows us to interact with it. We can easily interact with servlets by using parameters. Servlets use two types of parameters: initialization parameters and regular parameters. We will discuss regular parameters first and then explain initialization parameters later in this tutorial. Listing 3-3: Retrieving Parameters
import java.io.*; import javax.servlet.*; import javax.servlet.http.*; public class HelloWorld extends HttpServlet { public void init (ServletConfig config) throws ServletException { super.init (config); } public void service(HttpServletRequest servReq, HttpServletResponse servRes) throws IOException { String userName; ServletOutputStream out = servRes.getOutputStream(); if ( (userName = servReq.getParameter("userName")) != null) out.println("Hello " + userName); else out.println("Hello, who are you?"); } }
We can use parameters to make our example program print "Hello <your name>" instead of just "Hello World". Hereafter, for simplicity, our examples will implement only the methods necessary to make the servlet work. Listing 3-3 shows how we would retrieve a parameter value using the getParameter(String) s method. If the parameter name that we are attempting to retrieve is not defined, then the getParameter(String) method will return a null value Now that we know how to retrieve parameters, we need to learn how to specify them. The most basic way to specify parameters is to use a GET query string. With the GET query string, we can specify parameters as follows: http://host/servlet_directory/HelloWorld?userName=Hal
11
Another method of specifying parameters is through Server Side Include (SSI) and the use of the <servlet> tag, as demonstrated in Listing 3-4. Listing 3-4: Invoking the Hello World Servlet with <SERVLET>
<servlet code="HelloWorld" > <param name="userName" value="Hal"> </servlet>
We can specify parameters in other ways, such as in HTML forms. In Part 4 of this tutorial, we will explore the many ways to retrieve parameters in servlets.
Part 4
Now that we know how to retrieve and specify parameters, we will examine an example that requires initialization parameters. This section explains one of the many reasons why we need initialization parameters and how we can retrieve them in a servlet. For simplicity, we will continue using the same example program with new added features. Assume that we need a counter to record how many times a specific home page is accessed. Furthermore, we would like to print the value of the counter in a different font size. To accomplish these tasks, we need two extra variables: counter and fontSize (as shown in Listing 3-5). Listing 3-5: Hello World Servlet with Page Counter
import java.io.*; import javax.servlet.*; import javax.servlet.http.*; public class HelloWorld extends HttpServlet { //Default Values private static final int FONTSIZE = 3; private static final int COUNTER = 0; //Default Variables public static int fontSize; public static int counter; public void init (ServletConfig config) throws ServletException { super.init (config); if ( getInitParameter("fontSize") != null ){ try{ this.fontSize = Integer.parseInt(getInitParameter("fontSize")) ; } catch (NumberFormatException e){ this.fontSize = this.FONTSIZE; } } else this.fontSize = this.FONTSIZE; if ( getInitParameter("counter") != null ){ try{ this.counter = Integer.parseInt(getInitParameter("counter")) ; } catch (NumberFormatException e){ this.counter = this.counter; } } else this.counter = this.counter;
12
} public void service(HttpServletRequest servReq, HttpServletResponse servRes) throws IOException { // Set the content type servRes.setContentType("text/html"); String userName; ServletOutputStream out = servRes.getOutputStream(); if ( servReq.getParameter("userName") != null) userName = servReq.getParameter("userName"); else userName = new String("Stranger"); out.println("<HTML><HEAD><TITLE>Hello World</TITLE></HEAD><BODY>"); out.println(userName + "This page has been accessed " + counter++ + " times "); out.println("</BODY></HTML>"); } }
In Listing 3-5, we introduce methods that we have not previously seen; so we will explain each line of the program. Assuming that you know the basics of Java, we will not explain the constants and variables declarations. After the declarations, the first method that we encounter is the init(ServletConfig) method. This time, however, we are using the init(ServletConfig) method to retrieve the initialization parameters with the getInitParameter(String) method and to initialize the global variables. Before we proceed, we should review a few points. First, we know that servlets remain in memory until the server is restarted or until they are reloaded dynamically. Second, because the init method is called only once during the initialization cycle, the global variables will be initialized only one time (when the servlet is first invoked). Once the global variables are initialized, they will be available through the life cycle of the servlet, maintaining their state through different client requests. So, following the code in the init method, if the user declares valid initialization parameters, then the global variables will be set to those values. On the other hand, if the user does not specify valid initialization parameters, or specifies wrong initialization parameters, then the global variables will be set to the default values (the constants). This flexibility enables us to start counting at whatever value we wish. It also allows us to specify the desired font size for the value of the counter display.
13
Besides the new changes in the init(servletConfig) method, the service(HttpServletRequest, HttpServletResponse) method also introduces one method: the servRes.setContentType(String) method. The purpose of this program is to display the user name and time that the page is accessed. Furthermore, in order to display the counter with a different font size, we need to use embedded HTML in the print statements. We need to tell the browser that we are going to be displaying HTML. The servRes.setContentType("text/html") method enables us to set the content MIME type. Once s we set MIME type, the rest of the code is self-explanatory: We get the parameters and then print to the browser. We now know how to retrieve initialization parameters; but we still need to know how to send them to the servlet. Using JRun, you may send initialization parameters with the JRun Admin application (described in Chapter 4, JRun Administration). You should then be able to write almost any basic servlet.
14
JRun Administration
Starting the JRun Admin Application Selecting a JSM to Configure Selecting a Service to Configure Configuring General Settings for a Service Configuring Service Settings for a Service JRun Web Server JRun Servlet Engine
4
Chapter
This section describes how to configure JRun using the JRun Admin application as follows:
Configuring General Settings for a JSM Performing Remote Administration (JRun Pro Only) Starting the Remote JRun Administrator Applet Starting the Remote JRun Administrator Application Registering a Username and Password for Remote JRun Admin
15
Starting the JRun Admin Application

To start JRun Admin on a Windows platform, double-click the JRun Admin icon in the JRun folder (created during installation).
Figure 4-1: JRun Folder Contents On all platforms, you may enter the bin directory and run the startadmin script. If JRun Admin is started at the root-most level, the JRun Administrator window appears.
Figure 4-2: JRun Administrator Window: JRun Service Manager Tab

16
Selecting a JSM to Configure

The JRun Service Manger tab of the JRun Administrator window (Figure 4-2) displays the name and status of each available JSM instance. If the JRun root directory contains more than one jsm-XXX directory, each jsm-XXX directory is listed here. Select the JSM to edit and click Configure. The JSM configuration window appears, displaying the name of the JSM in the title bar.
Figure 4-3: JSM Configuration Window: Services Tab
17
Selecting a Service to Configure

The Services tab in the JSM configuration window (Figure 4-3) lists each available service for the current JSM. By default, JRun starts four different services, as described in Table 4-1. Table 4-1: JRun Service Names and Ids Service Name JRun Connector Proxy JRun Web Server JRun Servlet Engine (JCP) Service ID jcp jws jse Comments
JRun Servlet Engine (JWS)
jseweb
Responsible for handling servlet requests from a native web server via the JRun Connector Proxy Responsible for handling servlet requests from the JRun Web Server
The checkboxes in the Service Active column enable you to activate or deactivate each service. To configure a service, select it and then click either General Config (as discussed in Configuring General Settings for a Service) or Service Config (as discussed in Configuring Service Settings for a Service). The Default button enables you to restore the recommended settings that were configured during installation. Note that all changes made to a service in the JSM configuration window will be applied the next time that you start JRun. Related property file:
jsm-default/properties/services.properties
18
Configuring General Settings for a Service

The General Config button in the JSM configuration window (Figure 4-3) enables you to configure the network settings for a service. Figure 4-4 displays the General Config window that appears for the JRun Connector Proxy service. The Service Info tab is selected by default.
Figure 4-4: General Config Window: Service Info Tab The Endpoint Settings tab enables you to set specific network settings, as shown in Figure 4-5. The General subtab of this window enables you to configure JCP server port number, bind address, and allowed host/IP address (* => all).
19
Figure 4-5: General Config Window: Endpoint Settings Tab, General Subtab The Tuning subtab (Figure 4-6) enables you to configure the number of threads that JRun uses. Use the Active Handler Threads setting to specify a soft limit to the number of threads that JRun should handle. The Monitor Interval setting enables JCP thread usage to be reported at a specified time interval.
20
Figure 4-6: General Config Window: Endpoint Settings Tab, Tuning Subtab Related property files:
jsm-default/properties/jcp/endpoint.properties jsm-default/properties/jcp/services.properties jsm-default/services/jcp/properties/proxy.propertie s
21
Configuring Service Settings for a Service

The Service Config button in the JSM configuration window (Figure 4-3) enables you to configure the service settings for the selected JRun service. This section describes the settings for the JRun Web Server and the JRun Servlet Engine. JRun Web Server Figure 4-7 shows the Service Config window for the JRun Web Server.
Figure 4-7: Service Config Window (JWS): Service Settings Tab The Service Settings tab enables you to activate and deactivate keep-alive connection. The Paths Settings tab (Figure 4-8) enables you to set virtual paths.
22
Figure 4-8: Service Config Window (JWS): Path Settings Tab Related property files:
jsm-default/services/jws/properties/paths.properties jsm-default/services/jws/properties/web.properties
23
JRun Servlet Engine Figure 4-9 shows the Service Config window for the JRun Servlet Engine.
Figure 4-9: Service Config Window (JSE) This section describes the tabs in this window as follows: General Tab Mappings Tab: Prefix and Suffix Mappings Mappings Tab: Servlet Chaining Aliases Tab Mime Filters Tab Multi Home Tab Session Tracking Tab Page Compilation Tab Code Taglets Tab Dynamic Taglets Tab <CF_Anywhere> Tab
24
General Tab
The General tab enables you to set the basic configuration of the JSE. Table 4-2 describes the fields in the General tab.
Table 4-2: Fields in Service Config Window (JSE): General Tab Field
JSE Root Directory Default Servlets Dir Default Logging Dir SingleThreadModel Pool Size
Description Location of the JRun Servlet Engine root directory. This setting should rarely be modified. Location of the JRun Servlet Engine servlets directory. Location of the JRun Servlet Engine logging directory. When using the SingleThreadModel interface, this setting specifies the initial size of the servlet instance pool.
Related property file:

jsm-default/services/jse/properties/jrun.properties
Mappings Tab: Prefix and Suffix Mappings
The Mappings tab enables you to define prefix and suffix mappings for servlets. For example, when defining a prefix mapping, you may specify that if a request contains the /servlet/ prefix, then all HTTP requests with the /servlet/ prefix should be treated as servlet requests. That is, if you made the following request with your browser, then the SnoopServlet servlet would run:
25
http://www.yourdomain.com/servlet/SnoopServlet If any information follows the prefix, it is sent to the servlet as extra path information. For example: http://www.yourdomain.com/servlet/SnoopServlet?name=value For suffix mappings, you may define a file extension that will invoke a servlet. For example, you could map the .snoop extension to run the SnoopServlet. A real example is the .jsp extension. JRun invokes the JSP servlet to process the requested JSP. The servlet invoked could be an alias of the actual servlet. (To define an alias, use the Aliases Tab.) Figure 4-10 shows the Mappings tab displaying prefixes and a suffix mapping.
Figure 4-10: Service Config Window (JSE): Mappings Tab, Servlet Mappings To add a new mapping, click the Add button and enter the appropriate information in the row that appears. When entering a suffix mapping, use the asterisk (*) to denote any file with that mapping. The mapping of a prefix to the invoker servlet is a special case that causes the name after the prefix to be invoked as a servlet. For example, mapping /servlet/ to invoker causes the following request to invoke the SnoopServlet:
26
http://www.yourdomain.com/servlet/SnoopServlet You may also add new mappings to invoker or change the default /servlet/ mapping. To edit a mapping, select it and edit it in place. To delete a mapping, select it and click the Delete button. Related property file:
jsm-default/services/jse/properties/rules.properties
27
Mappings Tab: Servlet Chaining
Servlet chaining is the ability for one servlet output to be piped to the input of another s servlet. JRun supports chaining by comma-delimiting a list of servlets when making a request. For example, the following request runs SnoopServlet and then sends its output to the UpperCaseFilter servlet: http://www.yourdomain.com/servlet/SnoopServlet,UpperCaseFilter Figure 4-11 shows an example of a servlet chain in the Mappings tab. If a request for /snoopchain is made, SnoopServlet is run and then chained to UpperCaseFilter.
Figure 4-11: Service Config Window (JSE): Mappings Tab, Servlet Chaining
28
Aliases Tab
The Aliases tab (Figure 4-12) enables you to define alternate names, or aliases, for servlets. In addition, you may define initialization arguments for a servlet and specify whether the servlet should be loaded when the server starts.
Figure 4-12: Service Config Window (JSE): Aliases Tab Table 4-3 describes the fields for adding a new servlet alias.
29
Table 4-3: Fields in Service Config Window (JSE): Aliases Tab Field
Name Class Name
Init Arguments
Description Alternate name for the servlet. This name should not contain spaces or any special characters. The fully qualified class name of the servlet. For example, if the servlet is named TestServlet and is in a package named testing, enter testing.TestServlet. An optional, comma-delimited list of init name/value pairs in the following format:
name=value[, name=value[, ]]
Double-clicking this field invokes the Init Args Editor window (Figure 4-13), which enables you to enter name/value pairs.
Figure 4-13: Init Args Editor Window

Pre-Load
Option to specify whether the servlet should be loaded at server startup. Note that only a servlet with an associated alias (as defined in the Aliases Tab) can be pre-loaded at server startup.

jsm-default/services/jse/properties/servlets.properties
30
Mime Filters Tab
Mime-type chaining is similar to regular servlet chaining with one exception: Instead of explicitly specifying which servlets to chain, you specify the mime-type that should trigger a servlet to run. For example, as shown in Figure 4-14, if you map the text/plain mime-type to the UpperCaseFilter servlet, any servlet that responds with a Content Type of text/plain will automatically be chained to UpperCaseFilter.
Figure 4-14: Service Config Window (JSE): Mime Filters Tab To add a new mime-type chain filter, click the Add button. In the Mime-Type field, enter the mime-type in the form of xxx/yyy. In the Servlet Invoked field, enter the servlet name. Note: You may also enter a chain of servlets in the Servlet Invoked field (for example, UpperCaseFilter, SpellCheckFilter ). Related property file:
jsm-default/services/jse/properties/mimeservlets.properties
31
Multi Home Tab
The Multi-Home tab (Figure 4-15) enables you to specify alternate servlet and logging directories for virtual hosts. JRun uses the browser Host header to determine which s servlet directory to use.
Figure 4-15: Service Config Window (JSE): Multi Home Tab Table 4-4 describes the fields in the Multi Home tab. Table 4-4: Fields in Service Config Window (JSE): Multi Home Tab Field
Hostname
Servlet Dir Logging Dir
Description Full hostname that an Internet user would enter to access your website on that domain. Note that name and name.hostname are considered two different hosts. Absolute path to a servlets directory. Absolute path to a logging directory for this virtual host.

jsm-default/services/jse/properties/multihome.properties
32
Session Tracking Tab
The Session Tracking tab (Figure 4-16) controls the integrated Session Persistence Engine, which allows JRun to save and reload user session information when the server is stopped and restarted.
Figure 4-16: Service Config Window (JSE): Session Tracking Tab, General Subtab Table 4-5 describes the fields for session tracking. Table 4-5: Fields in Service Config Window (JSE): Session Tracking Tab, General Subtab Field
Use Session Persistence Engine
Maximum Sessions
Invalidation Time Invalidation Interval
Description Setting that tells JRun to use Java Serialization to save and restore sessions when JRun shuts down and starts up again. Session data is saved in the directory given in the Session Storage Dir field. Session data is saved only when JRun is shut down gracefully. Maximum number of sessions that JRun will hold in memory at a time. Old sessions are released when a new session is added when the total is at this maximum value. Number of milliseconds that a session is allowed to stay alive after its last access. Number of milliseconds between checks to determine whether any sessions need to be invalidated.
33
Session Storage Dir
Location of the JRun session swap file. This directory name can be relative to the JRun root directory or an absolute location.
The Session Tracking tab also enables you to set cookie properties using the Cookie subtab, as shown in Figure 4-17.
Figure 4-17: Service Config Window (JSE): Session Tracking Tab, Cookie Subtab Related property file:
jsm-default/services/jse/properties/session.properties
Page Compilation Tab
JRun supports Java Server Pages (JSPs), including Sun Java Server Page 0.92 s specification and Allaire code taglets and dynamic taglets. To configure JSPs, use the s Page Compilation tab in combination with the Code Taglets Tab and the Dynamic Taglets Tab. The Page Compilation tab (Figure 4-18) enables you to change different JSP compilation options. For example, you may specify an external Java compiler to compile your JSPs. By default (i.e., if the Java Compiler field is blank), JRun uses in-process compilation. For performance or compatibility reasons, you may want to specify another Java compiler. To do so, enter an appropriate Java compilation string in the Java Compiler field. For example:
34
D:\jdk1.1.7b\bin\javac -nowarn -classpath %c -d %d %f
or
jvc /cp:c %c /dest: %d %f
where
%f %c %d = filename = classpath (java classpath to use) = codepath (where to place compiled class files)
Figure 4-18: Service Config Window (JSE): Page Compilation Tab The Page Compilation tab also enables you to change character encoding. If you use a specified character encoding scheme in your JSPs, enter one of the character encoding schemes listed in Table 4-6 in the Default Text Encoding field. (For more information, see Appendix B, Other Resources.)
35
Table 4-6: Character Encoding Schemes Character Encoding ASCII ISO8859_1 ISO8859_2 ISO8859_3 ISO8859_4 ISO8859_5 ISO8859_6 ISO8859_7 ISO8859_8 ISO8859_9 Big5 Cp037 Cp1006 Cp1025 Cp1026 Cp1046 Cp1097 Cp1098 Cp1112 Cp1122 Cp1123 Cp1124 Cp1250 Cp1251 Cp1252 Cp1253 Cp1254 Cp1255 Cp1256 Cp1257 Cp1258 Cp1381 Cp1383 Cp273 Cp277
Description ASCII ISO 8859-1 ISO 8859-2 ISO 8859-3 ISO 8859-4 ISO 8859-5 ISO 8859-6 ISO 8859-7 ISO 8859-8 ISO 8859-9 Big5, Traditional Chinese USA, Canada (Bilingual, French), Netherlands, Portugal, Brazil, Australia IBM AIX Pakistan (Urdu) IBM Multilingual Cyrillic: Bulgaria, Bosnia, Herzegovinia, Macedonia (FYR) IBM Latin-5, Turkey IBM Open Edition US EBCDIC IBM Iran (Farsi) /Persian IBM Iran (Farsi) /Persian (PC) IBM Latvia, Lithuania IBM Estonia IBM Ukraine IBM AIX Ukraine Windows Eastern European Windows Cyrillic Windows Latin-1 Windows Greek Windows Turkish Windows Hebrew Windows Arabic Windows Baltic Windows Vietnamese IBM OS/2, DOS People Republic of China (PRC) s IBM AIX People Republic of China (PRC) s IBM Austria, Germany IBM Denmark, Norway
36
Cp278 Cp280 Cp284 Cp285 Cp297 Cp33722 Cp420 Cp424 Cp437 Cp500 Cp737 Cp775 Cp838 Cp850 Cp852 Cp855 Cp857 Cp860 Cp861 Cp862 Cp863 Cp864 Cp865 Cp866 Cp868 Cp869 Cp870 Cp871 Cp874 Cp875 Cp918 Cp921 Cp922 Cp930 Cp933 Cp935 Cp937 Cp939 Cp942 Cp948
IBM Finland, Sweden IBM Italy IBM Catalan/Spain, Spanish Latin America IBM United Kingdom, Ireland IBM France IBM-eucJP Japanese (superset of 5050) IBM Arabic IBM Hebrew MS-DOS United States, Australia, New Zealand, South Africa EBCDIC 500V1 PC Greek PC Baltic IBM Thailand extended SBCS MS-DOS Latin-1 MS-DOS Latin-2 IBM Cyrillic IBM Turkish MS-DOS Portuguese MS-DOS Icelandic PC Hebrew MS-DOS Canadian French PC Arabic MS-DOS Nordic MS-DOS Russian MS-DOS Pakistan IBM Modern Greek IBM Multilingual Latin-2 IBM Iceland IBM Thai IBM Greek IBM Pakistan(Urdu) IBM Latvia, Lithuania (AIX, DOS) IBM Estonia (AIX, DOS) Japanese Katakana-Kanji mixed with 4370 UDC, superset of 5026 Korean Mixed with 1880 UDC, superset of 5029 Simplified Chinese Host mixed with 1880 UDC, superset of 5031 Traditional Chinese Host mixed with 6204 UDC, superset of 5033 Japanese Latin Kanji mixed with 4370 UDC, superset of 5035 Japanese (OS/2) superset of 932 OS/2 Chinese (Taiwan) superset of 938
37
Cp949 Cp950 Cp964 Cp970 EUC_CN EUC_JP EUC_KR EUC_TW GBK ISO2022CN ISO2022CN_CNS ISO2022CN_GB ISO2022JP ISO2022KR JIS0201 JIS0208 JIS0212 KOI8_R MS874 MacArabic MacCentralEurope MacCroatian MacCyrillic MacDingbat MacGreek MacHebrew MacIceland MacRoman MacRomania MacSymbol MacThai MacTurkish MacUkraine SJIS UTF8
PC Korean PC Chinese (Hong Kong, Taiwan) AIX Chinese (Taiwan) AIX Korean GB2312, EUC encoding, Simplified Chinese JIS0201, 0208, 0212, EUC Encoding, Japanese KS C 5601, EUC Encoding, Korean CNS11643 (Plane 1-3), T. Chinese, EUC encoding GBK, Simplified Chinese ISO 2022 CN, Chinese CNS 11643 in ISO-2022-CN form, T. Chinese GB 2312 in ISO-2022-CN form, S. Chinese JIS0201, 0208, 0212, ISO2022 Encoding, Japanese ISO 2022 KR, Korean JIS 0201, Japanese JIS 0208, Japanese JIS 0212, Japanese KOI8-R, Russian Windows Thai Macintosh Arabic Macintosh Latin-2 Macintosh Croatian Macintosh Cyrillic Macintosh Dingbat Macintosh Greek Macintosh Hebrew Macintosh Iceland Macintosh Roman Macintosh Romania Macintosh Symbol Macintosh Thai Macintosh Turkish Macintosh Ukraine Shift-JIS, Japanese UTF-8

jsm-default/services/jse/properties/jsp.properties
38
Code Taglets Tab
Taglets are user-defined. server-side tags that are implemented in Java using Allaire s Taglet API. They provide flexibility for application developers to define and implement their own tags to use within SHTML or JSP files. Taglets are subdivided into the following main types, based on their use and responsibilities in the JRun Scripting Toolkit system: JSP Taglets: Defined for page compilation SSI Taglets: Used in SHTML files; e.g., the SERVLET tag and the INLUDE tag Dynamic Taglets: Provide a one-to-one mapping to call a servlet Note that JSP taglets and SSI taglets are also called code taglets. The Code Taglets tab (Figure 4-19) enables you to specify a new code taglet. To do so, click the Add button and then enter the new class name of the code taglet and its type (either jsp or ssi). For more information, see Appendix B, Other Resources.
Figure 4-19: Service Config Window (JSE): Code Taglets Tab Related property file:
jsm-default/services/jse/properties/codetaglet.properties
39
Dynamic Taglets Tab
Dynamic taglets provide a method of calling a specific servlet through a specific tag. They allow a one-to-one naming convention between a dynamic taglet and the servlet that it represents. The dynamic taglet is a subclass of the SSI taglet that is loaded by the SSIFilter based on the mappings defined in the taglet.properties file. The Dynamic Taglet tab (Figure 4-20) enables you to edit the taglet.properties file. For more information, see Appendix B, Other Resources.
Figure 4-20: Service Config Window (JSE): Dynamic Taglets Tab Related property file:
jsm-default/services/jse/properties/taglet.properties
40
<CF_Anywhere> Tab
The <CF_Anywhere> tab (Figure 4-21) enables you to configure settings for <CF_Anywhere> .
Figure 4-21: Service Config Window (JSE): <CF_Anywhere> Tab To configure <CF_Anywhere>: 1. Click Start <CF_Anywhere> Configuration. The <CF_Anywhere> Configuration window (Figure 4-22) appears, with the CF Tags tab selected.
Figure 4-22: <CF_Anywhere> Configuration Window: CF Tags Tab
41
2. In the CF Tags tab, select or deselect each checkbox to enable or disable the following ColdFusion tags:
CFCONTENT: download and delete server-side content CFDIRECTORY: server-side directory services (creation/deletion etc) CFFILE: server-side file manipulation CFOBJECT: invoke COM objects
3. The Web Application tab enables you to configure the ColdFusion Web Application Framework. In the Variables subtab (Figure 4-23): In the Client Variable Cleanup after (day) field, enter the number of days that JRun/<CF_Anywhere> should keep before cleaning up variables. Select or deselect the appropriate checkbox to enable or disable the following variables: Application variables: Variables that can be set in a ColdFusion web application. These variables may be accessed by different users. Session variables: Variables that a user can set on the server side. JRun stores these variables for retrieval in subsequent HTTP requests.
Figure 4-23: <CF_Anywhere> Configuration Window: Web Application Tab, Variables Subtab
42
4. In the Web Application tab, Timeout subtab (Figure 4-24), set the timeout value (in minutes) for each of the following parameters. To change the values, either use the sliders or type directly into the fields.
Application Variable Maximum Timeout Application Variable Default Timeout Session Variable Maximum Timeout Session Variable Default Timeout
Figure 4-24: <CF_Anywhere> Configuration Window: Web Application Tab, Timeout Subtab 5. The Data Sources tab (Figure 4-25) enables you to define data sources that can be used by the CFQUERY, CFTRANSACTION, CFINSERT and CFUPDATE tags. You may view, add, or delete the entry for each data source. Each entry contains the following information: Name: a name used by CF database tags to access the specified database. For example:
<CFQUERY NAME=datasource1> SELECT * FROM MYTABLE </CFQUERY> JDBC Driver: a JDBC driver class name (e.g., sun.jdbc.odbc.JdbcOdbcDriver).
For more information, consult your JDBC driver documentation or vendor.

JDBC URL: URL to access the specified database (e.g., jdbc:odbc:dsname). Username: Username to access the specified database. Password: Password to access the specified database.
43
Figure 4-25: <CF_Anywhere> Configuration Window: Data Sources Tab 6. The CFForm Applets tab (Figure 4-26) enables you to define custom applets for ColdFusion developers to use in CFAPPLET tags. You may view, add, or delete the entry for each applet. Each entry contains the following information: Name: Name of the custom applet. Tag Attributes: Values for CFAPPLET attributes. Parameters: Any parameters required for the applet to run. To add a custom applet definition, click Add. If you double-click the Tag Attributes part of the new record, the Tag Attribute Editor appears, enabling you to enter different tag attributes for CFAPPLET tags. If you double-click the Parameters part of the new record, the Parameter Editor appears, enabling you to to specify any required applet parameters to start the CFAPPLET custom applet.
44
Figure 4-26: <CF_Anywhere> Configuration Window: CFForm Applets Tab 7. To save your changes in the window, click Save. To restore default values, click Default. To close the window, click Close.
File Settings Tab
The File Settings tab (Figure 4-27) enables you to specify the sequence of default document names that JRun uses when a document name is not specified in a URL. It also enables you to modify the properties of the file cache. In addition, if the Directory Browsing Allowed checkbox is checked, JRun allows browsing of directories.
45
Figure 4-27: Service Config Window (JSE): File Settings Tab Related property file:
jsm-default/services/jse/properties/files.properties
46
Configuring General Settings for a JSM

The General tab in the JSM configuration window (Figure 4-28) shows the current settings for the selected JSM. This window contains two subtabs: General Subtab Java Subtab
Figure 4-28: JSM Configuration Window: General Tab, General Subtab General Subtab The General subtab (Figure 4-28) enables you to change the JSM admin port number, which is used by JRun to determine whether the JSM is running. You may also specify that error messages printed to System.out or System.err be redirected to error and event log files under the corresponding jsm-XXX directory. Related log files:
jsm-default/logs/event.log jsm-default/services/jse/logs/event.log jsm-default/services/jse/logs/error.log
47
Java Subtab The Java subtab (Figure 4-29) enables you to specify another JVM to run JRun. (By default, JRun for Windows and Solaris platforms uses JRE 1.2.)
Figure 4-29: JSM Configuration Window: General Tab, Java Subtab Before using this tab to specify another JVM, you should identify each of the available command-line options. Listings 4-1 and 4-2 display the command-line options for two popular JVMs. Listing 4-1: Sun Microsystems JDK1.1.7b Options
Sun Microsystems JDK1.1.7b usage: java [-options] class where options include: -help print out this message -version print out the build version -v -verbose turn on verbose mode -debug enable remote JAVA debugging -noasyncgc don't allow asynchronous garbage collection -verbosegc print a message when garbage collection occurs -noclassgc disable class garbage collection -ss<number> set the maximum native stack size for any thread -oss<number> set the maximum Java stack size for any thread -ms<number> set the initial Java heap size -mx<number> set the maximum Java heap size -classpath <directories separated by semicolons> list directories in which to look for classes -prof[:<file>] output profiling data to .\java.prof or .\<file>
48
-verify verify all classes when read in -verifyremote verify classes read in over the network [default] -noverify do not verify any class -nojit disable JIT compiler Sun Microsystems JDK1.2 (Java 2 Platform): Usage: java [-options] class [args...] (to execute a class) or java -jar [-options] jarfile [args...] (to execute a jar file) where options include: -cp -classpath <directories and zip/jar files separated by ;> set search path for application classes and resources -D<name>=<value> set a system property -verbose[:class|gc|jni] enable verbose output -version print product version -? -help print this help message -X print help on non-standard options
Listing 4-2: Microsoft Command-Line Loader Options

Microsoft (R) Command-line Loader for Java Version 5.00.3155 Copyright (C) Microsoft Corp 1996-1998. All rights reserved. Usage: JView [options] <classname> [arguments] Options: /? displays usage text /cp <classpath> set class path /cp:p <path> prepend path to class path /cp:a <path> append path to class path /n <namespace> namespace in which to run /p pauses before terminating if an error occurs /v verify all classes /d:<name>=<value> define system property /a execute AppletViewer /vst print verbose stack traces (requires debug classes) Classname: .CLASS file to be executed. Arguments: command-line arguments to be passed on to the class file

jsm-default/jsm.properties
49
Performing Remote Administration (JRun Pro Only)

Administering JRun may be performed remotely through either an applet or a stand-alone Java application. This section describes the remote administration procedures as follows: Starting the Remote JRun Administrator Applet Starting the JRun Admin Application Registering a Username and Password for Remote JRun Admin Starting the Remote JRun Administrator Applet The remote JRun Administrator applet enables you to perform remote administration through your web browser. In order to run the remote JRun Administrator applet, you must have Java Foundation Classes (JFC) Version 1.1 Swing (the platform-independent GUI library for Java) installed on your system. You may configure your browser to use JFC or use appletviewer with the JFC classes in your CLASSPATH. For information on configuring your browser for JFC support, see the following URL: http://www.javasoft.com/products/jfc/swingdoc-current/applets.html Before starting the remote JRun Administrator applet, ensure that you have started the JSM instance under the jsm-default directory. Then, to access the remote JRun Administrator applet, make the following request. (Note that the default admin port of JRun upon installation is port 8000.) http://yourhost:8000/jrunadmin/index.html The JRun Administrator Login window (Figure 4-30) appears in your browser.
50
Figure 4-30: Remote JRun Administrator Login Window: Applet Version Enter your username and password in the fields provided and click the Login button. (The JRun Admin Host field is not editable.) The window that appears next depends upon the level of your administration privileges. For instructions on assigning usernames, passwords, and administration privileges for the remote JRun Administrator, see Registering a Username and Password for Remote JRun Admin. Starting the Remote JRun Administrator Application In order to use the JRun Remote Administrator Application, you must first install it onto your system. Copy the following files to a remote machine: lib/jrunadmin/jrunadmin.jar lib/jrunadmin/swing.jar bin/remoteadmin.bat (Windows platform) or bin/remoteadmin.sh (Unix platform)
51
To start the application: On a Windows platform, run remoteadmin.bat. On a Unix platform, run remoteadmin.sh. The JRun Administrator Login window (Figure 4-31) appears.
Figure 4-31: Remote JRun Administrator Login Window: Application Version Enter the appropriate data in each field and click the Login button. In the JRun Admin Host field, enter t the port on which the JWS service is running (8000 by default). The window that appears next depends upon the level of your administration privileges. For instructions on assigning usernames, passwords, and administration privileges for the remote JRun Administrator, see Registering a Username and Password for Remote JRun Admin
52
Registering a Username and Password for Remote JRun Admin In order to access the remote JRun Administrator, a user must be assigned a username, password, and administration privileges. You may add or change these properties for a user by manually editing the pass.properties file, located in the <JRUN_HOME>/properties directory. Listing 4-3 provides an example of a pass.properties file. Listing 4-3: Example pass.properties File
# Password entries # # login.<name>=<password> # login.<name>.jsm=<permission level> # #JRun Root level permission login.admin=admin login.admin.jsm=root #JSM level permission login.joe=howdy login.joe.jsm=jsm-default #Service level permission login.frank=secret login.frank.jsm=jsm-default/services/jse
Each entry in the pass.properties file contains the following two associations:
login.<name>=<password> login.<name>.jsm=<permission level>
For each user, enter or edit a <name> and <password> and assign a <permission level> as indicated in Table 4-7. Note that, once JRun is successfully installed and you understand how to set up the pass.properties file, you may wish to change the default admin password.
53
Table 4-7: JRun Administrative Permission Levels Level

Root
Description
Entry for <permission level>
Enables user to administer all JRun root Service Managers and their services. Upon login, user is given e.g., in Listing 4-3, login.admin.jsm=root access to the JRun Service Manger tab of the JRun Administrator window (Figure 4-2). Enables user to administer only a specific JRun Service Manager and its services. Upon login, user is given access to the Services tab of the JSM Configuration window (Figure 4-3) for the specified JSM. Enables user to administer only a specific service under a specific JRun Service Manager. Upon login, user is given access to the Service Config window for the jsm-<jsm name> where <jsm name> is the name of the JSM that the user will be allowed to administer; e.g., in Listing 4-3, login.joe.jsm=jsm-default (which permits user joe to administer only the default JSM). jsm-<jsm name>/services/<service name> where <jsm name> is the name of the JSM and <service name> is the name of the service that the user will be allowed to administer; e.g., in Listing 4-3, login.frank.jsm=jsm-default/services/jse (which permits user frank to administer only the JRun Servlet Engine under the default JSM).
JSM
Service
specified service (e.g., Figure 4-9 for the JRun Servlet Engine
under the default JSM).
When saving your changes via Save, JRun will automatically reload your properties without restarting your web server. To abort any changes you have made since the last Save and return to the login screen , select Cancel. To restore all settings back to their defaults, select Default. Related property file:
properties/pass.properties
54
Common JRun Tasks

Using Multiple JSMs Accessing the Embedded JRun Web Server Developing Custom Services Under JRun Editing Thread Parameters
5
Chapter
This chapter discusses the following tasks that are commonly executed in JRun:
Using Multiple JSMs

To use multiple JRun Service Managers, each running its own JVM, follow these steps: 1. Make a copy of the 'jsm-default' directory, naming it 'jsm-<new jsm name>'. For example, 'jsm-myhost' . 2. Using the JRun Admin, adjust the settings for the new JSM, making sure to change the JSM admin port, JRun Connector Proxy port, and JRun Web Server port. Do this by adjusting the Endpoint Settings for the respective service (as discussed in Configuring General Settings for a Service). 3. If a native (or Java-based) server will connect to your new JSM, launch the Connector Wizard (located in the JRun folder, Wizards subfolder, as depicted in Figure 4-1) to configure the native server, ensuring that the Proxy Port and Proxy Host match the new JRun connector proxy port and host. 4. If running under Windows NT and you wish to install the new JSM as an NT service, use the jsm.exe application to install the service. Use the following syntax:
jsm.exe -i <jsm name> <jsm display name> <jsm directory>
For example:
jsm.exe -i myhost JRun Service Manager d:\JRunPro\jsm-myhost
55
From this point forward, administer the new JSM as you would the default JSM. For example, you may start it with net start myhost and stop it with net stop myhost. If you prefer editing property files by hand, then edit the following files to change the JSM port numbers and/or bind addresses:
<jsm name>/properties/jsm.properties <jsm name>/properties/services/jcp/endpoi nt.properties <jsm name>/properties/services/jws/endpoint.properties
Accessing the Embedded JRun Web Server

When JRun is installed, the JRun Web Server is automatically enabled. To access the default home page (Figure 5-1), point your browser to the following URL: http://yourdomain.com:8000/
Figure 5-1: JRun Embedded Web Server Default Home Page You may access a servlet (Figure 5-2) with the following URL: http://yourdomain.com:8000/servlet/SnoopServlet
56
Figure 5-2: Invoking SnoopServlet through the JRun Web Server The next section, Developing Custom Services Under JRun, provides more detail on running servlets. The default documents directory for the JRun Web Server is jsmdefault/services/jws/htdocs. You may alter this directory using the JRun Admin application.
Developing Custom Services Under JRun

JRun includes an API that allows the embedding of Java services under the JRun architecture. This tool relieves server developers from several tasks. The JRun Services Manager handles the thread management, process manipulation (start, stop, pause), and security for the services. In addition, under Windows NT, you do not need to write an installer to make the service an NT service. Becuase JRun is already running as a Windows service, the custom Java service will start and stop with JRun. For the Mac environment, the JRun Services API provides a unique opportunity for embedding services capabilities. Custom services can also be added to Novell Netware. Writing such services with the JRun API means that you do not need to rewrite anything to port the application to another platform. If it runs under JRun on one platform, it will run on others. To demonstrate the JRun Services API, we will develop a very simple HTTP daemon. Listing 5-1 is a very basic HTTP server written in Java. Keep in mind that this server is for demonstration purposes only and should never be used in a production setting without adding
57
the remainder of the HTTP protocol. In addition, this server has no security. Nevertheless, it makes a useful example of the JRun Services API. As shown in Listing 5-1, the code imports the JRun services API and implements the EndPointHandler interface. Next, the handleRequest() method provides a mechanism for running service-specific processing. The JRun Services API handles the socket creation and multi-threading. A socket is obtained through the tcpEndpointgetSocket() method, as shown in Listing 5-1. Listing 5-1: Simple HTTP Daemon
package serviceexamples.http; import java.util.*; import java.io.*; import java.net.*; import com.livesoftware.jrun.service.*; public class HttpServiceHandler implements EndpointHandler { public void init(NetworkService service, ServiceEndpoint sep) { } public void handleRequest (Endpoint x) throws IOException { TcpEndpoint tcpEndpoint = (TcpEndpoint) x; Socket sock = tcpEndpoint.getSocket (); PrintStream html; try { OutputStream out = sock.getOutputStream(); String req = new DataInputStream( sock.getInputStream() ).readLine(); html = new PrintStream(out); StringTokenizer st = new StringTokenizer( req ); if ( (st.countTokens() >= 2) && st.nextToken().equals("GET") ) { if ( (req = st.nextToken()).startsWith("/") ) req = req.substring( 1 ); if ( req.endsWith("/") || req.equals("") ) req = req + "index.html"; try { FileInputStream file = new FileInputStream ( req ); byte [] data = new byte [ file.available() ]; file.read( data ); out.write( data ); } catch ( FileNotFoundException e ) { new PrintStream( out ).println( "404 Not Found: Request: "+req ); } catch ( SecurityException e ) { html.println( "403 Forbidden Request: "+req ); } } else html.println( "400 Bad Request Request: "+req ); sock.close(); } catch ( IOException e ) { } sock.close(); } }
58
Now you need to compile the code. Keep in mind that you will need to add the jrun.jar file to your compiler CLASSPATH in order to compile it successfully. Once it is compiled, the s resulting HttpServiceHandler.class should be placed in the following directory:
<jrunroot>/classes/serviceexamples/http
Notice the directory structure follows the hierarchy of the package statement. Next, some property files must be created for the SimpleHttp service, and the JRun services property file needs to be changed to reflect the added service. First, create the following admin.properties file for the SimpleHttp service:
File: admin.properties # # JRunAdmin properties # ui.about=false # # Admin property panel list # # List panel names in the order that you would like them # loaded. # ui.panels=service,endpoint # # Admin property panel entries # # Usage: ui.panel.<Panel Name>=<Panel Class Name> # # Example: ui.panel.MyServer=com.company.MyServletAdminPanel # ui.panel.service=com.livesoftware.jrunadmin.plugins.JSPServicePanel ui.panel.endpoint=com.livesoftware.jrunadmin.plugins.JSPEndpointPanel
The admin.properties file provides a mechanism for customizing the administration tab for the HTTP service in the JRun administrator application.
59
Now create an endpoint.properties file:

File: endpoint.properties # # Service Endpoint Property File # #Sat Aug 29 14:50:44 PDT 1998 endpoint.main.max.threads=100 endpoint.main.interface=* endpoint.main.class=com.livesoftware.jrun.service.TcpServiceEndpoint endpoint.main.port=8080 endpoint.main.handler=serviceexamples.http.HttpServiceHandler endpoint.main.timeout=300 endpoint.main.min.threads=1 endpoint.main.bindaddress=*
Next, create a service.properties file for the HTTP service:

File: service.properties # # Service information # #Sat Aug 29 14:50:44 PDT 1998 service.vendor=Allaire Corporation service.class=com.livesoftware.jrun.service.NetworkService service.description=SimpleHttp Service service.version=1.0 service.name=SimpleHttp
Copy the three files that you created (admin.properties, endpoint.properties, and service.properties) into the following directory. (You may need to create the directory.)
<jrunroot>/jsm-default/properties/services/SimpleHttp
Notice the other JRun services property files in their respective directories? Finally, you must modify the JRun service.properties file as follows:
File: <jrunroot>/jsm-default/properties/service.properties # # # JRun Service Manager Property File # #Sat Feb 13 22:52:32 PST 1999 services=jse,jcp,jws,SimpleHttp services.inactive= jse.description=JRun Servlet Engine jws.description=JRun Web Server jcp.description=JRun Connector Proxy SimpleHttp.description=SimpleHttp
60
The next time that you start JRun, your SimpleHttp service will handle requests on port 8080. To change the port, launch the JRun administrator and select jsm-defaultSimpleHttp General ConfigEndpoint Settings. If you used the code provided in Listing 5-1, the likely response from a request to http://locahost:8080 was 404 Not Found. You will need to add code to direct the service to read from the correct directory. If you want to verify that the server works, you may hard code a directory by prepending your webroot directory (including trailing slash) to the req variable. For example:
try { req = c:/inetpub/wwwroot/+req; FileInputStream file = new FileInputStream ( req ); .
For more information on the JRun Services API, see Appendix B, Other Resources, or browse the javadocs included in the JRun download.
Editing Thread Parameters

JRun uses the Java threading mechanism to handle concurrent requests. Instead of creating a new thread for each request, it maintains a pool of threads that are ready for new requests. This pool of handler threads can grow and shrink as varying demands are placed on the server. The optimal parameters for the pool must strike a balance between traffic load and the capabilities of the server. The following parameters are available for editing in the JRun Administrator for the JRun Connector Proxy (JCP) and the JRun Web Server (JWS). You may also edit these parameters manually by editing the endpoint.properties file. For example, the JCP endpoint settings are located in <jrun>/jsm-default/properties/services/jcp/endpoint.properties . Minimum Handler Threads (endpoint.main.min.threads): When JRun starts up, an initial pool of handler threads is created. As the system runs, threads are created and destroyed; however, the pool size will never drop below this minimum number. Active Handler Threads (endpoint.main.active.threads): This parameter places an upper limit on the number of concurrent requests that JRun will handle. Any requests that arrive beyond this limit will be delayed until a handler thread is available to service them. This parameter is JRun primary mechanism for limiting concurrency. s Maximum Handler Threads (endpoint.main.max.threads): This parameter is the upper limit on the number of requests that the server can handle. Beyond this limit, one or more resources will be exhausted, and the server performance will degrade beyond acceptable s limits. Any requests that arrive beyond this absolute maximum will be quickly dropped. Handler Thread Idle Timeout (endpoint.main.timeout): When handler threads become idle for this number of seconds, they will be destroyed. This parameter determines how quickly the server returns to a quiescent state after a busy period.
61
Monitor Interval (endpoint.main.monitor): JRun includes a simple monitoring mechanism that enables the system administrator to track system load. This mechanism is helpful for determining reasonable settings for the handler thread pool. Each time that the interval expires, JRun prints out a line similar to the following:
Jcp: 3/10 threads busy, 8 peak. 55/91 requests delayed, 0 dropped. !
Reading from left to right, here is how to interpret the numbers: At the end of the monitor interval, 3 threads were busy out of a pool of 10 threads. During the interval, we peaked at 8 concurrent requests, which exceeded our active limit (5). Although we still processed 91 requests, 55 of them were delayed. No more than 5 at any one time were handled simultaneously. JRun adds an extra ! to indicate that some requests were delayed. The following is an example from a system under heavy stress:
Jws: 82/500 threads busy, 500 peak. 1345/1345 requests delayed, 2455 dropped. !!
In this case, the system reached its active limit and began queuing requests. The number of requests continued to increase until reaching the maximum handler thread limit of 500. 1,345 requests were delayed prior to being serviced, and 2,455 additional requests were dropped.
62
Appendix
Contacting Technical Support

Allaire offers several forms of technical support for JRun: Telephone-based support until the first successful installation FAQs Mailing Lists Bug Report Form
For additional information on these technical support services, visit Allaire Product s Support Center:
http://www.allaire.com/support
63
B
Other Resources
Java Servlet Books: Online Resources: JRun Magazine (http://www.jrunmag.com) Servlet Central (http://www.servletcentral.com)
Appendix
You may wish to consult the following resources for more detailed information on topics covered in this document:
Java Servlets by Karl Moss, published by McGraw Hill, 1998, ISBN: 0079137792 Java Servlets: By Example by Alan R. Williamson, published by Manning Publications, 1998, ISBN: 188477766X Java Servlet Programming by Jason Hunter and William Crawford, published by O'Reilly & Associates, 1998, ISBN: 156592391X
64

Java JRun

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Java JRun

Uploaded by

Copyright:

Available Formats

JRun User s Manual

JRun User Manual s

Introduction to Servlets .................................................................................................. 6

Servlet Tutorial .............................................................................................................. 8

Common JRun Tasks ................................................................................................... 55

Contacting Technical Support ..................................................................................... 63 Other Resources ........................................................................................................... 64

List of Figures, Tables, and Listings

JRun User Guide s Version 2.3.3

Comparing Client-Side Java and Server-Side Java

JRun User Guide s Version 2.3.3

Server Component Model

JRun User Guide s Version 2.3.3

Relationship to the Web Server

Figure 1-1: JRun Architecture

JRun User Guide s Version 2.3.3

JRun Servlet Runner

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

Extending Web Servers with Servlets

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

Starting the JRun Admin Application

Figure 4-2: JRun Administrator Window: JRun Service Manager Tab

Selecting a JSM to Configure

Figure 4-3: JSM Configuration Window: Services Tab

JRun User Guide s Version 2.3.3

Selecting a Service to Configure

JRun Servlet Engine (JWS)

JRun User Guide s Version 2.3.3

Configuring General Settings for a Service

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

Configuring Service Settings for a Service

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

Related property file:

Mappings Tab: Prefix and Suffix Mappings

JRun User Guide s Version 2.3.3

Mappings Tab: Servlet Chaining

JRun User Guide s Version 2.3.3

JRun User Guide s Version 2.3.3

Figure 4-13: Init Args Editor Window

Related property file:

JRun User Guide s Version 2.3.3

Mime Filters Tab

JRun User Guide s Version 2.3.3

Multi Home Tab

Servlet Dir Logging Dir

Related property file:

JRun User Guide s Version 2.3.3

Session Tracking Tab

Invalidation Time Invalidation Interval

Session Storage Dir

Page Compilation Tab

D:\jdk1.1.7b\bin\javac -nowarn -classpath %c -d %d %f

JRun User Guide s Version 2.3.3