com.streamhub.nio
Class NIOServer

java.lang.Object
  com.streamhub.nio.NIOServer

All Implemented Interfaces:

Publisher, PushServer

Direct Known Subclasses:

SecureNIOServer

public class NIOServer
extends Object
implements PushServer

The main Comet and HTTP Push server to which connections are made by all clients.

A common idiom for running the server until it is stopped by pressing a key is:

  PushServer server = new NIOServer(80);
  server.start();
  System.out.println("Server started on port 80");
  System.out.println("Press any key to stop...");
  System.in.read();
  server.stop();
  System.out.println("Server stopped");

In order to stream data to clients, listeners need to be added to the SubscriptionManager.

  PushServer server = new NIOServer(80);
  server.start();
  SubscriptionManager subscriptionManager = server.getSubscriptionManager();
  subscriptionManager.addSubscriptionListener(this);
  subscriptionManager.addPublishListener(this);

For more details on getting started please refer to the guides below:

• Getting Started with StreamHub and Comet
• Tutorial: Building a Comet Chat Application with StreamHub

See Also:

SecureNIOServer

Constructor Summary

NIOServer(InetSocketAddress address)
Creates a new NIOServer bound to address.

NIOServer(InetSocketAddress address, InetSocketAddress streamingAdapterAddress)
Creates a new NIOServer bound to address and a streaming adapter bound to streamingAdapterAddress

NIOServer(InetSocketAddress address, InetSocketAddress streamingAdapterAddress, String licenseDir)
Creates a new NIOServer bound to address and a streaming adapter bound to streamingAdapterAddress.

NIOServer(InetSocketAddress address, InetSocketAddress streamingAdapterAddress, URL licenseUrl, URL log4jConfigurationUrl)
Creates a new NIOServer bound to address and a streaming adapter bound to streamingAdapterAddress, loading the license and log4j xml configuration from the alternative locations specified by licenseUrl and log4jConfigurationUrl respectively.

NIOServer(int port)
Creates a new NIOServer bound to the wildcard address

Method Summary

void	addContext(String context, com.streamhub.handler.Handler handler) Adds or overrides a context.
void	addStaticContent(File directory) Adds a directory to be served from the root context / as if it were a standard HTTP server.
void	addStaticContent(File directory, String context) Adds a directory to be served from the a specified context as if it were a standard HTTP server.
SubscriptionManager	getSubscriptionManager() Returns the servers SubscriptionManager.
boolean	isStarted() Identifies whether the server is currently started or not
static void	main(String[] args)
void	publish(String topic, Payload payload) Sends the payload to all clients who are subscribed to topic.
void	setDefaultHeader(String name, String value) Sets the value of a default HTTP header for synchronous responses.
void	setDefaultPushHeader(String name, String value) Sets the value of a default HTTP header for asynchronous push responses.
void	start() Starts the server
void	stop() Stops the server

Methods inherited from class java.lang.Object

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

Constructor Detail

NIOServer

public NIOServer(int port)

Creates a new NIOServer bound to the wildcard address

Parameters:

port - the port to listen on

NIOServer

public NIOServer(InetSocketAddress address)

Creates a new NIOServer bound to address.

Parameters:

address - the address to bind to

NIOServer

public NIOServer(InetSocketAddress address,
                 InetSocketAddress streamingAdapterAddress)

Creates a new NIOServer bound to address and a streaming adapter bound to streamingAdapterAddress

Parameters:

address - the address to bind the server to

streamingAdapterAddress - the address to listen for streaming adapters

NIOServer

public NIOServer(InetSocketAddress address,
                 InetSocketAddress streamingAdapterAddress,
                 String licenseDir)

Creates a new NIOServer bound to address and a streaming adapter bound to streamingAdapterAddress. To choose not to start a streaming adapter, pass null as the second argument.

Parameters:

address - the address to bind the server to

streamingAdapterAddress - the address to listen for streaming adapters or null if a streaming adapter is not required

licenseDir - an alternative directory to load the license from. The license file must be called "license.txt"

NIOServer

public NIOServer(InetSocketAddress address,
                 InetSocketAddress streamingAdapterAddress,
                 URL licenseUrl,
                 URL log4jConfigurationUrl)

Creates a new NIOServer bound to address and a streaming adapter bound to streamingAdapterAddress, loading the license and log4j xml configuration from the alternative locations specified by licenseUrl and log4jConfigurationUrl respectively. To choose not to start a streaming adapter, pass null as the second argument.

The following URL formats are supported for the licenseUrl and log4jConfigurationUrl parameters:

