com.sun.electric.database.variable
Class Variable

java.lang.Object
  extended by com.sun.electric.database.variable.Variable
All Implemented Interfaces:
java.io.Serializable

public class Variable
extends java.lang.Object
implements java.io.Serializable

The Variable immutable class defines a single attribute-value pair that can be attached to any ElectricObject.

This immutable class is thread-safe.

See Also:
Serialized Form

Nested Class Summary
static class Variable.AttrKey
          The Key class caches attribute Variable names.
static class Variable.Key
          The Key class caches Variable names.
 
Field Summary
static Variable[] NULL_ARRAY
          empty array of Variables.
 
Method Summary
static java.lang.String betterVariableName(java.lang.String name)
          Method to convert the standard Variable names to more readable strings.
 void check(boolean paramAllowed, boolean inheritAllowed)
          Checks invariant of this Variable.
 boolean compare(java.lang.Object obj, java.lang.StringBuffer buffer)
          This function is to compare Variable elements.
 java.lang.String describe(int aindex)
          Return a description of this Variable without any context or helper object info
 java.lang.String describe(int aindex, VarContext context, java.lang.Object eobj)
          Method to return a String describing this Variable.
 java.lang.String describe(VarContext context, java.lang.Object eobj)
          Method to return a description of this Variable.
 boolean equals(java.lang.Object o)
           
static Variable.Key findKey(java.lang.String name)
          Method to return the Key object for a given Variable name.
 CodeExpression.Code getCode()
          Determine what code type this variable has, if any
 CodeExpression getCodeExpression()
          Returns CodeExpression of this Variable, it it is code variable.
 int getColorIndex()
          Method to return the color index of the Variable's TextDescriptor.
 AbstractTextDescriptor.DispPos getDispPart()
          Method to return the text display part of the Variable's TextDescriptor.
 int getFace()
          Method to return the text font of the Variable's TextDescriptor.
 java.lang.String getFullDescription(ElectricObject eobj)
          Method to return a full description of this Variable.
 Variable.Key getKey()
          Method to return the Variable Key associated with this Variable.
 int getLength()
          Get the number of entries stored in this Variable.
 java.lang.Object getObject()
          Returns thread-independent value of this Variable.
 java.lang.Object getObject(int index)
          Returns thread-independent element of array value of this Variable.
 AbstractTextDescriptor.Position getPos()
          Method to return the text position of the Variable's TextDescriptor.
 java.lang.String getPureValue(int aindex)
          Method to convert this Variable to a String without any evaluation of code.
 java.lang.String getReadableName(ElectricObject owner)
          Method to return a more readable name for this Variable.
 AbstractTextDescriptor.Rotation getRotation()
          Method to return the text rotation of the Variable's TextDescriptor.
 AbstractTextDescriptor.Size getSize()
          Method to return the text size of the text in the Variable's TextDescriptor.
 TextDescriptor getTextDescriptor()
          Method to return the TextDescriptor on this Variable.
 java.lang.String getTrueName()
          Method to return the "true" name for this Variable.
 double getTrueSize(EditWindow0 wnd)
          Method to find the true size in points for the Variable's TextDescriptor in a given EditWindow0.
 AbstractTextDescriptor.Unit getUnit()
          Method to return the Unit of the Variable's TextDescriptor.
 double getXOff()
          Method to return the X offset of the text in the Variable's TextDescriptor.
 double getYOff()
          Method to return the Y offset of the text in the Variable's TextDescriptor.
 int hashCode()
           
 boolean isArray()
          Returns true if the value is array,
 boolean isAttribute()
          Method to return if this is Variable is a User Attribute.
 boolean isBold()
          Method to return true if the text in the Variable's TextDescriptor is bold.
 boolean isCode()
          Method to tell whether this Variable is any code.
 boolean isDisplay()
          Method to return true if this Variable is displayable.
 boolean isInherit()
          Method to return true if the text in the Variable's TextDescriptor is inheritable.
 boolean isInterior()
          Method to return true if the text in the Variable's TextDescriptor is interior.
 boolean isItalic()
          Method to return true if the text in the Variable's TextDescriptor is italic.
 boolean isJava()
          Method to return true if this Variable is Java.
 boolean isLinked(ElectricObject owner)
          Returns true if variable is linked to a linked owner, false otherwise.
 boolean isUnderline()
          Method to return true if the text in the Variable's TextDescriptor is underlined.
