       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  * @since 1.8u40
      39  */
      40 public interface JSObject {
      41     /**
      42      * Call this object as a JavaScript function. This is equivalent to
      43      * 'func.apply(thiz, args)' in JavaScript.
      44      *
      45      * @param thiz 'this' object to be passed to the function. This may be null.
      46      * @param args arguments to method
      47      * @return result of call
      48      */
      49     public Object call(final Object thiz, final Object... args);
      50
      51     /**
      52      * Call this 'constructor' JavaScript function to create a new object.
      53      * This is equivalent to 'new func(arg1, arg2...)' in JavaScript.
      54      *
      55      * @param args arguments to method
      56      * @return result of constructor call
      57      */
      58     public Object newObject(final Object... args);
      59
      60     /**
      61      * Evaluate a JavaScript expression.
      62      *
      63      * @param s JavaScript expression to evaluate
      64      * @return evaluation result
      65      */
      66     public Object eval(final String s);
      67
      68     /**
      69      * Retrieves a named member of this JavaScript object.
      70      *
      71      * @param name of member
      72      * @return member
      73      * @throws NullPointerException if name is null
      74      */
      75     public Object getMember(final String name);
      76
      77     /**
      78      * Retrieves an indexed member of this JavaScript object.
      79      *
      80      * @param index index slot to retrieve
      81      * @return member
      82      */
      83     public Object getSlot(final int index);
      84
      85     /**
      86      * Does this object have a named member?
      87      *
      88      * @param name name of member
      89      * @return true if this object has a member of the given name
      90      */
      91     public boolean hasMember(final String name);
      92
      93     /**
      94      * Does this object have a indexed property?
      95      *
      96      * @param slot index to check
      97      * @return true if this object has a slot
      98      */
      99     public boolean hasSlot(final int slot);
     100
     101     /**
     102      * Remove a named member from this JavaScript object
     103      *
     104      * @param name name of the member
     105      * @throws NullPointerException if name is null
     106      */
     107     public void removeMember(final String name);
     108
     109     /**
     110      * Set a named member in this JavaScript object
     111      *
     112      * @param name  name of the member
     113      * @param value value of the member
     114      * @throws NullPointerException if name is null
     115      */
     116     public void setMember(final String name, final Object value);
     117
     118     /**
     119      * Set an indexed member in this JavaScript object
     120      *
     121      * @param index index of the member slot
     122      * @param value value of the member
     123      */
     124     public void setSlot(final int index, final Object value);
     125
     126     // property and value iteration
     127
     128     /**
     129      * Returns the set of all property names of this object.
     130      *
     131      * @return set of property names
     132      */
     133     public Set<String> keySet();
     134
     135     /**
     136      * Returns the set of all property values of this object.
     137      *
     138      * @return set of property values.
     139      */
     140     public Collection<Object> values();
     141
     142     // JavaScript instanceof check
     143
     144     /**
     145      * Checking whether the given object is an instance of 'this' object.
     146      *
     147      * @param instance instance to check
     148      * @return true if the given 'instance' is an instance of this 'function' object
     149      */
     150     public boolean isInstance(final Object instance);
     151
     152     /**
     153      * Checking whether this object is an instance of the given 'clazz' object.
     154      *
     155      * @param clazz clazz to check
     156      * @return true if this object is an instance of the given 'clazz'
     157      */
     158     public boolean isInstanceOf(final Object clazz);
     159
     160     /**
     161      * ECMA [[Class]] property
     162      *
     163      * @return ECMA [[Class]] property value of this object
     164      */
     165     public String getClassName();
     166
     167     /**
     168      * Is this a function object?
     169      *
     170      * @return if this mirror wraps a ECMAScript function instance
     171      */
     172     public boolean isFunction();
     173
     174     /**
     175      * Is this a 'use strict' function object?
     176      *
     177      * @return true if this mirror represents a ECMAScript 'use strict' function
     178      */
     179     public boolean isStrictFunction();
     180
     181     /**
     182      * Is this an array object?
     183      *
     184      * @return if this mirror wraps a ECMAScript array object
     185      */
     186     public boolean isArray();
     187
     188     /**
     189      * Returns this object's numeric value.
     190      *
     191      * @return this object's numeric value.
     192      * @deprecated use {@link #getDefaultValue(Class)} with {@link Number} hint instead.
     193      */
     194     @Deprecated
     195     default double toNumber() {
     196         return JSType.toNumber(JSType.toPrimitive(this, Number.class));
     197     }
     198
     199     /**
     200      * Implements this object's {@code [[DefaultValue]]} method as per ECMAScript 5.1 section 8.6.2.
     201      *
     202      * @param hint the type hint. Should be either {@code null}, {@code Number.class} or {@code String.class}.
     203      * @return this object's default value.
     204      * @throws UnsupportedOperationException if the conversion can't be performed. The engine will convert this
     205      * exception into a JavaScript {@code TypeError}.
     206      */
     207     default Object getDefaultValue(final Class<?> hint) throws UnsupportedOperationException {
     208         return DefaultValueImpl.getDefaultValue(this, hint);
     209     }
     210 }