001/* Interface representing a dependency between ports. 002 003 Copyright (c) 2008-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.actor.util; 029 030/////////////////////////////////////////////////////////////////// 031//// RealDependency 032 033/** 034 This dependency represents causal relationships that have a real value 035 or are infinite. Infinity represents the lack of a causal relationship. 036 A finite positive real value represents a causal dependency with (typically) 037 a time delay. A zero value represents an immediate causal relationship. 038 See the paper "Causality Interfaces for Actor Networks" by Ye Zhou and 039 Edward A. Lee, ACM Transactions on Embedded Computing Systems (TECS), 040 April 2008, as available as <a href="http://www.eecs.berkeley.edu/Pubs/TechRpts/2006/EECS-2006-148.pdf"> 041 Technical Report No. UCB/EECS-2006-148</a>, 042 November 16, 2006. 043 044 @author Edward A. Lee 045 @version $Id$ 046 @since Ptolemy II 8.0 047 @Pt.ProposedRating Yellow (eal) 048 @Pt.AcceptedRating Red (eal) 049 */ 050public class RealDependency implements Dependency { 051 052 /** Construct a dependency with the specified value. 053 * The constructor is private. Use valueOf() to construct 054 * an instance. 055 * @param value The value. 056 */ 057 private RealDependency(double value) { 058 _value = value; 059 } 060 061 /////////////////////////////////////////////////////////////////// 062 //// public methods //// 063 064 /** Return Dependency.LESS_THAN, EQUALS, or GREATER_THAN depending 065 * on whether the argument is less than, equal to, or greater than 066 * this dependency. Real dependencies are totally ordered, so 067 * this never returns Dependency.INCOMPARABLE. The order is the 068 * usual numerical ordering of doubles, with Double.POSITIVE_INFINITY 069 * on top. 070 * @param dependency The dependency to compare against. 071 * @return The result of comparison. 072 * @exception ClassCastException If the argument is not an instance 073 * of RealDependency. 074 */ 075 @Override 076 public int compareTo(Dependency dependency) { 077 if (equals(dependency)) { 078 return Dependency.EQUALS; 079 } 080 if (_value < ((RealDependency) dependency)._value) { 081 return Dependency.LESS_THAN; 082 } 083 return Dependency.GREATER_THAN; 084 } 085 086 /** Return true if the value of this dependency equals that 087 * of the specified one, and the specified one is an instance 088 * of RealDependency. 089 * @param object The object to compare against. 090 * @return true if this object is the same as the object argument. 091 */ 092 @Override 093 public boolean equals(Object object) { 094 if (object instanceof RealDependency) { 095 return _value == ((RealDependency) object)._value; 096 } 097 return false; 098 } 099 100 /** Return the same hashCode that that Java Double object would 101 * return had it the same value. 102 */ 103 @Override 104 public int hashCode() { 105 long v = Double.doubleToLongBits(_value); 106 return (int) (v ^ v >>> 32); 107 } 108 109 /** Return a dependency that results from parallel composition of 110 * this one and the specified one. 111 * @param d The dependency to add. 112 * @return A dependency whose value is the minimum of the two dependency 113 * values. 114 * @exception ClassCastException if d is not a RealDependency. 115 */ 116 @Override 117 public Dependency oPlus(Dependency d) { 118 // FIXME: Findbugs reports this as an Unchecked/unconfirmed cast 119 if (((RealDependency) d)._value < _value) { 120 return d; 121 } 122 return this; 123 } 124 125 /** Return the dependency that when added to any other 126 * dependency using oPlus() yields the other dependency. 127 * @return The additive identity. 128 */ 129 @Override 130 public Dependency oPlusIdentity() { 131 return OPLUS_IDENTITY; 132 } 133 134 /** Return a dependency that results from serial composition of 135 * this one and the specified one. 136 * @param d The dependency to multiply. 137 * @return A dependency whose value is the sum of the value of 138 * this one and the specified one. 139 * @exception ClassCastException if d is not a RealDependency. 140 */ 141 @Override 142 public Dependency oTimes(Dependency d) { 143 // FIXME: Findbugs reports this as an Unchecked/unconfirmed cast 144 return new RealDependency(_value + ((RealDependency) d)._value); 145 } 146 147 /** Return the dependency that when multiplied by any other 148 * dependency using oTimes() yields the other dependency. 149 * @return The multiplicative identity. 150 */ 151 @Override 152 public Dependency oTimesIdentity() { 153 return OTIMES_IDENTITY; 154 } 155 156 /** Return a string representation in the form 157 * "RealDependency(value)". 158 * @return A string representation. 159 */ 160 @Override 161 public String toString() { 162 return "RealDependency(_value)"; 163 } 164 165 /** Return the double value of the dependency. 166 * @return The value of the dependency. 167 */ 168 public double value() { 169 return _value; 170 } 171 172 /** Return an instance of RealDependency with the specified 173 * value. This is preferable to use over the constructor 174 * because it uses the same instances for the most common 175 * values. 176 * @param value The value used to determine the RealDependency 177 * to be returned. 178 * @return an instance of RealDependency, if value 179 * is 0.0, then {@link #OTIMES_IDENTITY} is returned, if 180 * value is Double.POSITIVE_INFINITY, then {@link #OPLUS_IDENTITY} 181 * is returned. Otherwise the RealDependency constructor 182 * is called. 183 */ 184 public static RealDependency valueOf(double value) { 185 if (value == 0.0) { 186 return OTIMES_IDENTITY; 187 } else if (value == Double.POSITIVE_INFINITY) { 188 return OPLUS_IDENTITY; 189 } 190 return new RealDependency(value); 191 } 192 193 /////////////////////////////////////////////////////////////////// 194 //// public variables //// 195 196 // FIXME: FindBugs suggests that both these fields be final 197 // "MS: Field isn't final but should be (MS_SHOULD_BE_FINAL) 198 // A mutable static field could be changed by malicious code or by 199 // accident from another package. The field could be made final to avoid 200 // this vulnerability." 201 202 /** The additive identity. */ 203 public static final RealDependency OPLUS_IDENTITY = new RealDependency( 204 Double.POSITIVE_INFINITY); 205 206 /** The multiplicative identity. */ 207 public static final RealDependency OTIMES_IDENTITY = new RealDependency( 208 0.0); 209 210 /////////////////////////////////////////////////////////////////// 211 //// private variables //// 212 213 /** The value. */ 214 private double _value; 215 216}