/*
 * 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);
}