changeset 13449:67ecd47614dc

8068938: javax.script package description should specify use of ServiceLoader Reviewed-by: alanb, hannesw
author sundar
date Tue, 12 Jan 2016 17:08:18 +0530
parents d09282af3b52
children f0cf478dc546 b14117a57650 dfb7f209f1a2
files src/java.scripting/share/classes/javax/script/ScriptEngineFactory.java src/java.scripting/share/classes/javax/script/ScriptEngineManager.java src/java.scripting/share/classes/javax/script/package-info.java src/java.scripting/share/classes/javax/script/package.html
diffstat 4 files changed, 104 insertions(+), 109 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.scripting/share/classes/javax/script/ScriptEngineFactory.java	Tue Jan 12 08:05:16 2016 +0000
+++ b/src/java.scripting/share/classes/javax/script/ScriptEngineFactory.java	Tue Jan 12 17:08:18 2016 +0530
@@ -31,12 +31,14 @@
  * <code>ScriptEngineFactory</code> is used to describe and instantiate
  * <code>ScriptEngines</code>.
  * <br><br>
- * Each class implementing <code>ScriptEngine</code> has a corresponding factory
- * that exposes metadata describing the engine class.
+ * Each class implementing <code>ScriptEngine</code> has a corresponding
+ * factory that exposes metadata describing the engine class.
  * <br><br>The <code>ScriptEngineManager</code>
- * uses the service provider mechanism described in the <i>Jar File Specification</i> to obtain
- * instances of all <code>ScriptEngineFactories</code> 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
  */
--- a/src/java.scripting/share/classes/javax/script/ScriptEngineManager.java	Tue Jan 12 08:05:16 2016 +0000
+++ b/src/java.scripting/share/classes/javax/script/ScriptEngineManager.java	Tue Jan 12 17:08:18 2016 +0530
@@ -33,7 +33,8 @@
  * The <code>ScriptEngineManager</code> implements a discovery and instantiation
  * mechanism for <code>ScriptEngine</code> classes and also maintains a
  * 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>
  * 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
@@ -64,7 +65,7 @@
     /**
      * This constructor loads the implementations of
      * <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
      * bundled with the platform are loaded. <br>
      *
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/java.scripting/share/classes/javax/script/package-info.java	Tue Jan 12 17:08:18 2016 +0530
@@ -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;
+
--- a/src/java.scripting/share/classes/javax/script/package.html	Tue Jan 12 08:05:16 2016 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -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>