001    package org.odmg;
002    
003    
004    
005    /**
006    
007     * This interface defines the operations associated with an ODMG bag collection.
008    
009     * All of the operations defined by the JavaSoft <code>Collection</code>
010    
011     * interface are supported by an ODMG implementation of <code>DBag</code>,
012    
013     * the exception <code>UnsupportedOperationException</code> is not thrown when a
014    
015     * call is made to any of the <code>Collection</code> methods.
016    
017     * @author      David Jordan (as Java Editor of the Object Data Management Group)
018    
019     * @version ODMG 3.0
020    
021     */
022    
023    // * @see java.lang.UnsupportedOperationException
024    
025    
026    
027    public interface DBag extends DCollection
028    
029    {
030    
031        /**
032    
033         * A new <code>DBag</code> instance is created that is the union of this object
034    
035         * and <code>otherBag</code>.
036    
037         * This method is similar to the <code>addAll</code> method in <code>Collection</code>,
038    
039         * except that this method creates a new collection and <code>addAll</code>
040    
041         * modifies the object to contain the result.
042    
043         * @param   otherBag        The other bag to use in the union operation.
044    
045         * @return A <code>DBag</code> instance that contains the union of this object
046    
047         * and <code>otherBag</code>.
048    
049         */
050    
051    // * @see       com.sun.java.util.collections.Collection#addAll
052    
053        public DBag union(DBag otherBag);
054    
055    
056    
057        /**
058    
059         * A new <code>DBag</code> instance is created that contains the intersection of
060    
061         * this object and the <code>DBag</code> referenced by <code>otherBag</code>.
062    
063         * This method is similar to the <code>retainAll</code> method in <code>Collection</code>,
064    
065         * except that this method creates a new collection and <code>retainAll</code>
066    
067         * modifies the object to contain the result.
068    
069         * @param   otherBag The other bag to use in creating the intersection.
070    
071         * @return A <code>DBag</code> instance that contains the intersection of this
072    
073         * object and <code>otherBag</code>.
074    
075         */
076    
077    // @see com.sun.java.util.collections.Collection#retainAll
078    
079        public DBag intersection(DBag otherBag);
080    
081    
082    
083        /**
084    
085         * A new <code>DBag</code> instance is created that contains the difference of
086    
087         * this object and the <code>DBag</code> instance referenced by <code>otherBag</code>.
088    
089         * This method is similar to the <code>removeAll</code> method in <code>Collection</code>,
090    
091         * except that this method creates a new collection and <code>removeAll</code>
092    
093         * modifies the object to contain the result.
094    
095         * @param   otherBag The other bag to use in creating the difference.
096    
097         * @return A <code>DBag</code> instance that contains the elements of this object
098    
099         * minus the elements in <code>otherBag</code>.
100    
101         */
102    
103    // * @see com.sun.java.util.collections.Collection#removeAll
104    
105        public DBag difference(DBag otherBag);
106    
107    
108    
109        /**
110    
111         * This method returns the number of occurrences of the object <code>obj</code>
112    
113         * in the <code>DBag</code> collection.
114    
115         * @param obj The value that may have elements in the collection.
116    
117         * @return The number of occurrences of <code>obj</code> in this collection.
118    
119         */
120    
121        public int occurrences(Object obj);
122    
123    }
124