001/* A marker interface for lazy composites.
002
003 Copyright (c) 1998-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
030//////////////////////////////////////////////////////////////////////////
031//// LazyComposite
032
033/**
034 A marker interface for lazy composites. A lazy composite is a
035 CompositeEntity that does not automatically populate itself
036 with contained entities and relations when it is instantiated.
037 It does populate itself with attributes and ports, but the
038 contained entities and relations are not created until they
039 are explicitly requested.
040 <p>
041 Note that a class that implements this interface cannot
042 have parameters whose values are expressions that refer to
043 contained entities or relations or attributes contained by
044 those. This is a rather esoteric use of expressions, so
045 this limitation may not be onerous.
046
047 @author  Edward A. Lee, Christopher Hylands
048 @version $Id$
049 @since Ptolemy II 8.0
050 @Pt.ProposedRating Green (eal)
051 @Pt.AcceptedRating Green (cxh)
052 @see NamedObj
053 @see RecorderListener
054
055 */
056public interface LazyComposite extends Configurable {
057    /** Populate the actor by reading the file specified by the
058     *  <i>source</i> parameter.  Note that the exception thrown here is
059     *  a runtime exception, inappropriately.  This is because execution of
060     *  this method is deferred to the last possible moment, and it is often
061     *  evaluated in a context where a compile-time exception cannot be
062     *  thrown.  Thus, extra care should be exercised to provide valid
063     *  MoML specifications.
064     *  @exception InvalidStateException If the source cannot be read, or if
065     *   an exception is thrown parsing its MoML data.
066     */
067    public void populate() throws InvalidStateException;
068
069}