001    package org.apache.ojb.otm;
002    
003    /* Copyright 2003-2005 The Apache Software Foundation
004     *
005     * Licensed under the Apache License, Version 2.0 (the "License");
006     * you may not use this file except in compliance with the License.
007     * You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    
018    import org.apache.ojb.broker.Identity;
019    import org.apache.ojb.otm.lock.LockingException;
020    import org.apache.ojb.otm.states.State;
021    
022    import java.util.Collection;
023    
024    /**
025     *
026     * The EditingContext contains and manages the set of object read/edited within the context of a
027     * transaction. Logically, this could be considered similar to a document that is being edited.
028     * During commit, all objects within this transaction that are marked as being written to (ones
029     * with a write lock) are written back to the persistent store.
030     *
031     * @author <a href="mailto:rraghuram@hotmail.com">Raghu Rajah</a>
032     *
033     */
034    public interface EditingContext
035    {
036    
037        /**
038         *
039         * Insert the given object into the EditingContext, acquiring the specified lock.
040         *
041         * @param oid                   the identity of the object to be inserted
042         * @param userObject            the object to insert, for user operations
043         * @param lock                  the lock to be acquired.
044         * @throws LockingException     thrown by the Lock Manager to avoid deadlocks. The insertion
045         *                              could be re-attempted if the lock fails.
046         *
047         */
048        public void insert (Identity oid, Object userObject, int lock)
049                throws LockingException;
050    
051        /**
052         *
053         * Remove a managed object from the management of this EditingContext. All edits on the object
054         * will be lost. All locks kept by this object will be released.
055         *
056         * @param oid                   the Identity of the object to be removed from this context.
057         *
058         */
059        public void remove (Identity oid);
060    
061        /**
062         *
063         * Lookup object with the given oid in the Context.
064         *
065         * @param oid           the oid of the object to lookup
066         *
067         */
068        public Object lookup (Identity oid)
069                throws LockingException;
070    
071            /**
072             * lookup the state of an object, given the oid, in the context
073             * @param oid
074             * @return the state of that object in the context, null if the object is not in the context
075             * @throws LockingException
076             */
077            State lookupState(Identity oid)
078                            throws LockingException;
079    
080            void setState(Identity oid, State state);
081    
082            Collection getAllObjectsInContext();
083    
084        /**
085         *  Rollback all changes made during this transaction to the given object.
086         */
087        public void refresh(Identity oid, Object object);
088    }