ptolemy.kernel.util
Class ConfigurableAttribute

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.util.Attribute
          extended byptolemy.kernel.util.ConfigurableAttribute
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Configurable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable, Settable
Direct Known Subclasses:
LibraryAttribute, SingletonConfigurableAttribute, TransientSingletonConfigurableAttribute

public class ConfigurableAttribute
extends Attribute
implements Configurable, Settable

This class provides a simple way to get a long string into an attribute. It implements Configurable, so its value can be set using a configure MoML element. For example,

   <property name="x" class="ptolemy.moml.ConfigurableAttribute">
   <configure source="url">xxx</configure>
   </property>
   
The value of this property, obtained via the value() method, will be whatever text is contained by the referenced URL (which is optional), followed by the text "xxx".

Since:
Ptolemy II 1.0
Version:
$Id: ConfigurableAttribute.java,v 1.27.2.1 2004/06/18 00:49:18 cxh Exp $
Author:
Steve Neuendorffer and Edward A. Lee
See Also:
Serialized Form
Accepted Rating:
Green (janneck)
Proposed Rating:
Green (eal)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.util.NamedObj
NamedObj.ContainedObjectsIterator
 
Nested classes inherited from class ptolemy.kernel.util.Settable
Settable.Visibility
 
Field Summary
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Fields inherited from interface ptolemy.kernel.util.Settable
EXPERT, FULL, NONE, NOT_EDITABLE
 
Constructor Summary
ConfigurableAttribute()
          Construct a new attribute with no container and an empty string as its name.
ConfigurableAttribute(NamedObj container, java.lang.String name)
          Construct a new attribute with the given container and name.
ConfigurableAttribute(Workspace workspace)
          Construct a new attribute with no container and an empty string as a name.
 
Method Summary
protected  void _exportMoMLContents(java.io.Writer output, int depth)
          Write a MoML description of the contents of this object.
protected  void _propagateValue(NamedObj destination)
          Propagate the value of this object to the specified object.
 void addValueListener(ValueListener listener)
          Add a listener to be notified when the value of this attribute changes.
 java.lang.Object clone(Workspace workspace)
          Clone the attribute.
 void configure(java.net.URL base, java.lang.String source, java.lang.String text)
          Configure the object with data from the specified input source (a URL) and/or textual data.
 java.net.URL getBase()
          Return the base specified in the most recent call to the configure() method, or null if none.
 java.lang.String getConfigureSource()
          Return the source specified in the most recent call to the configure() method, or null if none.
 java.lang.String getConfigureText()
          Return the text specified in the most recent call to the configure() method, or null if none.
 java.lang.String getDefaultExpression()
          Return the default value of this Settable, if there is one.
 java.lang.String getExpression()
          Return the the result of calling value().
 Settable.Visibility getVisibility()
          Get the visibility of this attribute, as set by setVisibility().
 void removeValueListener(ValueListener listener)
          Remove a listener from the list of listeners that is notified when the value of this attribute changes.
 void setExpression(java.lang.String expression)
          Set the value of the string attribute and notify the container of the value of this attribute by calling attributeChanged(), and notify any listeners that have been registered using addValueListener().
 void setVisibility(Settable.Visibility visibility)
          Set the visibility of this attribute.
 void validate()
          Validate any instances of Settable that this attribute may contain.
 java.lang.String value()
          Return the value given by the configure tag.
 
Methods inherited from class ptolemy.kernel.util.Attribute
_getContainedObject, _propagateExistence, getContainer, setContainer, setName
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _description, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, uniqueName, validateSettables, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface ptolemy.kernel.util.Nameable
description, getContainer, getFullName, getName, getName, setName
 

Constructor Detail

ConfigurableAttribute

public ConfigurableAttribute()
Construct a new attribute with no container and an empty string as its name. Add the attribute to the default workspace directory. Increment the version number of the workspace.


ConfigurableAttribute

public ConfigurableAttribute(Workspace workspace)
Construct a new attribute with no container and an empty string as a name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace. Add the attribute to the workspace directory. Increment the version number of the workspace.

Parameters:
workspace - The workspace that will list the attribute.

ConfigurableAttribute

public ConfigurableAttribute(NamedObj container,
                             java.lang.String name)
                      throws NameDuplicationException,
                             IllegalActionException
Construct a new attribute with the given container and name.

Parameters:
container - The container.
name - The name.
Throws:
IllegalActionException - If the attribute cannot be contained by the proposed container.
NameDuplicationException - If the container already has an attribute with this name.
Method Detail

addValueListener

public void addValueListener(ValueListener listener)
Add a listener to be notified when the value of this attribute changes. If the listener is already on the list of listeners, then do nothing.

Specified by:
addValueListener in interface Settable
Parameters:
listener - The listener to add.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
Clone the attribute. This creates a new attribute with the same value.

