## org.w3c.jigsaw.http
Class Client

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

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
`protected boolean` | `debug` Is this client in debug mode ?
`protected int` | `identifier` The uniq integer identifier for that client.
`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)` 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.
`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

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

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

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