/*
 * 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.gwt.requestfactory.shared;

/**
 * A Locator allows entity types that do not conform to the RequestFactory
 * entity protocol to be used. Instead of attempting to use a {@code findFoo()},
 * {@code getId()}, and {@code getVersion()} declared in the domain entity type,
 * an instance of a Locator will be created to provide implementations of these
 * methods.
 * <p>
 * Locator subtypes must be default instantiable (i.e. public static types with
 * a no-arg constructor). Instances of Locators may be retained and reused by
 * the RequestFactory service layer.
 * 
 * @param <T> the type of domain object the Locator will operate on
 * @param <I> the type of object the Locator expects to use as an id for the
 *          domain object
 * @see ProxyFor#locator()
 */
public abstract class Locator<T, I> {
  /**
   * Create a new instance of the requested type.
   * 
   * @param clazz the type of object to create
   * @return the new instance of the domain type
   */
  public abstract T create(Class<? extends T> clazz);

  /**
   * Retrieve an object. May return {@code null} to indicate that the requested
   * object could not be found.
   * 
   * @param clazz the type of object to retrieve
   * @param id an id previously returned from {@link #getId(Object)}
   * @return the requested object or {@code null} if it could not be found
   */
  public abstract T find(Class<? extends T> clazz, I id);

  /**
   * Returns the {@code T} type.
   */
  public abstract Class<T> getDomainType();

  /**
   * Returns a domain object to be used as the id for the given object. This
   * method may return {@code null} if the object has not been persisted or
   * should be treated as irretrievable.
   * 
   * @param domainObject the object to obtain an id for
   * @return the object's id or {@code null}
   */
  public abstract I getId(T domainObject);

  /**
   * Returns the {@code I} type.
   */
  public abstract Class<I> getIdType();

  /**
   * Returns a domain object to be used as the version for the given object.
   * This method may return {@code null} if the object has not been persisted or
   * should be treated as irretrievable.
   * 
   * @param domainObject the object to obtain an id for
   * @return the object's version or {@code null}
   */
  public abstract Object getVersion(T domainObject);

  /**
   * Returns a value indicating if the domain object should no longer be
   * considered accessible. This method might return false if the record
   * underlying the domain object had been deleted as a side-effect of
   * processing a request.
   * <p>
   * The default implementation of this method uses {@link #getId(Object)} and
   * {@link #find(Class, Object)} to determine if an object can be retrieved.
   */
  public boolean isLive(T domainObject) {
    // Can't us Class.asSubclass() in web-mode code
    @SuppressWarnings("unchecked")
    Class<T> clazz = (Class<T>) domainObject.getClass();
    return find(clazz, getId(domainObject)) != null;
  }
}