Package net.sf.jett.tag

Class BaseLoopTag

java.lang.Object

net.sf.jett.tag.BaseTag

net.sf.jett.tag.BaseLoopTag

All Implemented Interfaces:

Tag

Direct Known Subclasses:

ForEachTag, ForTag, MultiForEachTag

public abstract class BaseLoopTag
extends BaseTag

The abstract class BaseLoopTag is the base class for all tags that represent loops.

Attributes:

• Inherits all attributes from BaseTag.
• copyRight (optional): boolean
• fixed (optional): boolean
• pastEndAction (optional): String
• replaceValue (optional): String
• groupDir (optional): String
• collapse (optional): boolean
• onLoopProcessed (optional): TagLoopListener
• varStatus (optional): String

Author:

Randy Gettman

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	ATTR_COLLAPSE	Attribute for specifying whether the group should be displayed collapsed.
static java.lang.String	ATTR_COPY_RIGHT	Attribute for forcing "copy right" behavior.
static java.lang.String	ATTR_FIXED	Attribute for not shifting other content out of the way; works the same as "fixed size collections".
static java.lang.String	ATTR_GROUP_DIR	Attribute for specifying the direction of the grouping.
static java.lang.String	ATTR_ON_LOOP_PROCESSED	Attribute for specifying a TagLoopListener to listen for TagLoopEvents.
static java.lang.String	ATTR_PAST_END_ACTION	Attribute for specifying the "past end action", an action for dealing with content beyond the range of looping content.
static java.lang.String	ATTR_REPLACE_VALUE	Attribute for specifying a replacement value for expressions that reference a collection that is past the end of iteration.
static java.lang.String	ATTR_VAR_STATUS	Attribute for specifying the name of the LoopTagStatus object that will be exposed in the beans map.
static java.lang.String	GROUP_DIR_COLS	The "group dir" value to specify that columns should be grouped.
static java.lang.String	GROUP_DIR_NONE	The "group dir" value to specify that neither rows nor columns should be grouped.
static java.lang.String	GROUP_DIR_ROWS	The "group dir" value to specify that rows should be grouped.
static java.lang.String	PAST_END_ACTION_CLEAR	The "past end action" value to clear the content of cells.
static java.lang.String	PAST_END_ACTION_REMOVE	The "past end action" value to remove the cells, including things like borders and formatting.
static java.lang.String	PAST_END_ACTION_REPLACE_EXPR	The "past end action" value to replace only the expressions that contain past-end references.

Fields inherited from class net.sf.jett.tag.BaseTag

ATTR_ON_PROCESSED, SPEC_SEP

Constructor Summary

Constructors

Constructor	Description
BaseLoopTag()

Method Summary

