001/* Interface for objects that can be inherited.
002
003 Copyright (c) 2004-2013 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027 */
028package ptolemy.kernel.util;
029
030import java.util.List;
031
032///////////////////////////////////////////////////////////////////
033//// Derivable
034
035/**
036 This interface is for objects that can be derived.  A derived object
037 is "inherited" via the class mechanism in Ptolemy II and tracks the
038 object from which it is derived. That object is its "prototype."
039 The derived object is usually created in its container as a side effect
040 of the creation of the prototype.  The method propagateExistence()
041 is the mechanism by which derived objects are created.
042 <p>
043 The prototype and its derived objects are instances of the same Java
044 class, and by default, if they have a "value," then they have the
045 same value. The derived object may, however, "override" its value.
046 Propagation of changes in the value from the prototype to the
047 derived objects that do not override the value is handled by the
048 propagateValue() method.  It is up to that method to properly
049 handle shadowing that might occur if a derived object that is
050 overridden is also a prototype for other derived objects.
051 <p>
052 A derived object arises from a parent-child relationship, which
053 is supported by the subinterface Instantiable. Every object that
054 is (deeply) contained by a parent has a corresponding derived object
055 that is (deeply) contained by the child. Thus, the existence of the
056 derived object is "implied" by the parent-child relationship.
057 The depth of a derived object relative to this parent-child
058 relationship is returned by the getDerivedLevel() method.
059 For example, if the container of a derived object is the
060 child of the container of its prototype, then getDerivedLevel()
061 will return 1.
062 <p>
063 The derived level returned by getDerivedLevel() affects whether
064 a derived object is explicitly mentioned when a model is exported
065 to MoML. Normally, a derived object is not mentioned in the MoML
066 since its existence is "implied" by the existence of the prototype
067 and the parent-child relationship. However, since it is possible
068 to export MoML for any object in a hierarchical model, the exported
069 MoML may not include the parent-child relationship, since it might
070 be below it in the hierarchy.  In this case, the derived object
071 will be described in the exported MoML, since it is not implied
072 in the exported MoML.
073 <p>
074 The getDerivedList() method returns a list of all the objects that
075 are derived from a prototype. The getPrototypeList() method returns
076 a list of all prototypes from which this object is derived.
077
078 @author Edward A. Lee
079 @version $Id$
080 @since Ptolemy II 4.0
081 @see Instantiable
082 @see NamedObj
083 @Pt.ProposedRating Green (eal)
084 @Pt.AcceptedRating Green (neuendor)
085 */
086public interface Derivable extends Nameable {
087    ///////////////////////////////////////////////////////////////////
088    ////                         public methods                    ////
089
090    /** Get the minimum level above this object in the hierarchy where a
091     *  parent-child relationship implies the existence of this object.
092     *  A value Integer.MAX_VALUE is used to indicate that this object is
093     *  not a derived object. A value of 1 indicates that the container
094     *  of the object is a child, and that the this object is derived
095     *  from a prototype in the parent of the container. Etc.
096     *  @return The level above this object in the containment
097     *   hierarchy where a parent-child relationship implies this object.
098     */
099    public int getDerivedLevel();
100
101    /** Return a list of objects derived from this one.
102     *  This is the list of objects that are "inherited" by their
103     *  containers from a container of this object. The existence of
104     *  these derived objects is "implied" by a parent-child relationship
105     *  somewhere above this object in the containment hierarchy.
106     *  <p>
107     *  Implementors of this method may return an empty list,
108     *  but should not return null. This method should return a
109     *  complete list, including objects that have been overridden.
110     *  All objects in the returned list are required to be of the same
111     *  class as the object on which this method is called (they should
112     *  be clones constructed directly or indirectly, via another clone).
113     *  @return A list of objects of the same class as the object on
114     *   which this is called.
115     */
116    public List getDerivedList();
117
118    /** Return a list of prototypes for this object. The list is ordered
119     *  so that more local prototypes are listed before more remote
120     *  prototypes. A prototype is more local if the parent-child
121     *  relationship is deeper in the containment hierarchy.
122     *  @return A list of prototypes for this object, each of which is
123     *   assured of being an instance of the same (Java) class as this
124     *   object, or an empty list if there are no prototypes.
125     *  @exception IllegalActionException If a prototype with the right
126     *   name but the wrong class is found.
127     */
128    public List getPrototypeList() throws IllegalActionException;
129
130    /** Propagate the existence of this object.
131     *  If this object has a container, then ensure that all
132     *  objects derived from the container contain an object
133     *  with the same class and name as this object. Create that
134     *  object when needed. Return the list of objects that are created.
135     *  @return A list of derived objects of the same class
136     *   as this implementor that are created, or an empty list
137     *   if none are created.
138     *  @exception IllegalActionException If the object cannot be created.
139     */
140    public List propagateExistence() throws IllegalActionException;
141
142    /** Propagate the value (if any) held by this
143     *  object to derived objects that have not been overridden.
144     *  Implementors are required to leave all derived objects
145     *  unchanged if any single derived object throws an exception
146     *  when attempting to propagate the value to it.
147     *  @return The list of objects to which propagation occurred.
148     *  @exception IllegalActionException If propagation is not possible.
149     */
150    public List propagateValue() throws IllegalActionException;
151}