Java Advanced Imaging: Interface OperationNode

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.media.jai
Interface OperationNode

All Superinterfaces:: PropertyChangeEmitter, PropertySource

All Known Implementing Classes:: RenderableOp, RenderedOp, CollectionOp

public interface OperationNode
extends PropertySource, PropertyChangeEmitter

A class which is a node in a chain of operations. This interface aggregates the minimal set of methods which would be expected to be implemented by such a class.

Accessors and mutators of the critical attributes of the node are provided:

The name of the operation as a String;
The OperationRegistry to be used to resolve the operation name into an image factory which renders the node;
The lists of sources and parameters of the node as a ParameterBlock; and
The mapping of hints to be used when rendering the node.

Whether an implementing class maintains these critical attributes by reference or by copying or cloning is left to the discretion of the implementation.

OperationNodes should fire a PropertyChangeEventJAI when any of the critical attributes of the node is modified. These events should be named "OperationName", "OperationRegistry", "ParameterBlock", and "RenderingHints" corresponding to the respective critical attributes. Events named "Sources" and "Parameters" may instead be fired if it can be determined that a ParameterBlock modification has affected only the sources or parameters of the node, respectively. Nodes which implement convenience methods to edit individual node sources, parameters, or hints should still fire an event for the attribute as a whole. Note that this might require cloning the respective object. OperationNodes are also required to fire PropertySourceChangeEvents by virtue of their being a PropertySource as well as a PropertyChangeEmitter.

Methods are also provided to modify the local property environment of the node. The global property environment is maintained by the associated OperationRegistry and used to initialize the local property environment. Methods are provided to:

Add a PropertyGenerator;
Direct that a given property be copied from a certain source; and
Suppress the emission of a certain property.

Invocation of these methods would not affect the global property environment of the operation as maintained by the OperationRegistry.

Since:: JAI 1.1

Method Summary

void addPropertyGenerator(PropertyGenerator pg)
          Adds a PropertyGenerator to the node.

void copyPropertyFromSource(String propertyName, int sourceIndex)
          Forces a property to be copied from the specified source node.

Object getDynamicProperty(String name)
          Returns the property associated with the specified property name, or java.awt.Image.UndefinedProperty if the specified property is not set on the image.

String getOperationName()
          Returns the name of the operation this node represents as a String.

ParameterBlock getParameterBlock()
          Returns the ParameterBlock of this node.

OperationRegistry getRegistry()
          Returns the OperationRegistry that is used by this node.

String getRegistryModeName()
          Returns the name of the RegistryMode corresponding to this OperationNode.

RenderingHints getRenderingHints()
          Returns the RenderingHints of this node.

void setOperationName(String opName)
          Sets the name of the operation this node represents.

void setParameterBlock(ParameterBlock pb)
          Sets the ParameterBlock of this node.

void setRegistry(OperationRegistry registry)
          Sets the OperationRegistry that is used by this node.

void setRenderingHints(RenderingHints hints)
          Sets the RenderingHints of this node.

void suppressProperty(String name)
          Removes a named property from the property environment of this node.

Methods inherited from interface javax.media.jai.PropertySource

getProperty, getPropertyClass, getPropertyNames, getPropertyNames

Methods inherited from interface javax.media.jai.PropertyChangeEmitter

addPropertyChangeListener, addPropertyChangeListener, removePropertyChangeListener, removePropertyChangeListener

Method Detail

getRegistryModeName

public String getRegistryModeName()

Returns the name of the RegistryMode corresponding to this OperationNode. This value should be immutable for a given node.

getOperationName

public String getOperationName()

Returns the name of the operation this node represents as a String.

setOperationName

public void setOperationName(String opName)

Sets the name of the operation this node represents.

If the operation name changes according to a case-insensitive comparison by equals() of the old and new names, a PropertyChangeEventJAI named "OperationName" should be fired with source equal to this node and old and new values set to the old and new values of the operation name, respectively.

Parameters:: opName - The new operation name to be set.
Throws:: IllegalArgumentException - if opName is null.

