001: /*
002: * Copyright 2007 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: * This is the web mode version of this class. Because it's so special,
026: * there's also a hosted mode version. See GWT.java-hosted.
027: */
028:
029: /**
030: * This interface is used to catch exceptions at the "top level" just before
031: * they escape to the browser. This is used in places where the browser calls
032: * into user code such as event callbacks, timers, and RPC.
033: *
034: * In hosted mode, the default handler prints a stack trace to the log window.
035: * In web mode, the default handler is null and thus exceptions are allowed to
036: * escape, which provides an opportunity to use a JavaScript debugger.
037: */
038: public interface UncaughtExceptionHandler {
039: void onUncaughtException(Throwable e);
040: }
041:
042: // web mode default is to let the exception go
043: private static UncaughtExceptionHandler sUncaughtExceptionHandler = null;
044:
045: /**
046: * Instantiates a class via deferred binding.
047: *
048: * <p>
049: * The argument to {@link #create(Class)} <i>must</i> be a class
050: * literal because the web mode compiler must be able to statically determine
051: * the requested type at compile-time. This can be tricky because using a
052: * {@link Class} variable may appear to work correctly in hosted mode.
053: * </p>
054: *
055: * @param classLiteral a class literal specifying the base class to be
056: * instantiated
057: * @return the new instance, which must be typecast to the requested class.
058: */
059: public static <T> T create(Class<?> classLiteral) {
060: /*
061: * In web mode, the compiler directly replaces calls to this method with a
062: * new Object() type expression of the correct rebound type.
063: */
064: throw new UnsupportedOperationException(
065: "ERROR: GWT.create() is only usable in client code! It cannot be called, "
066: + "for example, from server code. If you are running a unit test, "
067: + "check that your test case extends GWTTestCase and that GWT.create() "
068: + "is not called from within an initializer, constructor, or "
069: + "setUp()/tearDown().");
070: }
071:
072: /**
073: * Gets the URL prefix of the hosting page, useful for prepending to relative
074: * paths of resources which may be relative to the host page. Typically, you
075: * should use {@link #getModuleBaseURL()} unless you have a specific reason to
076: * load a resource relative to the host page.
077: *
078: * @return if non-empty, the base URL is guaranteed to end with a slash
079: */
080: public static String getHostPageBaseURL() {
081: return Impl.getHostPageBaseURL();
082: }
083:
084: /**
085: * Gets the URL prefix of the module which should be prepended to URLs that
086: * are intended to be module-relative, such as RPC entry points and files in
087: * the module's public path.
088: *
089: * @return if non-empty, the base URL is guaranteed to end with a slash
090: */
091: public static String getModuleBaseURL() {
092: return Impl.getModuleBaseURL();
093: }
094:
095: /**
096: * Gets the name of the running module.
097: */
098: public static String getModuleName() {
099: return Impl.getModuleName();
100: }
101:
102: /**
103: * @deprecated Use {@link Object#getClass()}, {@link Class#getName()}.
104: */
105: @Deprecated
106: public static String getTypeName(Object o) {
107: return (o == null) ? null : o.getClass().getName();
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 message, Throwable 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: }
|