脚本开发

JS API 手册 REST API 手册 (仅专业版支持) RingoJS
RingoJS 1.2.1

模块 globals

RingoJS 采用了 Rhino shell 的一些 global 属性并增加了一些属性。

请注意，该模块必须和不能像普通模块一样导入。 RingoJS 启动时仅评估一次。

Functions

Properties

addToClasspath (path)

在运行时将路径添加到 RingoJS 应用程序类路径。如果库及其类不在默认的 Java 类路径中，这是必需的。

调用 addToClasspath() 将调用 org.ringojs.engine.AppClassLoader，它是 java.net.URLClassLoader 的子类。它检查 URL 是否已经被加载，如果没有，则将其添加到资源搜索路径。如果给定的 URL 以/结尾，则它将被视为资源目录，否则将被视为引用 .jar 文件。 .jar 文件封装了不同包中的各种 .class 文件，而资源目录是 JVM 的任意 .class 查找的起点。如果函数无法加载路径或失败，则该函数将引发异常。

Example

// Adds Apache Lucene text search engine to the classpath
addToClasspath("../jars/lucene-core.jar");

Parameters

String|Resource|Repository path

a directory or jar path; or a single resource; or a repository

arguments

参数数组包含 RingoJS 开始的命令行参数。

请注意，这个变量被函数内部的 arguments 对象遮蔽，这就是为什么通常使用 system.args 更安全的原因。

clearInterval (id)

取消先前使用 setInterval() 计划的超时。

Parameters

Object id

the id object returned by setInterval()

clearTimeout (id)

取消先前使用 setTimeout() 计划的超时。

Parameters

Object id

the id object returned by setTimeout()

console

调试控制台在 stderr 上打印消息。 它与大多数Web浏览器中实现的控制台对象类似。

Example

console.log('Hello World!');

See

console

defineClass (clazz)

将自定义的基于 Java 的主机对象加载到全局范围中。 这对于在JavaScript环境内提供对Java类的透明访问很有用。 它使用 ScriptableObject.defineClass() 来定义扩展。

Example

// org.somejavalib.Foo extends org.mozilla.javascript.ScriptableObject
defineClass(org.somejavalib.Foo);
var x = new Foo();

Parameters

java.lang.Class clazz

the host object's Java class

See

ECMAScript 5 host object definition
Rhino's ScriptableObject.defineClass()
Java 包 org.ringojs.wrappers 包含典型的主机对象，如 Binary，EventAdapter 和 Stream。

environment

环境对象包含 Java 系统属性。

export (name...)

从该模块中导出任意数量的顶级名称。

这是导出对象的非标准替代方式，用于以较不详细和侵入性的方式 导出 值。

Example

// equivalent to exports.foo = function() { ... }
// and exports.bar = function() { ... }
export(
  "foo",
  "bar"
);

function foo() { ... };
function bar() { ... };

Parameters

String... name...

one or more names of exported properties

exports

在 CommonJS Modules 1.1.1 规范中定义的exports对象。

在exports对象上定义属性，以使其可用于 需要 此模块的其他模块。

Example

exports.multiply = function(x, y) { return x * y; }

gc ()

运行垃圾回收器。

getRepository (path)

按照相同的逻辑解析路径需要使用模块 ID 并返回代表解析路径的 org.ringojs.repository.Repository 的实例。存储库提供脚本和其他应用程序资源的统一加载。它代表了一个抽象的资源容器。对于文件 I / O，使用 fs 模块，它为文件和流操作提供精细的函数。

Example

> var fileRepository = getRepository("/usr/local/httpd/htdocs/");
> var resource = fileRepository.getResource("someFile.xml");
> resource.getUrl();
[java.net.URL file:/usr/local/httpd/htdocs/someFile.xml]

Parameters

String path

the repository path

Returns

org.ringojs.repository.Repository

a repository

getResource (path)

按照相同逻辑解析路径需要使用模块 ID 并返回代表解析路径的 org.ringojs.repository.Resource 的实例。它代表一个资源的抽象容器。对于文件I / O，使用 fs 模块，它为文件和流操作提供精细的函数。

Example

// Current working directory: /usr/local/httpd/htdocs/
> var resource = getResource("./someFile.xml");
>
> resource.getChecksum();
1419793411000
>
> resource.getUrl();
[java.net.URL file:/usr/local/httpd/htdocs/someFile.xml]
>
> resource.getBaseName();
someFile
>
> resource.exists();
true
>
> // read the content
> resource.getContent();
'<?xml version="1.0" encoding="UTF-8"?> ...

Parameters

String path

the resource path

Returns

org.ringojs.repository.Resource

a resource

global

对全局对象本身的引用。

当一个模块在 RingoJS 中进行评估时，它使用自己的私有模块范围，该模块又将此共享全局对象用作原型。因此，全局对象的属性在每个模块中都可见。

由于全局对象隐藏在模块范围的原型链中，因此通常无法直接访问它。这个引用允许你这样做，如果你想这样做，定义真正的全局变量。

Example

global.foo = "bar";

include (moduleId)

加载一个模块并将其所有属性包含在调用范围中。

Example

include('fs');
// calls fs.isReadable()
if (isReadable('essay.txt') ) { ... }

Parameters

String moduleId

the id or path of the module to load

load (filename...)

加载由字符串参数命名的 JavaScript 源文件并执行它们。如果给出多个参数，则会依次读入并执行每个文件。

Parameters

String... filename...

one or more file names

module

CommonJS模块1.1.1 规范中定义的模块对象。

RingoJS模块对象具有以下属性：

module.directory

包含此模块的目录。

module.exports

默认情况下，module.exports 引用 exports 对象。将该属性设置为不同的值将导致该值被用作导出对象。

