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