       1 /*
       2  * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
       3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
       4  *
       5  * This code is free software; you can redistribute it and/or modify it
       6  * under the terms of the GNU General Public License version 2 only, as
       7  * published by the Free Software Foundation.  Oracle designates this
       8  * particular file as subject to the "Classpath" exception as provided
       9  * by Oracle in the LICENSE file that accompanied this code.
      10  *
      11  * This code is distributed in the hope that it will be useful, but WITHOUT
      12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
      13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
      14  * version 2 for more details (a copy is included in the LICENSE file that
      15  * accompanied this code).
      16  *
      17  * You should have received a copy of the GNU General Public License version
      18  * 2 along with this work; if not, write to the Free Software Foundation,
      19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
      20  *
      21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
      22  * or visit www.oracle.com if you need additional information or have any
      23  * questions.
      24  */
      25
      26 package jdk.nashorn.api.scripting;
      27
      28 import java.util.Collection;
      29 import java.util.Set;
      30 import jdk.nashorn.internal.runtime.JSType;
      31
      32 /**
      33  * This interface can be implemented by an arbitrary Java class. Nashorn will
      34  * treat objects of such classes just like nashorn script objects. Usual nashorn
      35  * operations like obj[i], obj.foo, obj.func(), delete obj.foo will be delegated
      36  * to appropriate method call of this interface.
      37  *
      38  * @deprecated Nashorn JavaScript script engine and APIs, and the jjs tool
      39  * are deprecated with the intent to remove them in a future release.
      40  *
      41  * @since 1.8u40
      42  */
      43 @Deprecated(since="11", forRemoval=true)
      44 public interface JSObject {
      45     /**
      46      * Call this object as a JavaScript function. This is equivalent to
      47      * 'func.apply(thiz, args)' in JavaScript.
      48      *
      49      * @param thiz 'this' object to be passed to the function. This may be null.
      50      * @param args arguments to method
      51      * @return result of call
      52      */
      53     public Object call(final Object thiz, final Object... args);
      54
      55     /**
      56      * Call this 'constructor' JavaScript function to create a new object.
      57      * This is equivalent to 'new func(arg1, arg2...)' in JavaScript.
      58      *
      59      * @param args arguments to method
      60      * @return result of constructor call
      61      */
      62     public Object newObject(final Object... args);
      63
      64     /**
      65      * Evaluate a JavaScript expression.
      66      *
      67      * @param s JavaScript expression to evaluate
      68      * @return evaluation result
      69      */
      70     public Object eval(final String s);
      71
      72     /**
      73      * Retrieves a named member of this JavaScript object.
      74      *
      75      * @param name of member
      76      * @return member
      77      * @throws NullPointerException if name is null
      78      */
      79     public Object getMember(final String name);
      80
      81     /**
      82      * Retrieves an indexed member of this JavaScript object.
      83      *
      84      * @param index index slot to retrieve
      85      * @return member
      86      */
      87     public Object getSlot(final int index);
      88
      89     /**
      90      * Does this object have a named member?
      91      *
      92      * @param name name of member
      93      * @return true if this object has a member of the given name
      94      */
      95     public boolean hasMember(final String name);
      96
      97     /**
      98      * Does this object have a indexed property?
      99      *
     100      * @param slot index to check
     101      * @return true if this object has a slot
     102      */
     103     public boolean hasSlot(final int slot);
     104
     105     /**
     106      * Remove a named member from this JavaScript object
     107      *
     108      * @param name name of the member
     109      * @throws NullPointerException if name is null
     110      */
     111     public void removeMember(final String name);
     112
     113     /**
     114      * Set a named member in this JavaScript object
     115      *
     116      * @param name  name of the member
     117      * @param value value of the member
     118      * @throws NullPointerException if name is null
     119      */
     120     public void setMember(final String name, final Object value);
     121
     122     /**
     123      * Set an indexed member in this JavaScript object
     124      *
     125      * @param index index of the member slot
     126      * @param value value of the member
     127      */
     128     public void setSlot(final int index, final Object value);
     129
     130     // property and value iteration
     131
     132     /**
     133      * Returns the set of all property names of this object.
     134      *
     135      * @return set of property names
     136      */
     137     public Set<String> keySet();
     138
     139     /**
     140      * Returns the set of all property values of this object.
     141      *
     142      * @return set of property values.
     143      */
     144     public Collection<Object> values();
     145
     146     // JavaScript instanceof check
     147
     148     /**
     149      * Checking whether the given object is an instance of 'this' object.
     150      *
     151      * @param instance instance to check
     152      * @return true if the given 'instance' is an instance of this 'function' object
     153      */
     154     public boolean isInstance(final Object instance);
     155
     156     /**
     157      * Checking whether this object is an instance of the given 'clazz' object.
     158      *
     159      * @param clazz clazz to check
     160      * @return true if this object is an instance of the given 'clazz'
     161      */
     162     public boolean isInstanceOf(final Object clazz);
     163
     164     /**
     165      * ECMA [[Class]] property
     166      *
     167      * @return ECMA [[Class]] property value of this object
     168      */
     169     public String getClassName();
     170
     171     /**
     172      * Is this a function object?
     173      *
     174      * @return if this mirror wraps a ECMAScript function instance
     175      */
     176     public boolean isFunction();
     177
     178     /**
     179      * Is this a 'use strict' function object?
     180      *
     181      * @return true if this mirror represents a ECMAScript 'use strict' function
     182      */
     183     public boolean isStrictFunction();
     184
     185     /**
     186      * Is this an array object?
     187      *
     188      * @return if this mirror wraps a ECMAScript array object
     189      */
     190     public boolean isArray();
     191
     192     /**
     193      * Returns this object's numeric value.
     194      *
     195      * @return this object's numeric value.
     196      * @deprecated use {@link #getDefaultValue(Class)} with {@link Number} hint instead.
     197      */
     198     @Deprecated
     199     default double toNumber() {
     200         return JSType.toNumber(JSType.toPrimitive(this, Number.class));
     201     }
     202
     203     /**
     204      * Implements this object's {@code [[DefaultValue]]} method as per ECMAScript 5.1 section 8.6.2.
     205      *
     206      * @param hint the type hint. Should be either {@code null}, {@code Number.class} or {@code String.class}.
     207      * @return this object's default value.
     208      * @throws UnsupportedOperationException if the conversion can't be performed. The engine will convert this
     209      * exception into a JavaScript {@code TypeError}.
     210      */
     211     default Object getDefaultValue(final Class<?> hint) throws UnsupportedOperationException {
     212         return DefaultValueImpl.getDefaultValue(this, hint);
     213     }
     214 }