changeset 1458:11b48db399bf

8139038: cleanup and documentation around JSAdapter Reviewed-by: attila, hannesw
author mhaupt
date Wed, 07 Oct 2015 14:00:45 +0200
parents 285628dac943
children 446625d6e8cc
files src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/NativeJSAdapter.java test/script/basic/jsadapter.js test/script/basic/jsadapter.js.EXPECTED
diffstat 3 files changed, 43 insertions(+), 33 deletions(-) [+]
line wrap: on
line diff
--- a/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/NativeJSAdapter.java	Tue Oct 06 08:42:02 2015 -0700
+++ b/src/jdk.scripting.nashorn/share/classes/jdk/nashorn/internal/objects/NativeJSAdapter.java	Wed Oct 07 14:00:45 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, 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
@@ -52,18 +52,18 @@
 import jdk.nashorn.internal.scripts.JO;
 
 /**
- * This class is the implementation of the Nashorn-specific global object named {@code JSAdapter}. It can be
- * thought of as the {@link java.lang.reflect.Proxy} equivalent for JavaScript. NativeJSAdapter calls specially named
+ * This class is the implementation of the Nashorn-specific global object named {@code JSAdapter}. It can be thought of
+ * as the {@link java.lang.reflect.Proxy} equivalent for JavaScript. A {@code NativeJSAdapter} calls specially named
  * JavaScript methods on an adaptee object when property access/update/call/new/delete is attempted on it. Example:
  *<pre>
  *    var y = {
- *                __get__    : function (name) { ... }
- *                __has__    : function (name) { ... }
- *                __put__    : function (name, value) {...}
- *                __call__   : function (name, arg1, arg2) {...}
- *                __new__    : function (arg1, arg2) {...}
- *                __delete__ : function (name) { ... }
- *                __getIds__ : function () { ... }
+ *                __get__     : function (name) { ... }
+ *                __has__     : function (name) { ... }
+ *                __put__     : function (name, value) {...}
+ *                __call__    : function (name, arg1, arg2) {...}
+ *                __new__     : function (arg1, arg2) {...}
+ *                __delete__  : function (name) { ... }
+ *                __getKeys__ : function () { ... }
  *            };
  *
  *    var x = new JSAdapter(y);
@@ -74,17 +74,21 @@
  *    i in x;                     // calls y.__has__
  *    x.p = 10;                   // calls y.__put__
  *    delete x.p;                 // calls y.__delete__
- *    for (i in x) { print(i); }  // calls y.__getIds__
+ *    for (i in x) { print(i); }  // calls y.__getKeys__
  * </pre>
  * <p>
- * JavaScript caller of adapter object is isolated from the fact that the property access/mutation/deletion are really
- * calls to JavaScript methods on adaptee.
+ * The {@code __getKeys__} and {@code __getIds__} properties are mapped to the same operation. Concrete
+ * {@code JSAdapter} implementations are expected to use only one of these. As {@code __getIds__} exists for
+ * compatibility reasons only, use of {@code __getKeys__} is recommended.
  * </p>
  * <p>
- * JSAdapter constructor can optionally receive an "overrides" object. Properties of overrides object is copied to
- * JSAdapter instance. When user accessed property is one of these, then adaptee's methods like {@code __get__},
- * {@code __put__} etc. are not called for those. This can be used to make certain "preferred" properties that can be
- * accessed in the usual/faster way avoiding proxy mechanism. Example:
+ * The JavaScript caller of an adapter object is oblivious of the property access/mutation/deletion's being adapted.
+ * </p>
+ * <p>
+ * The {@code JSAdapter} constructor can optionally receive an "overrides" object. The properties of overrides object
+ * are copied to the {@code JSAdapter} instance. In case user-accessed properties are among these, the adaptee's methods
+ * like {@code __get__}, {@code __put__} etc. are not called for them. This can be used to make certain "preferred"
+ * properties that can be accessed in the usual/faster way avoiding the proxy mechanism. Example:
  * </p>
  * <pre>
  *     var x = new JSAdapter({ foo: 444, bar: 6546 }) {
@@ -95,13 +99,13 @@
  *     x.bar = 'hello'; // "bar" directly set without __put__ call
  *     x.prop           // calls __get__("prop") as 'prop' is not overridden
  * </pre>
- * It is possible to pass a specific prototype for JSAdapter instance by passing three arguments to JSAdapter
- * constructor. So exact signature of JSAdapter constructor is as follows:
+ * It is possible to pass a specific prototype for the {@code JSAdapter} instance by passing three arguments to the
+ * {@code JSAdapter} constructor. The exact signature of the {@code JSAdapter} constructor is as follows:
  * <pre>
  *     JSAdapter([proto], [overrides], adaptee);
  * </pre>
- * Both proto and overrides are optional - but adaptee is not. When proto is not passed {@code JSAdapter.prototype} is
- * used.
+ * Both the {@code proto} and {@code overrides} arguments are optional - but {@code adaptee} is not. When {@code proto}
+ * is not passed, {@code JSAdapter.prototype} is used.
  */
 @ScriptClass("JSAdapter")
 public final class NativeJSAdapter extends ScriptObject {
@@ -113,7 +117,7 @@
     public static final String __call__      = "__call__";
     /** object new operation */
     public static final String __new__       = "__new__";
-    /** object getIds operation */
+    /** object getIds operation (provided for compatibility reasons; use of getKeys is preferred) */
     public static final String __getIds__    = "__getIds__";
     /** object getKeys operation */
     public static final String __getKeys__   = "__getKeys__";
@@ -142,7 +146,7 @@
     private final ScriptObject adaptee;
     private final boolean overrides;
 
-    private static final MethodHandle IS_JSADAPTOR = findOwnMH("isJSAdaptor", boolean.class, Object.class, Object.class, MethodHandle.class, Object.class, ScriptFunction.class);
+    private static final MethodHandle IS_JSADAPTER = findOwnMH("isJSAdapter", boolean.class, Object.class, Object.class, MethodHandle.class, Object.class, ScriptFunction.class);
 
     // initialized by nasgen
     private static PropertyMap $nasgenmap$;
@@ -626,7 +630,7 @@
                     // to name. Probably not a big deal, but if we can ever make it leaner, it'd be nice.
                     return new GuardedInvocation(MH.dropArguments(MH.constant(Object.class,
                             func.createBound(this, new Object[] { name })), 0, Object.class),
-                            testJSAdaptor(adaptee, null, null, null),
+                            testJSAdapter(adaptee, null, null, null),
                             adaptee.getProtoSwitchPoints(__call__, find.getOwner()), null);
                 }
             }
