4.4 Java4030: purpose of framework interfaces  (Page 3/4)

Collection classes should clearly specify in their documentation any restrictions on what elements may be added. If a collection refuses to add a particular element for any reason other than that it already contains the element, it must throw an exception (rather than returning false). This preserves the invariant that a collection always contains the specified element after this call returns."

As you can see, the behavior is defined in a very general way. There is no indication as to how that behavior is to be achieved.

The add method in Set

As you can see from the list above , the Set interface extends the Collection interface. In keeping with the general form of object-oriented design, Set is more specialized than Collection . Therefore, Set makes the contract for the add method more specific for objects of type Set . Here is some text from the Oracle documentation describing the contract of the add method for any class that implements the Set interface.

"Adds the specified element to this set if it is not already present (optional operation). More formally, adds the specified element e to this set if the set contains no element e2 such that (e==null ? e2==null : e.equals(e2)).

If this set already contains the element, the call leaves the set unchanged and returns false. In combination with the restriction on constructors, this ensures that sets never contain duplicate elements.

The stipulation above does not imply that sets must accept all elements; sets may refuse to add any particular element, including null, and throw an exception, as described in the specification for Collection.add. Individual set implementations should clearly document any restrictions on the elements that they may contain."

How do the contracts differ?

The contract for the add method, as declared in the Collection interface, does not prohibit duplicate elements, but does make the provision forinterfaces that extend Collection to prohibit duplicate elements.

The contract for the add method in the Set interface does prohibit duplicate elements.

What about the List interface?

Here is some text from the Oracle documentation describing the contract of the add method for any class that implements the List interface.

"Appends the specified element to the end of this list (optional operation).

Lists that support this operation may place limitations on what elements may be added to this list. In particular, some lists will refuse to add null elements, and others will impose restrictions on the type of elements that may be added. List classes should clearly specify in their documentation any restrictions on what elements may be added."

As you can see, the contract for the add method declared in the List interface, (which extends Collection) , does not prohibit duplicate elements. However, it does have some other requirementsthat don't apply to Set objects. For example, it must add new elements at the end of the list.

A major difference

This is one of the major differences between lists and sets in the Java Collection Framework. Both List objects and Set objects are collections, because both of the interfaces extend the Collection interface. However, the Set interface contract prohibits duplicate elements while the List interface contract does not prohibit duplicate elements.