From 1ef609ca8ffe8ef5b77cf66cc1a99b37c60c0f90 Mon Sep 17 00:00:00 2001 From: Athijegannathan Sundararajan Date: Tue, 12 Jan 2016 17:08:18 +0530 Subject: [PATCH] 8068938: javax.script package description should specify use of ServiceLoader Reviewed-by: alanb, hannesw --- .../javax/script/ScriptEngineFactory.java | 12 ++- .../javax/script/ScriptEngineManager.java | 5 +- .../classes/javax/script/package-info.java | 94 ++++++++++++++++ .../share/classes/javax/script/package.html | 102 ------------------ 4 files changed, 104 insertions(+), 109 deletions(-) create mode 100644 jdk/src/java.scripting/share/classes/javax/script/package-info.java delete mode 100644 jdk/src/java.scripting/share/classes/javax/script/package.html diff --git a/jdk/src/java.scripting/share/classes/javax/script/ScriptEngineFactory.java b/jdk/src/java.scripting/share/classes/javax/script/ScriptEngineFactory.java index 2afe0c25769..f1071d760bd 100644 --- a/jdk/src/java.scripting/share/classes/javax/script/ScriptEngineFactory.java +++ b/jdk/src/java.scripting/share/classes/javax/script/ScriptEngineFactory.java @@ -31,12 +31,14 @@ import java.util.List; * ScriptEngineFactory is used to describe and instantiate * ScriptEngines. *

- * Each class implementing ScriptEngine has a corresponding factory - * that exposes metadata describing the engine class. + * Each class implementing ScriptEngine has a corresponding + * factory that exposes metadata describing the engine class. *

The ScriptEngineManager - * uses the service provider mechanism described in the Jar File Specification to obtain - * instances of all ScriptEngineFactories available in - * the current ClassLoader. + * uses the service-provider loader mechanism described in the + * {@link java.util.ServiceLoader} class to obtain + * instances of {@code ScriptEngineFactory} instances. + * See {@link ScriptEngineManager#ScriptEngineManager()} and + * {@link ScriptEngineManager#ScriptEngineManager(java.lang.ClassLoader)}. * * @since 1.6 */ diff --git a/jdk/src/java.scripting/share/classes/javax/script/ScriptEngineManager.java b/jdk/src/java.scripting/share/classes/javax/script/ScriptEngineManager.java index 9423bec47a6..9ff154d3210 100644 --- a/jdk/src/java.scripting/share/classes/javax/script/ScriptEngineManager.java +++ b/jdk/src/java.scripting/share/classes/javax/script/ScriptEngineManager.java @@ -33,7 +33,8 @@ import java.util.ServiceConfigurationError; * The ScriptEngineManager implements a discovery and instantiation * mechanism for ScriptEngine classes and also maintains a * collection of key/value pairs storing state shared by all engines created - * by the Manager. This class uses the service provider 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 ScriptEngineFactory.

* The ScriptEngineManager 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 @@ -64,7 +65,7 @@ public class ScriptEngineManager { /** * This constructor loads the implementations of * ScriptEngineFactory visible to the given - * ClassLoader using the service provider mechanism.

+ * ClassLoader using the service provider mechanism.

* If loader is null, the script engine factories that are * bundled with the platform are loaded.
* diff --git a/jdk/src/java.scripting/share/classes/javax/script/package-info.java b/jdk/src/java.scripting/share/classes/javax/script/package-info.java new file mode 100644 index 00000000000..90cf6b5a1d2 --- /dev/null +++ b/jdk/src/java.scripting/share/classes/javax/script/package-info.java @@ -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. + */ + +/** + +

The scripting API consists of interfaces and classes that define +Java™ 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. +

+

The main areas of functionality of javax.script +package include +

+
    +

  1. Script execution: 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. +

    +

  2. Binding: 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. +

    +

  3. Compilation: 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 instanceof check. +

    +

  4. Invocation: 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. +

    +

  5. Script engine discovery: 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. ScriptEngineFactory has +methods to query attributes about script engine. +

    +
+ +@since 1.6 +*/ + +package javax.script; + diff --git a/jdk/src/java.scripting/share/classes/javax/script/package.html b/jdk/src/java.scripting/share/classes/javax/script/package.html deleted file mode 100644 index dd83b6bd9dd..00000000000 --- a/jdk/src/java.scripting/share/classes/javax/script/package.html +++ /dev/null @@ -1,102 +0,0 @@ - - - - - - - -

The scripting API consists of interfaces and classes that define -Java™ 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. -

-

The main areas of functionality of javax.script -package include -

-
    -

  1. Script execution: 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. -

    -

  2. Binding: 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. -

    -

  3. Compilation: 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 instanceof check. -

    -

  4. Invocation: 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. -

    -

  5. Script engine discovery and Metadata: 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 Jar File Specification. - Script engine implementing classes are packaged in jar files that - include a text resource named - META-INF/services/javax.script.ScriptEngineFactory. 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. ScriptEngineFactory has - methods to query attributes about script engine. -

    -
- -@since 1.6 - - -