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'));
Functions
Class Context
Instance Methods
- addServlet(servletPath, servlet, initParams)
- addWebSocket(path, onConnect, onCreate, initParams)
- serveApplication(app, engine)
- serveStatic(dir)
Class Server
Instance Methods
- destroy()
- getContext(path, virtualHosts, options)
- getDefaultContext()
- getJetty()
- isRunning()
- start()
- stop()
Class WebSocket
Instance Methods
- close()
- isOpen()
- send(message)
- sendBinary(byteArray, offset, length)
- sendBinaryAsync(byteArray, offset, length)
- sendString(message)
- sendStringAsync(message)
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 |
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
|
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):
For convenience, the constructor supports the definition of a JSGI application and static resource mapping in the options object using the following properties:
|
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 |
String|Array | virtualHosts | optional single or multiple virtual host names.
A virtual host may start with a |
Object | options | may have the following properties:
|
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 |
See
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 |
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 |