git.gag.com Git - debian/openrocket/blob - core/src/net/sf/openrocket/rocketcomponent/Visitable.java

   1 /*
   2  * Visitable.java
   3  */
   4 package net.sf.openrocket.rocketcomponent;
   5
   6 /**
   7  * This interface describes a portion of the Visitor pattern, using generics to assure type-safety.
   8  * The elements of the concrete object hierarchy are only visitable by an associated hierarchy of visitors,
   9  * while these visitors are only able to visit the elements of that hierarchy.
  10  *
  11  * The key concept regarding the Visitor pattern is to realize that Java will only "discriminate" the type of an
  12  * object being called, not the type of an object being passed.
  13  *
  14  * In order for the type of two objects to be determinable to the JVM, each object must be the receiver of an
  15  * invocation. Here, when accept is called on a Visitable, the concrete type of the Visitable becomes "known" but the
  16  * concrete type of the argument is still unknown.  <code>visit</code> is then called on the parameter object, passing
  17  * the Visitable back, which has type and identity. Flow of control has now been 'double-dispatched' such that the
  18  * type (and identity) of both objects are known.
  19  *
  20  * Specifically, this interface is to be implemented by every class in the RocketComponent hierarchy that
  21  * can be visited AND which are sufficiently specialized from their super class.  If they only provide
  22  * constraints to their superclass (such as TubeCoupler), then the implementation of this interface at
  23  * the superclass level is sufficient.
  24  *
  25  * Admittedly, the syntax is a bit contorted here, as it is necessarily self-referential for type-safety.
  26  *
  27  * <V> The visitor type
  28  * <T> The visitable (the concrete class that implements this interface)
  29  */
  30 public interface Visitable<V extends Visitor<V, T>, T extends Visitable<V, T>> {
  31
  32         /**
  33          * Any class in the hierarchy that allows itself to be visited will implement this method.  The normal
  34          * behavior is that the visitor will invoke this method of a Visitable, passing itself.  The Visitable
  35          * turns around calls the Visitor back. This idiom is also known as 'double-dispatching'.
  36          *
  37          * @param visitor  the visitor that will be called back
  38          */
  39         public void accept(V visitor);
  40
  41 }