001    package data;
002    
003    /**
004     * An entry in a {@link DataBasket}.
005     *
006     * <p>DataBasketEntries describe an object that was removed from a data container, put into a data container
007     * or moved between data containers. They know about the {@link #getSource source} and
008             * {@link #getDestination destination} of the operation and about the {@link #getValue object} that was moved.
009     * Additionally, they know how to {@link #commit commit} or {@link #rollback rollback} the operation.</p>
010     *
011     * <p>For reasons of efficency, DataBasketEntries are stored in a hierarchical structure, with three levels:
012     * categories, these are selected via the DataBasketEntry's {@link #getMainKey main key}; subcategories,
013     * selected via the DataBasketEntry's {@link #getSecondaryKey secondary key}; and the items selected by the
014     * DataBasketEntry's {@link #getValue value}.</p>
015     *
016     * @author Steffen Zschaler
017     * @version 2.0 14/06/1999
018     * @since v2.0
019     */
020    public interface DataBasketEntry extends DataBasketKeys {
021    
022        /**
023         * Roll back the operation described by the DataBasketEntry.
024         *
025         * @override Always
026         */
027        public void rollback();
028    
029        /**
030         * Commit the operation described by the DataBasketEntry.
031         *
032         * @override Always
033         */
034        public void commit();
035    
036        /**
037         * Notification that the DataBasketEntry was put into a DataBasket.
038         *
039         * @param dbOwner the DataBasket that owns this DataBasketEntry. Can be <code>null</code>.
040         *
041         * @override Always
042         */
043        public void setOwner(DataBasket dbOwner);
044    
045        /**
046         * Return the DataBasket containing this DataBasketEntry. Initially <code>null</code>. Once
047         * {@link #setOwner} has been called, always returns the last value of the <code>dbOwner</code>
048         * parameter passed to <code>setOwner</code>.
049         *
050         * @return the DataBasket containing this DataBasketEntry.
051         */
052        public DataBasket getOwner();
053    
054        /**
055         * Get the source of the operation described by the DataBasketEntry.
056         *
057         * @override Always
058         */
059        public DataBasketEntrySource getSource();
060    
061        /**
062         * Get the destination of the operation described by the DataBasketEntry.
063         *
064         * @override Always
065         */
066        public DataBasketEntryDestination getDestination();
067    
068        /**
069         * Get the object moved by the operation described by the DataBasketEntry.
070         *
071         * @override Always
072         */
073        public Object getValue();
074    
075        /**
076         * Get the DataBasketEntry's main key.
077         *
078         * @override Always
079         */
080        public String getMainKey();
081    
082        /**
083         * Get the DataBasketEntry's secondary key.
084         *
085         * @override Always
086         */
087        public String getSecondaryKey();
088    
089        /**
090         * Return false as long as no complete commit or rollback has been issued for this
091         * DataBasketEntry. Returning true will lead to the DataBasketEntry being removed from the
092         * DataBasket as soon as convenient. DataBasketEntries that return true from this method
093         * are, however, guaranteed to no longer participate in any iterations of the DataBasket.
094         *
095         * @override Always
096         */
097        public boolean isHandled();
098    }