From c553298c3e4f7191fccb9eac428a5b8f1b8f40dc Mon Sep 17 00:00:00 2001
From: Stephen Colebourne <scolebourne@apache.org>
Date: Sun, 28 Dec 2003 18:08:54 +0000
Subject: [PATCH] Document preferred equals behaviour

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@131465 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/commons/collections/Bag.java   | 28 +++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/src/java/org/apache/commons/collections/Bag.java b/src/java/org/apache/commons/collections/Bag.java
index 3dde3cc5b..e3897ec7f 100644
--- a/src/java/org/apache/commons/collections/Bag.java
+++ b/src/java/org/apache/commons/collections/Bag.java
@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Bag.java,v 1.11 2003/08/31 17:26:44 scolebourne Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/Bag.java,v 1.12 2003/12/28 18:08:54 scolebourne Exp $
  * ====================================================================
  *
  * The Apache Software License, Version 1.1
@@ -77,7 +77,7 @@ import java.util.Set;
  * which unfortunately will break backwards compatibility with this version.
  *
  * @since Commons Collections 2.0
- * @version $Revision: 1.11 $ $Date: 2003/08/31 17:26:44 $
+ * @version $Revision: 1.12 $ $Date: 2003/12/28 18:08:54 $
  * 
  * @author Chuck Burdick
  * @author Stephen Colebourne
@@ -239,4 +239,28 @@ public interface Bag extends Collection {
      */
     Iterator iterator();
 
+    // The following is not part of the formal Bag interface, however where possible
+    // Bag implementations should follow these comments.
+//    /**
+//     * Compares this Bag to another.
+//     * This Bag equals another Bag if it contains the same number of occurances of
+//     * the same elements.
+//     * This equals definition is compatable with the Set interface.
+//     * 
+//     * @param obj  the Bag to compare to
+//     * @return true if equal
+//     */
+//    boolean equals(Object obj);
+//
+//    /**
+//     * Gets a hash code for the Bag compatable with the definition of equals.
+//     * The hash code is defined as the sum total of a hash code for each element.
+//     * The per element hash code is defined as
+//     * <code>(e==null ? 0 : e.hashCode()) ^ noOccurances)</code>.
+//     * This hash code definition is compatable with the Set interface.
+//     * 
+//     * @return the hash code of the Bag
+//     */
+//    int hashCode();
+    
 }