static Variable newInstance(Variable.Key key, java.lang.Object value, TextDescriptor descriptor)
          Returns new Variable.
static Variable.Key newKey(java.lang.String name)
          Method to find or create the Key object for a given Variable name.
static Variable.Key newKey(java.lang.String name, ElectricObject parent)
          Method to find or create the Key object for a given Variable name.
static Variable read(IdReader reader)
          Read Variable from IdReader.
 java.lang.String toString()
          Returns a printable version of this Variable.
 Variable withAbsSize(int s)
          Returns Variable which differs from this Variable by text size.
 Variable withBold(boolean state)
          Returns Variable which differs from this Variable by bold flag.
 Variable withCode(CodeExpression.Code code)
          Returns Variable which differs from this Variable by code.
static java.lang.Object withCode(java.lang.Object value, CodeExpression.Code code)
          Returns Object of specified Code derived from specified Object If code is not NONE, the new Object will be of type CodeExpression.
 Variable withColorIndex(int colorIndex)
          Returns Variable which differs from this Variable by colorIndex.
 Variable withDisplay(boolean state)
          Returns Variable which differs from this Variable by displayable flag.
 Variable withDispPart(AbstractTextDescriptor.DispPos dispPos)
          Returns Variable which differs from this Variable by dislay part.
 Variable withFace(int f)
          Returns Variable which differs from this Variable by text font.
 Variable withInherit(boolean state)
          Returns Variable which differs from this Variable by inheritable flag.
 Variable withInterior(boolean state)
          Returns Variable which differs from this Variable by interior flag.
 Variable withItalic(boolean state)
          Returns Variable which differs from this Variable by italic flag.
 Variable withObject(java.lang.Object value)
          Returns Variable which differs from this Variable by value.
 Variable withOff(double xd, double yd)
          Returns Variable which differs from this Variable by X and Y offsets of the text in the Variable's TextDescriptor.
 Variable withParam(boolean state)
          Returns Variable which deffers from this Variable by parameter flag.
 Variable withPos(AbstractTextDescriptor.Position p)
          Returns Variable which differs from this Variable by position.
 Variable withRelSize(double s)
          Returns Variable which differs from this Variable by text size.
 Variable withRenamedIds(IdMapper idMapper)
          Returns Variable which differs from this Variable by renamed Ids.
 Variable withRotation(AbstractTextDescriptor.Rotation r)
          Returns Variable which differs from this Variable by rotation.
 Variable withText(java.lang.String text)
          Returns Variable which differs from this Variable by text value.
 Variable withTextDescriptor(TextDescriptor descriptor)
          Returns Variable which differs from this Variable by TextDescriptor.
 Variable withUnderline(boolean state)
          Returns Variable which differs from this Variable by underline flag.
 Variable withUnit(AbstractTextDescriptor.Unit u)
          Returns Variable which differs from this Variable by unit.
 void write(IdWriter writer)
          Write this Variable to IdWriter.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

NULL_ARRAY

public static final Variable[] NULL_ARRAY
empty array of Variables.

Method Detail

findKey

public static Variable.Key findKey(java.lang.String name)
Method to return the Key object for a given Variable name. Variable Key objects are caches of the actual string name of the Variable.

Returns:
the Key object for a given Variable name.

newKey

public static Variable.Key newKey(java.lang.String name)
Method to find or create the Key object for a given Variable name. Variable Key objects are caches of the actual string name of the Variable.

Parameters:
name - given Variable name.
Returns:
the Key object for a given Variable name.

newKey

public static Variable.Key newKey(java.lang.String name,
                                  ElectricObject parent)
