001/* An interface to specify the containment relationship as seen by the model
002designer.
003
004@Copyright (c) 2008-2012 The Regents of the University of California.
005All rights reserved.
006
007Permission is hereby granted, without written agreement and without
008license or royalty fees, to use, copy, modify, and distribute this
009software and its documentation for any purpose, provided that the
010above copyright notice and the following two paragraphs appear in all
011copies of this software.
012
013IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
014FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
015ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
016THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
017SUCH DAMAGE.
018
019THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
020INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
021MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
022PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
023CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
024ENHANCEMENTS, OR MODIFICATIONS.
025
026                        PT_COPYRIGHT_VERSION_2
027                        COPYRIGHTENDKEY
028
029
030
031 */
032
033package ptolemy.data.expr;
034
035import ptolemy.kernel.util.IllegalActionException;
036import ptolemy.kernel.util.NamedObj;
037
038/**
039 An interface to specify the containment relationship as seen by the model
040 designer. This interface can be implemented by an attribute (such as {@link
041 ptolemy.domains.modal.kernel.ContainmentExtender}. Such an attribute defines a
042 special containment relationship that is slightly different from the
043 containment relationship defined by {@link NamedObj#getContainer()}. The {@link
044 #getExtendedContainer()} method returns the container of the object that
045 contains the implementing attribute. The returned container is supposed to be
046 the object that visually contains the object that owns the implementing
047 attribute, as seen by the model designer. In particular, for a modal model
048 (either FSM or Ptera), even though a refinement is visually contained by a state
049 or an event, {@link NamedObj#getContainer()} of that refinement does not return
050 the state or event because of a difference between the visual representation
051 and internal data representation. In that case, {@link #getExtendedContainer()}
052 of this interface returns the state or event.
053 <p>
054 When the expression evaluator tries to resolve a variable name starting from an
055 object, it checks whether an attribute implementing this interface is owned by
056 the object if the variable cannot be found in that object. If one such
057 attribute is found, the evaluator considers the container returned by {@link
058 #getExtendedContainer()}, instead of the {@link NamedObj#getContainer()} that
059 it normally uses.
060
061 @author Thomas Huining Feng
062 @version $Id$
063 @since Ptolemy II 8.0
064 @Pt.ProposedRating Red (tfeng)
065 @Pt.AcceptedRating Red (tfeng)
066 */
067public interface ContainmentExtender {
068
069    /** Get an object with the given name within the container.
070     *
071     *  @param name The name of the object.
072     *  @return The object, or null if not found.
073     *  @exception IllegalActionException If exception occurs when trying to get
074     *   the contained object.
075     */
076    public NamedObj getContainedObject(String name)
077            throws IllegalActionException;
078
079    /** Get the extended container.
080     *
081     *  @return The container.
082     *  @exception IllegalActionException If exception occurs when trying to get
083     *   the container.
084     */
085    public NamedObj getExtendedContainer() throws IllegalActionException;
086}