    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Class org.w3c.jigsaw.http.Client

    java.lang.Object
       |
       +----org.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

##

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

##

Client()

##

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

##

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.

##

Client

     public Client()

##

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

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

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.

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.

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

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.

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.

getIdentifier

     public final int getIdentifier()

  Get this client identifier.

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

isRunning

     public final synchronized 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(String msg)

  Emit an error message on behalf of that client.

  Parameters:
    msg - The error message to output.

trace

     public final void trace(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 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 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.

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.

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

    All Packages  Class Hierarchy  This Package  Previous  Next  Index