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