1berry/openjdk
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

8068938: javax.script package description should specify use of ServiceLoader

Browse Source 
Reviewed-by: alanb, hannesw
This commit is contained in:
Athijegannathan Sundararajan 2016-01-12 17:08:18 +05:30
parent 26616a3176
commit 1ef609ca8f
4 changed files with 104 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
jdk/src/java.scripting/share/classes/javax/script/ScriptEngineFactory.java
View File

@ -31,12 +31,14 @@ import java.util.List;
* <code>ScriptEngineFactory</code> is used to describe and instantiate * <code>ScriptEngineFactory</code> is used to describe and instantiate
* <code>ScriptEngines</code>. * <code>ScriptEngines</code>.
* <br><br> * <br><br>
* Each class implementing <code>ScriptEngine</code> has a corresponding factory * Each class implementing <code>ScriptEngine</code> has a corresponding
* that exposes metadata describing the engine class. * factory that exposes metadata describing the engine class.
* <br><br>The <code>ScriptEngineManager</code> * <br><br>The <code>ScriptEngineManager</code>
* uses the service provider mechanism described in the <i>Jar File Specification</i> to obtain * uses the service-provider loader mechanism described in the
* instances of all <code>ScriptEngineFactories</code> available in * {@link java.util.ServiceLoader} class to obtain
* the current ClassLoader. * instances of {@code ScriptEngineFactory} instances.
* See {@link ScriptEngineManager#ScriptEngineManager()} and
* {@link ScriptEngineManager#ScriptEngineManager(java.lang.ClassLoader)}.
* *
* @since 1.6 * @since 1.6
*/ */

5
jdk/src/java.scripting/share/classes/javax/script/ScriptEngineManager.java
View File

@ -33,7 +33,8 @@ import java.util.ServiceConfigurationError;
* The <code>ScriptEngineManager</code> implements a discovery and instantiation * The <code>ScriptEngineManager</code> implements a discovery and instantiation
* mechanism for <code>ScriptEngine</code> classes and also maintains a * mechanism for <code>ScriptEngine</code> classes and also maintains a
* collection of key/value pairs storing state shared by all engines created * collection of key/value pairs storing state shared by all engines created
* by the Manager. This class uses the <a href="../../../technotes/guides/jar/jar.html#Service%20Provider">service provider</a> mechanism to enumerate all the * by the Manager. This class uses the service provider mechanism described in the
* {@link java.util.ServiceLoader} class to enumerate all the
* implementations of <code>ScriptEngineFactory</code>. <br><br> * implementations of <code>ScriptEngineFactory</code>. <br><br>
* The <code>ScriptEngineManager</code> provides a method to return a list of all these factories * The <code>ScriptEngineManager</code> provides a method to return a list of all these factories
* as well as utility methods which look up factories on the basis of language name, file extension * as well as utility methods which look up factories on the basis of language name, file extension
@ -64,7 +65,7 @@ public class ScriptEngineManager {
/** /**
* This constructor loads the implementations of * This constructor loads the implementations of
* <code>ScriptEngineFactory</code> visible to the given * <code>ScriptEngineFactory</code> visible to the given
* <code>ClassLoader</code> using the <a href="../../../technotes/guides/jar/jar.html#Service%20Provider">service provider</a> mechanism.<br><br> * <code>ClassLoader</code> using the service provider mechanism.<br><br>
* If loader is <code>null</code>, the script engine factories that are * If loader is <code>null</code>, the script engine factories that are
* bundled with the platform are loaded. <br> * bundled with the platform are loaded. <br>
* *

94
jdk/src/java.scripting/share/classes/javax/script/package-info.java Normal file
View File

@ -0,0 +1,94 @@
/*
* Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
<p>The scripting API consists of interfaces and classes that define
Java&trade; Scripting Engines and provides
a framework for their use in Java applications. This API is intended
for use by application programmers who wish to execute programs
written in scripting languages in their Java applications. The
scripting language programs are usually provided by the end-users of
the applications.
</p>
<p>The main areas of functionality of <code>javax.script</code>
package include
</p>
<ol>
<li><p><b>Script execution</b>: Scripts
are streams of characters used as sources for programs executed by
script engines. Script execution uses
{@link javax.script.ScriptEngine#eval eval} methods of
{@link javax.script.ScriptEngine ScriptEngine} and methods of the
{@link javax.script.Invocable Invocable} interface.
</p>
<li><p><b>Binding</b>: This facility
allows Java objects to be exposed to script programs as named
variables. {@link javax.script.Bindings Bindings} and
{@link javax.script.ScriptContext ScriptContext}
classes are used for this purpose.
</p>
<li><p><b>Compilation</b>: This
functionality allows the intermediate code generated by the
front-end of a script engine to be stored and executed repeatedly.
This benefits applications that execute the same script multiple
times. These applications can gain efficiency since the engines'
front-ends only need to execute once per script rather than once per
script execution. Note that this functionality is optional and
script engines may choose not to implement it. Callers need to check
for availability of the {@link javax.script.Compilable Compilable}
interface using an <I>instanceof</I> check.
</p>
<li><p><b>Invocation</b>: This
functionality allows the reuse of intermediate code generated by a
script engine's front-end. Whereas Compilation allows entire scripts
represented by intermediate code to be re-executed, Invocation
functionality allows individual procedures/methods in the scripts to
be re-executed. As in the case with compilation, not all script
engines are required to provide this facility. Caller has to check
for {@link javax.script.Invocable Invocable} availability.
</p>
<li><p><b>Script engine discovery</b>: Applications
written to the Scripting API might have specific requirements on
script engines. Some may require a specific scripting language
and/or version while others may require a specific implementation
engine and/or version. Script engines are packaged in a specified
way so that engines can be discovered at runtime and queried for
attributes. The Engine discovery mechanism is based on the service-provider
loading facility described in the {@link java.util.ServiceLoader} class.
{@link javax.script.ScriptEngineManager ScriptEngineManager}
includes
{@link javax.script.ScriptEngineManager#getEngineFactories getEngineFactories} method to get all
{@link javax.script.ScriptEngineFactory ScriptEngineFactory} instances
discovered using this mechanism. <code>ScriptEngineFactory</code> has
methods to query attributes about script engine.
</p>
</ol>
@since 1.6
*/
package javax.script;

102
jdk/src/java.scripting/share/classes/javax/script/package.html
View File

@ -1,102 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
</head>
<body bgcolor="white">
<p>The scripting API consists of interfaces and classes that define
Java&trade; Scripting Engines and provides
a framework for their use in Java applications. This API is intended
for use by application programmers who wish to execute programs
written in scripting languages in their Java applications. The
scripting language programs are usually provided by the end-users of
the applications.
</p>
<p>The main areas of functionality of <code>javax.script</code>
package include
</p>
<ol>
<li><p><b>Script execution</b>: Scripts
are streams of characters used as sources for programs executed by
script engines. Script execution uses
{@link javax.script.ScriptEngine#eval eval} methods of
{@link javax.script.ScriptEngine ScriptEngine} and methods of the
{@link javax.script.Invocable Invocable} interface.
</p>
<li><p><b>Binding</b>: This facility
allows Java objects to be exposed to script programs as named
variables. {@link javax.script.Bindings Bindings} and
{@link javax.script.ScriptContext ScriptContext}
classes are used for this purpose.
</p>
<li><p><b>Compilation</b>: This
functionality allows the intermediate code generated by the
front-end of a script engine to be stored and executed repeatedly.
This benefits applications that execute the same script multiple
times. These applications can gain efficiency since the engines'
front-ends only need to execute once per script rather than once per
script execution. Note that this functionality is optional and
script engines may choose not to implement it. Callers need to check
for availability of the {@link javax.script.Compilable Compilable}
interface using an <I>instanceof</I> check.
</p>
<li><p><b>Invocation</b>: This
functionality allows the reuse of intermediate code generated by a
script engine's front-end. Whereas Compilation allows entire scripts
represented by intermediate code to be re-executed, Invocation
functionality allows individual procedures/methods in the scripts to
be re-executed. As in the case with compilation, not all script
engines are required to provide this facility. Caller has to check
for {@link javax.script.Invocable Invocable} availability.
</p>
<li><p><b>Script engine discovery and Metadata</b>: Applications
written to the Scripting API might have specific requirements on
script engines. Some may require a specific scripting language
and/or version while others may require a specific implementation
engine and/or version. Script engines are packaged in a specified
way so that engines can be discovered at runtime and queried for
attributes. The Engine discovery mechanism is based on the Service
discovery mechanism described in the <b>Jar File Specification</b>.
Script engine implementing classes are packaged in jar files that
include a text resource named
<b>META-INF/services/javax.script.ScriptEngineFactory</b>. This
resource must include a line for each
{@link javax.script.ScriptEngineFactory ScriptEngineFactory}
that is packaged in the jar file.
{@link javax.script.ScriptEngineManager ScriptEngineManager}
includes
{@link javax.script.ScriptEngineManager#getEngineFactories getEngineFactories} method to get all
{@link javax.script.ScriptEngineFactory ScriptEngineFactory} instances
discovered using this mechanism. <code>ScriptEngineFactory</code> has
methods to query attributes about script engine.
</p>
</ol>
@since 1.6
</body>
</html>