1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
\r
5 Integrating FastCGI with Java
\r
7 <STYLE TYPE="text/css">
\r
9 background-color: #FFFFFF;
\r
12 :link { color: #cc0000 }
\r
13 :visited { color: #555555 }
\r
14 :active { color: #000011 }
\r
15 dt.c4 {font-style: italic}
\r
16 h5.c3 {text-align: center}
\r
17 p.c2 {text-align: center}
\r
18 div.c1 {text-align: center}
\r
23 <A HREF="http://fastcgi.com"><IMG BORDER="0" SRC="../images/fcgi-hd.gif" ALT="[[FastCGI]]"></A>
\r
28 Integrating FastCGI with Java
\r
31 <!--Copyright (c) 1996 Open Market, Inc. -->
\r
32 <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
\r
33 <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES. -->
\r
34 <!-- $Id: fcgi-java.htm,v 1.3 2001/11/27 01:03:47 robs Exp $ -->
\r
37 Open Market, Inc.<BR>
\r
41 Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.<BR>
\r
42 Tel: 617-621-9500 Fax: 617-621-1703 URL: <A HREF=
\r
43 "http://www.openmarket.com/">http://www.openmarket.com/</A><BR>
\r
47 <A NAME="S1">1. Introduction</A>
\r
50 Java is an object-oriented programming language developed by Sun Microsystems. The Java Depvelopers Kit (JDK),
\r
51 which contains the basic Java class packages, is available from Sun in both source and binary forms at
\r
52 Sun's <A HREF="http://java.sun.com/java.sun.com/JDK-1.0/index.html">JavaSoft</A> site. This document
\r
53 assumes that you have some familiarity with the basics of compiling and running Java programs.
\r
56 There are two kinds of applications built using Java.
\r
60 <I>Java Applets</I> are graphical components which are run off HTML pages via the <TT><APPLET></TT>
\r
61 HTML extention tag.<BR>
\r
65 <I>Java Applications (Apps)</I> are stand-alone programs that are run by invoking the Java interpreter
\r
66 directly. Like C programs, they have a <TT>main()</TT> method which the interpreter uses as an entry point.
\r
70 The initial emphasis on using Java for client side applets should not obscure the fact that Java is a full
\r
71 strength programming language which can be used to develop server side stand alone applications, including CGI
\r
72 and now FastCGI applications.
\r
75 The remainder of this document explains how to write and run FastCGI Java applications. It also illustrates
\r
76 the conversion of a sample Java CGI program to a FastCGI program.
\r
79 <A NAME="S2">2. Writing FastCGI applications in Java</A>
\r
82 Writing a FastCGI application in Java is as simple as writing one in C.
\r
86 Import the <TT>FCGIInterface</TT> class.
\r
89 Perform one-time initialization at the top of the <TT>main()</TT> method.
\r
92 Create a new <TT>FCGIInterface</TT> object and send it an <TT>FCGIaccept()</TT> message in a loop.
\r
95 Put the per-request application code inside that loop.
\r
99 On return from <TT>FCGIaccept()</TT> you can access the request's environment variables using
\r
100 <TT>System.getProperty</TT> and perform request-related I/O through the standard variables <TT>System.in</TT>,
\r
101 <TT>System.out</TT>, and <TT>System.err</TT>.
\r
104 To illustrate these points, the kit includes <TT>examples/TinyCGI</TT>, a CGI Java application, and
\r
105 <TT>examples/TinyFCGI</TT>, the FastCGI version of TinyCGI. These programs perform the same functions as the C
\r
106 programs <TT>examples/tiny-cgi.c</TT> and <TT>examples/tiny-fcgi.c</TT> that are used as examples in the <A
\r
107 HREF="fcgi-devel-kit.htm#S3.1.1">FastCGI Developer's Kit document</A>.
\r
115 public static void main (String args[]) {
\r
118 System.out.println("Content-type: text/html\n\n");
\r
119 System.out.println("<html>");
\r
120 System.out.println(
\r
121 "<head><TITLE>CGI Hello</TITLE></head>");
\r
122 System.out.println("<body>");
\r
123 System.out.println("<H3>CGI-Hello</H3>");
\r
124 System.out.println("request number " + count +
\r
125 " running on host "
\r
126 + System.getProperty<"SERVER_NAME"));
\r
127 System.out.println("</body>");
\r
128 System.out.println("</html>");
\r
138 import FCGIInterface;
\r
141 public static void main (String args[]) {
\r
143 while(new FCGIInterface().FCGIaccept()>= 0) {
\r
145 System.out.println("Content-type: text/html\n\n");
\r
146 System.out.println("<html>");
\r
147 System.out.println(
\r
148 "<head><TITLE>FastCGI-Hello Java stdio</TITLE></head>");
\r
149 System.out.println("<body>");
\r
150 System.out.println("<H3>FastCGI-HelloJava stdio</H3>");
\r
151 System.out.println("request number " + count +
\r
152 " running on host "
\r
153 + System.getProperty<"SERVER_NAME"));
\r
154 System.out.println("</body>");
\r
155 System.out.println("</html>");
\r
162 C. Running these Examples
\r
165 We assume that you have downloaded the JDK and the FastCGI Developer's Kit, and that you have a Web server
\r
166 running that can access the <TT>fcgi-devel-kit/examples</TT> directory. In all cases where we specify paths,
\r
167 we are using relative paths within <TT>fcgi-devel-kit</TT> or the JDK which will need to be enlarged to a full
\r
175 Add your JDK's <TT>java/bin</TT> directory to your Unix <TT>PATH</TT> if it isn't there
\r
180 Add the directories <TT>fcgi-devel-kit/examples</TT> and <TT>fcgi-devel-kit/java/classes</TT> to your Java
\r
181 <TT>CLASSPATH</TT>.<BR>
\r
185 In your Open Market Secure WebServer configuration file, <TT>httpd.config</TT>, add the following two
\r
188 <TT>ExternalAppClass TinyFCGI -host</TT> <I>hostName:portNum</I><BR>
\r
189 <TT>Responder TinyFCGI fcgi-devel-kit/examples/TinyFCGI</TT><BR>
\r
194 <I>hostName</I> is the name of your host machine.<BR>
\r
197 <I>portNum</I> is the port that you've selected for communication between the Web server and the
\r
198 Java application.<BR>
\r
202 On other servers you can use <TT>cgi-fcgi</TT> to get a similar effect.
\r
205 Create a soft link <TT>examples/javexe</TT> to the <TT>java/bin</TT> directory in your JDK. This link is
\r
206 required only to run the CGI scripts <TT>examples/TinyCGI.cgi</TT> and <TT>examples/TinyFCGI.cgi</TT>,
\r
207 which use it to invoke the Java interpreter <TT>java/bin/java</TT>. It is not used by FastCGI applications.
\r
210 You might have to modify <TT>examples/TinyFCGI.cgi</TT> to use a Unix shell for which your CLASSPATH is
\r
219 To run TinyFCGI as FastCGI, you invoke the Java interpreter with the -D option, giving it the
\r
220 <TT>FCGI_PORT</TT> environment variable and the same <I>portNum</I> that was used in the Web server
\r
221 configuration. The command is:<BR>
\r
223 <TT>java -DFCGI_PORT=portNum TinyFCGI</TT><BR>
\r
225 Then point your browser at <TT>fcgi-devel-kit/examples/TinyFCGI</TT>. Notice that each time you reload,
\r
226 the count increments.<BR>
\r
230 To run TinyCGI, point your browser at <TT>fcgi-devel-kit/examples/TinyCGI.cgi</TT> on your host machine.
\r
231 Notice that the count does not increment.<BR>
\r
235 Finally, you can run TinyFCGI as a straight CGI program by pointing your browser at
\r
236 <TT>fcgi-devel-kit/examplesi/TinyFCGI.cgi.</TT> The results are exactly the same as when you ran TinyCGI.
\r
237 Invoking a FastCGI program without an <TT>FCGI_PORT</TT> parameter tells the FastCGI interface to leave the
\r
238 normal CGI environment in place.
\r
242 Due to gaps in the Java interpreter's support for listening sockets, Java FastCGI applications are
\r
243 currently limited to being started as external applications. They can't be started and managed by the Web
\r
244 server because they are incapable of using a listening socket that the Web server creates.
\r
247 <A NAME="S3">3. Standard I/O and Application Libraries</A>
\r
250 As we have seen above, FastCGI for Java offers a redefinition of standard I/O corresponding to the the
\r
251 <I>fcgi_stdio</I> functionality. It also offers a set of directly callable I/O methods corresponding to the
\r
252 <I>fcgiapp</I> C library. To understand where these methods occur we need to look briefly at the FastCGI
\r
253 redefinition of standard I/O.
\r
256 Java defines standard I/O in the <I>java.System</I> class as follows:
\r
259 public static InputStream in = new BufferedInputStream(new FileInputStream(FileDescriptor.in), 128);<BR>
\r
260 public static PrintStream out = new PrintStream(new BufferedOutputStream(new
\r
261 FileOutputStream(FileDescriptor.out), 128), true);<BR>
\r
262 public static PrintStream err = new PrintStream(new BufferedOutputStream(new
\r
263 FileOutputStream(FileDescriptor.err), 128), true);
\r
266 The File Descriptors <I>in</I>, <I>out</I>, <I>err</I> are constants set to 0, 1 and 2 respectively.
\r
269 The FastCGI interface redefines <I>java.System in, out</I>, and <I>err</I> by replacing the File streams with
\r
270 Socket streams and inserting streams which know how to manage the FastCGI protocol between the Socket streams
\r
271 and the Buffered streams in the above definitions.
\r
274 For those cases where the FCGI application needs to bypass the standard I/O streams, it can directly access
\r
275 the methods of the FCGI input and output streams which roughly correspond to the functions in the C
\r
276 <I>fcgiapp</I> library. These streams can be accessed via the <I>request</I> class variable in FCGIInterface.
\r
277 Each Request object has instance variables that refer to an FCGIInputStream, and to two FCGIOutputStreams
\r
278 associated with that request.
\r
281 <A NAME="S4">4. Environment Variables</A>
\r
284 Java does not use the C <I>environ</I> list. Nor is there a <I>getenv</I> command that reads system
\r
285 environment variables. This is intentional for reasons of portability and security. Java has an internal
\r
286 dictionary of properties which belongs to the System class. These System properties are <I>name/value</I>
\r
287 associations that constitute the Java environment. When a Java application starts up, it reads in a file with
\r
288 default properties. As we have seen, additional System properties may be inserted by using the -D <I>Java</I>
\r
292 For CGI, where the Java application is invoked from a .cgi script that, in turn, invokes the Java interpreter,
\r
293 this script could read the environment and pass the variables to the Java application either by writing a file
\r
294 or by creating -D options on the fly. Both of these methods are somewhat awkward.
\r
297 For FastCGI Java applications, the environment variables are obtained from the FastCGI web server via
\r
298 <TT>FCGI_PARAMS</TT> records that are sent to the application at the start of each request. The FastCGI
\r
299 interface stores the original startup properties, combines these with the properties obtained from the server,
\r
300 and puts the new set of properties in the System properties dictionary. The only parameter that has to be
\r
301 specifically added at startup time is the FCGI_PORT parameter for the Socket creation. In the future, we
\r
302 expect that even this parameter won't be needed, since its use is due to an acknowledged rigidity in the
\r
303 JDK's implementation of sockets.
\r
308 <A NAME="S4">5. Further examples: EchoFCGI and Echo2FCGI</A>
\r
311 The next two examples illustrate the points made in the last two sections. EchoFCGI and Echo2FCGI both echo
\r
312 user input and display the application's environment variables. EchoFCGI reads the user input from
\r
313 System.in, while Echo2FCGI reads the user input directly from the intermediate FastCGI input stream.
\r
319 import FCGIInterface;
\r
320 import FCGIGlobalDefs;
\r
325 public static void main (String args[]) {
\r
327 while(new FCGIInterface().FCGIaccept()>= 0) {
\r
328 System.out.println("Content-type: text/html\n\n");
\r
329 System.out.println("<html>");
\r
330 System.out.println(
\r
331 "<head%gt;<TITLE>FastCGI echo
\r
332 </TITLE></head>");
\r
333 System.out.println("<body>");
\r
334 System.out.println(
\r
335 "<H2>FastCGI echo</H2>");
\r
336 System.out.println("<H3>STDIN</H3>");
\r
337 for ( int c = 0; c != -1; ) {
\r
339 c = System.in.read();
\r
340 } catch(IOException e) {
\r
341 System.out.println(
\r
342 "<br><b>SYSTEM EXCEPTION");
\r
343 Runtime rt = Runtime.getRuntime();
\r
347 System.out.print((char)c);
\r
350 System.out.println(
\r
351 "<H3>Environment Variables:</H3>");
\r
353 System.getProperties().list(System.out);
\r
354 System.out.println("</body>");
\r
355 System.out.println("</html>");
\r
364 import FCGIInterface;
\r
365 import FCGIGlobalDefs;
\r
366 import FCGIInputStream;
\r
367 import FCGIOutputStream;
\r
368 import FCGIMessage;
\r
369 import FCGIRequest;
\r
374 public static void main (String args[]) {
\r
376 FCGIInterface intf = new FCGIInterface();
\r
377 while(intf.FCGIaccept()>= 0) {
\r
378 System.out.println("Content-type: text/html\n\n");
\r
379 System.out.println("<html>");
\r
380 System.out.println(
\r
381 "<head><TITLE>FastCGI echo
\r
382 </TITLE></head>");
\r
383 System.out.println("<body>");
\r
384 System.out.println("<H2>FastCGI echo</H2>");
\r
385 System.out.println("<H3>STDIN:</H3">);
\r
386 for ( int c = 0; c != -1; ) {
\r
388 c = intf.request.inStream.read();
\r
389 } catch(IOException e) {
\r
390 System.out.println(
\r
391 "<br><b>SYSTEM EXCEPTION");
\r
392 Runtime rt = Runtime.getRuntime();
\r
396 System.out.print((char)c);
\r
399 System.out.println(
\r
400 "<H3>Environment Variables:</H3>");
\r
402 System.getProperties().list(System.out);
\r
403 System.out.println(<"/body>");
\r
404 System.out.println("</html>");
\r
410 C. Running these Examples
\r
416 As with TinyFCGI, you need to configure the web server to recognize these two FastCGI applications. Your
\r
417 configuration now looks like this:
\r
422 ExternalAppClass java1 -host hostname:portNum
\r
423 Responder java1 fcgi-devel-kit/examples/TinyFCGI
\r
424 ExternalAppClass java2 -host hostname:portNumA
\r
425 Responder java2 fcgi-devel-kit/examples/EchoFCGI
\r
426 ExternalAppClass java3 -host hostname:porNumB
\r
427 Responder java3 fcgi-devel-kit/examples/Echo2FCGI
\r
430 Note that the application classes and port numbers are different for each application.
\r
436 As with TinyFCGI, you need to run these programs with the -D option using FCGI_PORT and the appropriate port
\r
437 number. To get some data for standard input we have created two html pages with forms that use a POST method.
\r
438 These are echo.html and echo2.html. You must edit these .html files to expand the path to
\r
439 <I>fcgi-devel-kit/examples</I> to a full path. Once the appropriate Java program is running, point your
\r
440 browser at the corresponding HTML page, enter some data and select the <I>go_find</I> button.
\r
443 <A NAME="S6">6. FastCGI Java Classes</A>
\r
446 The Java FastCGI classes are included in both source and byte code format in <I>fcgi-devel-kit/java/src</I>
\r
447 and :<I>fcgi-devel-kit/java/classes</I> respectively. The following is a brief description of these classes:
\r
456 This class contains the FCGIaccept method called by the FastCGI user application. This method sets up the
\r
457 appropriate FastCGI environment for communication with the web server and manages FastCGI requests.<BR>
\r
463 This input stream manages FastCGI internal buffers to ensure that the user gets all of the FastCGI messages
\r
464 associated with a request. It uses FCGIMessage objects to interpret these incoming messages.<BR>
\r
470 This output stream manages FastCGI internal buffers to send user data back to the web server and to notify
\r
471 the server of various FCGI protocol conditions. It uses FCGIMessage objects to format outgoing FastCGI
\r
478 This is the only class that understands the actual structure of the FastCGI messages. It interprets
\r
479 incoming FastCGI records and constructs outgoing ones..<BR>
\r
485 This class currently contains data fields used by FastCGI to manage user requests. In a multi-threaded
\r
486 version of FastCGI, the role of this class will be expanded.<BR>
\r
492 This class contains definitions of FastCGI constants.
\r
497 <A HREF="mailto:harris@openmarket.com">Steve Harris // harris@openmarket.com</A>
\r
projects / catagits/fcgi2.git / blob