rhino/docs/tutorial.html at less_static · JavaScriptBench/rhino

History

336 lines (307 loc) · 14.3 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">

<html>

<head>

<title>Embedding Rhino</title>

</head>

<body>

<center>Tutorial: Embedding Rhino</center>

Embedding Rhino can be done simply with good results. With more effort

on the part of the embedder, the objects exposed to scripts can be customized

further.

This tutorial leads you through the steps from a simple embedding to

more customized, complex embeddings. Fully compilable examples are provided

along the way.

The examples live in the <tt>rhino/examples</tt> directory in the distribution

and in <tt>mozilla/js/rhino/examples</tt> in cvs. This document will link

to them using <a href="http://lxr.mozilla.org/">lxr</a>.

In this document, JavaScript code will be in green,

Java code will be in green, and shell logs

will be in purple.

<h3>

Contents</h3>

<ul>

<li>

<a href="#RunScript">RunScript: A simple embedding</a></li>

<ul>

<li>

<a href="#EnteringContext">Entering a Context</a></li>

<li>

<a href="#initializing">Initializing standard objects</a></li>

<li>

<a href="#Collecting">Collecting the arguments</a></li>

<li>

<a href="#Evaluating">Evaluating a script</a></li>

<li>

<a href="#Print">Print the result</a></li>

<li>

<a href="#Exit">Exit the Context</a></li>

</ul>

<li>

<a href="#Expose">Expose Java APIs</a></li>

<ul>

<li>

<li>

<a href="#ImplementingInterfaces">Implementing interfaces</a></li>

<li>

<a href="#AddJava">Add Java objects</a></li>

</ul>

<li>

<a href="#UsingJSObjs">Using JavaScript objects from Java</a></li>

<ul>

<li>

<a href="#UsingJSvars">Using JavaScript variables</a></li>

<li>

<a href="#CallingJSfuns">Calling JavaScript functions</a></li>

</ul>

<li>

<a href="#JavaScriptHostObjects">JavaScript host objects</a></li>

<ul>

<li>

<a href="#DefiningHostObjects">Defining Host Objects</a></li>

<li>

<a href="#Counter">Counter example</a></li>

<ul>

<li>

<a href="#CounterCtors">Counter's constructors</a></li>

<li>

<a href="#classname">Class name</a></li>

<li>

<a href="#Dynamic">Dynamic properties</a></li>

<li>

<a href="#DefiningMethods">Defining JavaScript "methods"</a></li>

<li>

<a href="#AddingCounter">Adding Counter to RunScript</a></li>

</ul>

<a NAME="RunScript"></a>RunScript: A simple embedding

About the simplest embedding of Rhino possible is the <a href="http://lxr.mozilla.org/mozilla/source/js/rhino/examples/RunScript.java">RunScript

example</a>. All it does it read a script from the command line, execute

it, and print a result.

Here's an example use of RunScript from a shell command line:

<pre>$ java RunScript 'Math.cos(Math.PI)'

-1

$ java RunScript 'function f(x){return x+1} f(7)'

8</pre>

</blockquote>

Note that you'll have to have both the Rhino classes and the RunScript

example class file in the classpath. Let's step through the body of <tt>main</tt>

one line at time.

<a NAME="EnteringContext"></a>Entering a Context

The code

<pre>Context cx = Context.enter();</pre>

</blockquote>

Creates and enters a <tt>Context. </tt>A <tt>Context</tt> stores information

about the execution environment of a script.

<a NAME="initializing"></a>Initializing standard objects

The code

<pre>Scriptable scope = cx.initStandardObjects(null);</pre>

</blockquote>

Initializes the standard objects (<tt>Object</tt>,

<tt>Function</tt>, etc.)

This must be done before scripts can be executed. The <tt>null</tt> parameter

tells <tt>initStandardObjects</tt> to create and return a scope object

that we use in later calls.

<a NAME="Collecting"></a>Collecting the arguments

This code is standard Java and not specific to Rhino. It just collects

all the arguments and concatenates them together.

<blockquote><tt>String s = "";</tt>

