ptolemy.kernel.util
Class ConfigurableAttribute

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.kernel.util.ConfigurableAttribute

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Changeable, Configurable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable, 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 57040 2010-01-27 20:52:32Z cxh $

Author:

Steve Neuendorffer and Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Green (janneck)

Proposed Rating:

Green (eal)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Nested classes/interfaces inherited from interface ptolemy.kernel.util.Settable

Settable.Visibility

Field Summary

private java.net.URL	_base
private java.lang.String	_configureSource
private java.lang.String	_configureText
private java.lang.String	_defaultText
private java.lang.String	_displayName
private java.util.List	_valueListeners
private Settable.Visibility	_visibility

Fields inherited from class ptolemy.kernel.util.NamedObj

_attributes, _changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _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	getDisplayName() Return a name to present to the user.
java.lang.String	getExpression() Return the the result of calling value().
java.lang.String	getValueAsString() Get the value of the attribute, which is the evaluated expression.
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	setDisplayName(java.lang.String name) Set a name to present to the user.
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.
java.util.Collection	validate() Validate this attribute by calling value().
java.lang.String	value() Return the value given by the configure tag.

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setContainer, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _description, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeChanged, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, 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

Field Detail

_base

private java.net.URL _base

_configureSource

private java.lang.String _configureSource

_configureText

private java.lang.String _configureText

_defaultText

private java.lang.String _defaultText

_displayName

private java.lang.String _displayName

_valueListeners

private java.util.List _valueListeners

_visibility

private Settable.Visibility _visibility

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.

See Also:

removeValueListener(ValueListener)

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() or validate() 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)

getDisplayName

public java.lang.String getDisplayName()

Return a name to present to the user. If setDisplayName(String) has been called, then return the name specified there, and otherwise return the name returned by getName().

Specified by:

getDisplayName in interface Nameable

Specified by:

getDisplayName in interface Settable

Overrides:

getDisplayName in class NamedObj

Returns:

A name to present to the user.

See Also:

setDisplayName(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(), setExpression(String)

getValueAsString

public java.lang.String getValueAsString()

Get the value of the attribute, which is the evaluated expression.

Specified by:

getValueAsString in interface Settable

Returns:

The same as getExpression().

See Also:

getExpression()

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.

See Also:

setVisibility(Settable.Visibility)

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.

See Also:

addValueListener(ValueListener)

setDisplayName

public void setDisplayName(java.lang.String name)

Set a name to present to the user.

Overrides:

setDisplayName in class NamedObj

Parameters:

name - A name to present to the user.

See Also:

getDisplayName()

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.

See Also:

getExpression()

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.

See Also:

getVisibility()

validate

public java.util.Collection validate()
                              throws IllegalActionException

Validate this attribute by calling value(). Notify the container and listeners that the value of this attribute has changed.

Specified by:

validate in interface Settable

Returns:

A list of contained instances of 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.