reference.java

一个关于java 的常用工具包

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 Software
License version 1.1 or later, a copy of which has been included with
this distribution in the LICENSE file, which can also be found at
http://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>*/