Overrides:
clone in class Attribute
Parameters:
workspace - The workspace in which to place the cloned variable.
Returns:
The cloned attribute.
Throws:
java.lang.CloneNotSupportedException - Not thrown in this base class.
See Also:
Object.clone()

configure

public void configure(java.net.URL base,
                      java.lang.String source,
                      java.lang.String text)
               throws java.lang.Exception
Configure the object with data from the specified input source (a URL) and/or textual data. The input source, if any, is assumed to contain textual data as well. Note that the URL is not read until the value() method is called.

Specified by:
configure in interface Configurable
Parameters:
base - The base relative to which references within the input are found, or null if this is not known, or there is none. This argument is ignored in this method.
source - The input source, which specifies a URL.
text - Configuration information given as text.
Throws:
java.lang.Exception - Not thrown in this base class.

getBase

public java.net.URL getBase()
Return the base specified in the most recent call to the configure() method, or null if none.

Returns:
The base with respect to which the relative references in the source file should be interpreted.

getConfigureSource

public java.lang.String getConfigureSource()
Return the source specified in the most recent call to the configure() method, or null if none.

Specified by:
getConfigureSource in interface Configurable
Returns:
A URL specifying an external source for configure information.

getConfigureText

public java.lang.String getConfigureText()
Return the text specified in the most recent call to the configure() method, or null if none.

Specified by:
getConfigureText in interface Configurable
Returns:
Text giving configure information.

getDefaultExpression

public java.lang.String getDefaultExpression()
Return the default value of this Settable, if there is one. If this is a derived object, then the default is the value of the object from which this is derived (the "prototype"). If this is not a derived object, then the default is the first value set using setExpression(), or null if setExpression() has not been called.

Specified by:
getDefaultExpression in interface Settable
Returns:
The default value of this attribute, or null if there is none.
See Also:
setExpression(String)

getExpression

public java.lang.String getExpression()
Return the the result of calling value().

Specified by:
getExpression in interface Settable
Returns:
The value, or a description of the exception if one is thrown.
See Also:
value()

getVisibility

public Settable.Visibility getVisibility()
Get the visibility of this attribute, as set by setVisibility(). The visibility is set by default to NONE.

Specified by:
getVisibility in interface Settable
Returns:
The visibility of this attribute.

removeValueListener

public void removeValueListener(ValueListener listener)
Remove a listener from the list of listeners that is notified when the value of this attribute changes. If no such listener exists, do nothing.

Specified by:
removeValueListener in interface Settable
Parameters:
listener - The listener to remove.

setExpression

public void setExpression(java.lang.String expression)
                   throws IllegalActionException
Set the value of the string attribute and notify the container of the value of this attribute by calling attributeChanged(), and notify any listeners that have been registered using addValueListener(). This is the same as calling configure with a null base and source, passing the argument as text.

Specified by:
setExpression in interface Settable
Parameters:
expression - The text to configure the attribute with.
Throws:
IllegalActionException - If the change is not acceptable to the container.

setVisibility

public void setVisibility(Settable.Visibility visibility)
Set the visibility of this attribute. The argument should be one of the public static instances in Settable.

Specified by:
setVisibility in interface Settable
Parameters:
visibility - The visibility of this attribute.

validate

public void validate()
              throws IllegalActionException
Validate any instances of Settable that this attribute may contain. Notify listeners that the value of this attribute has changed.

Specified by:
validate in interface Settable
Throws:
IllegalActionException - If the change is not acceptable to the container.

value

public java.lang.String value()
                       throws java.io.IOException
Return the value given by the configure tag. This is the text read from the specified URL (if any), followed by the text specified in the body of the configure element. Note that the URL given in the configure() method, if any, is read each time this method is called.

Returns:
The value set in the configure tag.
Throws:
java.io.IOException - If the URL given in the configure method (if any) cannot be read.

_exportMoMLContents

protected void _exportMoMLContents(java.io.Writer output,
                                   int depth)
                            throws java.io.IOException
Write a MoML description of the contents of this object. This method is called by exportMoML(). Each description is indented according to the specified depth and terminated with a newline character.

Overrides:
_exportMoMLContents in class NamedObj
Parameters:
output - The output stream to write to.
depth - The depth in the hierarchy, to determine indenting.
Throws:
java.io.IOException - If an I/O error occurs.
See Also:
NamedObj.exportMoML(Writer, int)

_propagateValue

protected void _propagateValue(NamedObj destination)
                        throws IllegalActionException
Propagate the value of this object to the specified object. The specified object is required to be an instance of the same class as this one, or a ClassCastException will be thrown.

Overrides:
_propagateValue in class NamedObj
Parameters:
destination - Object to which to propagate the value.
Throws:
IllegalActionException - If the value cannot be propagated.