com.deltaxml.cores9api

Class FilterChain

java.lang.Object

com.deltaxml.cores9api.FilterStep

com.deltaxml.cores9api.FilterChain

public class FilterChain
extends FilterStep

Represents a chain of FilterSteps that can be applied to XML input in a specified order to produce a result.

Since:

7.0

Method Summary

Modifier and Type	Method and Description
void	addStep(FilterStep filterStep) Adds a FilterStep to the end of the FilterChain.
void	appendFilterChain(FilterChain chain) Adds FilterSteps to the end of this FilterChain.
java.io.File	getDebugDir() Returns the File representing the directory in which debug files will be output.
FilterStep	getStep(int position) Returns the FilterStep Object at the given position in the FilterChain.
FilterStep	getStep(java.lang.String stepName) Returns the FilterStep Object with the given name.
java.lang.Object	getUnderlyingFilter() Returns the filter Object that this FilterStep wraps.
void	includeChainNameInDebug(boolean value) Whether or not to use the FilterChain name as a second-level of directory structure when outputting debug files.
void	includeChainNameInDebug(boolean value, boolean applyToSubChains) Whether or not to use the FilterChain name as a second-level of directory structure when outputting debug files.
void	insertStepAfterName(FilterStep filterStep, java.lang.String name) Inserts the supplied FilterStep into the FilterChain after the FilterStep with the supplied name.
void	insertStepAtPosition(FilterStep filterStep, int pos) Inserts the supplied FilterStep at the specified position in the FilterChain.
boolean	isChainNameInDebug() States whether the FilterChain name will be used in the debug output directory structure.
boolean	isDebug() States whether debug information will be output by this FilterChain.
boolean	isLocked() States whether this FilterChain is locked or not.
int	length() Returns a count of the number of steps in the FilterChain.
void	lockChain() Locks this FilterChain so that FilterSteps cannot be added, removed or replaced.
void	prependFilterChain(FilterChain chain) Adds FilterSteps to the start of this FilterChain.
void	removeStep(int position) Removes the FilterStep at the given position from the FilterChain.
void	removeStep(java.lang.String stepName) Removes the FilterStep with the supplied name from the FilterChain.
void	replaceStep(FilterStep step) Replaces an existing FilterStep by name.
void	setDebug(boolean value) Sets whether to output intermediate debug files from this FilterChain.
void	setDebug(boolean value, boolean applyToSubChains) Sets whether to output intermediate debug files from this FilterChain.
void	setDebugDir(java.io.File dir) Sets the top-level directory in which to place any debug output.
void	setDebugDir(java.io.File dir, boolean applyToSubChains) Sets the top-level directory in which to place any debug output.
void	setParameterValue(java.lang.String paramName, java.lang.Object value) Sets a parameter on this FilterStep.

Methods inherited from class com.deltaxml.cores9api.FilterStep

getParameterNames, getParameterType, getParameterTypeName, getParameterValue, getStepName, getStepSource, isEnabled, setEnabled

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

appendFilterChain

public void appendFilterChain(FilterChain chain)
                       throws DuplicateStepNameException,
                              java.lang.IllegalStateException

Adds FilterSteps to the end of this FilterChain.

All FilterSteps held in the specified FilterChain are added at the end of this FilterChain. The FilterChain passed as a parameter method is not affected except as detailed below.

N.B. The FilterSteps are NOT cloned, they are added by reference. Therefore, each FilterStep instance now exists in both FilterChain instances. Changes to the individual FilterSteps will be reflected in this FilterChain but subsequent changes to the supplied FilterChain will NOT affect this FilterChain.

If the specified FilterChain contains FilterSteps with names that clash with FilterSteps in this FilterChain, a DuplicateStepNameException will be thrown and this FilterChain will remain unchanged; no steps will be added.

Parameters:

chain - the FilterChain containing the FilterSteps to add at the end of this one

Throws:

DuplicateStepNameException - if the specified FilterChain contains FilterSteps whose names duplicate names of FilterSteps held in this FilterChain

java.lang.IllegalStateException - if the FilterChain is locked

prependFilterChain

public void prependFilterChain(FilterChain chain)
                        throws DuplicateStepNameException,
                               java.lang.IllegalStateException

Adds FilterSteps to the start of this FilterChain.

All FilterSteps held in the specified FilterChain are added at the start of this FilterChain. The FilterChain passed as a parameter method is not affected except as detailed below.

N.B. The FilterSteps are NOT cloned, they are added by reference. Therefore, each FilterStep instance now exists in both FilterChain instances. Changes to the individual FilterSteps will be reflected in this FilterChain but subsequent changes to the supplied FilterChain will NOT affect this FilterChain.

