Package com.blackrook.small

Class SmallEndpoint

java.lang.Object
javax.websocket.Endpoint
com.blackrook.small.SmallEndpoint
public abstract class SmallEndpoint extends javax.websocket.Endpoint
A base websocket endpoint that automatically has a connection to the Small application environment. Endpoints that extend this class should use the ServerEndpoint annotation to declare itself.

You should use this class for finding components created in Small, as this provides access for retrieving those components once this class is instantiated by the Servlet Container (see getComponent(Class).

Author:
Matthew Tropiano

  • Field Details

    • DEFAULT_BUFFER_SIZE

      public static final int DEFAULT_BUFFER_SIZE
      Default buffer size.
      See Also:

  • Constructor Details

    • SmallEndpoint

      public SmallEndpoint()

  • Method Details

    • onOpen

      public final void onOpen(javax.websocket.Session session, javax.websocket.EndpointConfig config)
      When this is called, this gets the SmallEnvironment from the config and saves the session on this class. This method is already annotated with OnOpen, and calls afterOpen(EndpointConfig) to set up configuration after the Session and the SmallEnvironment is set on the endpoint.
      Specified by:
      onOpen in class javax.websocket.Endpoint

    • afterOpen

      protected void afterOpen(javax.websocket.EndpointConfig config)
      Called after the session and environment setup in the onOpen(Session, EndpointConfig) method happens. Does nothing by default. See getSession() for getting the socket session. See getEnvironment() for setting up references to components.
      Parameters:
      config - the endpoint configuration.

    • getSession

      protected javax.websocket.Session getSession()
      Returns:
      gets the session for this websocket.

    • getEnvironment

      protected SmallEnvironment getEnvironment()
      Returns:
      the Small environment.

    • getJSONDriver

      protected JSONDriver getJSONDriver()
      Gets this application's JSON converter driver.
      Returns:
      the instantiated driver.

    • getXMLDriver

      protected XMLDriver getXMLDriver()
      Gets this application's XML converter driver.
      Returns:
      the instantiated driver.

    • getTemporaryDirectory

      protected File getTemporaryDirectory()
      Returns:
      the temporary directory to use for multipart files.

    • getComponent

      protected <T> T getComponent(Class<T> componentClass)
      Returns a singleton component instantiated by Small.
      Type Parameters:
      T - the object type.
      Parameters:
      componentClass - the component class.
      Returns:
      a singleton component annotated with Component by class.

    • getId

      public String getId()
      Convenience method for getting this endpoint's ID.

      getSession().getId()

      Returns:
      this endpoint's unique id.

    • getURI

      public URI getURI()
      Convenience method for getting the URI that created this endpoint.

      getSession().getRequestURI()

      Returns:
      this endpoint's constructor URI.
      Since:
      1.6.0

    • getPathVariable

      public String getPathVariable(String variableName)
      Convenience method for getting a path variable from the endpoint URI.

      getSession().getPathParameters().get(variableName)

      Parameters:
      variableName - the variable name.
      Returns:
      the corresponding value, or null if no value.
      Since:
      1.6.0

    • getParameters

      public List<String> getParameters(String parameterName)
      Convenience method for getting a list of query parameter values from the endpoint URI.

      getSession().getRequestParameterMap().get(parameterName)

      Parameters:
      parameterName - the parameter name.
      Returns:
      the corresponding list of values, or null if no such parameter.
      Since:
      1.6.0

    • getParameter

      public String getParameter(String parameterName)
      Convenience method for getting a query parameter from the endpoint URI. This only returns the last defined one.

      getSession().getRequestParameterMap().get(parameterName)

      Parameters:
      parameterName - the parameter name.
      Returns:
      the corresponding value, or null if no such parameter.
      Since:
      1.6.0

    • getQueryString

      public String getQueryString()
      Convenience method for getting the query string from the request that created this.

      getSession().getQueryString()

      Returns:
      the query string.
      Since:
      1.6.0

    • sendText

      public void sendText(String message)
      Sends a message string, synchronously, to the client. Execution halts until the client socket acknowledges receipt.
      Parameters:
      message - the message string to pass back to the connected client.
      Throws:
      SmallFrameworkException - on a send error.

    • sendTextPartial

      public void sendTextPartial(String message, boolean isLast)
      Sends a message string, synchronously, to the client, hinting that it may not be the last one in the complete message. Execution halts until the client socket acknowledges receipt.
      Parameters:
      message - the (partial) message string to pass back to the connected client.
      isLast - if true, tells the client that this is the final part. if false, it is not the last part.
      Throws:
      SmallFrameworkException - on a send error.

    • sendJSON

      public void sendJSON(Object object)
      Sends a JSON Object, synchronously, to the client. Execution halts until the client socket acknowledges receipt.
      Parameters:
      object - the object to pass back to the connected client (converted to JSON via the JSONDriver).
      Throws:
      SmallFrameworkException - on a send error.

    • sendXML

      public void sendXML(Object object)
      Sends an XML Document, synchronously, to the client. Execution halts until the client socket acknowledges receipt.
      Parameters:
      object - the object to pass back to the connected client (converted to XML via the XMLDriver).
      Throws:
      SmallFrameworkException - on a send error.

    • sendBinary

      public void sendBinary(ByteBuffer buffer)
      Sends binary data, synchronously, to the client. Execution halts until the client socket acknowledges receipt.
      Parameters:
      buffer - the buffer of data to pass back to the connected client.
      Throws:
      SmallFrameworkException - on a send error.

    • sendBinaryPartial

      public void sendBinaryPartial(ByteBuffer buffer, boolean isLast)
      Sends binary data, synchronously, to the client, hinting that it may not be the last one in the complete message. Execution halts until the client socket acknowledges receipt.
      Parameters:
      buffer - the buffer of data to pass back to the connected client.
      isLast - if true, this is the last part of the message.
      Throws:
      SmallFrameworkException - on a send error.

    • sendBinary

      public void sendBinary(byte[] buffer)
      Sends binary data, synchronously, to the client. Execution halts until the client socket acknowledges receipt. This method should not be used for repeated sends, as the array is wrapped in a ByteBuffer before it is sent.
      Parameters:
      buffer - the buffer of data to pass back to the connected client.
      Throws:
      SmallFrameworkException - on a send error.

    • sendBinaryPartial

      public void sendBinaryPartial(byte[] buffer, boolean isLast)
      Sends binary data, synchronously, to the client, hinting that it may not be the last one in the complete message. Execution halts until the client socket acknowledges receipt. This method should not be used for repeated sends, as the array is wrapped in a ByteBuffer before it is sent.
      Parameters:
      buffer - the buffer of data to pass back to the connected client.
      isLast - if true, this is the last part of the message.
      Throws:
      SmallFrameworkException - on a send error.

    • sendData

      public void sendData(InputStream in)
      Sends a stream of data, synchronously, until the end of the stream. The stream is not closed after this completes. Execution halts until the client socket acknowledges receipt.

      The buffer size used for this socket is DEFAULT_BUFFER_SIZE.

      Parameters:
      in - the input stream to read from.
      Throws:
      SmallFrameworkException - on a send or read error.
      Since:
      1.6.0

    • sendData

      public void sendData(InputStream in, int bufferSize)
      Sends a stream of data, synchronously, until the end of the stream. The stream is not closed after this completes. Execution halts until the client socket acknowledges receipt.
      Parameters:
      in - the input stream to read from.
      bufferSize - the size of the buffer to use during the send.
      Throws:
      IllegalArgumentException - if bufferSize is 0 or less.
      SmallFrameworkException - on a send or read error.

    • sendFileContents

      public void sendFileContents(File file)
      Sends the contents of a file as a stream of data, synchronously, until the end of the file. Execution halts until the client socket acknowledges receipt.
      Parameters:
      file - the file to read.
      Throws:
      SmallFrameworkException - on a send or read error.
      Since:
      1.6.0

    • sendFileContents

      public void sendFileContents(File file, int bufferSize)
      Sends the contents of a file as a stream of data, synchronously, until the end of the file. Execution halts until the client socket acknowledges receipt.
      Parameters:
      file - the file to read.
      bufferSize - the size of the buffer to use during the send.
      Throws:
      IllegalArgumentException - if bufferSize is 0 or less.
      SmallFrameworkException - on a send or read error.

    • sendAsyncText

      public Future<Void> sendAsyncText(String message)
      Sends a message string, asynchronously, to the client.
      Parameters:
      message - the message string to pass back to the connected client.
      Returns:
      the Future object to monitor the sent request after the call.
      Throws:
      SmallFrameworkException - on a send error.

    • sendAsyncJSON

      public Future<Void> sendAsyncJSON(Object object)
      Sends a JSON Object, asynchronously, to the client.
      Parameters:
      object - the object to pass back to the connected client.
      Returns:
      the Future object to monitor the sent request after the call.
      Throws:
      SmallFrameworkException - on a send error.

    • sendAsyncXML

      public Future<Void> sendAsyncXML(Object object)
      Sends a JSON Object, asynchronously, to the client.
      Parameters:
      object - the object to pass back to the connected client (converted to XML via the XMLDriver).
      Returns:
      the Future object to monitor the sent request after the call.
      Throws:
      SmallFrameworkException - on a send error.

    • sendAsyncBinary

      public Future<Void> sendAsyncBinary(ByteBuffer buffer)
      Sends binary data, asynchronously, to the client.
      Parameters:
      buffer - the buffer of data to pass back to the connected client.
      Returns:
      the Future object to monitor the sent request after the call.
      Throws:
      IllegalArgumentException - if buffer is null.

    • sendAsyncBinary

      public Future<Void> sendAsyncBinary(byte[] buffer)
      Sends binary data, asynchronously, to the client. This method should not be used for repeated sends, as the array is wrapped in a ByteBuffer before it is sent.
      Parameters:
      buffer - the buffer of data to pass back to the connected client.
      Returns:
      the Future object to monitor the sent request after the call.
      Throws:
      IllegalArgumentException - if buffer is null.