@@ -697,7 +701,7 @@
                 if (methodHandle != null) {
                     return new GuardedInvocation(
                             methodHandle,
-                            testJSAdaptor(adaptee, findData.getGetter(Object.class, INVALID_PROGRAM_POINT, null), findData.getOwner(), func),
+                            testJSAdapter(adaptee, findData.getGetter(Object.class, INVALID_PROGRAM_POINT, null), findData.getOwner(), func),
                             adaptee.getProtoSwitchPoints(hook, findData.getOwner()), null);
                 }
              }
@@ -710,16 +714,16 @@
             final MethodHandle methodHandle = hook.equals(__put__) ?
             MH.asType(Lookup.EMPTY_SETTER, type) :
             Lookup.emptyGetter(type.returnType());
-            return new GuardedInvocation(methodHandle, testJSAdaptor(adaptee, null, null, null), adaptee.getProtoSwitchPoints(hook, null), null);
+            return new GuardedInvocation(methodHandle, testJSAdapter(adaptee, null, null, null), adaptee.getProtoSwitchPoints(hook, null), null);
         }
     }
 
-    private static MethodHandle testJSAdaptor(final Object adaptee, final MethodHandle getter, final Object where, final ScriptFunction func) {
-        return MH.insertArguments(IS_JSADAPTOR, 1, adaptee, getter, where, func);
+    private static MethodHandle testJSAdapter(final Object adaptee, final MethodHandle getter, final Object where, final ScriptFunction func) {
+        return MH.insertArguments(IS_JSADAPTER, 1, adaptee, getter, where, func);
     }
 
     @SuppressWarnings("unused")
-    private static boolean isJSAdaptor(final Object self, final Object adaptee, final MethodHandle getter, final Object where, final ScriptFunction func) {
+    private static boolean isJSAdapter(final Object self, final Object adaptee, final MethodHandle getter, final Object where, final ScriptFunction func) {
         final boolean res = self instanceof NativeJSAdapter && ((NativeJSAdapter)self).getAdaptee() == adaptee;
         if (res && getter != null) {
             try {
--- a/test/script/basic/jsadapter.js	Tue Oct 06 08:42:02 2015 -0700
+++ b/test/script/basic/jsadapter.js	Wed Oct 07 14:00:45 2015 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2015, 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
@@ -45,8 +45,8 @@
         print("new with " + arg1 + ", " + arg2);
     },
 
-    __getIds__: function() {
-        print("__getIds__ called");
+    __getKeys__: function() {
+        print("__getKeys__ called");
         return [ "foo", "bar" ];
     },
 
@@ -78,22 +78,28 @@
 // calls __new__
 new obj("hey!", "it works!");
 
+// calls __getKeys__
 for (i in obj) {
     print(i);
 }
 
+// calls __getValues__
 for each (i in obj) {
     print(i);
 }
 
+// calls __has__
 var x = "foo" in obj;
 print(x);
 
+// calls __has__
 var y = "js" in obj;
 print(y);
 
+// calls __delete__
 print(delete obj.prop);
 
+// call __get__ and __set__
 print(obj["js"]);
 obj["js"] = "javascript";
 print(obj["javascript"]);
--- a/test/script/basic/jsadapter.js.EXPECTED	Tue Oct 06 08:42:02 2015 -0700
+++ b/test/script/basic/jsadapter.js.EXPECTED	Wed Oct 07 14:00:45 2015 +0200
@@ -3,7 +3,7 @@
 setter called for 'foo' with 33
 method 'func' called with hello, world
 new with hey!, it works!
-__getIds__ called
+__getKeys__ called
 foo
 bar
 __getValues__ called