001 /*
002 * Copyright 2006 Google Inc.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
005 * use this file except in compliance with the License. You may obtain a copy of
006 * the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
012 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
013 * License for the specific language governing permissions and limitations under
014 * the License.
015 */
016 package com.google.gwt.core.client;
017
018 /**
019 * Supports core functionality that in some cases requires direct support from
020 * the compiler and runtime systems such as runtime type information and
021 * deferred binding.
022 */
023 public final class GWT {
024
025 /**
026 * This interface is used to catch exceptions at the "top level" just before
027 * they escape to the browser. This is used in places where the browser calls
028 * into user code such as event callbacks, timers, and RPC.
029 *
030 * In hosted mode, the default handler prints a stack trace to the log window.
031 * In web mode, the default handler is null and thus exceptions are allowed to
032 * escape, which provides an opportunity to use a JavaScript debugger.
033 */
034 public interface UncaughtExceptionHandler {
035 void onUncaughtException(Throwable e);
036 }
037
038 // web mode default is to let the exception go
039 // hosted mode default is to log the exception to the log window
040 private static UncaughtExceptionHandler sUncaughtExceptionHandler = null;
041
042 /**
043 * Returns the currently active uncaughtExceptionHandler. "Top level" methods
044 * that dispatch events from the browser into user code must call this method
045 * on entry to get the active handler. If the active handler is null, the
046 * entry point must allow exceptions to escape into the browser. If the
047 * handler is non-null, exceptions must be caught and routed to the handler.
048 * See
049 * {@link com.google.gwt.user.client.DOM#dispatchEvent(Event, Element, EventListener)}
050 * for an example of how to handle this correctly.
051 *
052 * @return the currently active handler, or null if no handler is active.
053 */
054 public static UncaughtExceptionHandler getUncaughtExceptionHandler() {
055 return sUncaughtExceptionHandler;
056 }
057
058 /**
059 * Sets a custom uncaught exception handler. See
060 * {@link #getUncaughtExceptionHandler()} for details.
061 *
062 * @param handler the handler that should be called when an exception is about
063 * to escape to the browser, or null to clear the handler and
064 * allow exceptions to escape.
065 */
066 public static void setUncaughtExceptionHandler(
067 UncaughtExceptionHandler handler) {
068 sUncaughtExceptionHandler = handler;
069 }
070
071 /**
072 * Instantiates a class via deferred binding. <b>Very important:</b> the
073 * argument to {@link #create(Class)} <i>must</i> be a class literal because
074 * the web mode compiler must be able to statically determine the requested
075 * type at compile-time. This can be tricky because using a <code>Class</code>
076 * may appear to work correctly in hosted mode.
077 *
078 * @param classLiteral a class literal specifying the base class to be
079 * instantiated
080 * @return the new instance, which must be typecast to the requested class.
081 */
082 public static Object create(Class classLiteral) {
083 /*
084 * In hosted mode, this whole class definition is replaced at runtime with
085 * an implementation defined by the hosting environment. Maintainers: see
086 * {@link com.google.gwt.dev.shell.HostedModeSourceOracle#CU_Meta}.
087 *
088 * In web mode, the compiler directly replaces calls to this method with a
089 * new Object() type expression of the correct rebound type.
090 */
091 throw new RuntimeException(
092 "GWT has not been properly initialized; if you are running a unit test, check that your test case extends GWTTestCase");
093 }
094
095 /**
096 * Gets the class name of the specified object, as would be returned by
097 * <code>o.getClass().getName()</code>.
098 *
099 * @param o the object whose class name is being sought, or <code>null</code>
100 * @return the class name of the specified object, or <code>null</code> if
101 * <code>o</code> is <code>null</code>
102 */
103 public static native String getTypeName(Object o) /*-{
104 return (o == null) ? null : o.@java.lang.Object::typeName;
105 }-*/;
106
107 /**
108 * Determines whether or not the running program is script or bytecode.
109 */
110 public static boolean isScript() {
111 return true;
112 };
113
114 /**
115 * Gets the name of the running module.
116 */
117 public static native String getModuleName() /*-{
118 return $moduleName;
119 }-*/;
120
121 /**
122 * Gets the url prefix of the module, which can be prefixed to URLs that are
123 * known to be part of the module's public path.
124 */
125 public static String getModuleBaseURL() {
126 return Impl.getModuleBaseURL();
127 }
128
129 /**
130 * Logs a message to the development shell logger in hosted mode. Calls are
131 * optimized out in web mode.
132 */
133 public static void log(String message, Throwable e) {
134 // intentionally empty in web mode.
135 };
136 }