JsValue


1   /*
2    * Copyright 2006 Google Inc.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    * 
8    * http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package com.google.gwt.dev.shell;
17  
18  import java.util.Iterator  ;
19  import java.util.Vector  ;
20  
21  /**
22   * Represents a JavaScript value.
23   * 
24   * Note that in general the various get*() methods will return
25   * platform-independent values only if the corresponding is*() method returns
26   * true.  In some cases, an IllegalStateException may be thrown if the
27   * JavaScript value is not of the appropriate type or bogus values may be
28   * returned.  Note that getString will try very hard to return a reasonable
29   * result for any value, but it is intended only for human consumption and the
30   * exact format for anything besides a string value cannot be relied upon.
31   */
32  public abstract class JsValue {
33  
34    /**
35     * Allows JsValue subclasses to clean themselves up.
36     */
37    protected interface JsCleanup {
38      void doCleanup();
39    }
40  
41    /**
42     * For a thread-safety check to make sure only one thread ever accesses it.
43     */
44    private static Thread   theOnlyThreadAllowed;
45  
46    /**
47     * A queue of JsCleanup objects ready to be released by the main thread.
48     */
49    private static Vector   toBeReleased = new Vector  ();
50  
51    private static final Object   toBeReleasedLock = new Object  ();
52  
53    /**
54     * The main thread should call this from time to time to release hosted-mode
55     * objects that Java is no longer referencing.
56     */
57    public static void mainThreadCleanup() {
58      checkThread();
59      Vector   temp;
60      synchronized (toBeReleasedLock) {
61        temp = toBeReleased;
62        toBeReleased = new Vector  ();
63      }
64      for (Iterator   iter = temp.iterator(); iter.hasNext();) {
65        JsCleanup cleanup = (JsCleanup) iter.next();
66        cleanup.doCleanup();
67      }
68      temp.clear();
69    }
70  
71    /**
72     * Ensures that the current thread is actually the UI thread.
73     */
74    private static synchronized void checkThread() {
75      if (theOnlyThreadAllowed == null) {
76        theOnlyThreadAllowed = Thread.currentThread();
77      } else if (theOnlyThreadAllowed != Thread.currentThread()) {
78        throw new RuntimeException  ("This object has permanent thread affinity.");
79      }
80    }
81  
82    /**
83     * Moves this JS value to the queue of objects that are ready to be released.
84     */
85    private static void queueCleanup(JsCleanup cleanup) {
86      // Add to the queue to be released by the main thread later.
87      //
88      synchronized (toBeReleasedLock) {
89        toBeReleased.add(cleanup);
90      }
91    }
92  
93    /**
94     * Get the value of the object as a boolean.  May attempt to convert the
95     * value to a boolean if it is not a boolean.
96     * 
97     * @return the value of the underlying object as a boolean
98     */
99    public abstract boolean getBoolean();
100 
101   /**
102    * Get the value of the object as an integer. May attempt to convert the
103    * value to an integer if it is not an integer.
104    * 
105    * @return the value of the underlying object as an int
106    */
107   public abstract int getInt();
108 
109   /**
110    * Get the value of the object as a double. May attempt to convert the
111    * value to a double if it is not a double.
112    * 
113    * @return the value of the underlying object as a double
114    */
115   public abstract double getNumber();
116 
117   /**
118    * Get the value of the object as a string.  Tries very hard to return a
119    * reasonable value for any underyling type, but this should only be used
120    * for human consumption as the exact format is not reliable across platforms. 
121    * 
122    * @return the value of the underlying object as a string
123    */
124   public abstract String   getString();
125 
126   /**
127    * Returns a human-readable string describing the type of the JS object.
128    * This is intended only for human consumption and may vary across
129    * platforms.
130    */
131   public abstract String   getTypeString();
132 
133   /**
134    * Unwrap a wrapped Java object.
135    * 
136    * @return the original Java object wrapped in this JS object
137    */
138   public abstract Object   getWrappedJavaObject();
139 
140   /**
141    * Returns true if the JS value is a boolean.
142    */
143   public abstract boolean isBoolean();
144 
145   /**
146    * Returns true if getInt() can be used on this value.
147    */
148   public abstract boolean isInt();
149 
150   /**
151    * Returns true if the JS value is a native JS object.
152    */
153   public abstract boolean isJavaScriptObject();
154 
155   /**
156    * Returns true if the JS value is null.
157    */
158   public abstract boolean isNull();
159 
160   /**
161    * Returns true if the JS value is a numeric type.
162    */
163   public abstract boolean isNumber();
164 
165   /**
166    * Returns true if the JS value is a string.
167    */
168   public abstract boolean isString();
169 
170   /**
171    * Returns true if the JS value is undefined (void).
172    */
173   public abstract boolean isUndefined();
174 
175   /**
176    * Returns true if the JS value is a wrapped Java object.
177    */
178   public abstract boolean isWrappedJavaObject();
179 
180   /**
181    * Sets the JS object to be a boolean value.
182    * 
183    * @param val the boolean value to set
184    */
185   public abstract void setBoolean(boolean val);
186 
187   /**
188    * Sets the JS object to be a number, passed as an byte.
189    * 
190    * @param val the value to store
191    */
192   public abstract void setByte(byte val);
193 
194   /**
195    * Sets the JS object to be a number, passed as a char.
196    * 
197    * @param val the value to store
198    */
199   public abstract void setChar(char val);
200 
201   /**
202    * Sets the JS object to be a number, passed as a double.
203    * 
204    * @param val the value to store
205    */
206   public abstract void setDouble(double val);
207 
208   /**
209    * Sets the JS object to be a number, passed as an int.
210    * 
211    * @param val the value to store
212    */
213   public abstract void setInt(int val);
214 
215   /**
216    * Set the JS object to be null.
217    * 
218    * @throws HostedModeException
219    */
220   public abstract void setNull();
221 
222   /**
223    * Sets the JS object to be a number, passed as a short.
224    * 
225    * @param val the value to store
226    */
227   public abstract void setShort(short val);
228 
229   /**
230    * Set the JS object to the supplied string.
231    * 
232    * @param val the string to put in the JS object
233    * @throws HostedModeException on JS allocation failures
234    */
235   public abstract void setString(String   val);
236 
237   /**
238    * Set the JS object to be undefined (void).
239    * 
240    * @throws HostedModeException on JS allocation failures
241    */
242   public abstract void setUndefined();
243 
244   /**
245    * Make this JsValue refer to the same underlying object as another JsValue.
246    * 
247    * @param other JsValue to copy JS object from
248    */
249   public abstract void setValue(JsValue other);
250 
251   /**
252    * Wrap a Java method as a JavaScript function pointer.
253    * 
254    * @param string the name of the method
255    * @param dispMethod the DispatchMethod object describing the method tow wrap
256    */
257   // TODO(jat): platform-independent version of this?
258   // The problem is that each platform has different conventions for passing
259   // JavaScript values back into a Java method.
260   // public abstract void setWrappedFunction(String string,
261   // DispatchMethod dispMethod);
262   /**
263    * Set the JS object to the supplied object, which will be wrapped in a
264    * platform-dependent JavaScript class.
265    * 
266    * @param cl the classloader to create the wrapper object with
267    * @param val the Java object to wrap
268    * @throws HostedModeException
269    */
270   public abstract void setWrappedJavaObject(CompilingClassLoader cl, Object   val);
271 
272   /**
273    * Produce a string representation of the JsValue.
274    */
275   public String   toString() {
276     if (isUndefined()) {
277       return "void";
278     } else if (isNull()) {
279       return "null";
280     } else if (isBoolean()) {
281       return "bool: " + (getBoolean() ? "true" : "false");
282     } else if (isInt()) {
283       return "int: " + Integer.toString(getInt());
284     } else if (isNumber()) {
285       return "double: " + Double.toString(getNumber());
286     } else if (isWrappedJavaObject()) {
287       return "Java object: " + getWrappedJavaObject().toString();
288     } else if (isJavaScriptObject()) {
289       return "JS object [" + getTypeString() + "] : " + getString();
290     } else if (isString()) {
291       return "string: '" + getString() + "'";
292     } else {
293       return "*unknown type: " + getTypeString() + "*";
294     }
295   }
296 
297   /**
298    * Create an object which frees the underlying JS resource.
299    * 
300    * @return a JsCleanup object which will free the underlying JS resource
301    */
302   protected abstract JsCleanup createCleanupObject();
303 
304   /**
305    * When the Java object is garbage-collected, make sure the associated JS
306    * resource is freed. A helper object is used to avoid issues with
307    * resurrecting this object.
308    */
309   protected final void finalize() throws Throwable   {
310     queueCleanup(createCleanupObject());
311   }
312 }
313
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags