RingoJS

Module ringo/httpserver

This module provides methods to start and control a HTTP web server. It is a wrapper for the Jetty web server and has support for the WebSocket protocol.

Example

// starts the current module via module.id as web application
require("ringo/httpserver").main(module.id);

// starts the module "./app/actions" as web application
require("ringo/httpserver").main(module.resolve('./app/actions'));

See

Simple HTTP-Server example
Async HTTP-Server example
Eventsource example
Websocket example
Jetty – Servlet Engine and Http Server

Functions

Class Context

Instance Methods

Class Server

Instance Methods

Class WebSocket

Instance Methods


Context

Not exported as constructor by this module.


Context.prototype. addServlet (servletPath, servlet, initParams)

Map a request path within this context to the given servlet.

Parameters

String servletPath

the servlet path

Servlet servlet

a java object implementing the javax.servlet.Servlet interface.

Object initParams

optional object containing servlet init parameters


Context.prototype. addWebSocket (path, onConnect, onCreate, initParams)

Start accepting WebSocket connections in this context.

Example

var context = server.getDefaultContext();
context.addWebSocket("/chat", function (socket) {
  // reacts on an incoming message fromt the client
  socket.onmessage = function(msg) {
     // ...
  };

  // client closed the connection
  socket.onclose = function() {
     // ...
  };

  // sends a string to the client
  socket.sendString("...");
});

Parameters

String path

The URL path on which to accept WebSocket connections

Function onConnect

A function called for each new WebSocket connection with the WebSocket object and the session as arguments.

Function onCreate

Optional function called before a WebSocket instance is created. This function receives the request and response objects as arguments. Only if the function returns true the upgrade request is accepted and a WebSocket instance is created. Use this function for eg. authorization or authentication checks.

Object initParams

Optional object containing servlet initialization parameters

See


Context.prototype. serveApplication (app, engine)

Map this context to a JSGI application.

Example

var server = new Server({ ... config ... });

// 1st way: app argument is a JSGI application function
server.getDefaultContext().serveApplication(function(req) {
  return {
    status: 200,
    headers: {},
    body: ["Hello World!"]
  };
});

// 2nd way: app argument is an object
server.getDefaultContext().serveApplication({
  appModule: module.resolve("./myWebapp"),
  // myWebapp exports a function called 'app'
  appName: "app"
});

// since serveApplication() doesn't start the server:
server.start();

Parameters

Function|Object app

a JSGI application, either as a function or an object with the properties

  • appModule - the application module containing the application function
  • appName - the property's name that is exported by the application module and which is a valid JSGI application.
defining the application.
RhinoEngine engine

optional RhinoEngine instance for multi-engine setups


Context.prototype. serveStatic (dir)

Map this context to a directory containing static resources.

Parameters

String dir

the directory from which to serve static resources


Server (options)

Create a Jetty HTTP server with the given options. The options may either define properties to be used with the default jetty.xml, or define a custom configuration file.

Parameters

Object options

A javascript object with any of the following properties (default values in parentheses):

  • jettyConfig ('config/jetty.xml')
  • port (8080); overrides port of the default jetty.xml
  • host (localhost); overrides host of the default jetty.xml
  • sessions (true)
  • security (true)
  • statistics (false)
  • cookieName (null)
  • cookieDomain (null)
  • cookiePath (null)
  • httpOnlyCookies (false)
  • secureCookies (false)

For convenience, the constructor supports the definition of a JSGI application and static resource mapping in the options object using the following properties:

  • virtualHost (undefined)
  • mountpoint ('/')
  • staticDir ('static')
  • staticMountpoint ('/static')
  • appModule ('main')
  • appName ('app')

Server.prototype. destroy ()

Destroy the HTTP server, freeing its resources.


Server.prototype. getContext (path, virtualHosts, options)

Get a servlet application context for the given path and virtual hosts, creating it if it doesn't exist.

Parameters

String path

the context root path such as "/" or "/app"

String|Array virtualHosts

optional single or multiple virtual host names. A virtual host may start with a "*." wildcard.

Object options

may have the following properties:

  • sessions: true to enable sessions for this context, false otherwise
  • security: true to enable security for this context, false otherwise
  • statistics: true to enable statistics for this context, false otherwise
  • cookieName: optional cookie name
  • cookieDomain: optional cookie domain
  • cookiePath: optional cookie path
  • httpOnlyCookies: true to enable http-only session cookies
  • secureCookies: true to enable secure session cookies

Returns

Context

a Context object

See


Server.prototype. getDefaultContext ()

Get the server's default context. The default context is the context that is created when the server is created.

Returns

Context

the default Context

See


Server.prototype. getJetty ()

Get the Jetty server instance

Returns

org.eclipse.jetty.server.Server

the Jetty Server instance


Server.prototype. isRunning ()

Checks whether this server is currently running.

Returns

Boolean

true if the server is running, false otherwise.


Server.prototype. start ()

Start the HTTP server.


Server.prototype. stop ()

Stop the HTTP server.


WebSocket

Not exported as constructor by this module.


WebSocket.prototype. close ()

Closes the WebSocket connection.


WebSocket.prototype. isOpen ()

Check whether the WebSocket is open.

Returns

Boolean

true if the connection is open


WebSocket.prototype. send (message)

Deprecated!

Send a string over the WebSocket.

Parameters

String message

a string


WebSocket.prototype. sendBinary (byteArray, offset, length)

Send a byte array over the WebSocket. This method blocks until the message as been transmitted.

Parameters

ByteArray byteArray

The byte array to send

Number offset

Optional offset (defaults to zero)

Number length

Optional length (defaults to the length of the byte array)


WebSocket.prototype. sendBinaryAsync (byteArray, offset, length)

Send a byte array over the WebSocket. This method does not wait until the message as been transmitted.

Parameters

ByteArray byteArray

The byte array to send

Number offset

Optional offset (defaults to zero)

Number length

Optional length (defaults to the length of the byte array)

Returns

java.util.concurrent.Future

WebSocket.prototype. sendString (message)

Send a string over the WebSocket. This method blocks until the message has been transmitted

Parameters

String message

a string


WebSocket.prototype. sendStringAsync (message)

Send a string over the WebSocket. This method does not wait until the message as been transmitted.

Parameters

String message

a string


destroy ()

Daemon life cycle function invoked by init script. Frees any resources occupied by the Server instance. If the application exports a function called destroy, it will be invoked with the server as argument.

Returns

Server

the Server instance.


init (appPath)

Daemon life cycle function invoked by init script. Creates a new Server with the application at appPath. If the application exports a function called init, it will be invoked with the new server as argument.

Parameters

String appPath

optional application file name or module id. If undefined, the first command line argument will be used as application. If there are no command line arguments, module main in the current working directory is used.

Returns

Server

the Server instance.


main (appPath)

Main function to start an HTTP server from the command line. It automatically adds a shutdown hook which will stop and destroy the server at the JVM termination.

Example

// starts the current module via module.id as web application
require("ringo/httpserver").main(module.id);

// starts the module "./app/actions" as web application
require("ringo/httpserver").main(module.resolve('./app/actions'));

Parameters

String appPath

optional application file name or module id.

Returns

Server

the Server instance.


start ()

Daemon life cycle function invoked by init script. Starts the Server created by init(). If the application exports a function called start, it will be invoked with the server as argument immediately after it has started.

Returns

Server

the Server instance.


stop ()

Daemon life cycle function invoked by init script. Stops the Server started by start().

Returns

Server

the Server instance. If the application exports a function called stop, it will be invoked with the server as argument immediately before it is stopped.