Method to find or create the Key object for a given Variable name. Variable Key objects are caches of the actual string name of the Variable.

Parameters:
name - given Variable name.
parent - the object on which this Variable key will reside.
Returns:
the Key object for a given Variable name.

newInstance

public static Variable newInstance(Variable.Key key,
                                   java.lang.Object value,
                                   TextDescriptor descriptor)
Returns new Variable.

Parameters:
key - key of this Variable.
value - value of this Variable.
descriptor - text descriptor of this Variable.
Returns:
new Variable object.
Throws:
java.lang.NullPointerException - if key, descriptor or value is null.
java.lang.IllegalArgumentException - if value has invalid type

withCode

public static java.lang.Object withCode(java.lang.Object value,
                                        CodeExpression.Code code)
Returns Object of specified Code derived from specified Object If code is not NONE, the new Object will be of type CodeExpression. If code is NONE and the specified Object was CodeExpression, the new Object will be a String with expression text.

Parameters:
value - specified Object
code - code of new Object.
Returns:
Object of specified Code derived from specified Object

check

public void check(boolean paramAllowed,
                  boolean inheritAllowed)
Checks invariant of this Variable.

Parameters:
paramAllowed - true if paramerer flag is allowed on this Variable
inheritAllowed - true if inherit flag is allowed on this Variable
Throws:
java.lang.AssertionError - or NullPointerException if invariant is broken.

isArray

public boolean isArray()
Returns true if the value is array,

Returns:
true if the value is array,

getLength

public int getLength()
Get the number of entries stored in this Variable. For non-arrayed Variables, this is 1.

Returns:
the number of entries stored in this Variable.

getObject

public java.lang.Object getObject()
Returns thread-independent value of this Variable.

Returns:
thread-independent value of this variable.

write

public void write(IdWriter writer)
           throws java.io.IOException
Write this Variable to IdWriter.

Parameters:
writer - where to write.
Throws:
java.io.IOException

read

public static Variable read(IdReader reader)
                     throws java.io.IOException
Read Variable from IdReader.

Parameters:
reader - from to read.
Returns:
Variable read
Throws:
java.io.IOException

withObject

public Variable withObject(java.lang.Object value)
Returns Variable which differs from this Variable by value.

Parameters:
value - value of new Variable.
Returns:
Variable which differs from this Variable by value.
Throws:
java.lang.NullPointerException - if value is null.
java.lang.IllegalArgumentException - if value has invalid type

withText

public Variable withText(java.lang.String text)
Returns Variable which differs from this Variable by text value. If this Variable is Code Varibale its Code type is preserved

Parameters:
text - text value of new Variable.
Returns:
Variable which differs from this Variable by value.
Throws:
java.lang.NullPointerException - if value is null.
java.lang.IllegalArgumentException - if value has invalid type

withCode

public Variable withCode(CodeExpression.Code code)
Returns Variable which differs from this Variable by code.

Parameters:
code - code of new Variable.
Returns:
Variable which differs from this Variable by code

withRenamedIds

public Variable withRenamedIds(IdMapper idMapper)
Returns Variable which differs from this Variable by renamed Ids.

Parameters:
idMapper - a mapper from old Ids to new Ids.
Returns:
Variable which differs from this Variable by renamed Ids.

getObject

public java.lang.Object getObject(int index)
Returns thread-independent element of array value of this Variable.

Parameters:
index - index of array
Returns:
element of array value.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if index is scalar of value is out of bounds.

getKey

public Variable.Key getKey()
Method to return the Variable Key associated with this Variable.

Returns:
the Variable Key associated with this variable.

isLinked

public boolean isLinked(ElectricObject owner)
Returns true if variable is linked to a linked owner, false otherwise.

Parameters:
owner - owner of this variable.
Returns:
true if variable is linked to a linked owner, false otherwise.

getReadableName

public java.lang.String getReadableName(ElectricObject owner)
Method to return a more readable name for this Variable. The method adds "Parameter" or "Attribute" as appropriate and uses sensible names such as "Diode Size" instead of "SCHEM_diode".

