模块 ringo/httpserver

该模块提供了启动和控制 HTTP Web 服务器的方法。 它是 Jetty Web 服务器的包装器,并且支持 WebSocket 协议。

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

Class Server

Instance Methods

Class WebSocket

Instance Methods


Context

不通过此模块导出为构造函数。


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

将此上下文中的请求路径映射到给定的 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)

在这种情况下开始接受 WebSocket 连接。

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)

将此上下文映射到 JSGI 应用程序。

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)

将该上下文映射到包含静态资源的目录。

Parameters

String dir

the directory from which to serve static resources


Server (options)

使用给定的选项创建一个 Jetty HTTP 服务器。这些选项可以定义要与默认 jetty.xml 一起使用的属性,也可以定义自定义配置文件。

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

销毁 HTTP 服务器,释放其资源。


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

获取给定路径和虚拟主机的 servlet 应用程序 context,如果它不存在则创建它。

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

获取服务器的默认上下文。默认 context 是创建服务器时创建的上下文。

Returns

Context

the default Context

See


Server.prototype. getJetty ()

获取 Jetty 服务器实例

Returns

org.eclipse.jetty.server.Server

the Jetty Server instance


Server.prototype. isRunning ()

检查此服务器当前是否在运行。

Returns

Boolean

true if the server is running, false otherwise.


Server.prototype. start ()

启动 HTTP 服务器。


Server.prototype. stop ()

停止 HTTP 服务器。


WebSocket

不通过此模块导出为构造函数。


WebSocket.prototype. close ()

关闭 WebSocket 连接。


WebSocket.prototype. isOpen ()

检查 WebSocket 是否打开。

Returns

Boolean

true if the connection is open


WebSocket.prototype. send (message)

不推荐使用!

通过 WebSocket 发送一个字符串。

Parameters

String message

a string


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

通过 WebSocket 发送一个字节数组。该方法阻塞,直到消息被发送。

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)

通过 WebSocket 发送一个字节数组。这种方法不会等待消息被传输。

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)

通过 WebSocket 发送一个字符串。这种方法阻塞直到消息已经被发​​送

Parameters

String message

a string


WebSocket.prototype. sendStringAsync (message)

通过 WebSocket 发送一个字符串。这种方法不会等待消息被传输。

Parameters

String message

a string


destroy ()

守护程序生命周期函数由init脚本调用。释放服务器实例占用的任何资源。如果应用程序导出一个名为 destroy 的函数,它将作为参数与服务器一起调用。

Returns

Server

the Server instance.


init (appPath)

守护程序生命周期函数由 init 脚本调用。使用 appPath 中的应用程序创建一个新的服务器。如果应用程序导出一个名为 init 的函数,它将以新服务器作为参数进行调用。

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)

主要功能是从命令行启动 HTTP 服务器。它会自动添加一个关闭挂钩,以停止并销毁 JVM 终端处的服务器。

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

守护程序生命周期函数由 init 脚本调用。启动由 init() 创建的服务器。如果应用程序导出一个名为 start 的函数,它将在服务器启动后立即作为参数调用。

Returns

Server

the Server instance.


stop ()

守护程序生命周期函数由 init 脚本调用。停止由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.