• File URLs e.g. file:///C:/licenses/license.txt
• Remote URLs e.g. http://www.example.com/logging/log4j.xml
• JAR URLs e.g. jar:file:///C:/lib/streamhub-license.jar!/license.txt or jar:http://www.example.com/logging/streamhub-logging.jar!/log4j.xml
• Classpath URLs via com.streamhub.util.UrlLoader e.g. UrlLoader.load("classpath:/license.txt"), or UrlLoader.load("classpath:/conf/log4j.xml")

The default location for the license file is a file named "license.txt" in the current working directory (or "."). The default location for the log4j configuration is "conf/log4j.xml" relative to the current working directory.

Parameters:

address - the address to bind the server to

streamingAdapterAddress - the address to listen for streaming adapters or null if a streaming adapter is not required

licenseUrl - an alternative URL to load the license from

log4jConfigurationUrl - an alternative URL to load the log4j xml configuration from

Method Detail

main

public static void main(String[] args)
                 throws Exception

Throws:

Exception

stop

public void stop()
          throws IOException

Description copied from interface: PushServer

Stops the server

This method will block until all the connections have been forcibly closed and internal threads shutdown

Specified by:

stop in interface PushServer

Throws:

IOException

start

public void start()

Description copied from interface: PushServer

Starts the server

Note this method is non-blocking

Specified by:

start in interface PushServer

getSubscriptionManager

public SubscriptionManager getSubscriptionManager()

Description copied from interface: PushServer

Returns the servers SubscriptionManager.

The SubscriptionManager provides the core publish and subscribe listening capabilities of the server.

Use SubscriptionManager.addPublishListener(PublishListener) to receive callbacks when a client publishes a message to the server.

Use SubscriptionManager.addSubscriptionListener(SubscriptionListener) to receive callbacks when a client subscribes to a topic.

It is recommended to call this method after starting the server using PushServer.start()

Specified by:

getSubscriptionManager in interface PushServer

Returns:

the SubscriptionManager associated with this server

isStarted

public boolean isStarted()

Description copied from interface: PushServer

Identifies whether the server is currently started or not

Specified by:

isStarted in interface PushServer

Returns:

true if the server is currently started and running, false if it has not been started or has been stopped

publish

public void publish(String topic,
                    Payload payload)

Description copied from interface: Publisher

Sends the payload to all clients who are subscribed to topic. Only connected clients who are subscribed to topic will receive the payload. This interface is implemented by NIOServer.

This method should generally be preferred over Client.send(String, Payload) except where unique information must be sent to each client.

StreamHub keeps its own internal map of subscriptions. If you need to send something on a topic which a client has not subscribed to, use Client.send(String, Payload).

Specified by:

publish in interface Publisher

Parameters:

topic - the topic on which to send the message

payload - the message payload

See Also:

Payload

addStaticContent

public void addStaticContent(File directory)

Description copied from interface: PushServer

Adds a directory to be served from the root context / as if it were a standard HTTP server. This allows static content, for example HTML pages, to be retrieved via a web browser.

Although StreamHub is capable of serving normal static content it was primarily designed as a Comet and HTTP Push server. For a live website or application it is recommended to serve static content from a standard HTTP Web server such as Apache or IIS.

Specified by:

addStaticContent in interface PushServer

Parameters:

directory - the directory on the local filesytem to make available via the web

See Also:

PushServer.addStaticContent(File, String)

addStaticContent

public void addStaticContent(File directory,
                             String context)

Description copied from interface: PushServer

Adds a directory to be served from the a specified context as if it were a standard HTTP server. This allows static content, for example HTML pages, to be retrieved via a web browser.

Although StreamHub is capable of serving normal static content it was primarily designed as a Comet and HTTP Push server. For a live website or application it is recommended to serve static content from a standard HTTP Web server such as Apache or IIS.

Specified by:

addStaticContent in interface PushServer

Parameters:

directory - the directory on the local filesytem to make available via the web

context - the context to serve the directory under. For example using a context of site would make content available under http://serverurl/site/

See Also:

PushServer.addStaticContent(File)

setDefaultPushHeader

public void setDefaultPushHeader(String name,
                                 String value)

Description copied from interface: PushServer

Sets the value of a default HTTP header for asynchronous push responses.

Specified by:

setDefaultPushHeader in interface PushServer

Parameters:

name - the name of the header

value - the value of the header

setDefaultHeader

public void setDefaultHeader(String name,
                             String value)

Description copied from interface: PushServer

Sets the value of a default HTTP header for synchronous responses.

Specified by:

setDefaultHeader in interface PushServer

Parameters:

name - the name of the header

value - the value of the header

addContext

public void addContext(String context,
                       com.streamhub.handler.Handler handler)

Description copied from interface: PushServer

Adds or overrides a context. An example of a context is /examples/*. Any incoming requests which match the context will be routed to the handler.

Specified by:

addContext in interface PushServer

Parameters:

context - a context specifier string e.g. /examples/*

handler - a handler which will handle requests matching the context