getRegistry

public OperationRegistry getRegistry()

Returns the OperationRegistry that is used by this node. If the registry is not set, the default registry is returned.

setRegistry

public void setRegistry(OperationRegistry registry)

Sets the OperationRegistry that is used by this node. If the specified registry is null, the default registry is used.

If the registry changes according to a direct comparison of the old and new registry references, a PropertyChangeEventJAI named "OperationRegistry" should be fired with source equal to this node and old and new values set to the old and new values of the registry, respectively.

Parameters:: registry - The new OperationRegistry to be set; it may be null.

getParameterBlock

public ParameterBlock getParameterBlock()

Returns the ParameterBlock of this node.

setParameterBlock

public void setParameterBlock(ParameterBlock pb)

Sets the ParameterBlock of this node. If the specified new ParameterBlock is null, it is assumed that this node has no input sources and parameters.

This method does not validate the content of the supplied ParameterBlock. The caller should ensure that the sources and parameters in the ParameterBlock are suitable for the operation this node represents; otherwise some form of error or exception may occur at the time of rendering.

If the ParameterBlock changes according to a comparison of the sources and parameters Vectors of the old and new ParameterBlocks using equals(), a PropertyChangeEventJAI named "ParameterBlock" should be fired with source equal to this node and old and new values set to the old and new values of the ParameterBlock, respectively. A PropertyChangeEventJAI named "Sources" or "Parameters" may instead be fired if it can be determined that the ParameterBlock modification has affected only the sources or parameters of the node, respectively.

The ParameterBlock may include DeferredData parameters. These will not be evaluated until their values are actually required, i.e., when the node is rendered. Any Observable events generated by such DeferredData parameters will be trapped by the node and acted upon.

Parameters:: pb - The new ParameterBlock to be set; it may be null.

getRenderingHints

public RenderingHints getRenderingHints()

Returns the RenderingHints of this node. It may be null.

setRenderingHints

public void setRenderingHints(RenderingHints hints)

Sets the RenderingHints of this node. It is legal for nodes to ignore RenderingHints set on them by this mechanism.

If the RenderingHints changes according to a comparison by equals() of the old and new hints, a PropertyChangeEventJAI named "RenderingHints" should be fired with source equal to this node and old and new values set to the old and new values of the hints, respectively.

Parameters:: hints - The new RenderingHints to be set; it may be null.

getDynamicProperty

public Object getDynamicProperty(String name)

Returns the property associated with the specified property name, or java.awt.Image.UndefinedProperty if the specified property is not set on the image. This method is dynamic in the sense that subsequent invocations of this method on the same object may return different values as a function of changes in the property environment of the node, e.g., a change in which PropertyGenerators are registered or in the values associated with properties of node sources. The case of the property name passed to this method is ignored.

Parameters:: name - A String naming the property.
Throws:: IllegalArgumentException - if name is null.

addPropertyGenerator

public void addPropertyGenerator(PropertyGenerator pg)

Adds a PropertyGenerator to the node. The property values emitted by this property generator override any previous definitions.

Parameters:: pg - A PropertyGenerator to be added to this node's property environment.
Throws:: IllegalArgumentException - if pg is null.

copyPropertyFromSource

public void copyPropertyFromSource(String propertyName,
                                   int sourceIndex)

Forces a property to be copied from the specified source node. By default, a property is copied from the first source node that emits it. The result of specifying an invalid source is undefined.

Parameters:: propertyName - the name of the property to be copied.; sourceIndex - the index of the from which to copy the property.
Throws:: IllegalArgumentException - if propertyName is null.

suppressProperty

public void suppressProperty(String name)

Removes a named property from the property environment of this node. Unless the property is stored locally either due to having been set explicitly or to having been cached for property synchronization purposes, subsequent calls to getProperty(name) will return java.awt.Image.UndefinedProperty, and name will not appear on the list of properties emitted by getPropertyNames().

Parameters:: name - A String naming the property to be suppressed.
Throws:: IllegalArgumentException - if name is null.