Modifier and Type	Method	Description
protected abstract void	afterBlockProcessed(TagContext context, Block currBlock, java.lang.Object item, int index)	This method is called once per iteration loop, immediately after the given Block is processed.
protected abstract void	beforeBlockProcessed(TagContext context, Block currBlock, java.lang.Object item, int index)	This method is called once per iteration loop, immediately before the given Block is processed.
protected abstract java.util.List<java.lang.String>	getCollectionNames()	Returns the names of the Collections that are being used in this BaseLoopTag.
protected abstract int	getCollectionSize()	Returns the size of the collection being iterated.
protected abstract java.util.Iterator<?>	getLoopIterator()	Returns an Iterator that iterates over some Collection of objects.
protected BaseLoopTagStatus	getLoopTagStatus()	Returns a BaseLoopTagStatus that will be exposed in the beans map if the appropriate attribute is given.
protected abstract int	getNumIterations()	Returns the number of iterations.
protected java.util.List<java.lang.String>	getOptionalAttributes()	All BaseLoopTags support the optional copy down tag.
protected PastEndAction	getPastEndAction()	Returns the PastEndAction, which is controlled by the attribute specified by ATTR_PAST_END_ACTION.
protected java.lang.String	getReplacementExprValue()	Returns the replacement expression value, which defaults to am empty string "".
protected java.util.List<java.lang.String>	getRequiredAttributes()	There are no required attributes that all BaseLoopTags support.
protected abstract java.util.List<java.lang.String>	getVarNames()	Returns the names of the variables that are being used in this BaseLoopTag.
boolean	process()	Provide a generic way to process a tag that loops, with the Template Method pattern.
void	setCollapsed(boolean collapsed)	Sets whether any Excel Group created is collapsed.
void	setCopyRight(boolean copyRight)	Sets whether the repeated blocks are to be copied to the right (true) or downward (default, false).
void	setFixed(boolean fixed)	Sets "fixed" mode, which doesn't shift other content out of the way when copying repeated blocks of cells.
void	setGroupDirection(Block.Direction direction)	Sets the directionality of the Excel Group to be created, if any.
void	setOnLoopProcessed(TagLoopListener listener)	Sets the TagLoopListener.
void	setPastEndAction(PastEndAction pae)	Sets the PastEndAction.
void	setReplaceExprValue(java.lang.String value)	Sets the replacement expression value.
protected void	validateAttributes()	Ensure that the past end action (if specified) is a valid value.

Methods inherited from class net.sf.jett.tag.BaseTag

checkAttributes, clearBlock, deleteBlock, getAttributes, getContext, getLocation, getParentTag, getWorkbookContext, isBodiless, processTag, removeBlock, setAttributes, setBodiless, setContext, setParentTag, setWorkbookContext

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.jett.tag.Tag

getName

Field Detail

ATTR_COPY_RIGHT

public static final java.lang.String ATTR_COPY_RIGHT

Attribute for forcing "copy right" behavior. (Default is copy down.)

See Also:

Constant Field Values

ATTR_FIXED

public static final java.lang.String ATTR_FIXED

Attribute for not shifting other content out of the way; works the same as "fixed size collections".

See Also:

Constant Field Values

ATTR_PAST_END_ACTION

public static final java.lang.String ATTR_PAST_END_ACTION

Attribute for specifying the "past end action", an action for dealing with content beyond the range of looping content.

See Also:

PAST_END_ACTION_CLEAR, PAST_END_ACTION_REMOVE, PAST_END_ACTION_REPLACE_EXPR, Constant Field Values

ATTR_GROUP_DIR

public static final java.lang.String ATTR_GROUP_DIR

Attribute for specifying the direction of the grouping. This defaults to no grouping.

Since:

0.2.0

See Also:

GROUP_DIR_ROWS, GROUP_DIR_COLS, GROUP_DIR_NONE, Constant Field Values

ATTR_COLLAPSE

public static final java.lang.String ATTR_COLLAPSE

Attribute for specifying whether the group should be displayed collapsed. The default is false, for not collapsed. It is ignored if neither rows nor columns are being grouped.

Since:

0.2.0

See Also:

Constant Field Values

ATTR_ON_LOOP_PROCESSED

public static final java.lang.String ATTR_ON_LOOP_PROCESSED

Attribute for specifying a TagLoopListener to listen for TagLoopEvents.

Since:

0.3.0

See Also:

Constant Field Values

ATTR_REPLACE_VALUE

public static final java.lang.String ATTR_REPLACE_VALUE

Attribute for specifying a replacement value for expressions that reference a collection that is past the end of iteration. This defaults to an empty string "", and is only relevant when the "past end action" is replaceExpr.

Since:

0.7.0

See Also:

ATTR_PAST_END_ACTION, PAST_END_ACTION_REPLACE_EXPR, Constant Field Values

ATTR_VAR_STATUS

public static final java.lang.String ATTR_VAR_STATUS

Attribute for specifying the name of the LoopTagStatus object that will be exposed in the beans map. If this attribute is not present, or the value is null, then no such object will be exposed.

