001    package org.apache.ojb.broker;
002    
003    /* Copyright 2002-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 java.util.Iterator;
019    
020    /**
021     * OJB can handle java.util.Collection as well as user defined collection classes as collection attributes
022     * in persistent classes. In order to collaborate with the OJB mechanisms these collection must provide a minimum
023     * protocol as defined by this interface ManageableCollection.
024     * The methods have a prefix "ojb" that indicates that these methods are "technical" methods, required
025     * by OJB and not to be used in business code.
026     *
027     * @author Thomas Mahler
028     * @version $Id: ManageableCollection.java,v 1.1 2007-08-24 22:17:36 ewestfal Exp $
029     */
030    public interface ManageableCollection extends java.io.Serializable
031    {
032        /**
033         * Adds a single object to the Collection. This method is used during reading collection elements
034         * from the database. Thus it is safe to cast the object to the underlying element type of the
035         * collection.
036         * 
037         * @param anObject The object to add
038         */
039        void ojbAdd(Object anObject);
040    
041        /**
042         * Adds another collection to this collection. Used in reading extents from the database.
043         * Thus it is safe to cast the given collection to this class.
044         * 
045         * @param otherCollection The added collection
046         */
047        void ojbAddAll(ManageableCollection otherCollection);
048    
049        /**
050         * Returns an iterator over all elements in the collection. Used during store and delete
051         * operations. If the implementor does not return an iterator over ALL elements, OJB cannot
052         * store and delete all elements properly.
053         *
054         * @return The iterator
055         */
056        Iterator ojbIterator();
057    
058        /**
059         * A callback method to implement 'removal-aware' (track removed objects and delete
060         * them by its own) collection implementations.
061         * 
062         * @param broker The persistence broker
063         */
064        public void afterStore(PersistenceBroker broker) throws PersistenceBrokerException;
065    }