Class SocketTransport

  • All Implemented Interfaces:
    Socket, Transport

    public class SocketTransport
    extends java.lang.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.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.nio.channels.SocketChannel channel
      This is the underlying byte channel used to send the data.
      private boolean closed
      This is used to determine if the transport has been closed.
      private Socket socket
      This is the socket that this transport is representing.
      private Trace trace
      This is the trace used to monitor all transport events.
      private SocketBufferWriter writer
      This is the writer that is used to flush the buffer queue.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      java.util.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.
      java.nio.channels.SocketChannel getChannel()
      This method is used to acquire the SocketChannel for the connection.
      javax.net.ssl.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​(java.nio.ByteBuffer data)
      This is used to perform a non-blocking read on the transport.
      void write​(java.nio.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
    • Field Detail

      • writer

        private SocketBufferWriter writer
        This is the writer that is used to flush the buffer queue.
      • channel

        private java.nio.channels.SocketChannel channel
        This is the underlying byte channel used to send the data.
      • socket

        private Socket socket
        This is the socket that this transport is representing.
      • trace

        private Trace trace
        This is the trace used to monitor all transport events.
      • closed

        private boolean closed
        This is used to determine if the transport has been closed.
    • Constructor Detail

      • SocketTransport

        public SocketTransport​(Socket socket,
                               Reactor reactor)
                        throws java.io.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:
        java.io.IOException
      • SocketTransport

        public SocketTransport​(Socket socket,
                               Reactor reactor,
                               int buffer)
                        throws java.io.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:
        java.io.IOException
      • SocketTransport

        public SocketTransport​(Socket socket,
                               Reactor reactor,
                               int buffer,
                               int threshold)
                        throws java.io.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:
        java.io.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 java.util.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 javax.net.ssl.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 java.nio.channels.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​(java.nio.ByteBuffer data)
                 throws java.io.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:
        java.io.IOException
      • write

        public void write​(java.nio.ByteBuffer data)
                   throws java.io.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:
        java.io.IOException
      • flush

        public void flush()
                   throws java.io.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:
        java.io.IOException
      • close

        public void close()
                   throws java.io.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:
        java.io.IOException