package org.jutil.relation;import java.util.List;import java.util.ArrayList;/** * <p>A class of Relation components for implementing a binding in which the object of * the Reference has a relation with only 1 other object.</p> * * <center><img src="doc-files/Reference.png"/></center> * * <p>In UML this class is used for implementing multiplicity 1:</p> * * <center><img src="doc-files/reference_uml.png"/></center> * * <p>In Java, you get the following situation.</p> * <center><img src="doc-files/reference_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>Reference</code>  * object and <code>A</code> is made by passing <code>this</code> to the constructor of  * Reference.</p> * * <p>This is actually a lightweight version of the APElement 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 B { *  public B() { *    _a = new Reference(this); *  } * *  public A getA() { *    return (A)_a.getOtherEnd(); *  } * *  public void setA(A a) { *    _a.connectTo(a == null ? null : a.getBLink()); *  } * *  Reference getALink() { *    return _a; *  } * *  private Reference _a; *} * </code></pre> * * <p>The other class must have a method <code>getBLink()</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>getBLink()</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>B</code> the <code>setA()</code> may be removed. Similarly, <code>getALink()</code> may  * be removed if the binding is not mutable from class <code>A</code>.</p> * * @path    $Source: /cvsroot/org-jutil/jutil.org/src/org/jutil/relation/Reference.java,v $ * @version $Revision: 1.6 $ * @date    $Date: 2002/09/07 20:47:41 $ * @state   $State: Exp $ * @author  Marko van Dooren * @release $Name:  $ */public class Reference extends Relation { 	/* The revision of this class */	public final static String CVS_REVISION ="$Revision: 1.6 $"; /*@    @ public invariant getOtherRelation() != null ==>   @                  getOtherRelation().contains(this);   @*/    /**   * Initialize a new Reference for the given object.   * The new Reference will be unconnected.   *   * @param object   *        The object at this side of the binding.   */ /*@   @ public behavior   @   @ pre object != null;   @   @ post getObject() == object;   @ post getOtherRelation() == null;   @*/  public Reference(Object object) {    super(object);  }  /**   * Initialize a new Reference for the given object,   * connected to the given Relation.   *   * @param object   *        The object at this side of the binding.   * @param other   *        The Relation component at the other side of the binding.   */ /*@   @ public behavior   @   @ pre object != null;   @   @ post getObject() == object;   @ post getOtherRelation() == other;   @ post other != null ==> other.contains(this);   @ post other.registered(new ArrayList(), this);   @*/  public Reference(Object object, Relation other) {    super(object);    connectTo(other);  }      /**   * Return the Object at the other end of this double binding.   */ /*@   @ public behavior   @   @ post getOtherRelation() == null ==> \result == null;   @ post getOtherRelation() != null ==> \result == getOtherRelation().getObject();   @*/  public Object getOtherEnd() {    if (getOtherRelation() == null) {        return null;    }    return getOtherRelation().getObject();  } /*@   @ also public behavior   @   @ post \result != null;   @ post getOtherEnd() != null ==> (   @                                 \result.size() == 1 &&   @                                 \result.contains(getOtherEnd())   @                                );   @ post getOtherEnd() == null ==> \result.isEmpty();   @*/  public List getOtherEnds() {    if (getOtherRelation() == null) {        return new ArrayList();    }    ArrayList result = new ArrayList();    result.add(getOtherRelation().getObject());    return result;  }  /**   * Set the other side of this binding.   *   * @param other   *        The new Relation this Reference will be connected to.   */ /*@   @ public behavior   @   @ post registered(\old(getOtherRelations()), other);   @ post other != null ==> other.registered(\old(other.getOtherRelations()), this);   @*/  public void connectTo(Relation other) {    if (other != _other) {      register(other);      if (other != null) {          other.register(this);      }    }  } /*@   @ also public behavior   @   @ post \result == (registered != null ==> contains(registered)) &&   @                 (   @                   (   @                     (oldConnections.size() == 0)   @                   )   @                   ||   @                   (   @                     (oldConnections.size() == 1) &&   @                     (   @                       (oldConnections.get(1) == registered)   @                       ||   @                       (   @                         (! contains((Relation)oldConnections.get(1)))   @                         //(\forall Relation r; r != this;   @                         //   \old(((Relation)oldConnections.get(1)).contains(r)) ==    @                         //   ((Relation)oldConnections.get(1)).contains(r)   @                         //) FIXME   @                       )   @                     )   @                   )   @                 );   @*/  public boolean registered(List oldConnections, Relation registered) {    return (oldConnections != null) &&           (contains(registered)) &&           (             (               (oldConnections.size() == 0)             )             ||             (               (oldConnections.size() == 1) &&               (                 (oldConnections.get(1) == registered)                 ||                 (                   (! contains((Relation)oldConnections.get(1)))                 )               )             )           );  } /*@   @ also public behavior   @   @ post \result == (getOtherRelations().isEmpty()) &&   @                 (   @                   (   @                     (oldConnections.size() == 1) &&   @                     (oldConnections.get(1) == unregistered)   @                   )   @                   ||   @                   (oldConnections.size() == 0)   @                 );   @*/  public boolean unregistered(List oldConnections, Relation unregistered) {    return (oldConnections != null) &&           (getOtherEnds().isEmpty()) &&           (             (               (oldConnections.size() == 1) &&               (oldConnections.get(1) == unregistered)             )             ||             (oldConnections.size() == 0)           );  } /*@   @ also public behavior   @   @ post \result == true;   @*/  protected boolean isValidElement(Relation relation) {    return true;  }  /**   * See superclass   */  protected void unregister(Relation other) {    _other = null;  }  /**   * See superclass   */  protected void register(Relation other) {    if(_other != null) {      _other.unregister(this);    }    _other = other;  }  /**   * return the Relation this Reference belongs to   */  public Relation getOtherRelation() {    return _other;  }    /**   * See superclass.   */  public List getOtherRelations() {    ArrayList result = new ArrayList();    if(_other != null) {      result.add(_other);    }    return result;  }    /**   * The Relation this Reference belongs to   */  private Relation _other;  }/*<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>*/