KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > google > gwt > core > client > GWT


1 /*
2  * Copyright 2007 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.core.client;
17
18 /**
19  * Supports core functionality that in some cases requires direct support from
20  * the compiler and runtime systems such as runtime type information and
21  * deferred binding.
22  */
23 public final class GWT {
24   /*
25    * This is the web mode version of this class. Because it's so special,
26    * there's also a hosted mode version. See GWT.java-hosted.
27    */
28
29   /**
30    * This interface is used to catch exceptions at the "top level" just before
31    * they escape to the browser. This is used in places where the browser calls
32    * into user code such as event callbacks, timers, and RPC.
33    *
34    * In hosted mode, the default handler prints a stack trace to the log window.
35    * In web mode, the default handler is null and thus exceptions are allowed to
36    * escape, which provides an opportunity to use a JavaScript debugger.
37    */
38   public interface UncaughtExceptionHandler {
39     void onUncaughtException(Throwable JavaDoc e);
40   }
41
42   // web mode default is to let the exception go
43 private static UncaughtExceptionHandler sUncaughtExceptionHandler = null;
44
45   /**
46    * Instantiates a class via deferred binding.
47    *
48    * <p>
49    * The argument to {@link #create(Class)}&#160;<i>must</i> be a class
50    * literal because the web mode compiler must be able to statically determine
51    * the requested type at compile-time. This can be tricky because using a
52    * {@link Class} variable may appear to work correctly in hosted mode.
53    * </p>
54    *
55    * @param classLiteral a class literal specifying the base class to be
56    * instantiated
57    * @return the new instance, which must be typecast to the requested class.
58    */
59   public static Object JavaDoc create(Class JavaDoc classLiteral) {
60     /*
61      * In web mode, the compiler directly replaces calls to this method with a
62      * new Object() type expression of the correct rebound type.
63      */
64     throw new RuntimeException JavaDoc(
65         "GWT has not been properly initialized; if you are running a unit test, check that your test case extends GWTTestCase");
66   }
67
68   /**
69    * Gets the URL prefix of the hosting page, useful for prepending to relative
70    * paths of resources which may be relative to the host page. Typically, you
71    * should use {@link #getModuleBaseURL()} unless you have a specific reason to
72    * load a resource relative to the host page.
73    *
74    * @return if non-empty, the base URL is guaranteed to end with a slash
75    */
76   public static String JavaDoc getHostPageBaseURL() {
77     return Impl.getHostPageBaseURL();
78   }
79
80   /**
81    * Gets the URL prefix of the module which should be prepended to URLs that
82    * are intended to be module-relative, such as RPC entry points and files in
83    * the module's public path.
84    *
85    * @return if non-empty, the base URL is guaranteed to end with a slash
86    */
87   public static String JavaDoc getModuleBaseURL() {
88     return Impl.getModuleBaseURL();
89   }
90
91   /**
92    * Gets the name of the running module.
93    */
94   public static String JavaDoc getModuleName() {
95     return Impl.getModuleName();
96   }
97
98   /**
99    * Gets the class name of the specified object, as would be returned by
100    * <code>o.getClass().getName()</code>.
101    *
102    * @param o the object whose class name is being sought, or <code>null</code>
103    * @return the class name of the specified object, or <code>null</code> if
104    * <code>o</code> is <code>null</code>
105    */
106   public static native String JavaDoc getTypeName(Object JavaDoc o) /*-{
107     return (o == null) ? null : o.@java.lang.Object::typeName;
108   }-*/;
109
110   /**
111    * Returns the currently active uncaughtExceptionHandler. "Top level" methods
112    * that dispatch events from the browser into user code must call this method
113    * on entry to get the active handler. If the active handler is null, the
114    * entry point must allow exceptions to escape into the browser. If the
115    * handler is non-null, exceptions must be caught and routed to the handler.
116    * See the source code for <code>DOM.dispatchEvent()</code> for an example
117    * of how to handle this correctly.
118    *
119    * @return the currently active handler, or null if no handler is active.
120    */
121   public static UncaughtExceptionHandler getUncaughtExceptionHandler() {
122     return sUncaughtExceptionHandler;
123   };
124
125   /**
126    * Determines whether or not the running program is script or bytecode.
127    */
128   public static boolean isScript() {
129     return true;
130   }
131
132   /**
133    * Logs a message to the development shell logger in hosted mode. Calls are
134    * optimized out in web mode.
135    */
136   public static void log(String JavaDoc message, Throwable JavaDoc e) {
137     // intentionally empty in web mode.
138 }
139
140   /**
141    * Sets a custom uncaught exception handler. See
142    * {@link #getUncaughtExceptionHandler()} for details.
143    *
144    * @param handler the handler that should be called when an exception is about
145    * to escape to the browser, or <code>null</code> to clear the
146    * handler and allow exceptions to escape.
147    */
148   public static void setUncaughtExceptionHandler(
149       UncaughtExceptionHandler handler) {
150     sUncaughtExceptionHandler = handler;
151   };
152 }
153
Popular Tags