Module ringo/httpserver

A wrapper for the Jetty HTTP server.

Functions

Class Context

Instance Methods

Class Server

Instance Methods

Class WebSocket

Instance Methods

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)

Start accepting WebSocket connections in this context context.

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 as argument.

See

WebSocket

Context.prototype.serveApplication (app, engine)

Map this context to a JSGI application.

Parameters

function|object app a JSGI application, either as a function or an object with properties appModule and appName defining the application.
{ appModule: 'main', appName: 'app' }
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, with the default value in parentheses:
  • jettyConfig ('config/jetty.xml')
  • port (8080)
  • host (undefined)
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

Returns

a Context object

Server.prototype.getDefaultContext ()

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

Returns

the default context

Server.prototype.getJetty ()

Get the Jetty server instance

Returns

the Jetty Server instance

Server.prototype.isRunning ()

Checks whether this server is currently running.

Returns

true if the server is running, false otherwise.

Server.prototype.start ()

Start the HTTP server.

Server.prototype.stop ()

Stop the HTTP server.

WebSocket

Provides support for WebSockets in the HTTP server.

WebSocket is an event emitter that supports the following events:

  • open: called when a new websocket connection is accepted
  • message: Called with a complete text message when all fragments have been received.
  • close: called when an established websocket connection closes

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 (msg)

Send a string over the WebSocket.

Parameters

msg 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 (path)

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

Parameters

path {string} optional path to the application. If undefined, the path will be taken from `system.args`.

Returns

Server the Server instance.

main (path)

Main webapp startup function.

Parameters

String path optional path to the web application directory or config module.

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.