001/* An interface for actors that act as refinements of states in FSMs or events
002 in Ptera models.
003
004 Copyright (c) 2008-2014 The Regents of the University of California.
005 All rights reserved.
006 Permission is hereby granted, without written agreement and without
007 license or royalty fees, to use, copy, modify, and distribute this
008 software and its documentation for any purpose, provided that the above
009 copyright notice and the following two paragraphs appear in all copies
010 of this software.
011
012 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
013 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
014 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
015 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
016 SUCH DAMAGE.
017
018 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
019 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
021 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
022 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
023 ENHANCEMENTS, OR MODIFICATIONS.
024
025 PT_COPYRIGHT_VERSION_2
026 COPYRIGHTENDKEY
027
028 */
029package ptolemy.domains.modal.kernel;
030
031import ptolemy.actor.InstanceOpener;
032import ptolemy.actor.TypedActor;
033import ptolemy.kernel.Entity;
034import ptolemy.kernel.util.IllegalActionException;
035
036//////////////////////////////////////////////////////////////////////////
037//// RefinementActor
038
039/**
040 An interface for actors that act as refinements of states in FSMs or events in
041 Ptera models.
042
043 @author Thomas Huining Feng
044 @version $Id$
045 @since Ptolemy II 8.0
046 @Pt.ProposedRating Red (tfeng)
047 @Pt.AcceptedRating Red (tfeng)
048 */
049public interface RefinementActor extends TypedActor {
050
051    /** Create a refinement for the given state.
052     *  @param state The state that will contain the new refinement.
053     *  @param name The name of the composite entity that stores the refinement.
054     *  @param template The template used to create the refinement, or null if
055     *   template is not used.
056     *  @param className The class name for the refinement, which is used when
057     *   template is null.
058     *  @param instanceOpener The instanceOpener, typically a
059     *   Configuration, that is used to open the refinement (as a
060     *   look-inside action) after it is created, or null if it is not
061     *   needed to open the refinement.
062     *  @exception IllegalActionException If error occurs while creating the
063     *   refinement.
064     */
065    public void addRefinement(State state, String name, Entity template,
066            String className, InstanceOpener instanceOpener)
067            throws IllegalActionException;
068
069    /** Return the state (or event, which subclasses state) that this actor
070     *  refines.
071     *  @return The state or event that this actor refines.
072     *  @exception IllegalActionException If thrown while trying to find the
073     *  refined state or event.
074     */
075    public State getRefinedState() throws IllegalActionException;
076
077    /** Control whether adding a port should be mirrored in the modal
078     *  model and the mode controller.
079     *  @param disable 0 if mirroring should occur, -1
080     *   if mirroring should not occur downwards in the hierarchy,
081     *   1 if mirroring should not occur upwards in the hierarchy.
082     */
083    public void setMirrorDisable(int disable);
084}