Returns:
a more readable name for this Variable.

getFullDescription

public java.lang.String getFullDescription(ElectricObject eobj)
Method to return a full description of this Variable. The description includes the object on which this Variable resides.

Returns:
a full description of this Variable.

betterVariableName

public static java.lang.String betterVariableName(java.lang.String name)
Method to convert the standard Variable names to more readable strings.

Parameters:
name - the actual Variable name.
Returns:
a better name for it (returns the same name if no better one exists).

getTrueName

public java.lang.String getTrueName()
Method to return the "true" name for this Variable. The method removes the "ATTR_" and "ATTRP_" prefixes.

Returns:
the "true" name for this Variable.

describe

public java.lang.String describe(VarContext context,
                                 java.lang.Object eobj)
Method to return a description of this Variable.

Returns:
a description of this Variable.

describe

public java.lang.String describe(int aindex)
Return a description of this Variable without any context or helper object info


describe

public java.lang.String describe(int aindex,
                                 VarContext context,
                                 java.lang.Object eobj)
Method to return a String describing this Variable.

Parameters:
aindex - if negative, print the entire array.
context - the VarContext for this Variable.
eobj - the Object on which this Variable resides.
Returns:
a String desribing this Variable.

getPureValue

public java.lang.String getPureValue(int aindex)
Method to convert this Variable to a String without any evaluation of code.

Parameters:
aindex - if negative, print the entire array.
Returns:
a String desribing this Variable.

compare

public boolean compare(java.lang.Object obj,
                       java.lang.StringBuffer buffer)
This function is to compare Variable elements. Initiative CrossLibCopy

Parameters:
obj - Object to compare to
buffer - To store comparison messages in case of failure
Returns:
True if objects represent same PortInst

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

toString

public java.lang.String toString()
Returns a printable version of this Variable.

Overrides:
toString in class java.lang.Object
Returns:
a printable version of this Variable.

getTextDescriptor

public TextDescriptor getTextDescriptor()
Method to return the TextDescriptor on this Variable. The TextDescriptor gives information for displaying the Variable.

Returns:
the TextDescriptor on this Variable.

withTextDescriptor

public Variable withTextDescriptor(TextDescriptor descriptor)
Returns Variable which differs from this Variable by TextDescriptor. The TextDescriptor gives information for displaying the Variable.

Parameters:
descriptor - the new TextDescriptor on this Variable.
Returns:
Variable which differs from this Variable by TextDescriptor.

withDisplay

public Variable withDisplay(boolean state)
Returns Variable which differs from this Variable by displayable flag. Displayable Variables are shown with the object.

Parameters:
state - true, if new Variable is displayable.
Returns:
Variable which differs from this Variable by displayable flag.

isDisplay

public boolean isDisplay()
Method to return true if this Variable is displayable.

Returns:
true if this Variable is displayable.

getCodeExpression

public CodeExpression getCodeExpression()
Returns CodeExpression of this Variable, it it is code variable. Returns null otherwise

Returns:
CodeExprssion of this Variable or null

getCode

public CodeExpression.Code getCode()
Determine what code type this variable has, if any

Returns:
the code type

isJava

public boolean isJava()
Method to return true if this Variable is Java. Java Variables contain Java code that is evaluated in order to produce a value.

Returns:
true if this Variable is Java.

isCode

public boolean isCode()
Method to tell whether this Variable is any code.

Returns:
true if this Variable is any code.

isAttribute

public boolean isAttribute()
Method to return if this is Variable is a User Attribute.

Returns:
true if this Variable is an attribute, false otherwise.

getColorIndex

public int getColorIndex()
Method to return the color index of the Variable's TextDescriptor. Color indices are more general than colors, because they can handle transparent layers, C-Electric-style opaque layers, and full color values. Methods in "EGraphics" manipulate color indices.

Returns:
the color index of the Variables's TextDescriptor.

withColorIndex

