com.google.gwt.requestfactory.shared.Locator.java Source code

Introduction

Here is the source code for com.google.gwt.requestfactory.shared.Locator.java

Source

/*
 * 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.
 *
 * <p><span style='color:red'>RequestFactory has moved to
 * <code>com.google.web.bindery.requestfactory</code>.  This package will be
 * removed in a future version of GWT.</span></p>
 *
 * @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()
 */
@Deprecated
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;
    }
}