<a NAME="Evaluating"></a>Evaluating a script

The code

<pre>Object result = cx.evaluateString(scope, s, "<cmd>", 1, null);</pre>

</blockquote>

uses the Context <tt>cx</tt> to evaluate a string. Evaluation of the script

looks up variables in <tt>scope</tt>, and errors will be reported with

the filename <tt><cmd></tt> and line number 1.

<a NAME="Print"></a>Print the result

The code

<pre>System.out.println(cx.toString(result));</pre>

</blockquote>

prints the result of evaluating the script (contained in the variable <tt>result</tt>).

<tt>result</tt>

could be a string, JavaScript object, or other values..The

<tt>toString</tt>

method converts any JavaScript value to a string.

<a NAME="Exit"></a>Exit the Context

The code

<pre>Context.exit();</pre>

</blockquote>

exits the Context. This removes the association between the Context and

the current thread and is an essential cleanup action. There should be

a call to <tt>exit</tt> for every call to <tt>enter</tt>.

<a NAME="Expose"></a>Expose Java APIs

<a NAME="UseJava"></a>Use Java APIs

No additional code in the embedding needed! The JavaScript feature called

LiveConnect

allows JavaScript programs to interact with Java objects:

<dir><tt>$ java RunScript 'java.lang.System.out.println(3)'</tt>

<tt>undefined</tt></dir>

<a NAME="ImplementingInterfaces"></a>Implementing interfaces

Using Rhino, JavaScript objects can implement arbitrary Java interfaces.

There's no Java code to write--it's part of Rhino's LiveConnect implementation.

For example, we can see how to implement java.lang.Runnable in a Rhino

shell session:

<pre>js> obj = { run: function() { print('hi'); } }

[object Object]

js> obj.run()

js> r = new java.lang.Runnable(obj);

[object Object]

js> t = new java.lang.Thread(r)

Thread[Thread-0,5,main]

js> t.start()

hi</pre>

</blockquote>

<a NAME="AddJava"></a>Add Java objects

The next example is <a href="http://lxr.mozilla.org/mozilla/source/js/rhino/examples/RunScript2.java">RunScript2</a>.

This is the same as RunScript, but with the addition of two extra lines

of code:

<dir><tt>Scriptable jsArgs = Context.toObject(System.out,

scope);</tt>

<tt>scope.put("out", scope, jsArgs);</tt></dir>

These lines add a global variable <tt>out</tt> that is a JavaScript reflection

of the <tt>System.out</tt> variable:

<dir><tt>$ java RunScript2 'out.println(42)'</tt>

<tt>undefined</tt></dir>

<a NAME="UsingJSObjs"></a>Using JavaScript objects

from Java

After evaluating a script it's possible to query the scope for variables

and functions, extracting values and calling JavaScript functions. This

is illustrated in the <a href="http://lxr.mozilla.org/mozilla/source/js/rhino/examples/RunScript3.java">RunScript3</a>

example. This example adds the ability to print the value of variable <tt>x</tt>

and the result of calling function <tt>f</tt>. Both <tt>x</tt> and <tt>f</tt>

are expected to be defined by the evaluated script. For example,

<blockquote><tt>$ java RunScript3 'x = 7'</tt>

<tt>f is undefined or not a function.</tt>

<tt>$ java RunScript3 'function f(a) { return

a; }'</tt>

<tt>x is not defined.</tt>

<a NAME="UsingJSvars"></a>Using JavaScript variables

To print out the value of <tt>x</tt>, we add the following code.

<dir><tt>Object x = scope.get("x", scope);</tt>

<tt>if (x == Scriptable.NOT_FOUND)</tt>