module.id

该模块的模块 ID。

Example

// We are inside the foo.js module
// prints /usr/local/ringo-app/lib/foo
console.log(module.id);

module.path

这个模块的源代码的绝对路径。

module.resolve (path)

解析相对于此模块的路径。解析自身等价于使用以'./'开头的严格相对路径调用 require。如果提供了绝对路径，则该函数仍将相对于当前模块进行解析，而不会解析为文件系统根目录。

Example

// current module is located at /usr/local/a/b/module.js
module.resolve('.')          // -> /usr/local/a/b/
module.resolve('./other.js') // -> /usr/local/a/b/other.js
module.resolve('../c/d')     // -> /usr/local/a/c/d
module.resolve('/etc/hosts') // -> /usr/local/a/b/etc/hosts

Parameters

String path

Returns

String

the resolved path

module.singleton (id, factory)

module.singleton 允许使用相同模块在所有工作人员中创建单身人士。这意味着即使工作人员通常在自己的专用作用域和变量上运行，但对于所有并发工作线程，模块中的值最多只会实例化一次。

id 参数标识模块中的单例。当使用尚未初始化的 id 调用 module.singleton 并且定义了 factory 参数时，将调用 factory，并且其返回值此后将用作给定id的单例值。

一旦设置了单例的值，就不会再调用工厂函数，并且使用该 id 对 module.singleton 的所有调用都会返回该原始值。

module.singleton 支持延迟初始化。如果 module.singleton 在没有工厂参数的情况下被调用，单例可以保持未定义。在这种情况下，module.singleton 直到首次使用工厂参数调用时才返回 undefined。

Example

// db-controller.js
// Create a single cache for all workers
var entityCache = module.singleton("entityCache", function() {
  return new SomeFancyCache(1000);
});

// All instances of "db-controller" in different workers
// will use the same cache because it's a singleton
entityCache.put("somekey", { ... });
entityCache.get("somekey");

Parameters

String id

the singleton id
Function factory

(optional) factory function for the singleton

Returns

the singleton value

module.uri

这个模块的 URI。

Example

// We are inside the foo.js module
// prints: /usr/local/ringo-app/lib/foo.js
console.log(module.uri);

print (args...)

将每个参数转换为一个字符串并打印出来。

Parameters

*... args...

one ore more arguments

privileged (func)

使用当前代码库的特权调用 func，而不是调用堆栈中代码的特权。

在使用 -P 或 --policy 命令行开关启用 Java 安全管理器的情况下运行时，这非常有用。

Parameters

Function func

a function

Returns

Object

the return value of the function

quit ()

退出 RingoJS 外壳。如果在提示符处键入文件结束符（CTRL-D），则 shell 也将以交互模式退出。

require (moduleId)

CommonJS模块1.1.1 规范中定义的require函数。

遵循以下规则解决 moduleId 问题：

  • 如果 moduleId 以 './' 或 '../' 开头，则相对于当前模块进行解析。
  • 如果 moduleId 是相对的（从文件或目录名开始），它将相对于模块搜索路径进行解析。
  • 如果路径是绝对路径（例如以 '/' 开始），则它被解释为绝对文件名。

RingoJS require 功能具有以下属性：

Parameters

String moduleId

the id or path of the module to load

Returns

Object

the exports object of the required module

require.extensions

用于扩展方式的对象 需要 加载模块。

使用文件扩展名作为键和作为值的函数。该函数应接受一个 Resource 对象作为参数，并返回一个字符串作为 JavaScript 模块源或一个将直接由 require 返回的对象。

例如，以下单行命令将使 require() 能够将 XML 文件作为 E4X 模块加载:

require.extensions['.xml'] = function(r) new XML(r.content);

require.main

如果 RingoJS 以命令行脚本启动，require.main 将包含主模块的模块对象。否则，该属性被定义，但具有未定义的值。

Example

// is the current module is the main module?
 if (require.main === module) {
  // Start up actions like in a Java public static void main() method
  var server = new Server();
  server.start();
}

require.paths

包含模块搜索路径的数组。你可以在这个数组中添加或删除路径项目，以改变 RingoJS 寻找模块的地方。

seal (obj)

密封指定的对象，以便尝试添加，删除或修改其属性会引发异常。

Parameters

Object obj

a JavaScript object

setInterval (callback, delay, args...)

重复调用一个函数，每次调用函数之间都有固定的时间延迟。该函数将在本地事件循环的线程中调用。这意味着它只会在当前正在执行的代码和其他代码在其终止之前运行之后才运行。

Parameters

Function callback

a function
Number delay

the delay in milliseconds
*... args...

optional arguments to pass to the function

Returns

Object

an id object useful for cancelling the scheduled invocation

setTimeout (callback, delay, [args...])

在指定的延迟后执行一个功能。该函数将在本地事件循环的线程中调用。这意味着它只会在当前正在执行的代码和其他代码在其终止之前运行之后才运行。

Parameters

Function callback

a function
Number delay

the delay in milliseconds
*... [args...]

optional arguments to pass to the function

Returns

Object

an id object useful for cancelling the scheduled invocation

spawn (func)

在内部线程池的新线程中调用func并立即返回。

Parameters

Function func

a function

sync (func, [obj])

返回一个封装函数，该函数在原始函数或第二个参数（如果提供）上同步。

当多个线程调用在同一个对象上同步的函数时，一次只允许执行一个函数调用。

Example

exports.synchronizedFunction = sync(function() {
  // no two threads can execute this code in parallel
});

Parameters

Function func

a function
Object [obj]

optional object to synchronize on

Returns

Function

a synchronized wrapper around the function