public Variable withColorIndex(int colorIndex)
Returns Variable which differs from this Variable by colorIndex. Color indices are more general than colors, because they can handle transparent layers, C-Electric-style opaque layers, and full color values. Methods in "EGraphics" manipulate color indices.

Parameters:
colorIndex - color index of new Variable.
Returns:
Variable which differs from this Variable by colorIndex.

getPos

public AbstractTextDescriptor.Position getPos()
Method to return the text position of the Variable's TextDescriptor. The text position describes the "anchor point" of the text, which is the point on the text that is attached to the object and does not move.

Returns:
the text position of the Variable's TextDescriptor.

withPos

public Variable withPos(AbstractTextDescriptor.Position p)
Returns Variable which differs from this Variable by position. The text position describes the "anchor point" of the text, which is the point on the text that is attached to the object and does not move.

Parameters:
p - the text position of new Variable.
Returns:
Variable which differs from this Variable by position.
Throws:
java.lang.NullPointerException - if p is null.

getSize

public AbstractTextDescriptor.Size getSize()
Method to return the text size of the text in the Variable's TextDescriptor. This is a Size object that can describe either absolute text (in points) or relative text (in quarter units).

Returns:
the text size of the text in the Variable's TextDescriptor.

getTrueSize

public double getTrueSize(EditWindow0 wnd)
Method to find the true size in points for the Variable's TextDescriptor in a given EditWindow0. If the TextDescriptor is already Absolute (in points) nothing needs to be done. Otherwise, the scale of the EditWindow0 is used to determine the acutal point size.

Parameters:
wnd - the EditWindow0 in which drawing will occur.
Returns:
the point size of the text described by the Variable's TextDescriptor.

withAbsSize

public Variable withAbsSize(int s)
Returns Variable which differs from this Variable by text size. New size is absolute size (in points). The size must be between 1 and 63 points.

Parameters:
s - the point size of new Variable.
Returns:
Variable which differs from this Variable by text size.

withRelSize

public Variable withRelSize(double s)
Returns Variable which differs from this Variable by text size. New size is a relative size (in units). The size must be between 0.25 and 127.75 grid units (in .25 increments).

Parameters:
s - the unit size of new Variable.
Returns:
Variable which differs from this Variable by text size.

getFace

public int getFace()
Method to return the text font of the Variable's TextDescriptor.

Returns:
the text font of the Variable's TextDescriptor.

withFace

public Variable withFace(int f)
Returns Variable which differs from this Variable by text font.

Parameters:
f - the text font of new Variable.
Returns:
Variable which differs from this Variable by text font.

getRotation

public AbstractTextDescriptor.Rotation getRotation()
Method to return the text rotation of the Variable's TextDescriptor. There are only 4 rotations: 0, 90 degrees, 180 degrees, and 270 degrees.

Returns:
the text rotation of the Variable's TextDescriptor.

withRotation

public Variable withRotation(AbstractTextDescriptor.Rotation r)
Returns Variable which differs from this Variable by rotation. There are only 4 rotations: 0, 90 degrees, 180 degrees, and 270 degrees.

Parameters:
r - the text rotation of new Variable.
Returns:
Variable which differs from this Variable by rotation.

getDispPart

public AbstractTextDescriptor.DispPos getDispPart()
Method to return the text display part of the Variable's TextDescriptor.

Returns:
the text display part of the Variable's TextDescriptor.

withDispPart

public Variable withDispPart(AbstractTextDescriptor.DispPos dispPos)
Returns Variable which differs from this Variable by dislay part.

Parameters:
dispPos - the text display part of new Variable.
Returns:
Variable which differs from this Variable by dislay part.
Throws:
java.lang.NullPointerException - if dispPos is null

isItalic

public boolean isItalic()
Method to return true if the text in the Variable's TextDescriptor is italic.

Returns:
true if the text in the Variable's TextDescriptor is italic.

withItalic

public Variable withItalic(boolean state)
Returns Variable which differs from this Variable by italic flag.

Parameters:
state - true if text of new Variable is italic.
Returns:
Variable which differs from this Variable by italic flag.

