package org.jutil.relation;import org.jutil.java.collections.Visitor;import java.util.HashSet;import java.util.Set;import java.util.List;import java.util.ArrayList;import org.jutil.java.collections.ForAll;/** * <p>A class of Relation components for implementing a binding in which the object of * the Reference has a relation with N other objects. This component behaves as a set.</p> * * <center><img src="doc-files/ReferenceSet.png"/></center> * * <p>In UML this class is used for implementing multiplicity n:</p> * * <center><img src="doc-files/referenceset_uml.png"/></center> * * <p>In Java, you get the following situation.</p> * <center><img src="doc-files/referenceset_java.png"/></center> * * <p>Note that the question mark is represented by a <code>Relation</code> object since * we don't know its multiplicity. The double binding between the <code>ReferenceSet</code>  * object and <code>A</code> is made by passing <code>this</code> to the constructor of  * ReferenceSet.</p> * * <p>This is actually a lightweight version of the APSet class. * of the <a href="http://www.beedra.org">Beedra</a> framework of Jan Dockx.</p> * * <p>This class is typically using in the following way. * <pre><code> *public class A { * *  public A() { *    _b= new ReferenceSet(this); *  } * *  public List getBs() { *    return _b.getOtherEnds(); *  } * *  // public Set getBs() { *  //   return new TreeSet(_b.getOtherEnds()); *  // } * *  public void addB(B b) { *    _b.add(b.getALink()); *  } * *  public void removeB(B b) { *    _b.remove(b.getALink()); *  } * *  private ReferenceSet _b; *} * </code></pre> * * <p>The other class must have a method <code>getALink()</code>, which returns a  * <a href="Relation.html"><code>Relation</code></a> object that represents the other side * of the bi-directional binding. In case the two classes are not in the same package that means * that <code>getALink()</code> must be <code>public</code> there, but that is also the case when * not working with these components. Note that if the binding should not be mutable from class  * <code>A</code> the <code>addB()</code> may be removed. Similarly, <code>getBLink()</code> may  * be removed if the binding is not mutable from class <code>B</code>.</p> * * <p>If <code>getBs()</code> must return a Set, you should add the result of <code>_b.getOtherEnds()</code> * to a new Set (e.g. TreeSet). The general method <code>getOtherEnds()</code> must return a <code>List</code> * because in some bindings the order may be important.</p> * * @path    $Source: /cvsroot/org-jutil/jutil.org/src/org/jutil/relation/ReferenceSet.java,v $ * @version $Revision: 1.9 $ * @date    $Date: 2002/09/08 14:47:11 $ * @state   $State: Exp $ * @author  Marko van Dooren * @release $Name:  $ */public class ReferenceSet extends Relation {  	/* The revision of this class */	public final static String CVS_REVISION ="$Revision: 1.9 $"; //@ public invariant contains(null) == false; //@ public invariant getObject() != null;  /*@    @ public invariant (\forall Relation e; contains(e);   @                    e.contains(this));   @*/  /**   * Initialize an empty ReferenceSet for the given object.   *   * @param object   *        The object on this side of the binding   */ /*@   @ public behavior   @   @ pre object != null;   @   @ post getObject() == object;   @ post (\forall Relation r;; !contains(r));   @*/  public ReferenceSet(Object object) {    super(object);    _elements = new HashSet();  }    /**   * Remove the given Relation from this ReferenceSet.   *   * @param element   *        The Relation to be removed.   */ /*@   @ public behavior   @   @ pre other != null;   @   @ post unregistered(\old(getOtherRelations()), other);   @ post other.unregistered(\old(other.getOtherRelations()), this);   @*/    public void remove(Relation other) {    if (contains(other)) {      other.unregister(this);      unregister(other);    }  }  /**   * Add the given Relation to this ReferenceSet.   *   * @param element   *        The Relation to be added.   */ /*@   @ public behavior   @   @ pre element != null;   @   @ post registered(\old(getOtherRelations()), element);   @ post element.registered(\old(element.getOtherRelations()),this);   @*/    public void add(Relation element) {    element.register(this);    register(element);  }        /**   * Return a set containing the objects at the   * n side of the 1-n binding.   */ /*@   @ also public behavior   @   @ post (\forall Object o;;   @        \result.contains(o) <==>    @        (\exists Relation r; contains(r);   @          r.getObject().equals(o)));   @ post \result != null;   @*/  public List getOtherEnds() {    final List result = new ArrayList();    new Visitor() {      public void visit(Object element) {        result.add(((Relation)element).getObject());      }    }.applyTo(_elements);    return result;  }      /**   * Return a set containing the Relations at the   * other side of this binding.   */ /*@   @ also public behavior   @   @ post (\forall Relation s;;   @       contains(s) <==> \result.contains(s));   @ post \result != null;   @*/  public List getOtherRelations() {    return new ArrayList(_elements);  }    /**   * Remove the given Relation from this ReferenceSet   *   * @param element   *        The element to be removed.   */ /*@   @ also protected behavior   @   @ pre element != null;   @   @ post ! contains(element);   @*/  protected void unregister(Relation element) {    _elements.remove(element);  }        /**   * Add the given Relation to this ReferenceSet   *   * @param element   *        The element to be added.   */ /*@   @ also protected behavior   @   @ pre element != null;   @*/  protected void register(Relation element) {    _elements.add(element);  }   /*@   @ also public behavior   @   @ post \result == (contains(registered)) &&   @                 (\forall Relation r; r != registered;   @                   oldConnections.contains(r) == contains(r)   @                 );   @*/  public boolean registered(List oldConnections, Relation registered) {    return (oldConnections != null) &&           (contains(registered)) &&           new ForAll() {             public boolean criterion(Object o) {               return (o instanceof Relation) && ReferenceSet.this.contains((Relation)o);             }           }.in(_elements);  } /*@   @ also public behavior   @   @ post \result == (oldConnections.contains(unregistered)) &&   @                 (\forall Object o; oldConnections.contains(o); o instanceof Relation) &&   @                 (! contains(unregistered)) &&   @                 (\forall Relation r; r != unregistered;   @                   oldConnections.contains(r) == contains(r));   @*/  public boolean unregistered(List oldConnections, final Relation unregistered) {    // FIXME : implementation is not correct   return (oldConnections != null) &&          (oldConnections.contains(unregistered)) &&          new ForAll() {            public boolean criterion(Object o) {              return o instanceof Relation;            }          }.in(oldConnections) &&           (! contains(unregistered)) &&          new ForAll() {            public boolean criterion(Object o) {              return (o == unregistered) || contains((Relation)o);            }          }.in(oldConnections);  } /*@   @ also public behavior   @   @ post \result == (relation != null);   @*/  protected boolean isValidElement(Relation relation) {    return (relation != null);  }	/**	 * Return the size of the ReferenceSet	 */ /*@	 @ public behavior	 @	 @ post \result == getOtherRelations().size();	 @*/	public int size() {		return _elements.size();  }	  /**   * Check whether or not the given element is connected to   * this ReferenceSet.   *   * @param element   *        The element of which one wants to know if it is in   *        this ReferenceSet.   */  public boolean contains(Relation element) {    return _elements.contains(element);  }    /**   * The set containing the StructureElements at the n side of the 1-n binding.   */ /*@   @ private invariant ! _elements.contains(null);   @ private invariant (\forall Object o; _elements.contains(o);   @                      o instanceof Relation);   @*/  private HashSet _elements;}/*<copyright>Copyright (C) 1997-2001. This software is copyrighted by the people and entities mentioned after the "@author" tags above, on behalf of the JUTIL.ORG Project. The copyright is dated by the dates after the "@date" tags above. All rights reserved.This software is published under the terms of the JUTIL.ORG SoftwareLicense version 1.1 or later, a copy of which has been included withthis distribution in the LICENSE file, which can also be found athttp://org-jutil.sourceforge.net/LICENSE. This software is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the JUTIL.ORG Software License for more details.For more information, please see http://org-jutil.sourceforge.net/</copyright>*/