| /* |
| * Copyright 2010 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.web.bindery.requestfactory.shared; |
| |
| import com.google.web.bindery.event.shared.EventBus; |
| |
| /** |
| * Marker interface for the RequestFactory code generator. |
| * <p> |
| * <b>Limitations on the transferrability of types.</b> <br> |
| * RequestFactory currently supports the transfer of basic value types, entity |
| * types, and collections, with limitations. The basic value types supported are |
| * {@link String}, {@link Enum}, {@link Boolean}, {@link Character}, subtypes of |
| * {@link Number}, and {@link java.util.Date}. Any value type not included in |
| * this list may not be declared in the type signature of a service method, or |
| * {@link EntityProxy}. {@link java.util.Collection} types supported are |
| * {@link java.util.List} and {@link java.util.Set} with the restriction that a |
| * collection must be homogeneous and only hold one type of value. |
| * </p> |
| * <p> |
| * Polymorphism is not supported at this time. RequestFactory encoding and |
| * decoding requires exact knowledge of the concrete type. If a method declares |
| * a given type <code>T</code> as a parameter or return type, only |
| * <code>T</code>'s transferrable properties will be sent over the wire if it is |
| * a proxy, even if the underlying domain value contains extra fields, in |
| * effect, treating it as an instance of the supertype. Returning abstract |
| * supertypes of value types is not supported (e.g. Object, Enum, Number). |
| * </p> |
| * |
| * @see com.google.web.bindery.requestfactory.shared.testing.FakeRequestFactory |
| * @see com.google.web.bindery.requestfactory.server.testing.InProcessRequestTransport |
| */ |
| public interface RequestFactory { |
| /** |
| * The JSON content type String. |
| */ |
| String JSON_CONTENT_TYPE_UTF8 = "application/json; charset=utf-8"; |
| |
| /** |
| * Return a request to find a fresh instance of the referenced proxy. If it is |
| * necessary to load several proxy instances, use |
| * {@link RequestContext#find(EntityProxyId)}, which supports chained |
| * requests. |
| * |
| * @param proxyId an {@link EntityProxyId} instance of type P |
| * @return a {@link Request} object |
| * @see RequestContext#find(EntityProxyId) |
| */ |
| <P extends EntityProxy> Request<P> find(EntityProxyId<P> proxyId); |
| |
| /** |
| * Returns the event bus this factory's events are posted on, which was set |
| * via {@link #initialize}. |
| * |
| * @return the {@link EventBus} associated with this instance |
| */ |
| EventBus getEventBus(); |
| |
| /** |
| * Get a {@link com.google.gwt.user.client.History} compatible token that |
| * represents the given class. It can be processed by |
| * {@link #getProxyClass(String)} |
| * |
| * @param clazz a Class object for an {@link EntityProxy} subclass |
| * @return a {@link com.google.gwt.user.client.History} compatible token |
| */ |
| String getHistoryToken(Class<? extends EntityProxy> clazz); |
| |
| /** |
| * Get a {@link com.google.gwt.user.client.History} compatible token that |
| * represents the given proxy class. It can be processed by |
| * {@link #getProxyClass(String)}. |
| * <p> |
| * The history token returned for an EntityProxyId associated with a |
| * newly-created (future) EntityProxy will differ from the token returned by |
| * this method after the EntityProxy has been persisted. Once an EntityProxy |
| * has been persisted, the return value for this method will always be stable, |
| * regardless of when the EntityProxyId was retrieved relative to the persist |
| * operation. In other words, the "future" history token returned for an |
| * as-yet-unpersisted EntityProxy is only valid for the duration of the |
| * RequestFactory's lifespan. |
| * |
| * @param proxy an {@link EntityProxyId} instance |
| * @return a {@link com.google.gwt.user.client.History} compatible token |
| */ |
| String getHistoryToken(EntityProxyId<?> proxy); |
| |
| /** |
| * Return the class object which may be used to create new instances of the |
| * type of this token, via {@link RequestContext#create}. The token may |
| * represent either a proxy instance (see {@link #getHistoryToken}) or a proxy |
| * class (see {@link #getProxyClass}). |
| * |
| * @param historyToken a String token |
| * @return a Class object for an {@link EntityProxy} subclass |
| */ |
| Class<? extends EntityProxy> getProxyClass(String historyToken); |
| |
| /** |
| * Return the appropriate {@link EntityProxyId} using a string returned from |
| * {@link #getHistoryToken(EntityProxyId)}. |
| * |
| * @param historyToken a String token |
| * @return an {@link EntityProxyId} |
| */ |
| <T extends EntityProxy> EntityProxyId<T> getProxyId(String historyToken); |
| |
| /** |
| * Returns the RequestTransport set via {@link #initialize}. |
| * |
| * @return the {@link RequestTransport} associated with this instance |
| */ |
| RequestTransport getRequestTransport(); |
| |
| /** |
| * Returns a ProxySerializer that can encode and decode the various |
| * EntityProxy and ValueProxy types reachable from the RequestFactory. |
| * |
| * @param store a helper object for the ProxySerializer to provide low-level |
| * storage access |
| * @return a new ProxySerializer |
| * @see DefaultProxyStore |
| */ |
| ProxySerializer getSerializer(ProxyStore store); |
| |
| /** |
| * Start this request factory with a |
| * {@link com.google.web.bindery.requestfactory.gwt.client.DefaultRequestTransport} |
| * . |
| * |
| * @param eventBus an {@link EventBus} |
| */ |
| void initialize(EventBus eventBus); |
| |
| /** |
| * Start this request factory with a user-provided transport. |
| * |
| * @param eventBus an {@link EventBus} |
| * @param transport a {@link RequestTransport} instance |
| */ |
| void initialize(EventBus eventBus, RequestTransport transport); |
| } |