isBold

public boolean isBold()
Method to return true if the text in the Variable's TextDescriptor is bold.

Returns:
true if the text in the Variable's TextDescriptor is bold.

withBold

public Variable withBold(boolean state)
Returns Variable which differs from this Variable by bold flag.

Parameters:
state - true if text of new Variable is bold.
Returns:
Variable which differs from this Variable by bold flag.

isUnderline

public boolean isUnderline()
Method to return true if the text in the Variable's TextDescriptor is underlined.

Returns:
true if the text in the Variable's TextDescriptor is underlined.

withUnderline

public Variable withUnderline(boolean state)
Returns Variable which differs from this Variable by underline flag.

Parameters:
state - true text of new Variable is underlined.
Returns:
Variable which differs from this Variable by underline flag.

isInterior

public boolean isInterior()
Method to return true if the text in the Variable's TextDescriptor is interior. Interior text is not seen at higher levels of the hierarchy.

Returns:
true if the text in the Variable's TextDescriptor is interior.

withInterior

public Variable withInterior(boolean state)
Returns Variable which differs from this Variable by interior flag. Interior text is not seen at higher levels of the hierarchy.

Parameters:
state - true if text with new Variable is interior.
Returns:
Variable which differs from this Variable by interior flag.

isInherit

public boolean isInherit()
Method to return true if the text in the Variable's TextDescriptor is inheritable. Inheritable variables copy their contents from prototype to instance. Only Variables on NodeProto and PortProto objects can be inheritable. When a NodeInst is created, any inheritable Variables on its NodeProto are automatically created on that NodeInst.

Returns:
true if the text in the Variable's TextDescriptor is inheritable.

withInherit

public Variable withInherit(boolean state)
Returns Variable which differs from this Variable by inheritable flag. Inheritable variables copy their contents from prototype to instance. Only Variables on NodeProto and PortProto objects can be inheritable. When a NodeInst is created, any inheritable Variables on its NodeProto are automatically created on that NodeInst.

Parameters:
state - true if new Variable is inheritable.
Returns:
Variable which differs from this Variable by inheritable flag.

withParam

public Variable withParam(boolean state)
Returns Variable which deffers from this Variable by parameter flag. Parameters are those Variables that have values on instances which are passed down the hierarchy into the contents. Parameters can only exist on Cell objects.

Parameters:
state - true if new Variable is parameter.
Returns:
Variable which deffers from this Variable by parameter flag.

getXOff

public double getXOff()
Method to return the X offset of the text in the Variable's TextDescriptor.

Returns:
the X offset of the text in the Variable's TextDescriptor.

getYOff

public double getYOff()
Method to return the Y offset of the text in the Variable's TextDescriptor.

Returns:
the Y offset of the text in the Variable's TextDescriptor.

withOff

public Variable withOff(double xd,
                        double yd)
Returns Variable which differs from this Variable by X and Y offsets of the text in the Variable's TextDescriptor. The values are scaled by 4, so a value of 3 indicates a shift of 0.75 and a value of 4 shifts by 1.

Parameters:
xd - the X offset of the text in new Variable's TextDescriptor.
yd - the Y offset of the text in new Variable's TextDescriptor.
Returns:
Variable which differs from this Variable by X and Y offsets of the text in the Variable's TextDescriptor.

getUnit

public AbstractTextDescriptor.Unit getUnit()
Method to return the Unit of the Variable's TextDescriptor. Unit describes the type of real-world unit to apply to the value. For example, if this value is in volts, the Unit tells whether the value is volts, millivolts, microvolts, etc.

Returns:
the Unit of the Variable's TextDescriptor.

withUnit

public Variable withUnit(AbstractTextDescriptor.Unit u)
Returns Variable which differs from this Variable by unit. Unit describe the type of real-world unit to apply to the value. For example, if this value is in volts, the Unit tells whether the value is volts, millivolts, microvolts, etc.

Parameters:
u - the Unit of new Variable.
Returns:
Variable which differs from this Variable by unit.