001/* Interface for objects that can be instantiated.
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//// Instantiable
034
035/**
036 This interface is for objects that can be instantiated.  Such objects serve a
037 role similar to "classes" in Java and other object oriented languages.
038 They are Ptolemy II objects, but whose purpose is to serve as
039 a factory for instances that are (deep) clones of themselves.  Normally,
040 they play no role in the execution of a model, and their ports cannot
041 be connected to other ports.
042 <p>
043 An object that implements this interface can be in one of two states.
044 Either it is a class definition ({@link #isClassDefinition()} returns true)
045 or it is not.  Only objects that are class definitions can be instantiated.
046 Instantiation is done via the {@link #instantiate(NamedObj, String)}
047 method. If an object
048 is instantiated from this object, then the new object is called the "child"
049 and this object is called the "parent." An instance of Instantiable can have
050 at most one parent (returned by the {@link #getParent()} method), but it
051 can have many children (returned by the {@link #getChildren()} method).
052 An object may be both a child and a parent.
053 <p>
054 A child is required to be a deep clone of its parent. That is, every
055 object deeply contained by the parent must have a corresponding object
056 deeply contained by the child.  The object that is deeply contained
057 by the parent is called the "prototype" and the object deeply contained
058 by the child is called the "derived" object. A derived object has the
059 same name relative to the child as the prototype has relative to the
060 parent. Moreover, a derived object is an instance of the same Java
061 class as the prototype.
062 <p>
063 This correspondence between a parent and child is called the
064 "derivation invariant." Any correct implementation of this interface
065 must ensure that the derivation invariant is always satisfied, even
066 if the parent changes after the child was instantiated. If new objects
067 are added to the parent, then derived objects must be added to the
068 child.
069
070 @author Edward A. Lee
071 @version $Id$
072 @since Ptolemy II 4.0
073 @Pt.ProposedRating Green (eal)
074 @Pt.AcceptedRating Green (neuendor)
075 */
076public interface Instantiable extends Derivable {
077    ///////////////////////////////////////////////////////////////////
078    ////                         public methods                    ////
079
080    /** Return a list of weak references to instances of Instantiable
081     *  that are children of this object.  An implementor of this method
082     *  may return null or an empty list to indicate that there are
083     *  no children.
084     *  @return An unmodifiable list of instances of
085     *   java.lang.ref.WeakReference that refer to
086     *   instances of Instantiable or null if this object
087     *   has no children.
088     */
089    public List getChildren();
090
091    /** Return the parent of this object, or null if there is none.
092     *  @return The parent of this object, or null if there is none.
093     */
094    public Instantiable getParent();
095
096    /** Create an instance by (deeply) cloning this object and then adjusting
097     *  the parent-child relationships between the clone and its parent.
098     *  Specifically, the clone defers its definition to this object,
099     *  which becomes its "parent." The "child" inherits all the objects
100     *  contained by this object. If this object is a composite, then this
101     *  method must adjust any parent-child relationships that are entirely
102     *  contained within the child. That is, for any parent-child relationship
103     *  that is entirely contained within this object (i.e., both the parent
104     *  and the child are deeply contained by this object), a corresponding
105     *  parent-child relationship is created within the clone such that
106     *  both the parent and the child are entirely contained within
107     *  the clone.
108     *  <p>
109     *  The new object is not a class definition by default (it is an
110     *  "instance" rather than a "class"). That is, {@link #isClassDefinition()}
111     *  returns <i>false</i>.
112     *  @param container The container for the instance, or null
113     *   to instantiate it at the top level.
114     *  @param name The name for the instance.
115     *  @return A new instance that is a clone of this object
116     *   with adjusted deferral relationships.
117     *  @exception CloneNotSupportedException If this object
118     *   cannot be cloned.
119     *  @exception IllegalActionException If this object is not a
120     *   class definition or the proposed container is not acceptable.
121     *  @exception NameDuplicationException If the name collides with
122     *   an object already in the container.
123     */
124    public Instantiable instantiate(NamedObj container, String name)
125            throws CloneNotSupportedException, IllegalActionException,
126            NameDuplicationException;
127
128    /** Return true if this object is a class definition, which means that
129     *  it can be instantiated.
130     *  @return True if this object is a class definition.
131     */
132    public boolean isClassDefinition();
133}