If the specified FilterChain contains FilterSteps with names that clash with FilterSteps in this FilterChain, a DuplicateStepNameException will be thrown and this FilterChain will remain unchanged; no steps will be added.

Parameters:

chain - the FilterChain containing the FilterSteps to add at the start of this one

Throws:

DuplicateStepNameException - if the specified FilterChain contains FilterSteps whose names duplicate names of FilterSteps held in this FilterChain

java.lang.IllegalStateException - if the FilterChain is locked

addStep

public void addStep(FilterStep filterStep)
             throws java.lang.IllegalArgumentException,
                    DuplicateStepNameException,
                    java.lang.IllegalStateException

Adds a FilterStep to the end of the FilterChain.

Parameters:

filterStep - the FilterStep to add to the end of the FilterChain

Throws:

java.lang.IllegalArgumentException - if the supplied FilterStep is null

DuplicateStepNameException - if the FilterChain already contains a FilterStep with the same name as the supplied one

java.lang.IllegalStateException - if the FilterChain is locked

insertStepAtPosition

public void insertStepAtPosition(FilterStep filterStep,
                                 int pos)
                          throws java.lang.IndexOutOfBoundsException,
                                 DuplicateStepNameException,
                                 java.lang.IllegalStateException

Inserts the supplied FilterStep at the specified position in the FilterChain.

Parameters:

filterStep - the FilterStep to insert

pos - the position at which to insert the supplied FilterStep

Throws:

java.lang.IndexOutOfBoundsException - if the supplied position is less than zero or greater than the size of the FilterChain

DuplicateStepNameException - if the FilterChain already contains a FilterStep with the same name as the provided FilterStep

java.lang.IllegalStateException - if this FilterChain is locked

See Also:

FilterChain.isLocked()

insertStepAfterName

public void insertStepAfterName(FilterStep filterStep,
                                java.lang.String name)
                         throws DuplicateStepNameException,
                                java.lang.IllegalArgumentException,
                                java.lang.IllegalStateException

Inserts the supplied FilterStep into the FilterChain after the FilterStep with the supplied name.

Parameters:

filterStep - the FilterStep to insert

name - the name of the existing FilterStep after which the insertion should happen

Throws:

DuplicateStepNameException - if the FilterChain already contains a FilterStep with the same name as the one supplied

java.lang.IllegalArgumentException - if the FilterChain does not contain a FilterStep with the name supplied as the second argument

java.lang.IllegalStateException - if this FilterChain is locked

See Also:

FilterChain.isLocked()

replaceStep

public void replaceStep(FilterStep step)
                 throws java.lang.IllegalArgumentException,
                        java.lang.IllegalStateException

Replaces an existing FilterStep by name.

Parameters:

step - the FilterStep to insert as a replacement

Throws:

java.lang.IllegalArgumentException - if there is no existing FilterStep that has the same name as the specified step

java.lang.IllegalStateException - if the FilterChain is locked

removeStep

public void removeStep(java.lang.String stepName)
                throws java.lang.IllegalStateException

Removes the FilterStep with the supplied name from the FilterChain.

N.B. If the FilterChain does not contain a FilterStep with the supplied name, this method will have no effect.

Parameters:

stepName - the name of the FilterStep to remove from the FilterChain

Throws:

java.lang.IllegalStateException - if the FilterChain is locked

removeStep

public void removeStep(int position)
                throws java.lang.IndexOutOfBoundsException,
                       java.lang.IllegalStateException

Removes the FilterStep at the given position from the FilterChain.

Parameters:

position - a zero-based index position of the the FilterStep to remove from the FilterChain

Throws:

java.lang.IndexOutOfBoundsException - if the supplied position is < 0 or >= the size of the FilterChain

java.lang.IllegalStateException - if the FilterChain is locked

getStep

public FilterStep getStep(java.lang.String stepName)
                   throws java.lang.IllegalArgumentException

Returns the FilterStep Object with the given name.

If the FilterChain does not contains a FilterStep with the given name, the return value will be null

Parameters:

stepName - the name of the FilterStep to return

Returns:

the FilterStep with the given name, or null if no such FilterStep exists in the FilterChain

Throws:

java.lang.IllegalArgumentException - if the supplied stepName is null

getStep

public FilterStep getStep(int position)
                   throws java.lang.IndexOutOfBoundsException

Returns the FilterStep Object at the given position in the FilterChain.

Parameters:

position - a zero-based index position of the FilterStep to return

Returns:

