JIIP: A Java IIP Server | Installation Guide

Prerequisites

This guide assumes you have already installed and configured a web server and servlet engine that uses Java 2. In addition, you have already downloaded the current JIIP distribution.

1. Unpack the distribution

UNIX:
    cd BASE_DIR
    gzip -cdf jiip.tar.gz | tar -xf - 

Windows:
    cd BASE_DIR
    unzip jiip.zip

Unpacking creates the directory BASE_DIR/jiip-VERSION, which I'll call the JIIP install directory or

INSTALL_DIR.

2. Add the JIIP class archive to the servlet engine's CLASSPATH

The iip.jar file in an archive of all the JIIP classes.

UNIX:
    INSTALL_DIR/lib/iip.jar
Windows:
    INSTALL_DIR\lib\iip.jar

This file needs to be added to your servlet engine's CLASSPATH. Or, if you have compiled JIIP from source, your CLASSPATH entry will be the root directory of the source tree:

UNIX:
    INSTALL_DIR/src/classes
Windows:
    INSTALL_DIR\src\classes

Servlet engines have different methods for adding CLASSPATH entries, so you'll need to check your servlet engine's documentation for instructions.

Apache tip: Apache JServ gets its CLASSPATH from the main Apache configuration file, usually named httpd.conf. Find the section of httpd.conf with lots of entries that start with Servlet. Add a ServletClassPath entry to point to the JIIP archive.

  ServletClassPath   INSTALL_DIR/lib/iip.jar

These httpd.conf entries don't need to be changed, but I'll refer to the their values later in the instructions:

  ServletProperties  SERVLET_PROPERTIES
  ServletAlias       SERVLET_ALIAS   path
  ServletBinary      path-to-java

These are entries from a typical installation:

  ServletClassPath   /usr/local/jiip-1.0a/lib/iip.jar
  ServletProperties  properties/localhost.properties
  ServletAlias       /servlets  /usr/local/apache/jserv/servlets
  ServletBinary      /usr/local/java1.2/bin/javac

Make sure that the ServletBinary directive points to a java 1.2 interpreter. If you're switching from JDK1.1 to 1.2 at the same time you're installing JIIP, comment out the line that adds classes.zip to the servlet classpath. The java 1.2 interpreter doesn't need it:

  # Comment out this line for JDK1.2
  ServletClassPath   JAVA1.1_INSTALL_DIRECTORY/lib/classes.zip

3. Set the initialization arguments for the JIIP servlet

Servlet engines typically configure individual servlets through a .properties file. The location of this file -- or a UI for manipulating it -- differs across servlet engines, so check your servlet engine's documentation for details.

Apache tip: The ServletProperties directive in httpd.conf sets the location of the properties file you need to edit. If you previously installed JServ without setting ServletProperties, you can set one now and create the properties file from scratch.

The properties file needs two entries for the JIIP servlet:

An alias or nickname for the class org.dig.iip.IIPServlet.
This nickname will be part of the URL IIP clients use to talk to the server.

The initialization arguments to pass to the servlet when it is first created. The JIIP servlet takes 3 arguments:

Name Value

propFile full pathname to the iip.properties file

imageRoot full pathname of the image repository

logLevel level of logging to perform
Possible values: none, error, info, debug, all

Notes
You'll find the iip.properties file in the INSTALL_DIR. You can move or rename this file, as long as propFile points to the new location.
The image respository is where JIIP will look for images. In IIP talk, this is the directory against which paths in FIF requests are resolved. For example, a request for FIF=image.jpg will map to the file imageRoot/image.jpg. The image repository will typically be the same as the web server's document root.
Log messages are written to the JVM's System.err, which the servlet engine typically sends to a log file. logLevel is an optional property: the default level is error.

A UNIX Example

Here are the properties file entries that set up IIP as the nickname for the servlet and use INSTALL_DIR/samples/images as the image repository:

servlet.IIP.code=org.dig.iip.IIPServlet servlet.IIP.initArgs=propFile=/opt/jiip-0.9/iip.properties,\ imageRoot=/opt/jiip-0.9/samples/images,\ logLevel=debug

A Windows Example

Note that a literal '\' needs to be escaped as '\\'!

