net.java.ao.Preload Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of activeobjects Show documentation
This is the full Active Objects library, if you don't know which one to use, you probably want this one.
The newest version!
/*
 * Copyright 2007 Daniel Spiewak
 * 
 * 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 net.java.ao;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Specifies a list of fields which should be appended to the
 * SELECT clause every time a row of the type in question is
 * retrieved.  If the developer knows that every time an entity of
 * a certain type is retrieved, certain fields will be accessed, this is
 * a prime candidate for preloading.  For example:
 *
 * @Preload("name")
 * public interface Person extends Entity {
 *     public String getName();
 *     public void setName(String name);
 *
 *     // ...
 * }
 *
 * // ...
 * manager.find(Person.class, "age > 12");
 *
 * This code will run a query something like the following:
 *
 * SELECT id,name FROM people WHERE age > 12
 *
 * A list of fields may also be specified:
 *
 * @Preload({"firstName", "lastName"})
 * public interface Person extends Entity {
 *     public String getFirstName();
 *     public void setFirstName(String firstName);
 *
 *     public String getLastName();
 *     public void setLastName(String lastName);
 *
 *     // ...
 * }
 *
 * // ...
 * manager.find(Person.class, "age > 12");
 *
 * This produces a query like the following:
 *
 * SELECT id,firstName,lastName FROM people WHERE age > 12
 *
 * * may also be specified to force queries to load all
 * fields.  As such, @Preload is the primary mechanism
 * provided by ActiveObjects to override its lazy-loading underpinnings.
 *
 * This flag is a hint.  There are still queries (such as those
 * executed by {@link EntityManager#findWithSQL(Class, String, String, Object...)})
 * which will ignore the @Preload values and simply
 * execute a vanilla query.
 *
 * @author Daniel Spiewak
 * @see #value()
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Preload {
    String ALL = "*";

    /**
     * Contains the list of fields to be preloaded.  This can be a single field (e.g.
     * "name", "*", etc) or an array of fields (e.g. {"firstName", "lastName"}).
     */
    String[] value() default {ALL};
}