/*
* 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.
*/
package org.apache.openjpa.persistence;
import java.util.Collection;
import java.util.Map;
import javax.persistence.LockModeType;
import javax.persistence.PessimisticLockScope;
import org.apache.openjpa.kernel.DataCacheRetrieveMode;
import org.apache.openjpa.kernel.DataCacheStoreMode;
import org.apache.openjpa.kernel.FetchConfiguration;
import org.apache.openjpa.lib.util.Reflectable;
import org.apache.openjpa.meta.FetchGroup;
/**
* The fetch plan allows you to dynamically alter eager fetching
* configuration and other aspects of data loading.
*
* @author Abe White
* @author Pinaki Poddar
* @since 0.4.1
* @published
*/
public interface FetchPlan {
/**
* Fetch group representing all fields.
*/
public static final String GROUP_ALL = FetchGroup.NAME_ALL;
/**
* The default fetch group.
*/
public static final String GROUP_DEFAULT = FetchGroup.NAME_DEFAULT;
/**
* Infinite fetch depth.
*/
public static final int DEPTH_INFINITE = FetchGroup.DEPTH_INFINITE;
/**
* Constant to revert any setting to its default value.
*/
public static final int DEFAULT = FetchConfiguration.DEFAULT;
/**
* The maximum fetch depth when loading an object.
*/
public int getMaxFetchDepth();
/**
* The maximum fetch depth when loading an object.
*/
public FetchPlan setMaxFetchDepth(int depth);
/**
* Return the fetch batch size for large result set support.
* Defaults to the <code>openjpa.FetchBatchSize</code> setting. Note
* that this property will be ignored under some data stores.
*/
public int getFetchBatchSize();
/**
* Set the fetch batch size for large result set support.
* Defaults to the <code>openjpa.FetchBatchSize</code> setting. Note
* that this property will be ignored under some data stores.
*/
public FetchPlan setFetchBatchSize(int fetchBatchSize);
/**
* Return whether or not query caching is enabled. If this returns
* <code>true</code> but the datacache plugin is not installed, caching
* will not be enabled. If this
* returns <code>false</code>, query caching will not be used
* even if the datacache plugin is installed.
*
* @since 1.0.0
*/
public boolean getQueryResultCacheEnabled();
/**
* Control whether or not query caching is enabled. This has no effect
* if the datacache plugin is not installed, or if the query cache size
* is set to zero.
*
* @since 1.0.0
*/
public FetchPlan setQueryResultCacheEnabled(boolean cache);
/**
* @deprecated use {@link #getQueryResultCacheEnabled()} instead.
*/
public boolean getQueryResultCache();
/**
* @deprecated use {@link #setQueryResultCacheEnabled} instead.
*/
public FetchPlan setQueryResultCache(boolean cache);
/**
* Returns the names of the fetch groups that this component will use
* when loading objects. Defaults to the
* <code>openjpa.FetchGroups</code> setting.
*/
public Collection<String> getFetchGroups();
/**
* Adds <code>group</code> to the set of fetch group to
* use when loading objects.
*/
public FetchPlan addFetchGroup(String group);
/**
* Adds <code>groups</code> to the set of fetch group names to
* use when loading objects.
*/
public FetchPlan addFetchGroups(String... groups);
/**
* Adds <code>groups</code> to the set of fetch group names to
* use when loading objects.
*/
public FetchPlan addFetchGroups(Collection groups);
/**
* Remove the given fetch group.
*/
public FetchPlan removeFetchGroup(String group);
/**
* Removes <code>groups</code> from the set of fetch group names
* to use when loading objects.
*/
public FetchPlan removeFetchGroups(String... groups);
/**
* Removes <code>groups</code> from the set of fetch group names
* to use when loading objects.
*/
public FetchPlan removeFetchGroups(Collection groups);
/**
* Clears the set of fetch group names to use wen loading
* data. After this operation is invoked, only those fields in
* the default fetch group (and any requested field) will be
* loaded when loading an object.
*/
public FetchPlan clearFetchGroups();
/**
* Resets the set of fetch groups to the list in the global configuration.
*/
public FetchPlan resetFetchGroups();
/**
* Returns the fully qualified names of the fields that this component
* will use when loading objects. Defaults to the empty set.
*/
public Collection<String> getFields();
/**
* Return true if the given field has been added.
*/
public boolean hasField(String field);
/**
* Return true if the given field has been added.
*/
public boolean hasField(Class cls, String field);
/**
* Adds <code>field</code> to the set of fully-qualified field names to
* use when loading objects.
*/
public FetchPlan addField(String field);
/**
* Adds <code>field</code> to the set of field names to
* use when loading objects.
*/
public FetchPlan addField(Class cls, String field);
/**
* Adds <code>fields</code> to the set of fully-qualified field names to
* use when loading objects.
*/
public FetchPlan addFields(String... fields);
/**
* Adds <code>fields</code> to the set of field names to
* use when loading objects.
*/
public FetchPlan addFields(Class cls, String... fields);
/**
* Adds <code>fields</code> to the set of fully-qualified field names to
* use when loading objects.
*/
public FetchPlan addFields(Collection fields);
/**
* Adds <code>fields</code> to the set of field names to
* use when loading objects.
*/
public FetchPlan addFields(Class cls, Collection fields);
/**
* Remove the given fully-qualified field.
*/
public FetchPlan removeField(String field);
/**
* Remove the given field.
*/
public FetchPlan removeField(Class cls, String field);
/**
* Removes <code>fields</code> from the set of fully-qualified field names
* to use when loading objects.
*/
public FetchPlan removeFields(String... fields);
/**
* Removes <code>fields</code> from the set of field names
* to use when loading objects.
*/
public FetchPlan removeFields(Class cls, String... fields);
/**
* Removes <code>fields</code> from the set of fully-qualified field names
* to use when loading objects.
*/
public FetchPlan removeFields(Collection fields);
/**
* Removes <code>fields</code> from the set of field names
* to use when loading objects.
*/
public FetchPlan removeFields(Class cls, Collection fields);
/**
* Clears the set of field names to use wen loading
* data. After this operation is invoked, only those fields in
* the configured fetch groups will be loaded when loading an object.
*/
public FetchPlan clearFields();
/**
* The number of milliseconds to wait for an object lock, or -1 for no
* limit.
*/
public int getLockTimeout();
/**
* The number of milliseconds to wait for an object lock, or -1 for no
* limit.
*/
public FetchPlan setLockTimeout(int timeout);
/**
* The lock scope to use for locking loaded objects.
*/
public PessimisticLockScope getLockScope();
/**
* The lock scope to use for locking loaded objects.
*/
public FetchPlan setLockScope(PessimisticLockScope scope);
/**
* The number of milliseconds to wait for a query, or -1 for no
* limit.
*/
public int getQueryTimeout();
/**
* The number of milliseconds to wait for a query, or -1 for no
* limit.
*/
public FetchPlan setQueryTimeout(int timeout);
/**
* The lock level to use for locking loaded objects.
*/
public LockModeType getReadLockMode();
/**
* The lock level to use for locking loaded objects.
*/
public FetchPlan setReadLockMode(LockModeType mode);
/**
* The lock level to use for locking dirtied objects.
*/
public LockModeType getWriteLockMode();
/**
* The lock level to use for locking dirtied objects.
*/
public FetchPlan setWriteLockMode(LockModeType mode);
/**
* @deprecated cast to {@link FetchPlanImpl} instead. This
* method pierces the published-API boundary, as does the SPI cast.
*/
@Reflectable(false)
public org.apache.openjpa.kernel.FetchConfiguration getDelegate();
/**
* Affirms if extended path lookup feature is active.
*
* @since 2.0.0
*/
public boolean getExtendedPathLookup();
/**
* Sets extended path lookup feature.
*
* @since 2.0.0
*/
public FetchPlan setExtendedPathLookup(boolean flag);
/**
* Gets the current storage mode for data cache.
*
* @since 2.0.0
*/
public DataCacheStoreMode getCacheStoreMode();
/**
* Sets the current storage mode for data cache.
*
* @since 2.0.0
*/
public FetchPlan setCacheStoreMode(DataCacheStoreMode mode);
/**
* Gets the current retrieve mode for data cache.
*
* @since 2.0.0
*/
public DataCacheRetrieveMode getCacheRetrieveMode();
/**
* Sets the current retrieve mode for data cache.
*
* @since 2.0.0
*/
public FetchPlan setCacheRetrieveMode(DataCacheRetrieveMode mode);
/**
* Set the hint for the given key to the given value.
*
* @param value the value of the hint.
* @param name the name of the hint.
*
* @since 2.0.0
*/
public void setHint(String key, Object value);
/**
* Get the hints and their values currently set on this receiver.
*
* @return empty map if no hint has been set.
*/
Map<String, Object> getHints();
/**
* Get the hint value for the given key.
*
* @return null if the key has not been set.
*/
Object getHint(String key);
}