org.apache.river.tool

Class ClassServer

java.lang.Object

java.lang.Thread

org.apache.river.tool.ClassServer

All Implemented Interfaces:

Runnable, Startable

public class ClassServer
extends Thread
implements Startable

A simple HTTP server, for serving up JAR and class files.

The following items are discussed below:

• Command line options
• Logging
• Examples for running ClassServer

Logging

This implementation uses the Logger named org.apache.river.tool.ClassServer to log information at the following logging levels:

org.apache.river.tool.ClassServer

Level	Description
SEVERE	failure to accept an incoming connection
WARNING	failure to read the contents of a requested file, failure to find the message resource bundle, failure while executing the -stop option
INFO	server startup and termination
CONFIG	the JAR files being used for -trees
HANDLED	failure reading an HTTP request or writing a response
FINE	bad HTTP requests, HTTP requests for nonexistent files
FINER	good HTTP requests

Examples for running ClassServer

This server can be run directly from the command line or as a nonactivatable service under the ServiceStarter.

An example of running directly from the command line is:

 % java -jar install_dir/lib/classserver.jar \
        -port 8081 -dir install_dir/lib-dl -verbose
 

where install_dir is the directory where the Apache River release is installed. This command places the class server on the (non-default) port 8081, which serves out the files under the (non-default) directory install_dir/lib-dl. The -verbose option also causes download attempts to be logged.

An example of running under the Service Starter is:

 % java -Djava.security.policy=start_policy \
        -jar install_dir/lib/start.jar \
        httpd.config
 

where start_policy is the name of a security policy file (not provided), and httpd.config is the following configuration file:

 import org.apache.river.start.NonActivatableServiceDescriptor;
 import org.apache.river.start.ServiceDescriptor;
 
 org.apache.river.start {
 
   serviceDescriptors = new ServiceDescriptor[]{
     new NonActivatableServiceDescriptor(
       "",
       "httpd_policy",
       "install_dir/lib/classserver.jar",
       "org.apache.river.tool.ClassServer",
       new String[]{"-port", "8081", "-dir", "install_dir/lib-dl", "-verbose"})
     };
 }
 

where httpd_policy is the name of a security policy file (not provided).

Author:

Sun Microsystems, Inc.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
ClassServer(int port, String dirlist, boolean trees, boolean verbose) Construct a server that does not support network shutdown.
ClassServer(int port, String dirlist, boolean trees, boolean verbose, boolean stoppable) Construct a server.
ClassServer(String[] args, LifeCycle lifeCycle) Construct a server, accepting the same command line options supported by main, except for the -stop option.

Method Summary

Modifier and Type	Method and Description
protected void	fileDownloaded(String fp, InetAddress addr) This method provides a way for subclasses to be notified when a file has been completely downloaded.
int	getPort() Returns the port on which this server is listening.
static void	main(String[] args) Command line interface for creating an HTTP server.
void	run() Just keep looping, spawning a new thread for each incoming request.
void	terminate() Close the server socket, causing the thread to terminate.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.river.api.util.Startable

start

Constructor Detail

ClassServer

public ClassServer(int port,
                   String dirlist,
                   boolean trees,
                   boolean verbose)
            throws IOException

Construct a server that does not support network shutdown. Use the start method to run it.

Parameters:

port - the port to use

dirlist - the list of directories to serve files from, with entries separated by the path-separator character

trees - true if files within JAR files should be served up

verbose - true if downloads should be logged

Throws:

IOException - if the server socket cannot be created

NullPointerException - if dir is null

ClassServer

public ClassServer(int port,
                   String dirlist,
                   boolean trees,
                   boolean verbose,
                   boolean stoppable)
            throws IOException

Construct a server. Use the start method to run it.

Parameters:

port - the port to use

dirlist - the list of directories to serve files from, with entries separated by the path-separator character

trees - true if files within JAR files should be served up

verbose - true if downloads should be logged

stoppable - true if network shutdown from the local host should be supported

Throws:

IOException - if the server socket cannot be created

NullPointerException - if dir is null

ClassServer

public ClassServer(String[] args,
                   LifeCycle lifeCycle)
            throws IOException

Construct a server, accepting the same command line options supported by main, except for the -stop option. If constructed by ServiceStarter, Commission#start() , is called automatically, otherwise Thread.start() must be called manually after construction.

Parameters:

args - command line options

lifeCycle - life cycle control object, or null

Throws:

IOException - if the server socket cannot be created

IllegalArgumentException - if a command line option is not understood

NullPointerException - if args or any element of args is null

See Also:

Startable

Method Detail

run

public void run()

Just keep looping, spawning a new thread for each incoming request.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

terminate

public void terminate()

Close the server socket, causing the thread to terminate.

getPort

public int getPort()

Returns the port on which this server is listening.

fileDownloaded

protected void fileDownloaded(String fp,
                              InetAddress addr)

This method provides a way for subclasses to be notified when a file has been completely downloaded.

Parameters:

fp - The path to the file that was downloaded.

main

public static void main(String[] args)

Command line interface for creating an HTTP server. The command line options are:

 [-port port] [-dir dirlist] [-dirs dirlist] [-stoppable] [-verbose] [-trees]
 

The default port is 8080; the default can be overridden with the -port option. The default directory on Windows is J: and the default on other systems is /vob/jive/lib-dl; the default can be overridden with the -dir or -dirs option, providing one or more directories separated by the path-separator character. All files under these directories (including all subdirectories) are served up via HTTP. If the pathname of a file is path relative to one of the top-level directories, then the file can be downloaded using the URL

 http://host:port/path
 

If a relative path matches a file under more than one top-level directory, the file under the first top-level directory with a match is used. No caching of directory contents or file contents is performed.

If the -stoppable option is given, the HTTP server can be shut down with a custom HTTP SHUTDOWN request originating from the local host. The command line options for stopping an existing HTTP server are:

 [-port port] -stop
 

If the -verbose option is given, then all attempts to download files are output.

The -trees option can be used to serve up individual files stored within JAR and zip files in addition to the files that are served up as described above. If the option is used, the server finds all JAR and zip files in the top-level directories (not in subdirectories). If the name of the JAR or zip file is name.jar or name.zip, then any individual file named file within it (or within the JAR or zip files referenced transitively in Class-Path manifest attributes), can be downloaded using a URL of the form:

 http://host:port/name/file
 

If multiple top-level directories have JAR or zip files with the same name, the file under the first top-level directory with a match is used. If a Class-Path element matches a file under more than one top-level directory, the file under the first top-level directory with a match is used. When this option is used, an open file descriptor and cached information is held for each JAR or zip file, for the life of the process.