org.simpleframework.transport
Class SocketTransport

java.lang.Object
  org.simpleframework.transport.SocketTransport

All Implemented Interfaces:

Socket, Transport

public class SocketTransport
extends Object
implements Transport

The SocketTransport object offers a transport that can send and receive bytes in a non-blocking manner. The contract of the Transport is that it must either write the data it is asked to write or it must queue that data for delivery. For the vast majority of cases data is written directly to the socket without any need for queuing or selection for write ready events.

In the event that the client TCP window is full and writing would block this makes use of a queue of buffers which can be used to append data to. The buffers are lazily instantiated so the memory required is created only in the rare case that they are needed. Once a buffer is full it is queued to an asynchronous thread where the buffer queue is drained and sent to the client when the TCP window of the client is capable of accepting it.

In order to improve the network performance of this transport the default packet size sent to the TCP stack is four kilobytes. This ensures that the fragments of response delivered to the TCP layer are sufficiently large for optimum network performance.

Author:

Niall Gallagher

Constructor Summary

SocketTransport(Socket socket, Reactor reactor)
Constructor for the SocketTransport object.

SocketTransport(Socket socket, Reactor reactor, int buffer)
Constructor for the SocketTransport object.

SocketTransport(Socket socket, Reactor reactor, int buffer, int threshold)
Constructor for the SocketTransport object.

Method Summary

void	close() This method is used to flush the internal buffer and close the underlying socket.
void	flush() This is used to flush the internal buffer to the underlying socket.
Map	getAttributes() This method is used to get the Map of attributes by this pipeline.
Certificate	getCertificate() This is used to acquire the SSL certificate used when the server is using a HTTPS connection.
SocketChannel	getChannel() This method is used to acquire the SocketChannel for the connection.
SSLEngine	getEngine() This is used to acquire the SSL engine used for https.
Trace	getTrace() This is used to acquire the trace object that is associated with the socket.
int	read(ByteBuffer data) This is used to perform a non-blocking read on the transport.
void	write(ByteBuffer data) This method is used to deliver the provided buffer of bytes to the underlying transport.

Methods inherited from class java.lang.Object

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

Constructor Detail

SocketTransport

public SocketTransport(Socket socket,
                       Reactor reactor)
                throws IOException

Constructor for the SocketTransport object. This requires a reactor to perform asynchronous writes and also the pipeline which is used to read and write data. This transport will use a queue of buffers which are lazily initialized so as to only allocate the memory on demand.

Parameters:

socket - this is used to read and write the data

reactor - this is used to perform asynchronous writes

Throws:

IOException

SocketTransport

public SocketTransport(Socket socket,
                       Reactor reactor,
                       int buffer)
                throws IOException

Constructor for the SocketTransport object. This requires a reactor to perform asynchronous writes and also the pipeline which is used to read and write data. This transport will use a queue of buffers which are lazily initialized so as to only allocate the memory on demand.

Parameters:

socket - this is used to read and write the data

reactor - this is used to perform asynchronous writes

buffer - this is the size of the output buffer to use

Throws:

IOException

SocketTransport

public SocketTransport(Socket socket,
                       Reactor reactor,
                       int buffer,
                       int threshold)
                throws IOException

Constructor for the SocketTransport object. This requires a reactor to perform asynchronous writes and also the pipeline which is used to read and write data. This transport will use a queue of buffers which are lazily initialized so as to only allocate the memory on demand.

Parameters:

socket - this is used to read and write the data

reactor - this is used to perform asynchronous writes

buffer - this is the size of the output buffer to use

threshold - this is the maximum size of the output buffer

Throws:

IOException

Method Detail

getCertificate

public Certificate getCertificate()

This is used to acquire the SSL certificate used when the server is using a HTTPS connection. For plain text connections or connections that use a security mechanism other than SSL this will be null. This is only available when the connection makes specific use of an SSL engine to secure the connection.

Specified by:

getCertificate in interface Transport

Returns:

this returns the associated SSL certificate if any

getTrace

public Trace getTrace()

This is used to acquire the trace object that is associated with the socket. A trace object is used to collection details on what operations are being performed on the socket. For instance it may contain information relating to I/O events or more application specific events such as errors.

Specified by:

getTrace in interface Socket

Returns:

this returns the trace associated with this socket

getAttributes

public Map getAttributes()

This method is used to get the Map of attributes by this pipeline. The attributes map is used to maintain details about the connection. Information such as security credentials to client details can be placed within the attribute map.

Specified by:

getAttributes in interface Socket

Returns:

this returns the map of attributes for this pipeline

getEngine

public SSLEngine getEngine()

This is used to acquire the SSL engine used for https. If the pipeline is connected to an SSL transport this returns an SSL engine which can be used to establish the secure connection and send and receive content over that connection. If this is null then the pipeline represents a normal transport.

Specified by:

getEngine in interface Socket

Returns:

the SSL engine used to establish a secure transport

getChannel

public SocketChannel getChannel()

This method is used to acquire the SocketChannel for the connection. This allows the server to acquire the input and output streams with which to communicate. It can also be used to configure the connection and perform various network operations that could otherwise not be performed.

Specified by:

getChannel in interface Socket

Returns:

this returns the socket used by this HTTP pipeline

read

public int read(ByteBuffer data)
         throws IOException

This is used to perform a non-blocking read on the transport. If there are no bytes available on the input buffers then this method will return zero and the buffer will remain the same. If there is data and the buffer can be filled then this will return the number of bytes read. Finally if the socket is closed this will return a -1 value.

Specified by:

read in interface Transport

Parameters:

data - this is the buffer to append the bytes to

Returns:

this returns the number of bytes that were read

Throws:

IOException

write

public void write(ByteBuffer data)
           throws IOException

This method is used to deliver the provided buffer of bytes to the underlying transport. Depending on the connection type the array may be encoded for SSL transport or send directly. This will buffer the bytes within the internal buffer to ensure that the response fragments are sufficiently large for the network. Smaller packets result poorer performance.

Specified by:

write in interface Transport

Parameters:

data - this is the array of bytes to send to the client

Throws:

IOException

flush

public void flush()
           throws IOException

This is used to flush the internal buffer to the underlying socket. Flushing with this method is always non-blocking, so if the socket is not write ready and the buffer can be queued it will be queued and the calling thread will return.

Specified by:

flush in interface Transport

Throws:

IOException

close

public void close()
           throws IOException

This method is used to flush the internal buffer and close the underlying socket. This method will not complete until all buffered data is written and the underlying socket is closed at which point this can be disposed of.

Specified by:

close in interface Transport

Throws:

IOException