Since:

0.9.1

See Also:

Constant Field Values

PAST_END_ACTION_CLEAR

public static final java.lang.String PAST_END_ACTION_CLEAR

The "past end action" value to clear the content of cells.

See Also:

Constant Field Values

PAST_END_ACTION_REMOVE

public static final java.lang.String PAST_END_ACTION_REMOVE

The "past end action" value to remove the cells, including things like borders and formatting.

See Also:

Constant Field Values

PAST_END_ACTION_REPLACE_EXPR

public static final java.lang.String PAST_END_ACTION_REPLACE_EXPR

The "past end action" value to replace only the expressions that contain past-end references.

Since:

0.7.0

See Also:

Constant Field Values

GROUP_DIR_COLS

public static final java.lang.String GROUP_DIR_COLS

The "group dir" value to specify that columns should be grouped.

Since:

0.2.0

See Also:

Constant Field Values

GROUP_DIR_ROWS

public static final java.lang.String GROUP_DIR_ROWS

The "group dir" value to specify that rows should be grouped.

Since:

0.2.0

See Also:

Constant Field Values

GROUP_DIR_NONE

public static final java.lang.String GROUP_DIR_NONE

The "group dir" value to specify that neither rows nor columns should be grouped.

Since:

0.2.0

See Also:

Constant Field Values

Constructor Detail

BaseLoopTag

public BaseLoopTag()

Method Detail

setCopyRight

public void setCopyRight(boolean copyRight)

Sets whether the repeated blocks are to be copied to the right (true) or downward (default, false).

Parameters:

copyRight - Whether the repeated blocks are to be copied to the right (true) or downward (default, false).

Since:

0.3.0

setFixed

public void setFixed(boolean fixed)

Sets "fixed" mode, which doesn't shift other content out of the way when copying repeated blocks of cells.

Parameters:

fixed - Whether to execute in "fixed" mode.

Since:

0.3.0

setPastEndAction

public void setPastEndAction(PastEndAction pae)

Sets the PastEndAction.

Parameters:

pae - The PastEndAction.

Since:

0.3.0

setReplaceExprValue

public void setReplaceExprValue(java.lang.String value)

Sets the replacement expression value. This defaults to an empty string "". This is only relevant if a past end action of "replaceExpr" is used.

Parameters:

value - The replacement expression value.

Since:

0.7.0

See Also:

setPastEndAction(net.sf.jett.model.PastEndAction), PAST_END_ACTION_REPLACE_EXPR

setGroupDirection

public void setGroupDirection(Block.Direction direction)

Sets the directionality of the Excel Group to be created, if any.

Parameters:

direction - The directionality.

Since:

0.3.0

setCollapsed

public void setCollapsed(boolean collapsed)

Sets whether any Excel Group created is collapsed.

Parameters:

collapsed - Whether any Excel group created is collapsed.

Since:

0.3.0

setOnLoopProcessed

public void setOnLoopProcessed(TagLoopListener listener)

Sets the TagLoopListener.

Parameters:

listener - The TagLoopListener.

Since:

0.3.0

getRequiredAttributes

protected java.util.List<java.lang.String> getRequiredAttributes()

There are no required attributes that all BaseLoopTags support.

Overrides:

getRequiredAttributes in class BaseTag

Returns:

An empty List.

getOptionalAttributes

protected java.util.List<java.lang.String> getOptionalAttributes()

All BaseLoopTags support the optional copy down tag.

Overrides:

getOptionalAttributes in class BaseTag

Returns:

A List of optional attribute names.

validateAttributes

protected void validateAttributes()
                           throws TagParseException

Ensure that the past end action (if specified) is a valid value. Ensure that the group direction (if specified) is a valid value.

Overrides:

validateAttributes in class BaseTag

Throws:

TagParseException - If the attribute values are illegal or unacceptable.

getPastEndAction

protected PastEndAction getPastEndAction()