<tt>    System.out.println("x

is not defined.");</tt>

<tt>    System.out.println("x

= " + Context.toString(x));</tt>

<a NAME="CallingJSfuns"></a>Calling JavaScript functions

To get the function <tt>f</tt>, call it, and print the result, we add

this code:

<dir><tt>Object f = scope.get("f", scope);</tt>

<tt>if (!(f instanceof Function))</tt>

<tt>    System.out.println("f

is undefined or not a function.");</tt>

<tt>    Object functionArgs[]

= { "my arg" };</tt>

<tt>    Object result = ((Function)

f).call(cx, scope, scope, functionArgs);</tt>

<tt>    System.out.println("f('my

args') = " + Context.toString(result));</tt>

<a NAME="JavaScriptHostObjects"></a>JavaScript host

objects

<a NAME="DefiningHostObjects"></a>Defining Host Objects

Custom host objects can implement special JavaScript features like dynamic

properties.

<a NAME="Counter"></a>Counter example

The <a href="http://lxr.mozilla.org/mozilla/source/js/rhino/examples/Counter.java">Counter

example</a> is a simple host object. We'll go through it method by method

below.

It's easy to try out new host object classes in the shell using its

built-in <tt>defineClass</tt> function. We'll see how to add it to RunScript

later. (Note that because the <tt>java -jar</tt> option preempts the rest

of the classpath, we can't use that and access the <tt>Counter</tt> class.)

<pre>$ java -cp 'js.jar;examples' org.mozilla.javascript.tools.shell.Main

js> defineClass("Counter")

js> c = new Counter(7)

[object Counter]

js> c.count

js> c.resetCount()

js> c.count

0</pre>

</blockquote>

<a NAME="CounterCtors"></a>Counter's constructors

The zero-argument constructor is used by Rhino runtime to create instances.

For the counter example, no initialization work is needed, so the implementation

is empty.

<dir><tt>public Counter () { }</tt></dir>

The method <tt>jsConstructor</tt> defines the JavaScript constructor that

was called with the expression <tt>new Counter(7)</tt> in the JavaScript

code above.

<dir><tt>public void jsConstructor(int a) { count

= a; }</tt></dir>

<a NAME="classname"></a>Class name

The class name is defined by the <tt>getClassName</tt> method. This

is used to determine the name of the constructor.

<dir><tt>public String getClassName() { return "Counter";

}</tt></dir>

<a NAME="Dynamic"></a>Dynamic properties

Dynamic properties are defined by methods beginning with <tt>jsGet_</tt>

or <tt>jsSet_</tt>. The method <tt>jsGet_count</tt> defines the count

property.

<dir><tt>public int jsGet_count() { return count++;

}</tt></dir>

The expression <tt>c.count</tt> in the JavaScript code above results in

a call to this method.

<a NAME="DefiningMethods"></a>Defining JavaScript "methods"

Methods can be defined using the <tt>jsFunction_ prefix</tt>. Here we

define <tt>resetCount</tt> for JavaScript.

<dir><tt>public void jsFunction_resetCount() { count

= 0; }</tt></dir>

The call <tt>c.resetCount()</tt> above calls this method.

<a NAME="AddingCounter"></a>Adding Counter to RunScript

Now take a look at the <a href="http://lxr.mozilla.org/mozilla/source/js/rhino/examples/RunScript4.java">RunScript4

example</a>. It's the same as RunScript except for two additions. The method

<tt>ScriptableObject.defineClass</tt>

uses a Java class to define the Counter "class" in the top-level scope:

<dir><tt>ScriptableObject.defineClass(scope, Counter.class);</tt></dir>

Now we can reference the <tt>Counter</tt> object from our script:

<dir><tt>$ java RunScript4 'c = new Counter(3); c.count;

c.count;'</tt>

It also creates a new instance of the <tt>Counter</tt> object from within

our Java code, constructing it with the value 7, and assigning it to the

top-level variable <tt>myCounter</tt>:

<dir><tt>Object[] arg = { new Integer(7) };</tt>

<tt>Scriptable myCounter = cx.newObject(scope,

"Counter", arg);</tt>

<tt>scope.put("myCounter", scope, myCounter);</tt></dir>

Now we can reference the <tt>myCounter</tt> object from our script:

<dir><tt>$ java RunScript3 'RunScript4 'myCounter.count;

myCounter.count'</tt>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

tutorial.html

Latest commit

History

tutorial.html

File metadata and controls