changeset 814:8c53a58a5b72

8044415: ant makefile should have a target to generate javadoc only for jdk.nashorn.api and sub-packages Reviewed-by: jlaskey
author sundar
date Fri, 30 May 2014 17:22:38 +0530
parents 32b66f4661ea
children fed8c83dfba4
files make/build.xml samples/filebrowser.js samples/word_histogram.js src/jdk/nashorn/api/scripting/ScriptObjectMirror.java src/jdk/nashorn/api/scripting/package-info.java src/jdk/nashorn/internal/ir/annotations/Reference.java
diffstat 6 files changed, 174 insertions(+), 6 deletions(-) [+]
line wrap: on
line diff
--- a/make/build.xml	Tue May 27 17:40:19 2014 +0530
+++ b/make/build.xml	Fri May 30 17:22:38 2014 +0530
@@ -196,14 +196,16 @@
     </jar>
   </target>
 
-  <target name="javadoc" depends="prepare">
-    <javadoc destdir="${dist.javadoc.dir}" use="yes" overview="src/overview.html" windowtitle="${nashorn.product.name} ${nashorn.version}" additionalparam="-quiet" failonerror="true">
+  <target name="javadoc" depends="jar">
+    <javadoc destdir="${dist.javadoc.dir}" use="yes" overview="src/overview.html" 
+        extdirs="${nashorn.ext.path}" windowtitle="${nashorn.product.name} ${nashorn.version}"
+        additionalparam="-quiet" failonerror="true">
       <classpath>
         <pathelement location="${build.classes.dir}"/>
       </classpath>
       <fileset dir="${src.dir}" includes="**/*.java"/>
       <fileset dir="${jdk.asm.src.dir}" includes="**/*.java"/>
-      <link href="http://docs.oracle.com/javase/7/docs/api/"/>
+      <link href="http://docs.oracle.com/javase/8/docs/api/"/>
       <!-- The following tags are used only in ASM sources - just ignore these -->
       <tag name="label" description="label tag in ASM sources" enabled="false"/>
       <tag name="linked" description="linked tag in ASM sources" enabled="false"/>
@@ -211,6 +213,19 @@
     </javadoc>
   </target>
 