the FilterStep at the given position in the FilterChain

Throws:

java.lang.IndexOutOfBoundsException - if the supplied position is < 0 or >= the size of the FilterChain

lockChain

public void lockChain()

Locks this FilterChain so that FilterSteps cannot be added, removed or replaced.

N.B. A locked FilterChain cannot be unlocked.

isLocked

public boolean isLocked()

States whether this FilterChain is locked or not.

Returns:

a boolean stating whether the chain is locked or not

length

public int length()

Returns a count of the number of steps in the FilterChain. Note, this method does not count nested steps.

Returns:

the number of steps in the FilterChain

setParameterValue

public void setParameterValue(java.lang.String paramName,
                              java.lang.Object value)
                       throws java.lang.IllegalArgumentException,
                              FilterParameterizationException

Description copied from class: FilterStep

Sets a parameter on this FilterStep.

Specified by:

setParameterValue in class FilterStep

Parameters:

paramName - the name of the parameter to set

value - the value to set the parameter to

Throws:

java.lang.IllegalArgumentException - if the parameter name is null

FilterParameterizationException - if the parameter name provided is not a valid parameter for this FilterStep or if there is a problem setting the value

setDebug

public void setDebug(boolean value)

Sets whether to output intermediate debug files from this FilterChain.

After each FilterStep, the current result will be output as an XML file with the filename [pos]-stepName where 'pos' is the zero-based position of the step within the chain.

Note that FilterSteps that are also FilterChains are NOT affected by this method call.

Parameters:

value - whether or not to output debug files

setDebug

public void setDebug(boolean value,
                     boolean applyToSubChains)

Sets whether to output intermediate debug files from this FilterChain.

After each FilterStep, the current result will be output as an XML file with the filename [pos]-stepName where 'pos' is the zero-based position of the step within the chain.

If the second parameter to this method is true, FilterSteps that are also FilterChains will have FilterChain.setDebug(boolean, boolean) called on them.

Parameters:

value - whether or not to output debug files

applyToSubChains - whether to set debug on sub-chains as well

isDebug

public boolean isDebug()

States whether debug information will be output by this FilterChain.

Returns:

a boolean stating whether debug output will be produced

setDebugDir

public void setDebugDir(java.io.File dir)

Sets the top-level directory in which to place any debug output.

Note that any FilterSteps that are also FilterChains will NOT be affected by this method call.

Parameters:

dir - a File representing a directory in which to place debug output

setDebugDir

public void setDebugDir(java.io.File dir,
                        boolean applyToSubChains)

Sets the top-level directory in which to place any debug output.

If the second parameter to this method is true, FilterSteps that are also FilterChains will have FilterChain.setDebugDir(File, boolean) called on them.

Parameters:

dir - a File representing a directory in which to place debug output

applyToSubChains - whether to set a debug dir on sub-chains as well

getDebugDir

public java.io.File getDebugDir()

Returns the File representing the directory in which debug files will be output.

Returns:

a File object representing the directory in which debug files will be placed

includeChainNameInDebug

public void includeChainNameInDebug(boolean value)

Whether or not to use the FilterChain name as a second-level of directory structure when outputting debug files.

Typically, this should be set to false for 'top-level' FilterChains but true for sub– FilterChains so that it is easier to understand the arrangement of the debug output.

Note that any FilterSteps that are also FilterChains will NOT be affected by this method call.

Parameters:

value - whether or not to include the FilterChain name in the directory structure for debug output

includeChainNameInDebug

public void includeChainNameInDebug(boolean value,
                                    boolean applyToSubChains)

Whether or not to use the FilterChain name as a second-level of directory structure when outputting debug files.

Typically, this should be set to false for 'top-level' FilterChains but true for sub– FilterChains so that it is easier to understand the arrangement of the debug output.

If the second parameter to this method is true, FilterSteps that are also FilterChains will have FilterChain.includeChainNameInDebug(boolean, boolean) called on them.

Parameters:

value - whether or not to include the FilterChain name in the directory structure for debug output

applyToSubChains - whether to apply setting to sub-chains as well

isChainNameInDebug

public boolean isChainNameInDebug()

States whether the FilterChain name will be used in the debug output directory structure.

Returns:

a boolean stating whether the chain name will appear in the debug directory structure

getUnderlyingFilter

public java.lang.Object getUnderlyingFilter()

Description copied from class: FilterStep

Returns the filter Object that this FilterStep wraps.

Specified by:

getUnderlyingFilter in class FilterStep

Returns:

the underlying filter. This will be either an Object that extends XMLFilterImpl or an XsltExecutable