All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class w3c.jigsaw.http.Client

java.lang.Object
   |
   +----w3c.jigsaw.http.Client

public abstract class Client
extends 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

Variable Index

 o buffer
The buffer used to emit copy data back to the client.
 o debug
Is this client in debug mode ?
 o identifier
The uniq integer identifier for that client.
 o reqcount
Number of requests handled within this client context.
 o server
The server context responsible for that client.

Constructor Index

 o Client()

Method Index

 o chunkTransfer(InputStream)
Run chunk encoding on the provided stream to emit reply's body.
 o emitReply(Reply)
Emit the given reply to the client.
 o error(String)
Emit an error message on behalf of that client.
 o getIdentifier()
Get this client identifier.
 o getInetAddress()
Get the IP address of the host that runs the client described by this context.
 o getInputStream()
Get this client input stream.
 o getMajorVersion()
Get the HTTP major version number spoken on the current connection.
 o getMinorVersion()
Get the HTTP minor version number spoken on the current connection.
 o getNextRequest()
Read the next request from our current input stream.
 o getOutputStream()
Get this client outpu stream.
 o getRequestCount()
Get the total number of requests handled within this client context.
 o getServer()
Get the server context responsible for this client context.
 o getThread()
Get the thread powering that client, if any.
 o handleTimerEvent(Object, long)
Handle timer events.
 o idleConnection()
Client callback - The client is about to block, getting next request.
 o initialize(httpd, int)
Initialize this client.
 o interruptConnection(boolean)
Interrupt the currently handled connection.
 o isInterrupted()
Does this client has an interrupt pending ?
 o isRunning()
Is this client currently running for a connection.
 o log(Request, Reply, int, long)
Log the given HTTP transaction.
 o processRequest(Request)
Process a request.
 o sendContinue()
Send a 100 HTTP continue message on the currently handled connection.
 o startConnection(InputStream, DataOutputStream)
Start processing the given connection.
 o stopConnection()
Client callback - The current connection has been terminated.
 o trace(String)
Emit a trace on behalf of the given client.
 o tryKeepConnection(Request, 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.
 o usedConnection()
Client callback - A full request has been received on input stream.

Variables

 o identifier
 protected int identifier
The uniq integer identifier for that client.

 o server
 protected httpd server
The server context responsible for that client.

 o debug
 protected boolean debug
Is this client in debug mode ?

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

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

Constructors

 o Client
 public Client()

Methods

 o handleTimerEvent
 public synchronized void handleTimerEvent(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.

Parameters:
data - The timer closure.
time - The absolute time at which the event was triggered.
See Also:
EventManager, EventHandler
 o 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.
 o getNextRequest
 protected Request getNextRequest() throws ClientException
Read the next request from our current input stream.

Returns:
a Request instance, or null if interrupted.
Throws: IOException
If some IO error occured.
Throws: ClientException
If either an IO error happened or bad HTTP was received. In both cases the connection needs to be closed.
 o chunkTransfer
 protected int chunkTransfer(InputStream is) throws 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: IOException
If IO error occurs.
 o emitReply
 protected int emitReply(Reply reply) throws 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: IOException
If some IO error occurs.
 o 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.
 o startConnection
 protected boolean startConnection(InputStream in,
                                   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.
 o interruptConnection
 protected synchronized 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.
 o sendContinue
 public int sendContinue() throws 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: IOException
If some IO error occured.
 o getIdentifier
 public final int getIdentifier()
Get this client identifier.

Returns:
An integer identifying uniquely this client's context.
 o isRunning
 public final synchronized boolean isRunning()
Is this client currently running for a connection.

Returns:
A boolean, true if it is, false otherwise.
 o 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.
 o 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.
 o isInterrupted
 public final boolean isInterrupted()
Does this client has an interrupt pending ?

Returns:
A boolean, true if an interrupt is pending, false otherwise.
 o 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.
 o getServer
 public final httpd getServer()
Get the server context responsible for this client context.

Returns:
An httpd instance.
 o error
 public final void error(String msg)
Emit an error message on behalf of that client.

Parameters:
msg - The error message to output.
 o trace
 public final void trace(String msg)
Emit a trace on behalf of the given client.

Parameters:
msg - The trace to output.
 o 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.
 o getInputStream
 public 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.
 o getOutputStream
 public DataOutputStream getOutputStream()
Get this client outpu stream.

Returns:
An instance of OutputStream, or null if the client is not handling any connection at that time.
 o getInetAddress
 public abstract 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.
 o 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.
 o 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.

 o 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.

 o getThread
 protected abstract 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.
 o 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.

All Packages  Class Hierarchy  This Package  Previous  Next  Index