001/* A Base class for monotonic function type constraints.
002
003 Copyright (c) 1998-2014 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 */
027package ptolemy.data.type;
028
029import ptolemy.graph.InequalityTerm;
030import ptolemy.kernel.util.IllegalActionException;
031
032///////////////////////////////////////////////////////////////////
033//// MonotonicFunction
034
035/**
036 Actors often need to implement monotonic functions as part of the
037 declaration of type constraints.  This base class makes it easy to do
038 so.  In most cases, it is simply necessary to implement the getValue()
039 and getVariables() abstract methods.
040
041 @author Steve Neuendorffer
042 @version $Id$
043 @since Ptolemy II 4.0
044 @Pt.ProposedRating Yellow (neuendor)
045 @Pt.AcceptedRating Red (neuendor)
046 */
047public abstract class MonotonicFunction implements InequalityTerm {
048    ///////////////////////////////////////////////////////////////////
049    ////                         public methods                    ////
050
051    /** Return null.
052     *  @return null.
053     */
054    @Override
055    public Object getAssociatedObject() {
056        return null;
057    }
058
059    /** Return the current value of this monotonic function given the
060     *  current value of the variables returned by getVariables().   Derived
061     *  classes should implement this method to return the current value
062     *  of the monotonic function.
063     *  @exception IllegalActionException Thrown in derived classes if
064     *  there is a problem getting the value.
065     *  @return A Type.
066     *  @see #setValue(Object)
067     */
068    @Override
069    public abstract Object getValue() throws IllegalActionException;
070
071    /** Return the type variables in this inequality term. These are
072     *  the variables on which the value of the function depends.  Derived
073     *  classes should implement this method to return an array of
074     *  InequalityTerms that this function depends on.
075     *  @return An array of InequalityTerm.
076     */
077    @Override
078    public abstract InequalityTerm[] getVariables();
079
080    /** Return an additional string describing the current value
081     *  of this function.  Subclasses may override this method to
082     *  give additional information in the toString() method.   This
083     *  method may return null, indicating that no additional information is
084     *  desired.
085     *  @return null.
086     */
087    public String getVerboseString() {
088        return null;
089    }
090
091    /** Throw an Exception. This method cannot be called on a
092     *  monotonic function term.
093     *  @exception IllegalActionException Always thrown.
094     */
095    @Override
096    public final void initialize(Object e) throws IllegalActionException {
097        throw new IllegalActionException(
098                getClass().getName() + ": Cannot initialize a function term.");
099    }
100
101    /** Return false.  Monotonic Functions are not settable.
102     *  @return False.
103     */
104    @Override
105    public final boolean isSettable() {
106        return false;
107    }
108
109    /** Return true.  Monotonic Functions are, by default, always
110     *  acceptable.  This method might be overridden by derived classes.
111     *  @return True.
112     */
113    @Override
114    public boolean isValueAcceptable() {
115        return true;
116    }
117
118    /** Throw an Exception. The value of a function term cannot be set.
119     *  @exception IllegalActionException Always thrown.
120     *  @see #getValue()
121     */
122    @Override
123    public final void setValue(Object e) throws IllegalActionException {
124        throw new IllegalActionException(
125                getClass().getName() + ": The type is not settable.");
126    }
127
128    /** Override the base class to give a description of this term.
129     *  @return A description of this term.
130     */
131    @Override
132    public String toString() {
133        String string = getVerboseString();
134
135        if (string == null) {
136            string = "";
137        } else {
138            string = ", " + string;
139        }
140
141        try {
142            return "(" + getClass().getName() + ", " + getValue() + string
143                    + ")";
144        } catch (IllegalActionException ex) {
145            return "(" + getClass().getName() + ", INVALID" + string + ")";
146        }
147    }
148}