All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.openjpa.kernel.Broker Maven / Gradle / Ivy

Go to download

There is a newer version: 4.0.0
Show newest version
/*
 * 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.kernel;

import java.util.Collection;
import java.util.Map;
import java.util.Set;

import javax.transaction.Synchronization;

import org.apache.openjpa.ee.ManagedRuntime;
import org.apache.openjpa.event.CallbackModes;
import org.apache.openjpa.event.LifecycleEventManager;
import org.apache.openjpa.lib.util.Closeable;
import org.apache.openjpa.meta.ClassMetaData;
import org.apache.openjpa.meta.FieldMetaData;
import org.apache.openjpa.meta.ValueMetaData;
import org.apache.openjpa.util.RuntimeExceptionTranslator;

/**
 * The broker is the primary interface into the OpenJPA runtime. Each broker
 * maintains an independent object cache and an independent transactional
 * context.
 *
 * @since 0.4.0
 * @author Abe White
 */
public interface Broker
    extends Synchronization, Closeable, StoreContext,
    ConnectionRetainModes, DetachState, LockLevels,
    RestoreState, AutoClear, AutoDetach, CallbackModes {

    /**
     * Set the broker's behavior for implicit actions such as flushing,
     * automatic detachment, and exceptions thrown by managed instances outside
     * a broker operation. A broker's implicit behavior can only be set once;
     * after the first invocation with non-null arguments,
     * subsequent invocations of this method are ignored.
     */
    public void setImplicitBehavior(OpCallbacks call,
        RuntimeExceptionTranslator ex);

    /**
     * Return the factory that produced this broker.
     */
    public BrokerFactory getBrokerFactory();

    /**
     * Return the connection retain mode for this broker.
     */
    public int getConnectionRetainMode();

    /**
     * Return the managed runtime in use.
     */
    public ManagedRuntime getManagedRuntime();

    /**
     * Return the inverse manager in use.
     *
     * @since 0.3.2
     */
    public InverseManager getInverseManager();

    /**
     * Whether the broker or its managed instances are used in a multithreaded
     * environment.
     */
    public boolean getMultithreaded();

    /**
     * Whether the broker or its managed instances are used in a multithreaded
     * environment.
     */
    public void setMultithreaded(boolean multi);

    /**
     * Whether to take into account changes in the transaction when executing
     * a query or iterating an extent.
     */
    public boolean getIgnoreChanges();

    /**
     * Whether to take into account changes in the transaction when executing
     * a query or iterating an extent.
     */
    public void setIgnoreChanges(boolean ignore);

    /**
     * Whether to allow nontransactional access to persistent state.
     */
    public boolean getNontransactionalRead();

    /**
     * Whether to allow nontransactional access to persistent state.
     */
    public void setNontransactionalRead(boolean read);

    /**
     * Whether to allow nontransactional changes to persistent state.
     */
    public boolean getNontransactionalWrite();

    /**
     * Whether to allow nontransactional changes to persistent state.
     */
    public void setNontransactionalWrite(boolean write);

    /**
     * Whether to restore an object's original state on rollback.
     */
    public int getRestoreState();

    /**
     * Whether to restore an object's original state on rollback.
     */
    public void setRestoreState(int restore);

    /**
     * Whether to use optimistic transactional semantics.
     */
    public boolean getOptimistic();

    /**
     * Whether to use optimistic transactional semantics.
     */
    public void setOptimistic(boolean opt);

    /**
     * Whether objects retain their persistent state on transaction commit.
     */
    public boolean getRetainState();

    /**
     * Whether objects retain their persistent state on transaction commit.
     */
    public void setRetainState(boolean retain);

    /**
     * Whether objects clear when entering transactions.
     */
    public int getAutoClear();

    /**
     * Whether objects clear when entering transactions.
     */
    public void setAutoClear(int clear);

    /**
     * Whether to check for a global transaction upon every managed,
     * non-transactional operation. Defaults to false.
     */
    public boolean getSyncWithManagedTransactions();

    /**
     * Whether to check for a global transaction upon every managed,
     * non-transactional operation. Defaults to false.
     */
    public void setSyncWithManagedTransactions(boolean resync);

    /**
     * Bit flags marked in {@link AutoDetach} which indicate when persistent
     * managed objects should be automatically detached in-place.
     */
    public int getAutoDetach();

    /**
     * Bit flags marked in {@link AutoDetach} which indicate when persistent
     * managed objects should be automatically detached in-place.
     */
    public void setAutoDetach(int flags);

    /**
     * Bit flags marked in {@link AutoDetach} which indicate when persistent
     * managed objects should be automatically detached in-place.
     */
    public void setAutoDetach(int flag, boolean on);
    
    /**
     * Retrieve the current properties for this broker Some of these properties
     * may have been changed from the original configuration.
     * 
     * @return the changed properties
     * 
     * @since 2.0.0
     */
    public Map getProperties();
    
    /**
     * Return the supported properties for this broker as property keys. If a
     * property has multiple keys, all keys will be returned.
     * 
     * @since 2.0.0
     */
    public Set getSupportedProperties();

    /**
     * Whether to treat relations to detached instances during persist
     * operations as new or as pseudo-hollow instances.
     */
    public boolean isDetachedNew();

    /**
     * Whether to treat relations to detached instances as new.
     */
    public void setDetachedNew(boolean isNew);

    /**
     * Whether to also evict an object from the store cache when it is
     * evicted through this broker.
     */
    public boolean getEvictFromDataCache();

    /**
     * Whether to also evict an object from the store cache when it is
     * evicted through this broker.
     */
    public void setEvictFromDataCache(boolean evict);

    /**
     * Put the specified key-value pair into the map of user objects. Use
     * a value of null to remove the key.
     *
     * @since 0.3.2
     */
    public Object putUserObject(Object key, Object val);

    /**
     * Get the value for the specified key from the map of user objects.
     *
     * @since 0.3.2
     */
    public Object getUserObject(Object key);

    /**
     * Register a listener for transaction-related events.
     *
     * @since 0.2.5
     */
    public void addTransactionListener(Object listener);

    /**
     * Remove a listener for transaction-related events.
     *
     * @since 0.2.5
     */
    public void removeTransactionListener(Object listener);
    
    /**
     * Gets an umodifiable collection of currently registered lsteners.
     * 
     * @since 2.0.0
     */
    public Collection getTransactionListeners();

    /**
     * The callback mode for handling exceptions from transaction event
     * listeners.
     */
    public int getTransactionListenerCallbackMode();

    /**
     * The callback mode for handling exceptions from transaction event
     * listeners.
     */
    public void setTransactionListenerCallbackMode(int mode);

    /**
     * Register a listener for lifecycle-related events on the specified
     * classes. If the classes are null, all events will be propagated to
     * the listener.
     *
     * @since 0.3.3
     */
    public void addLifecycleListener(Object listener, Class[] classes);

    /**
     * Remove a listener for lifecycle-related events.
     *
     * @since 0.3.3
     */
    public void removeLifecycleListener(Object listener);

    /**
     * Return the lifecycle event manager associated with the broker.
     */
    public LifecycleEventManager getLifecycleEventManager();

    /**
     * The callback mode for handling exceptions from lifecycle event listeners.
     */
    public int getLifecycleListenerCallbackMode();

    /**
     * The callback mode for handling exceptions from lifecycle event listeners.
     */
    public void setLifecycleListenerCallbackMode(int mode);

    
    /**
     * Affirms if this receiver is caching prepared queries.
     *  
     * @since 2.0.0
     */
    public boolean getCachePreparedQuery();
    
    /**
     * Sets whether this receiver will cache prepared queries during its 
     * lifetime. The cache configured at BrokerFactory level is not affected by 
     * setting it inactive for this receiver. 
     * 
     * @since 2.0.0
     */
    public void setCachePreparedQuery(boolean flag);

    /**
     * Begin a transaction.
     */
    public void begin();

    /**
     * Commit the current transaction.
     */
    public void commit();

    /**
     * Rollback the current transaction.
     */
    public void rollback();

    /**
     * Attempt to synchronize with a current managed transaction, returning
     * true if successful, false if no managed transaction is active.
     */
    public boolean syncWithManagedTransaction();

    /**
     * Issue a commit and then start a new transaction. This is identical to:
     * 
 broker.commit (); broker.begin ();
     * 
 except that the broker's internal atomic lock is utilized,
     * so this method can be safely executed from multiple threads.
     *
     * @see #commit()
     * @see #begin()
     * @since 0.2.4
     */
    public void commitAndResume();

    /**
     * Issue a rollback and then start a new transaction. This is identical to:
     * 
 broker.rollback (); broker.begin ();
     * 
 except that the broker's internal atomic lock is utilized,
     * so this method can be safely executed from multiple threads.
     *
     * @see #rollback()
     * @see #begin()
     * @since 0.2.4
     */
    public void rollbackAndResume();

    /**
     * Return whether the current transaction has been marked for rollback.
     */
    public boolean getRollbackOnly();

    /**
     * Mark the current transaction for rollback.
     */
    public void setRollbackOnly();

    /**
     * Mark the current transaction for rollback with the specified cause
     * of the rollback.
     *
     * @since 0.9.7
     */
    public void setRollbackOnly(Throwable cause);

    /** 
     * Returns the Throwable that caused the transaction to be
     * marked for rollback. 
     *  
     * @return the Throwable, or null if none was given
     *
     * @since 0.9.7
     */
    public Throwable getRollbackCause();

    /**
     * Set a transactional savepoint where operations after this savepoint
     * will be rolled back.
     */
    public void setSavepoint(String name);

    /**
     * Rollback the current transaction to the last savepoint.
     * Savepoints set after this one will become invalid.
     */
    public void rollbackToSavepoint();

    /**
     * Rollback the current transaction to the given savepoint name.
     * Savepoints set after this one will become invalid.
     */
    public void rollbackToSavepoint(String name);

    /**
     * Release the last set savepoint and any resources associated with it.
     * The given savepoint and any set after it will become invalid.
     */
    public void releaseSavepoint();

    /**
     * Release the savepoint and any resources associated with it.
     * The given savepoint and any set after it will become invalid.
     */
    public void releaseSavepoint(String name);

    /**
     * Flush all transactional instances to the data store. This method may
     * set the rollback only flag on the current transaction if it encounters
     * an error.
     *
     * @since 0.2.5
     */
    public void flush();

    /**
     * Run pre-flush actions on transactional objects, including
     * persistence-by-reachability, inverse relationship management,
     * deletion of dependent instances, and instance callbacks.
     * Transaction listeners are not invoked.
     *
     * @since 0.3.3
     */
    public void preFlush();

    /**
     * Validate the changes made in this transaction, reporting any optimistic
     * violations, constraint violations, etc. In a datastore transaction or
     * a flushed optimistic transaction, this method will act just like
     * {@link #flush}. In an optimistic transaction that has not yet begun a
     * datastore-level transaction, however, it will only report exceptions
     * that would occur on flush, without retaining any datastore resources.
     */
    public void validateChanges();

    /**
     * Persist the given object.
     */
    public void persist(Object obj, OpCallbacks call);

    /**
     * Persist the given objects.
     */
    public void persistAll(Collection objs, OpCallbacks call);

    /**
     * Make the given instance persistent. Unlike other persist operations,
     * this method does not immediately cascade to fields marked
     * {@link ValueMetaData#CASCADE_IMMEDIATE}.
     *
     * @param pc the instance to persist
     * @param id the id to give the state manager; may be null for default
     * @return the state manager for the newly persistent instance
     */
    public OpenJPAStateManager persist(Object pc, Object id, OpCallbacks call);

    /**
     * Delete the given object.
     */
    public void delete(Object pc, OpCallbacks call);

    /**
     * Delete the given objects.
     */
    public void deleteAll(Collection objs, OpCallbacks call);

    /**
     * Release the given object from management. This operation is not
     * recursive.
     */
    public void release(Object pc, OpCallbacks call);

    /**
     * Release the given objects from management. This operation is not
     * recursive.
     */
    public void releaseAll(Collection objs, OpCallbacks call);

    /**
     * Refresh the state of the given object.
     */
    public void refresh(Object pc, OpCallbacks call);

    /**
     * Refresh the state of the given objects.
     */
    public void refreshAll(Collection objs, OpCallbacks call);

    /**
     * Evict the given object.
     */
    public void evict(Object pc, OpCallbacks call);

    /**
     * Evict the given objects.
     */
    public void evictAll(Collection objs, OpCallbacks call);

    /**
     * Evict all clean objects.
     */
    public void evictAll(OpCallbacks call);

    /**
     * Evict all persistent-clean and persistent-nontransactional
     * instances in the given {@link Extent}.
     */
    public void evictAll(Extent extent, OpCallbacks call);

    /**
     * Detach all objects in place.  A flush will be performed before
     * detaching the entities.
     */
    public void detachAll(OpCallbacks call);

    /**
     * Detach all objects in place, with the option of performing a
     * flush before doing the detachment.
     * @param call Persistence operation callbacks
     * @param flush boolean value to indicate whether to perform a
     * flush before detaching the entities (true, do the flush;
     * false, don't do the flush)
     */
    public void detachAll(OpCallbacks call, boolean flush);

    /**
     * Detach the specified object from the broker.
     *
     * @param pc the instance to detach
     * @return the detached instance
     */
    public Object detach(Object pc, OpCallbacks call);

    /**
     * Detach the specified objects from the broker. The objects returned can
     * be manipulated and re-attached with {@link #attachAll}. The
     * detached instances will be unmanaged copies of the specified parameters,
     * and are suitable for serialization and manipulation outside
     * of a OpenJPA environment. When detaching instances, only fields
     * in the current {@link FetchConfiguration} will be traversed. Thus,
     * to detach a graph of objects, relations to other persistent
     * instances must either be in the default-fetch-group,
     * or in the current custom {@link FetchConfiguration}.
     *
     * @param objs the instances to detach
     * @return the detached instances
     */
    public Object[] detachAll(Collection objs, OpCallbacks call);

    /**
     * Import the specified detached object into the broker.
     *
     * @param pc instance to import
     * @return the re-attached instance
     * @param copyNew whether to copy new instances
     */
    public Object attach(Object pc, boolean copyNew, OpCallbacks call);

    /**
     * Import the specified objects into the broker. Instances that were
     * previously detached from this or another broker will have their
     * changed merged into the persistent instances. Instances that
     * are new will be persisted as new instances.
     *
     * @param objs array of instances to import
     * @return the re-attached instances
     * @param copyNew whether to copy new instances
     */
    public Object[] attachAll(Collection objs, boolean copyNew,
        OpCallbacks call);

    /**
     * Create a new instance of type cls. If cls is
     * an interface or an abstract class whose abstract methods follow the
     * JavaBeans convention, this method will create a concrete implementation
     * according to the metadata that defines the class.
     * Otherwise, if cls is a managed type, this will return an
     * instance of the specified class.
     *
     * @throws IllegalArgumentException if cls is not a managed
     * type or interface.
     */
    public Object newInstance(Class cls);

    /**
     * Returns true if obj is a detached object
     * (one that can be reattached to a {@link Broker} via a call to
     * {@link Broker#attach}); otherwise returns false.
     */
    public boolean isDetached(Object obj);

    /**
     * Return an extent of the given class, optionally including subclasses.
     */
    public Extent newExtent(Class cls, boolean subs);

    /**
     * Create a new query from the given data, with the given candidate class
     * and language.
     */
    public Query newQuery(String language, Class cls, Object query);

    /**
     * Create a new query in the given language.
     */
    public Query newQuery(String language, Object query);

    /**
     * Returns a {@link Seq} for the datastore identity values of the
     * specified persistent class, or null if the class' identity cannot be
     * represented as a sequence.
     */
    public Seq getIdentitySequence(ClassMetaData meta);

    /**
     * Returns a {@link Seq} for the generated values of the specified
     * field, or null if the field is not generated.
     */
    public Seq getValueSequence(FieldMetaData fmd);

    /**
     * Ensure that the given instance is locked at the given lock level.
     *
     * @param pc the object to lock
     * @param level the lock level to use
     * @param timeout the number of milliseconds to wait for the lock before
     * giving up, or -1 for no limit
     * @since 0.3.1
     */
    public void lock(Object pc, int level, int timeout, OpCallbacks call);

    /**
     * Ensure that the given instance is locked at the current lock level, as
     * set in the {@link FetchConfiguration} for the broker.
     *
     * @since 0.3.1
     */
    public void lock(Object pc, OpCallbacks call);

    /**
     * Ensure that the given instances are locked at the given lock level.
     *
     * @param objs the objects to lock
     * @param level the lock level to use
     * @param timeout the number of milliseconds to wait for the lock before
     * giving up, or -1 for no limit
     * @since 0.3.1
     */
    public void lockAll(Collection objs, int level, int timeout,
        OpCallbacks call);

    /**
     * Ensure that the given instances are locked at the current lock level, as
     * set in the {@link FetchConfiguration} for the broker.
     *
     * @since 0.3.1
     */
    public void lockAll(Collection objs, OpCallbacks call);

    /**
     * Cancel all pending data store statements. If statements are cancelled
     * while a flush is in progress, the transaction rollback only flag will
     * be set.
     *
     * @return true if any statements were cancelled, false otherwise
     * @since 0.3.1
     */
    public boolean cancelAll();

    /**
     * Mark the given class as dirty within the current transaction.
     *
     * @since 0.3.0
     */
    public void dirtyType(Class cls);

    /**
     * Begin a logical operation. This indicates to the broker the
     * granularity of an operation which may require pre/post operation
     * side-effects, such as non-tx detach.
     * Will lock the broker until the {@link #endOperation} is called.
     *
     * @param syncTrans whether instances may be loaded/modified during
     * this operation requiring a re-check of global tx
     * @return whether this is the outermost operation on the stack
     */
    public boolean beginOperation(boolean syncTrans);

    /**
     * End a logical operation. This indicates to the broker the
     * granularity of an operation which may require pre/post operation
     * side-effects, such as non-tx detach. Unlocks the given broker.
     *
     * @return whether this is the outermost operation on the stack
     */
    public boolean endOperation();

    /**
     * Whether the broker is closed.
     */
    public boolean isClosed();

    /**
     * Whether {@link #close} has been invoked, though the broker might 
     * remain open until the current managed transaction completes.
     */
    public boolean isCloseInvoked();

    /**
     * Close the broker.
     */
    public void close();

    /**
     * Throw an exception if this broker has been closed.
     */
    public void assertOpen();

    /**
     * Throw an exception if there is no active transaction.
     */
    public void assertActiveTransaction();

    /**
     * Throw an exception if there is no transaction active and
     * nontransactional reading is not enabled.
	 */
	public void assertNontransactionalRead ();

	/**
	 * Throw an exception if a write operation is not permitted (there is
	 * no active transaction and nontransactional writing is not enabled).
	 */
	public void assertWriteOperation ();
}
 















© 2015 - 2024 Weber Informatics LLC | Privacy Policy