javax.jdo.FetchPlan Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jdo-api Show documentation
Show all versions of jdo-api Show documentation
The Java Data Objects (JDO) API is a standard interface-based Java model abstraction of persistence, developed as Java Specification Request 243 under the auspices of the Java Community Process.
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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.
*/
/*
* FetchPlan.java
*
*/
package javax.jdo;
import java.util.Collection;
import java.util.Set;
/**
* Fetch groups are activated using methods on this interface. An
* instance of this interface can be obtained from {@link
* PersistenceManager#getFetchPlan}, {@link Extent#getFetchPlan}, and
* {@link Query#getFetchPlan}. When a Query or
* Extent is retrieved from a
* PersistenceManager, its FetchPlan is
* initialized to the same settings as that of the
* PersistenceManager. Subsequent modifications of the
* Query or Extent's FetchPlan
* are not reflected in the FetchPlan of the
* PersistenceManager.
* @version 2.0
* @since 2.0
*/
public interface FetchPlan {
/**
* For use with {@link #addGroup}, {@link #removeGroup}, and the
* various {@link #setGroups} calls. Value: default.
* @since 2.0
*/
public static final String DEFAULT = "default";
/**
* For use with {@link #addGroup}, {@link #removeGroup}, and the
* various {@link #setGroups} calls. Value: all.
* @since 2.0
*/
public static final String ALL = "all";
/**
* For use with {@link PersistenceManager#detachCopy} and
* {@link #setDetachmentOptions}. Specifies that
* fields that are loaded but not in the current fetch plan should
* be unloaded prior to detachment.
* @since 2.0
*/
public static final int DETACH_UNLOAD_FIELDS = 2;
/**
* For use with {@link PersistenceManager#detachCopy} and
* {@link #setDetachmentOptions}. Specifies that
* fields that are not loaded but are in the current fetch plan should
* be loaded prior to detachment.
* @since 2.0
*/
public static final int DETACH_LOAD_FIELDS = 1;
/**
* For use with {@link #setFetchSize}. Value: -1.
* @since 2.0
*/
public static final int FETCH_SIZE_GREEDY = -1;
/**
* For use with {@link #setFetchSize}. Value: 0.
* @since 2.0
*/
public static final int FETCH_SIZE_OPTIMAL = 0;
/**
* Add the fetch group to the set of active fetch groups.
* @return the FetchPlan
* @since 2.0
*/
FetchPlan addGroup(String fetchGroupName);
/**
* Remove the fetch group from the set active fetch groups.
* @return the FetchPlan
* @since 2.0
*/
FetchPlan removeGroup(String fetchGroupName);
/**
* Remove all active groups leaving no active fetch group.
* @return the FetchPlan
* @since 2.0
*/
FetchPlan clearGroups();
/**
* Return an immutable Set containing the names
* of all active fetch groups. The Set is a copy of
* the currently active groups and will not change
* based on subsequent changes to the groups.
* @return an immutable Set containing the names
* of all currently active fetch groups
* @since 2.0
*/
Set getGroups();
/**
* Set a collection of groups.
* @param fetchGroupNames a collection of names of fetch groups
* @return the FetchPlan
* @since 2.0
*/
FetchPlan setGroups(Collection fetchGroupNames);
/**
* Set a collection of groups.
* @param fetchGroupNames a String array of names of fetch groups
* @return the FetchPlan
* @since 2.0
*/
FetchPlan setGroups(String... fetchGroupNames);
/**
* Set the active fetch groups to the single named fetch group.
* @param fetchGroupName the single fetch group
* @return the FetchPlan
* @since 2.0
*/
FetchPlan setGroup(String fetchGroupName);
/**
* Set the maximum fetch depth when fetching.
* A value of 0 has no meaning and will throw a JDOUserException.
* A value of -1 means that no limit is placed on fetching.
* A positive integer will result in that number of references from the
* initial object to be fetched.
* @param fetchDepth the depth
* @return the FetchPlan
* @since 2.0
*/
FetchPlan setMaxFetchDepth(int fetchDepth);
/**
* Return the maximum fetch depth used when fetching instances.
* @return the maximum fetch depth
* @since 2.0
*/
int getMaxFetchDepth();
/**
* Set the roots for DetachAllOnCommit.
* @param roots Collection of the detachment roots.
* @since 2.0
*/
FetchPlan setDetachmentRoots(Collection roots);
/**
* Get the roots for DetachAllOnCommit.
* @return Collection of detachment roots.
* @since 2.0
*/
Collection getDetachmentRoots();
/**
* Set the root classes for DetachAllOnCommit.
* @param rootClasses The root classes.
* @since 2.0
*/
FetchPlan setDetachmentRootClasses(Class... rootClasses);
/**
* Get the root classes for DetachAllOnCommit.
* @return The detachment root classes
* @since 2.0
*/
Class[] getDetachmentRootClasses();
/**
* Set the fetch size for large result set support. Use
* {@link #FETCH_SIZE_OPTIMAL} to unset, and {@link #FETCH_SIZE_GREEDY}
* to force loading of everything.
* @param fetchSize the fetch size
* @return the FetchPlan
* @since 2.0
*/
FetchPlan setFetchSize(int fetchSize);
/**
* Return the fetch size, or {@link #FETCH_SIZE_OPTIMAL} if not set,
* or {@link #FETCH_SIZE_GREEDY} to fetch all.
* @return the fetch size
* @since 2.0
*/
int getFetchSize();
/**
* Set options to be used during detachment. Options are {@link
* #DETACH_LOAD_FIELDS} and {@link #DETACH_UNLOAD_FIELDS}.
*/
FetchPlan setDetachmentOptions(int options);
/**
* Get options used during detachment.
*/
int getDetachmentOptions();
}