Promotes Gin's AsyncProvider to GWT, along with a more general
AsyncCallback than the one in com.google.gwt.user.client.rpc.
Retrofits GWT RPC to use the new callback interface for ease
of use, and for ease of migration for existing GIN users.
Review in http://gwt-code-reviews.appspot.com/1387801
git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@9872 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/user/src/com/google/gwt/core/client/AsyncProvider.java b/user/src/com/google/gwt/core/client/AsyncProvider.java
new file mode 100644
index 0000000..cbea880
--- /dev/null
+++ b/user/src/com/google/gwt/core/client/AsyncProvider.java
@@ -0,0 +1,47 @@
+/*
+ * Copyright 2011 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package com.google.gwt.core.client;
+
+/**
+ * An object capable of providing an instance of type T asynchronously
+ * via {@link Callback}. For example, the instance might be
+ * created within a GWT.runAsync block using the following template:
+ *
+ * <pre style=code>
+ * public void get(final Callback<T, Throwable> callback) {
+ * GWT.runAsync(new RunAsyncCallback() {
+ * public void onSuccess() {
+ * callback.onSuccess(javax.inject.Provider<T>.get());
+ * }
+ * public void onFailure(Throwable ex) {
+ * callback.onFailure(ex);
+ * }
+ * }
+ * }
+ * </pre>
+ *
+ * @param <T> the type of the provided value
+ * @param <F> the type returned on failure
+ */
+public interface AsyncProvider<T, F> {
+
+ /**
+ * @param callback Callback used to pass the instance of T or an exception
+ * if there is an issue creating that instance.
+ */
+ void get(Callback<? super T, ? super F> callback);
+}
diff --git a/user/src/com/google/gwt/core/client/Callback.java b/user/src/com/google/gwt/core/client/Callback.java
new file mode 100644
index 0000000..2540262
--- /dev/null
+++ b/user/src/com/google/gwt/core/client/Callback.java
@@ -0,0 +1,39 @@
+/*
+ * Copyright 2011 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.google.gwt.core.client;
+
+/**
+ * A callback for any asynchronous call that can result in success or failure.
+ *
+ * @param <T> The type returned on success
+ * @param <F> The type returned on failure
+ */
+public interface Callback<T, F> {
+
+ /**
+ * Called when an asynchronous call fails to complete normally.
+ *
+ * @param reason failure encountered
+ */
+ void onFailure(F reason);
+
+ /**
+ * Called when an asynchronous call completes successfully.
+ *
+ * @param result the value returned
+ */
+ void onSuccess(T result);
+}
