001/** An interface for a term in an inequality over a CPO.
002
003 Copyright (c) 1997-2008 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
028 */
029package ptolemy.graph;
030
031import ptolemy.kernel.util.IllegalActionException;
032
033//////////////////////////////////////////////////////////////////////////
034//// InequalityTerm
035
036/**
037 An interface for a term in an inequality over a CPO.
038 A term is either a constant, a variable, or a function.
039 In some applications, a term may be associated with an Object. For
040 example, the value of the term may represent a certain characteristic
041 of an Object, and it is necessary to get a reference of that Object
042 from a term. This can be done through the getAssociatedObject() method
043 of this interface.
044
045 @author Yuhong Xiong
046 @version $Id$
047 @since Ptolemy II 0.2
048 @Pt.ProposedRating Green (yuhong)
049 @Pt.AcceptedRating Green (kienhuis)
050 @see CPO
051 */
052public interface InequalityTerm {
053    /** Return the Object associated with this term. If this term is
054     *  not associated with a particular Object, or it is not necessary
055     *  to obtain the reference of the associated Object, this method
056     *  can return <code>null</code>.
057     *  @return The associated Object.
058     */
059    public Object getAssociatedObject();
060
061    /** Return the value of this term.  If this term is a constant,
062     *  return that constant; if this term is a variable, return the
063     *  current value of that variable; if this term is a function,
064     *  return the evaluation of that function based on the current
065     *  value of variables in the function.
066     *  @return An Object representing an element in the underlying CPO.
067     *  @exception IllegalActionException If the value of this
068     *  inequality term is not valid.
069     *  @see #setValue(Object)
070     */
071    public Object getValue() throws IllegalActionException;
072
073    /** Return an array of variables contained in this term.
074     *  If this term is a constant, return an array of size zero;
075     *  if this term is a variable, return an array of size one that
076     *  contains this variable; if this term is a function, return an
077     *  array containing all the variables in the function.
078     *  @return An array of InequalityTerms
079     */
080    public InequalityTerm[] getVariables();
081
082    /** Initialize the value of this term to the specified CPO element.
083     *  If this InequalityTerm is a simple variable that can be set to any
084     *  CPO element, set the value of the variable to the specified argument.
085     *  In this case, this method is equivalent to <code>setValue()</code>
086     *  with the same argument.
087     *  In some applications, this term is a structured object that only part
088     *  of it is a simple variable. In this case, set that variable part to
089     *  the specified argument.
090     *  @param e An Object representing an element in the underlying CPO.
091     *  @exception IllegalActionException If this term is not a variable.
092     */
093    public void initialize(Object e) throws IllegalActionException;
094
095    /** Check whether this term can be set to a specific element of the
096     *  underlying CPO. Only variable terms are settable, constant
097     *  and function terms are not.
098     *  @return True if this term is a variable;
099     *  false otherwise.
100     */
101    public boolean isSettable();
102
103    /** Check whether the current value of this term is acceptable,
104     *  and return true if it is.
105     *  @return True if the current value is acceptable.
106     */
107    public boolean isValueAcceptable();
108
109    /** Set the value of this term to the specified CPO element.
110     *  Only terms consisting of a single variable can have their
111     *  values set.
112     *  @param e An Object representing an element in the
113     *   underlying CPO.
114     *  @exception IllegalActionException If this term is not a variable.
115     *  @see #getValue()
116     */
117    public void setValue(Object e) throws IllegalActionException;
118}