Returns the PastEndAction, which is controlled by the attribute specified by ATTR_PAST_END_ACTION. It defaults to CLEAR_CELL.

Returns:

A PastEndAction.

See Also:

PastEndAction

getReplacementExprValue

protected java.lang.String getReplacementExprValue()

Returns the replacement expression value, which defaults to am empty string "". This is only relevant if the past end action is "replaceExpr".

Returns:

The replacement expression value.

Since:

0.7.0

See Also:

getPastEndAction(), PAST_END_ACTION_REPLACE_EXPR, ATTR_REPLACE_VALUE

process

public boolean process()

Provide a generic way to process a tag that loops, with the Template Method pattern.

1. Decide whether content needs to be shifted out of the way, and shift the content out of the way if necessary. This involves calling getCollectionNames() to determine if any of the collection names are "fixed". This also involves calling getVarNames() to determine which, if any, past end actions, need to be taken.
2. Call getNumIterations to determine the number of Blocks needed.
3. Copy the Block the needed number of times.
4. Get the loop iterator by calling getLoopIterator().
5. Over each loop of the iterator...
   1. Create a Block for the iteration.
   2. If the collection values are exhausted, apply any "past end actions".
   3. Call beforeBlockProcessed().
   4. Process the current Block with a BlockTransformer.
   5. Call afterBlockProcessed().

Specified by:

process in class BaseTag

Returns:

Whether the first Cell in the Block associated with this Tag was processed.

See Also:

getCollectionNames(), getVarNames(), getNumIterations(), getLoopIterator(), beforeBlockProcessed(net.sf.jett.tag.TagContext, net.sf.jett.model.Block, java.lang.Object, int), afterBlockProcessed(net.sf.jett.tag.TagContext, net.sf.jett.model.Block, java.lang.Object, int)

getCollectionNames

protected abstract java.util.List<java.lang.String> getCollectionNames()

Returns the names of the Collections that are being used in this BaseLoopTag.

Returns:

A List collection names, or null if not operating on any Collections.

getVarNames

protected abstract java.util.List<java.lang.String> getVarNames()

Returns the names of the variables that are being used in this BaseLoopTag.

Returns:

A List of variable names, or null if there are not any variable names into any Collections.

Since:

0.7.0

getNumIterations

protected abstract int getNumIterations()

Returns the number of iterations.

Returns:

The number of iterations.

getCollectionSize

protected abstract int getCollectionSize()

Returns the size of the collection being iterated. This may be different than the number of iterations because of the "limit" attribute.

Returns:

The size of the collection being iterated.

getLoopTagStatus

protected BaseLoopTagStatus getLoopTagStatus()

Returns a BaseLoopTagStatus that will be exposed in the beans map if the appropriate attribute is given. Subclasses may want to override this method to return an object that provides more information.

Returns:

A BaseLoopTagStatus.

Since:

0.9.1

getLoopIterator

protected abstract java.util.Iterator<?> getLoopIterator()

Returns an Iterator that iterates over some Collection of objects. The Iterator doesn't need to support the remove operation.

Returns:

An Iterator.

beforeBlockProcessed

protected abstract void beforeBlockProcessed(TagContext context,
                                             Block currBlock,
                                             java.lang.Object item,
                                             int index)

This method is called once per iteration loop, immediately before the given Block is processed. An iteration index is supplied as well.

Parameters:

context - The TagContext.

currBlock - The Block that is about to processed.

item - The Object that resulted from the iterator.

index - The iteration index (0-based).

afterBlockProcessed

protected abstract void afterBlockProcessed(TagContext context,
                                            Block currBlock,
                                            java.lang.Object item,
                                            int index)

This method is called once per iteration loop, immediately after the given Block is processed. An iteration index is supplied as well.

Parameters:

context - The TagContext.

currBlock - The Block that was just processed.

item - The Object that resulted from the iterator.

index - The iteration index (0-based).