org.w3c.jigsaw.http
Class Client

java.lang.Object
  extended by org.w3c.jigsaw.http.Client
All Implemented Interfaces:
EventHandler
Direct Known Subclasses:
MuxClient, SocketClient

public abstract class Client
extends java.lang.Object
implements EventHandler

Client instances keep track of a specific connection with a browser. This abstract class is responsible for handling an HTTP connection, as described by an input and output stream, from right after the connection is accepted, until the connection has to be shutdown. It provides all the methods to run the HTTP dialog, and leave it to subclasses to implement the accept connection and the persistent connections strategy.

Customizing this class is done by subclassing it, and implementing the abstract methods.

For sample implementations, you can check the socket and mux sub packages.

See Also:
ClientFactory, SocketClient, MuxClient

Field Summary
protected  byte[] buffer
          The buffer used to emit copy data back to the client.
protected  boolean cont
          flags to avoid multiple 100-Continue during multiple stages of a request
 java.net.URL currentURI
          the current URI
protected  boolean debug
          Is this client in debug mode ?
protected  int identifier
          The uniq integer identifier for that client.
protected  long prev_body_count
          The number of bytes in the body of the previously handled request
protected  int reqcount
          Number of requests handled within this client context.
protected  httpd server
          The server context responsible for that client.
 
Constructor Summary
Client()
           
 
Method Summary
protected  int chunkTransfer(java.io.InputStream is, Reply reply)
          Run chunk encoding on the provided stream to emit reply's body.
protected  int emitReply(Reply reply)
          Emit the given reply to the client.
 void error(java.lang.String msg)
          Emit an error message on behalf of that client.
 int getIdentifier()
          Get this client identifier.
abstract  java.net.InetAddress getInetAddress()
          Get the IP address of the host that runs the client described by this context.
 java.io.InputStream getInputStream()
          Get this client input stream.
 short getMajorVersion()
          Get the HTTP major version number spoken on the current connection.
 short getMinorVersion()
          Get the HTTP minor version number spoken on the current connection.
protected  Request getNextRequest()
          Read the next request from our current input stream.
 java.io.DataOutputStream getOutputStream()
          Get this client output stream.
 int getRequestCount()
          Get the total number of requests handled within this client context.
 httpd getServer()
          Get the server context responsible for this client context.
protected abstract  java.lang.Thread getThread()
          Get the thread powering that client, if any.
 void handleTimerEvent(java.lang.Object data, long time)
          Handle timer events.
protected abstract  boolean idleConnection()
          Client callback - The client is about to block, getting next request.
protected  void initialize(httpd server, int identifier)
          Initialize this client.
protected  void interruptConnection(boolean now)
          Interrupt the currently handled connection.
 boolean isInterrupted()
          Does this client has an interrupt pending ?
 boolean isRunning()
          Is this client currently running for a connection.
 void log(Request request, Reply reply, int nbytes, long duration)
          Log the given HTTP transaction.
protected  Reply processRequest(Request request)
          Process a request.
 int sendContinue()
          Send a 100 HTTP continue message on the currently handled connection.
 int sendContinue(Reply contReply)
          Send a 100 HTTP continue message on the currently handled connection.
protected  boolean startConnection(java.io.InputStream in, java.io.DataOutputStream out)
          Start processing the given connection.
protected abstract  void stopConnection()
          Client callback - The current connection has been terminated.
 void trace(java.lang.String msg)
          Emit a trace on behalf of the given client.
protected  boolean tryKeepConnection(Request request, Reply reply)
          Request has been processed into Reply, should we keep connection alive ? Test wether we can keep the connection alive, after the given reply has been emited.
protected abstract  void usedConnection()
          Client callback - A full request has been received on input stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

identifier

protected int identifier
The uniq integer identifier for that client.


server

protected httpd server
The server context responsible for that client.


debug

protected boolean debug
Is this client in debug mode ?


buffer

protected byte[] buffer
The buffer used to emit copy data back to the client.


reqcount

protected int reqcount
Number of requests handled within this client context.


cont

protected boolean cont
flags to avoid multiple 100-Continue during multiple stages of a request


prev_body_count

protected long prev_body_count
The number of bytes in the body of the previously handled request


currentURI

public java.net.URL currentURI
the current URI

Constructor Detail

Client

public Client()
Method Detail

handleTimerEvent

public void handleTimerEvent(java.lang.Object data,
                             long time)
Handle timer events. For the time being, timer events are only used to detect an overrunning request, so this handler just kills the correponding client.

Specified by:
handleTimerEvent in interface EventHandler
Parameters:
data - The timer closure.
time - The absolute time at which the event was triggered.
See Also:
EventManager, EventHandler

tryKeepConnection

protected boolean tryKeepConnection(Request request,
                                    Reply reply)
Request has been processed into Reply, should we keep connection alive ? Test wether we can keep the connection alive, after the given reply has been emited.

Parameters:
request - The request to examine.
reply - Its computed reply.

getNextRequest

protected Request getNextRequest()
                          throws ClientException,
                                 java.io.IOException
Read the next request from our current input stream.

Returns:
a Request instance, or null if interrupted.
Throws:
java.io.IOException - If some IO error occured.
ClientException - If either an IO error happened or bad HTTP was received. In both cases the connection needs to be closed.

chunkTransfer

protected int chunkTransfer(java.io.InputStream is,
                            Reply reply)
                     throws java.io.IOException