+  <!-- generate javadoc only for nashorn extension api classes -->
+  <target name="javadocapi" depends="jar">
+    <javadoc destdir="${dist.javadoc.dir}" use="yes" extdirs="${nashorn.ext.path}" 
+        windowtitle="${nashorn.product.name}" additionalparam="-quiet" failonerror="true">
+      <classpath>
+        <pathelement location="${build.classes.dir}"/>
+      </classpath>
+      <fileset dir="${src.dir}" includes="jdk/nashorn/api/**/*.java"/>
+      <link href="http://docs.oracle.com/javase/8/docs/api/"/>
+    </javadoc>
+  </target>
+
+
   <!-- generate shell.html for shell tool documentation -->
   <target name="shelldoc" depends="jar">
     <java classname="${nashorn.shell.tool}" dir="${basedir}" output="${dist.dir}/shell.html" failonerror="true" fork="true">
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/samples/filebrowser.js	Fri May 30 17:22:38 2014 +0530
@@ -0,0 +1,100 @@
+#// Usage: jjs -fx filebrowser.js -- <start_dir>
+
+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ * 
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ * 
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+// Uses -fx and javafx TreeView to visualize directories
+if (!$OPTIONS._fx) {
+    print("Usage: jjs -fx filebrowser.js -- <start_dir>");
+    exit(1);
+}
+
+// Java classes used
+var File = Java.type("java.io.File");
+var Files = Java.type("java.nio.file.Files");
+
+// check directory argument, if passed
+var dir = arguments.length > 0? new File(arguments[0]) : new File(".");
+if (! dir.isDirectory()) {
+    print(dir + " is not a directory!");
+    exit(2);
+}
+
+// JavaFX classes used
+var FXCollections = Java.type("javafx.collections.FXCollections");
+var Scene     = Java.type("javafx.scene.Scene");
+var TreeItem  = Java.type("javafx.scene.control.TreeItem");
+var TreeView  = Java.type("javafx.scene.control.TreeView");
+
+// create a subclass of JavaFX TreeItem class
+var LazyTreeItem = Java.extend(TreeItem);
+
+// lazily filling children of a directory LazyTreeItem
+function buildChildren(dir) {
+    var children = FXCollections.observableArrayList();
+    var stream = Files.list(dir.toPath());
+    stream.forEach(function(path) {
+        var file = path.toFile();
+        var item = file.isDirectory()?
+            makeLazyTreeItem(file) : new TreeItem(file.name);
+        children.add(item);
+    });
+    stream.close();
+    return children;
+}
+
+// create an instance LazyTreeItem with override methods
+function makeLazyTreeItem(dir) {
+    var item = new LazyTreeItem(dir.name) {
+        expanded: false,
+        isLeaf: function() false,
+        getChildren: function() {
+            if (! this.expanded) {
+                // call super class (TreeItem) method
+                Java.super(item).getChildren().setAll(buildChildren(dir));
+                this.expanded = true;
+            }
+            // call super class (TreeItem) method
+            return Java.super(item).getChildren();
+        }
+    }
+    return item;
+}
+
+// JavaFX start method
+function start(stage) {
+    stage.title = dir.absolutePath;
+    var rootItem = makeLazyTreeItem(dir);
+    rootItem.expanded = true;
+    var tree = new TreeView(rootItem);
+    stage.scene = new Scene(tree, 300, 450);
+    stage.show();
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/samples/word_histogram.js	Fri May 30 17:22:38 2014 +0530
@@ -0,0 +1,53 @@
+#nashorn word histogram of a file
+
+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 
+ *   - Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ * 
+ *   - Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ * 
+ *   - Neither the name of Oracle nor the names of its
+ *     contributors may be used to endorse or promote products derived
+ *     from this software without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This example demonstrates how to print word histogram
+ * of a given text file using regex, array and JSON
+ * functions.
+ */
+
+if (arguments.length < 1) {
+    print("Usage: jjs -scripting word_histogram.js -- <file>");
+    exit(1);
+}
+
+var obj = {};
+
+readFully(arguments[0]).
+    split(/[^\w+]/).
+    forEach(function(x)
+      (x in obj? obj[x]++ : obj[x] = 1));
+
+print(JSON.stringify(obj));
+
--- a/src/jdk/nashorn/api/scripting/ScriptObjectMirror.java	Tue May 27 17:40:19 2014 +0530
+++ b/src/jdk/nashorn/api/scripting/ScriptObjectMirror.java	Fri May 30 17:22:38 2014 +0530
@@ -621,6 +621,7 @@
     /**
      * Utilitity to convert this script object to the given type.
      *
+     * @param <T> destination type to convert to
      * @param type destination type to convert to
      * @return converted object
      */
--- a/src/jdk/nashorn/api/scripting/package-info.java	Tue May 27 17:40:19 2014 +0530
+++ b/src/jdk/nashorn/api/scripting/package-info.java	Fri May 30 17:22:38 2014 +0530
@@ -32,7 +32,8 @@
  * ScriptEngine nashornEngine = new ScriptEngineManager().getEngineByName("Nashorn");
  * </pre>
  * <p>Nashorn script engines implement the optional {@link javax.script.Invocable} and {@link javax.script.Compilable}
- * interfaces, allowing for efficient pre-compilation and repeated execution of scripts. See
+ * interfaces, allowing for efficient pre-compilation and repeated execution of scripts. In addition,
+ * this package provides nashorn specific extension classes, interfaces and methods. See
  * {@link jdk.nashorn.api.scripting.NashornScriptEngineFactory} for further details.
  */
 package jdk.nashorn.api.scripting;
--- a/src/jdk/nashorn/internal/ir/annotations/Reference.java	Tue May 27 17:40:19 2014 +0530
+++ b/src/jdk/nashorn/internal/ir/annotations/Reference.java	Fri May 30 17:22:38 2014 +0530
@@ -32,9 +32,7 @@
  * Reference node in AST, i.e. anything not a copy. Important for
  * AST traversal and cloning. Cloning currently as a rule uses
  * existingOrSame for references and otherwise existingOrCopy
- * <p>
  */
-
 @Retention(value=RetentionPolicy.RUNTIME)
 public @interface Reference {
     // EMPTY