{#========================================== Spincast Undertow plugin ==========================================#} {% extends "../../layout.html" %} {% block sectionClasses %}plugins plugins-spincast-undertow{% endblock %} {% block meta_title %}Plugins - Spincast Undertow{% endblock %} {% block meta_description %}Spincast Undertow plugin provides the default HTTP server for a Spincast application.{% endblock %} {% block scripts %} {% endblock %} {% block body %}
  1. Plugins
  2. Spincast Undertow plugin

Spincast Undertow plugin
Javadoc
default

Spincast Undertow plugin

Overview

The Spincast Undertow plugin provides an implementation of the IServer interface using the Undertow server.

Installation

If you use the spincast-default artifact, this plugin is already installed so you have nothing more to do!

If you start from scratch using the spincast-core artifact, you can use the plugin by adding this artifact to your project: 

<dependency>
    <groupId>org.spincast</groupId>
    <artifactId>spincast-plugins-undertow</artifactId>
    <version>{{spincastCurrrentVersion}}</version>
</dependency>

You then install the plugin's Guice module, by passing it to the Guice.createInjector(...) method: 

Injector guice = Guice.createInjector(
        new SpincastCoreGuiceModule(args),
        new SpincastUndertowPluginGuiceModule(IAppRequestContext.class, IAppWebsocketContext.class)
        // other modules...
        );

... or by using the install(...) method from your custom Guice module: 

public class AppModule extends SpincastCoreGuiceModule {

    @Override
    protected void configure() {
        super.configure();
        install(new SpincastUndertowPluginGuiceModule(getRequestContextType(), 
                                                      getWebsocketContextType()));
        // other modules...
    }
    
    // ...
}

Methods

Few of the IServer's methods are made to be used directly. We are only going to list those here, so have a look at the IServer's Javadoc for a listing of all the available methods.

  • void start()
    Starts the server.
  • void stop()
    Stops the server
  • void createHttpAuthenticationRealm(String pathPrefix, String realmName)
    Creates HTTP authentication protection (realm) for the specified path prefix.
    @param realmName The name of the realm. Must be unique on this server, otherwise an exception is thrown. This allows the application to add user to the realm using its name.
  • Map<String, String> getHttpAuthenticationRealms()
    Returns the existing HTTP authentication realms, the key being the realm's name and the value being the prefix path associated to this realm.


    The map is immutable.

  • void addHttpAuthentication(String realmName, String username, String password)
    Adds a user to an HTTP protected realm.
  • void removeHttpAuthentication(String username, String realmName)
    Removes a user to an HTTP protected realm.
  • void removeHttpAuthentication(String username)
    Removes a user from all HTTP protected realms.
  • IWebsocketEndpointManager websocketCreateEndpoint(String endpointId, IWebsocketEndpointHandler endpointHandler)
    Creates a new WebSocket endpoint.
    @return the manager for this endpoint.
  • void websocketCloseEndpoint(String endpointId)
    Closes a WebSocket endpoint. No more connections will be accepter
  • void websocketCloseEndpoint(String endpointId, int closingCode, String closingReason)
    Closes the entire WebSocket endpoint.
    All peer connections of this endpoint will be closed.
    @param closingCode The closing code.
    @param closingReason The closing reason.
  • void websocketConnection(Object exchange, String endpointId, String peerId)
    Transforms the request to a peer WebSocket connection on the endpoint 'endpointId'.
  • List<IWebsocketEndpointManager> getWebsocketEndpointManagers()
    Returns the managers of the existing WebSockets endpoints.
  • IWebsocketEndpointManager getWebsocketEndpointManager(String endpointId)
    Returns the manager for a WebSockets endpoint.
    @return the manager or null if not found.

Configurations

You can bind the ISpincastUndertowConfig interface if you want to change some default configurations. The default implementation class for those configurations is SpincastUndertowConfigDefault.

Here are the available configurations:

  • boolean isWebsocketAutomaticPing()
    If true, pings will automatically be sent to peers of a WebSocket endpoint as an heartbeat.
    Enabled by default.
  • int getWebsocketAutomaticPingIntervalSeconds()
    When the automatic WebSocket pings are enabled, this is the interval (in seconds) between two pings.
    Defaults to 20 seconds.
  • String getWebsocketPingMessageString()
    The ping text to use. Must be < 125 characters.
    Defaults to "__ping"
  • int getWebsocketDefaultClosingCode()
    The default code to use when sending a "closing WebSocket connection" event to a peer.
    Valid codes can be found here
    Defaults to 1000, a normal closure.
  • String getWebsocketDefaultClosingReason()
    The default reason to use when sending a "closing WebSocket connection" event to a peer.
    Defaults to an empty message.
  • int getWebsocketThreadExecutorForAppEventsThreadNumber()
    The maximum number of concurrent threads used when sending WebSocket events to the application.
    Defaults to 100.
  • int getWebsocketThreadExecutorForAppEventsTimeoutAmount()
    The timeout amount before cancelling a task when sending WebSocket events to the application.
    Defaults to 60.
  • TimeUnit getWebsocketThreadExecutorForAppEventsTimeoutTimeUnit()
    The timeout TimeUnit before cancelling a task when sending WebSocket events to the application.
    Defaults to SECONDS.
  • ThreadFactory getWebsocketThreadExecutorForAppEventsThreadFactory()
    The ThreadFactory to use to create threads when sending WebSocket events to the application.
    Defaults to null.

{% endblock %}