Run chunk encoding on the provided stream to emit reply's body.

Parameters:
is - The reply's body that has to be chunk encoded.
Throws:
java.io.IOException - If IO error occurs.

emitReply

protected int emitReply(Reply reply)
                 throws java.io.IOException
Emit the given reply to the client.

Parameters:
reply - The reply to be emited.
Returns:
The number of body bytes emited, or -1 if no bytes needed to be emitted.
Throws:
java.io.IOException - If some IO error occurs.

processRequest

protected Reply processRequest(Request request)
                        throws ClientException
Process a request. This methods processs the request to the point that a reply is available. This methods sets a timeout, to limit the duration of this request processing.

Parameters:
request - The request to process.
Throws:
ClientException - If either the timeout expires or the entity was unable to handle the request.

startConnection

protected boolean startConnection(java.io.InputStream in,
                                  java.io.DataOutputStream out)
                           throws ClientException
Start processing the given connection. This is the entry point for sub classes, in order to make the client start processing the HTTP protocol on the given input and output streams.

Before this method returns, both provided streams are always closed, and the stopConnection method invoked.

Parameters:
in - The input stream to receive HTTP requests.
out - The output stream to send HTTP replies.
Returns:
A boolean true if this method returns because of an interruption, false otherwsie (ie the connection was gracefully shutdown).
Throws:
ClientException - If some severe error has occured and the current connection needs to be terminated.

interruptConnection

protected void interruptConnection(boolean now)
Interrupt the currently handled connection. This method will make best effort to interrupt any thread currently processing the connection.

Parameters:
now - Make sure the thread is interrupted right now if true, otherwise, just schedule an interruption after the current request (if any) has been processed.

sendContinue

public int sendContinue()
                 throws java.io.IOException
Send a 100 HTTP continue message on the currently handled connection. This method will take care of creating the appropriate HTTP continue reply, and will emit that reply only if the spoken HTTP version allows for it.

Throws:
java.io.IOException - If some IO error occured.

sendContinue

public int sendContinue(Reply contReply)
                 throws java.io.IOException
Send a 100 HTTP continue message on the currently handled connection. This method will take care of creating the appropriate HTTP continue reply, and will emit that reply only if the spoken HTTP version allows for it.

Throws:
java.io.IOException - If some IO error occured.

getIdentifier

public final int getIdentifier()
Get this client identifier.

Returns:
An integer identifying uniquely this client's context.

isRunning

public final boolean isRunning()
Is this client currently running for a connection.

Returns:
A boolean, true if it is, false otherwise.

getMajorVersion

public final short getMajorVersion()
Get the HTTP major version number spoken on the current connection.

Returns:
The HTTP major version number, or -1 if that client is not running.

getMinorVersion

public final short getMinorVersion()
Get the HTTP minor version number spoken on the current connection.

Returns:
The HTTP minor version number, or -1 if that client is not running.

isInterrupted

public final boolean isInterrupted()
Does this client has an interrupt pending ?

Returns:
A boolean, true if an interrupt is pending, false otherwise.

getRequestCount

public final int getRequestCount()
Get the total number of requests handled within this client context.

Returns:
An integer giving the number of requests handled.

getServer

public final httpd getServer()
Get the server context responsible for this client context.

Returns:
An httpd instance.

error

public final void error(java.lang.String msg)
Emit an error message on behalf of that client.

Parameters:
msg - The error message to output.

trace

public final void trace(java.lang.String msg)
Emit a trace on behalf of the given client.

Parameters:
msg - The trace to output.

log

public void log(Request request,
                Reply reply,
                int nbytes,
                long duration)
Log the given HTTP transaction.

Parameters:
request - The request that has been processed.
reply - The generated reply.
nbytes - Number of content bytes sent along with the reply.
duration - The processing time for that request in milliseconds.

getInputStream

public java.io.InputStream getInputStream()
Get this client input stream.

Returns:
An instance of InputStream, or null if the client is not handling any connection at that time.

getOutputStream

public java.io.DataOutputStream getOutputStream()
Get this client output stream.

Returns:
An instance of OutputStream, or null if the client is not handling any connection at that time.

getInetAddress

public abstract java.net.InetAddress getInetAddress()
Get the IP address of the host that runs the client described by this context.

Returns:
An InetAddress instance, or null if that client is not handling any connection at that given time.

idleConnection

protected abstract boolean idleConnection()
Client callback - The client is about to block, getting next request. This method is triggered by the client instance itself, before reading next request from the input stream provided at startConnection time.

Returns:
A boolean, if true, the client will consider itself interrupted, and terminate the connection it is current handling.

usedConnection

protected abstract void usedConnection()
Client callback - A full request has been received on input stream. This method is called by the client itself, before starting processing the newly received request. The purpose of this callback is typically to mark that client buzy.


stopConnection

protected abstract void stopConnection()
Client callback - The current connection has been terminated. This client has finished processing the connection provided at startConnection time, it is now stopped.


getThread

protected abstract java.lang.Thread getThread()
Get the thread powering that client, if any. This method is called to kill the client (by interrupting the thread used to run it).

Returns:
A Thread instance, or null.

initialize

protected void initialize(httpd server,
                          int identifier)
Initialize this client. It is up to this method to initialize:
parser
The MimeParser to be used to parse incomminf requests.

Parameters:
server - The server responsible for that client.
factory - The factory that created this client.
identifier - The uniq identifier for this client.