001/* Attribute that requires a particular version of Ptolemy II.
002
003 Copyright (c) 2001-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
027 */
028package ptolemy.kernel.attributes;
029
030import ptolemy.kernel.util.IllegalActionException;
031import ptolemy.kernel.util.NameDuplicationException;
032import ptolemy.kernel.util.NamedObj;
033
034///////////////////////////////////////////////////////////////////
035//// RequireVersion
036
037/**
038 An attribute that requires a particular version of Ptolemy II.
039 When the value of this attribute is set (via setExpression()),
040 the value that is set is compared against the version of the
041 currently executing Ptolemy II installation.  If the executing
042 version is less than the value set, we throw an expression.
043 <p>
044 @author Edward A. Lee
045 @version $Id$
046 @since Ptolemy II 2.0
047 @Pt.ProposedRating Red (eal)
048 @Pt.AcceptedRating Red (cxh)
049 */
050public class RequireVersion extends VersionAttribute {
051    /** Construct an attribute with the given name contained by the
052     *  specified container. The container argument must not be null, or a
053     *  NullPointerException will be thrown.  This attribute will use the
054     *  workspace of the container for synchronization and version counts.
055     *  If the name argument is null, then the name is set to the empty
056     *  string. Increment the version of the workspace.
057     *  @param container The container.
058     *  @param name The name of this attribute.
059     *  @exception IllegalActionException If the attribute is not of an
060     *   acceptable class for the container, or if the name contains a period.
061     *  @exception NameDuplicationException If the name coincides with
062     *   an attribute already in the container.
063     */
064    public RequireVersion(NamedObj container, String name)
065            throws IllegalActionException, NameDuplicationException {
066        super(container, name);
067        setExpression(CURRENT_VERSION.getExpression());
068    }
069
070    ///////////////////////////////////////////////////////////////////
071    ////                         public methods                    ////
072
073    /** Return true if the hash code of this object is equal (==) to
074     *  the hash code of the argument.
075     *  @param object  The specified object that is compared against.
076     *  @return True if the specified version is the same as this one.
077     */
078    @Override
079    public boolean equals(Object object) {
080        // VersionAttribute.equals() has a bug where if we had a
081        // VersionAttribute and a RequireVersion and the RequireVersion
082        // is deleted, then only the first VersionAttribute was deleted, so we
083        // define equals() and hashCode().  For details, see
084        // http://bugzilla.ecoinformatics.org/show_bug.cgi?id=3984
085        if (object instanceof RequireVersion) {
086            return this.hashCode() == object.hashCode();
087        }
088
089        return false;
090    }
091
092    /** Return a hash code value for attribute. This method returns
093     *  the identity hash code for this attribute.  The hashCode()
094     *  method of the super class is <b>not</b> called.
095     *  @return A hash code value for this token.
096     */
097    @Override
098    public int hashCode() {
099        return System.identityHashCode(this);
100    }
101
102    /** Set the required version, check it against the currently
103     *  executing version, and throw an exception if the executing
104     *  version is older.
105     *  @param expression The version string, consisting of
106     *   version ID tuples separated by '.', '-' or '_'. For example:
107     *   "1.2", "1.2_beta-4".
108     *  @exception IllegalActionException If the argument contains a
109     *   space, which violates the JNLP Version format specification,
110     *   and if the specified version is newer than the executing version.
111     */
112    @Override
113    public void setExpression(String expression) throws IllegalActionException {
114        super.setExpression(expression);
115
116        if (CURRENT_VERSION.isLessThan(this)) {
117            throw new IllegalActionException(this,
118                    "Current version of Ptolemy II is "
119                            + CURRENT_VERSION.getExpression()
120                            + ", but required version is " + expression + ".");
121        }
122    }
123}