servlet.IIP.code=org.dig.iip.IIPServlet servlet.IIP.initArgs=propFile=\\jiip-1.0a\\iip.properties,\ imageRoot=\\jiip-1.0a\\samples\\images,\ logLevel=debug

Name		Value
`propFile`		full pathname to the iip.properties file
`imageRoot`		full pathname of the image repository
`logLevel`		level of logging to perform Possible values: `none, error, info, debug, all`
Notes
You'll find the iip.properties file in the INSTALL_DIR. You can move or rename this file, as long as `propFile` points to the new location.
The image respository is where JIIP will look for images. In IIP talk, this is the directory against which paths in FIF requests are resolved. For example, a request for `FIF=image.jpg` will map to the file imageRoot/image.jpg. The image repository will typically be the same as the web server's document root.
Log messages are written to the JVM's `System.err`, which the servlet engine typically sends to a log file. `logLevel` is an optional property: the default level is `error`.
A UNIX Example
Here are the properties file entries that set up `IIP` as the nickname for the servlet and use INSTALL_DIR/samples/images as the image repository: servlet.IIP.code=org.dig.iip.IIPServlet servlet.IIP.initArgs=propFile=/opt/jiip-0.9/iip.properties,\ imageRoot=/opt/jiip-0.9/samples/images,\ logLevel=debug
A Windows Example
Note that a literal '`\`' needs to be escaped as '`\\'`! servlet.IIP.code=org.dig.iip.IIPServlet servlet.IIP.initArgs=propFile=\\jiip-1.0a\\iip.properties,\ imageRoot=\\jiip-1.0a\\samples\\images,\ logLevel=debug

4. Test the installation

The exact URL for invoking the IIP servlet depends (again) on how your servlet engine and web server are tied together. It's typically something like:

   http://YOUR_SERVER/SERVLET_ALIAS/JIIP_SERVLET_NICKNAME

SERVLET_ALIAS		the name signalling to the web server that the rest of the URI names a servlet.
		A SERVLET_ALIAS is just one way of marking servlets: your web server/servlet engine may have a different method. In Apache JServ, the alias is set by the directive ... `ServletAlias`.
IIP_SERVLET_NICKNAME		the nickname you gave `org.dig.iip.IIPServlet` in the servlet properties file.

Invoking the servlet without any arguments should give an HTTP response of mime type application/vnd.netfpx:

Content-type: application/vnd.netfpx

IIP:1.0
Error/93:3 1 none Missing required command OBJ=IIP,<version>

Check your web server and servlet engine's error log file(s) for clues if the response is different. The ServletProperties directive in httpd.conf sets the location of the properties file you need to edit. If you previously installed JServ without setting ServletProperties, set one now and create the properties file from scratch. iiptalk is a command line tool that sends groups of commands directly to the IIP engine, bypassing the HTTP servlet interface. It is included as a simple development tool for testing the installation or running regression tests against the engine.

It's a bourne shell script (UNIX) or batch file (Windows) that runs a Java application. The script expects these files to be where they were originally unpacked:

INSTALL_DIR/lib/iip.jar
INSTALL_DIR/samples/images - where iiptalk looks for images 
INSTALL_DIR/iip.properties

Edit the script to suit your needs!

To invoke it, be sure you've got a JDK1.2 interpreter (java) in your PATH, then:

UNIX:
    unix%  cd INSTALL_DIR
    unix%  chmod u+x ./bin/iiptalk
    unix% ./bin/iiptalk 

Windows (MS-DOS):
    dos>  cd INSTALL_DIR\bin
    dos>  .\iiptalk.bat

Run without an argument, iiptalk reads lines of IIP commands from standard input. Each line of input is an independent set of IIP commands: commands are separated by a space and are not url-encoded.

HTTP GET Request:    
     OBJ=IIP,1.0&FIF=jack%2Bjill.jpg
Equivalent iiptalk input:       
     OBJ=IIP,1.0 FIF=jack+jill.jpg

iiptalk can also take IIP commands from a file instead of reading from standard input. Just run iiptalk with the data file as the sole argument. INSTALL_DIR/samples/iiptalk.data is an example of a file of IIP data.

Installing and Configuring JIIP

Prerequisites

1. Unpack the distribution

2. Add the JIIP class archive to the servlet engine's CLASSPATH

3. Set the initialization arguments for the JIIP servlet

4. Test the installation

Using iiptalk