org.apache.wicket

Class MarkupContainer

java.lang.Object

org.apache.wicket.Component

org.apache.wicket.MarkupContainer

All Implemented Interfaces:

Serializable, Iterable<Component>, IEventSink, IEventSource, IConverterLocator, IHeaderContributor, IRequestableComponent, IHierarchical<Component>, IClusterable

Direct Known Subclasses:

AbstractOutputTransformerContainer, Page, WebMarkupContainer

public abstract class MarkupContainer
extends Component
implements Iterable<Component>

A MarkupContainer holds a map of child components.

• Children - Children can be added by calling the add(Component...) method, and they can be looked up using a colon separated path. For example, if a container called "a" held a nested container "b" which held a nested component "c", then a.get("b:c") would return the Component with id "c". The number of children in a MarkupContainer can be determined by calling size(), and the whole hierarchy of children held by a MarkupContainer can be traversed by calling visitChildren(), passing in an implementation of IVisitor.
• Markup Rendering - A MarkupContainer also holds/references associated markup which is used to render the container. As the markup stream for a container is rendered, component references in the markup are resolved by using the container to look up Components in the container's component map by id. Each component referenced by the markup stream is given an opportunity to render itself using the markup stream.

  Components may alter their referring tag, replace the tag's body or insert markup after the tag. But components cannot remove tags from the markup stream. This is an important guarantee because graphic designers may be setting attributes on component tags that affect visual presentation.

  The type of markup held in a given container subclass can be determined by calling getMarkupType(). Markup is accessed via a MarkupStream object which allows a component to traverse ComponentTag and RawMarkup MarkupElements while rendering a response. Markup in the stream may be HTML or some other kind of markup, such as VXML, as determined by the specific container subclass.

  A markup stream may be directly associated with a container via setMarkupStream. However, a container which does not have a markup stream (its getMarkupStream() returns null) may inherit a markup stream from a container above it in the component hierarchy. The Component.findMarkupStream() method will locate the first container at or above this container which has a markup stream.

  All Page containers set a markup stream before rendering by calling the method getAssociatedMarkupStream(boolean) to load the markup associated with the page. Since Page is at the top of the container hierarchy, it is guaranteed that Component.findMarkupStream() will always return a valid markup stream.

Author:

Jonathan Locke

See Also:

MarkupStream, Serialized Form

Field Summary

Fields inherited from class org.apache.wicket.Component

ENABLE, FLAG_INITIALIZED, FLAG_REMOVING_FROM_HIERARCHY, FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4, FLAG_RESERVED5, FLAG_RESERVED8, PARENT_PATH, PATH_SEPARATOR, RENDER

Constructor Summary

Constructors

Constructor and Description
MarkupContainer(String id)
MarkupContainer(String id, IModel<?> model)

Method Summary

Methods

Modifier and Type	Method and Description
MarkupContainer	add(Component... childs) Adds a child component to this container.
MarkupContainer	addOrReplace(Component... childs) Replaces a child component of this container with another or just adds it in case no child with the same id existed yet.
boolean	autoAdd(Component component, MarkupStream markupStream) This method allows a component to be added by an auto-resolver such as AutoLinkResolver.
boolean	contains(Component component, boolean recurse)
Component	get(int index) Returns child component at the specified index
Component	get(String path) Get a child component by looking it up with the given path.
Markup	getAssociatedMarkup() Gets a fresh markup stream that contains the (immutable) markup resource for this class.
MarkupStream	getAssociatedMarkupStream(boolean throwException) Gets a fresh markup stream that contains the (immutable) markup resource for this class.
IMarkupFragment	getMarkup(Component child) Get the childs markup
MarkupType	getMarkupType() Get the type of associated markup for this component.
void	internalAdd(Component child) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
void	internalInitialize() THIS METHOD IS NOT PART OF THE PUBLIC API, DO NOT CALL IT Overrides Component.internalInitialize() to call Component.fireInitialize() for itself and for all its children.
Iterator<Component>	iterator()
Iterator<Component>	iterator(Comparator<Component> comparator)
protected void	onAfterRenderChildren()
void	onComponentTagBody(MarkupStream markupStream, ComponentTag openTag) Handle the container's body.
protected void	onRender() Implementation that renders this component.
MarkupContainer	remove(Component component)
MarkupContainer	remove(String id) Removes the given component
MarkupContainer	removeAll() Removes all children from this container.
protected void	renderAll(MarkupStream markupStream, ComponentTag openTag) Loop through the markup in this container
void	renderAssociatedMarkup(String openTagName, String exceptionMessage) Renders the entire associated markup for a container such as a Border or Panel.
protected boolean	renderNext(MarkupStream markupStream) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
MarkupContainer	replace(Component child) Replaces a child component of this container with another
MarkupContainer	setDefaultModel(IModel<?> model) Sets the given model.
int	size() Get the number of children in this container.
void	swap(int idx1, int idx2) Swaps position of children.
String	toString() Gets the string representation of this component.
String	toString(boolean detailed)
ComponentHierarchyIterator	visitChildren() Deprecated. ComponentHierarchyIterator is deprecated. Use visitChildren(org.apache.wicket.util.visit.IVisitor) instead
ComponentHierarchyIterator	visitChildren(Class<?> clazz) Deprecated. ComponentHierarchyIterator is deprecated. Use visitChildren(Class, org.apache.wicket.util.visit.IVisitor) instead.
<S extends Component,R> R	visitChildren(Class<?> clazz, IVisitor<S,R> visitor) Traverses all child components of the given class in this container, calling the visitor's visit method at each one.
<R> R	visitChildren(IVisitor<Component,R> visitor) Traverses all child components in this container, calling the visitor's visit method at each one.

Methods inherited from class org.apache.wicket.Component

add, addStateChange, afterRender, beforeRender, canCallListenerInterface, checkComponentTag, checkComponentTagAttribute, checkHierarchyChange, clearOriginalDestination, configure, continueToOriginalDestination, debug, detach, detachModel, detachModels, determineVisibility, error, exceptionMessage, fatal, findMarkupStream, findPage, findParent, findParentWithAssociatedMarkup, getAjaxRegionMarkupId, getApplication, getBehaviorById, getBehaviorId, getBehaviors, getBehaviors, getClassRelativePath, getConverter, getDefaultModel, getDefaultModelObject, getDefaultModelObjectAsString, getDefaultModelObjectAsString, getEscapeModelStrings, getFeedbackMessages, getFlag, getId, getInnermostModel, getInnermostModel, getLocale, getLocalizer, getMarkup, getMarkupAttributes, getMarkupId, getMarkupId, getMarkupIdFromMarkup, getMarkupIdImpl, getMarkupSourcingStrategy, getMetaData, getModelComparator, getOutputMarkupId, getOutputMarkupPlaceholderTag, getPage, getPageRelativePath, getParent, getPath, getRenderBodyOnly, getRequest, getRequestCycle, getRequestFlag, getResponse, getSession, getSizeInBytes, getStatelessHint, getString, getString, getString, getStyle, getVariation, hasBeenRendered, hasErrorMessage, hasFeedbackMessage, info, initModel, internalOnModelChanged, internalPrepareForRender, internalRenderComponent, isActionAuthorized, isAuto, isBehaviorAccepted, isEnableAllowed, isEnabled, isEnabledInHierarchy, isIgnoreAttributeModifier, isRenderAllowed, isRendering, isStateless, isVersioned, isVisibilityAllowed, isVisible, isVisibleInHierarchy, markRendering, modelChanged, modelChanging, newMarkupSourcingStrategy, onAfterRender, onBeforeRender, onComponentTag, onConfigure, onDetach, onEvent, onInitialize, onModelChanged, onModelChanging, onReAdd, onRemove, prepareForRender, redirectToInterceptPage, remove, remove, render, renderComponentTag, rendered, renderHead, renderHead, renderHead, renderPlaceholderTag, replaceComponentTagBody, replaceWith, sameInnermostModel, sameInnermostModel, send, setAuto, setDefaultModelObject, setEnabled, setEscapeModelStrings, setFlag, setIgnoreAttributeModifier, setMarkup, setMarkupId, setMarkupIdImpl, setMetaData, setOutputMarkupId, setOutputMarkupPlaceholderTag, setParent, setRenderBodyOnly, setRequestFlag, setResponsePage, setResponsePage, setResponsePage, setVersioned, setVisibilityAllowed, setVisible, success, urlFor, urlFor, urlFor, urlFor, urlFor, visitParents, visitParents, warn, wrap

Methods inherited from class java.lang.Object

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

Constructor Detail

MarkupContainer

public MarkupContainer(String id)

See Also:

Component.Component(String)

MarkupContainer

public MarkupContainer(String id,
               IModel<?> model)

See Also:

Component.Component(String, IModel)

Method Detail

add

public MarkupContainer add(Component... childs)

Adds a child component to this container.

Parameters:

childs - The child(ren) to add.

Returns:

This

Throws:

IllegalArgumentException - Thrown if a child with the same id is replaced by the add operation.

addOrReplace

public MarkupContainer addOrReplace(Component... childs)

Replaces a child component of this container with another or just adds it in case no child with the same id existed yet.

Parameters:

childs - The child(s) to be added or replaced

Returns:

This

autoAdd

public final boolean autoAdd(Component component,
              MarkupStream markupStream)

This method allows a component to be added by an auto-resolver such as AutoLinkResolver. While the component is being added, the component's FLAG_AUTO boolean is set. The isAuto() method of Component returns true if a component or any of its parents has this bit set. When a component is added via autoAdd(), the logic in Page that normally (a) checks for modifications during the rendering process, and (b) versions components, is bypassed if Component.isAuto() returns true.

The result of all this is that components added with autoAdd() are free from versioning and can add their own children without the usual exception that would normally be thrown when the component hierarchy is modified during rendering.

Parameters:

component - The component to add

markupStream - Null, if the parent container is able to provide the markup. Else the markup stream to be used to render the component.

Returns:

True, if component has been added

contains

public boolean contains(Component component,
               boolean recurse)

Parameters:

component - The component to check

recurse - True if all descendents should be considered

Returns:

True if the component is contained in this container

get

public final Component get(String path)

Get a child component by looking it up with the given path.

A component path consists of component ids separated by colons, e.g. "b:c" identifies a component "c" inside container "b" inside this container.

Specified by:

get in interface IRequestableComponent

Overrides:

get in class Component

Parameters:

path - path to component

Returns:

The component at the path

getAssociatedMarkupStream

public MarkupStream getAssociatedMarkupStream(boolean throwException)

Gets a fresh markup stream that contains the (immutable) markup resource for this class.

Parameters:

throwException - If true, throw an exception, if markup could not be found

Returns:

A stream of MarkupElement elements

getAssociatedMarkup

public Markup getAssociatedMarkup()

Gets a fresh markup stream that contains the (immutable) markup resource for this class.

Returns:

A stream of MarkupElement elements. Null if not found.

getMarkup

public IMarkupFragment getMarkup(Component child)

Get the childs markup

Parameters:

child - The child component. If null, the container's markup will be returned. See Border, Panel or Enclosure where getMarkup(null) != getMarkup().

Returns:

The childs markup

See Also:

Component.getMarkup()

getMarkupType

public MarkupType getMarkupType()

Get the type of associated markup for this component.

Returns:

The type of associated markup for this component (for example, "html", "wml" or "vxml"). The markup type for a component is independent of whether or not the component actually has an associated markup resource file (which is determined at runtime). If there is no markup type for a component, null may be returned, but this means that no markup can be loaded for the class. Null is also returned if the component, or any of its parents, has not been added to a Page.

internalAdd

public void internalAdd(Component child)

THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT. Adds a child component to this container.

Parameters:

child - The child

Throws:

IllegalArgumentException - Thrown if a child with the same id is replaced by the add operation.

iterator

public Iterator<Component> iterator()

Specified by:

iterator in interface Iterable<Component>

Returns:

Iterator that iterates through children in the order they were added

iterator

public final Iterator<Component> iterator(Comparator<Component> comparator)

Parameters:

comparator - The comparator

Returns:

Iterator that iterates over children in the order specified by comparator

remove

public MarkupContainer remove(Component component)

Parameters:

component - Component to remove from this container

Returns:

this for chaining

remove

public MarkupContainer remove(String id)

Removes the given component

Parameters:

id - The id of the component to remove

Returns:

this for chaining

removeAll

public MarkupContainer removeAll()

Removes all children from this container.

Note: implementation does not call remove(Component) for each component.

Returns:

this for method chaining

renderAssociatedMarkup

public final void renderAssociatedMarkup(String openTagName,
                          String exceptionMessage)

Renders the entire associated markup for a container such as a Border or Panel. Any leading or trailing raw markup in the associated markup is skipped.

Parameters:

openTagName - the tag to render the associated markup for

exceptionMessage - message that will be used for exceptions

replace

public MarkupContainer replace(Component child)

Replaces a child component of this container with another

Parameters:

child - The child

Returns:

This

Throws:

IllegalArgumentException - Thrown if there was no child with the same id.

setDefaultModel

public MarkupContainer setDefaultModel(IModel<?> model)

Description copied from class: Component

Sets the given model.

WARNING: DO NOT OVERRIDE THIS METHOD UNLESS YOU HAVE A VERY GOOD REASON FOR IT. OVERRIDING THIS MIGHT OPEN UP SECURITY LEAKS AND BREAK BACK-BUTTON SUPPORT.

Overrides:

setDefaultModel in class Component

Parameters:

model - The model

Returns:

This

See Also:

Component.setDefaultModel(org.apache.wicket.model.IModel)

size

public int size()

Get the number of children in this container.

Returns:

Number of children in this container

toString

public String toString()

Description copied from class: Component

Gets the string representation of this component.

Overrides:

toString in class Component

Returns:

The path to this component

See Also:

Component.toString()

toString

public String toString(boolean detailed)

Overrides:

toString in class Component

Parameters:

detailed - True if a detailed string is desired

Returns:

String representation of this container

visitChildren

public final <S extends Component,R> R visitChildren(Class<?> clazz,
                                      IVisitor<S,R> visitor)

Traverses all child components of the given class in this container, calling the visitor's visit method at each one. Make sure that if you give a type S that the clazz parameter will only resolve to those types. Else a class cast exception will occur.

Type Parameters:

S - The type that goes into the Visitor.component() method.

R -

Parameters:

clazz - The class of child to visit

visitor - The visitor to call back to

Returns:

The return value from a visitor which halted the traversal, or null if the entire traversal occurred

visitChildren

public final <R> R visitChildren(IVisitor<Component,R> visitor)

Traverses all child components in this container, calling the visitor's visit method at each one.

Type Parameters:

R -

Parameters:

visitor - The visitor to call back to

Returns:

The return value from a visitor which halted the traversal, or null if the entire traversal occurred

visitChildren

@Deprecated
public final ComponentHierarchyIterator visitChildren()

Deprecated. ComponentHierarchyIterator is deprecated. Use visitChildren(org.apache.wicket.util.visit.IVisitor) instead

Returns:

A iterator which iterators over all children and grand-children the Component

visitChildren

@Deprecated
public final ComponentHierarchyIterator visitChildren(Class<?> clazz)

Deprecated. ComponentHierarchyIterator is deprecated. Use visitChildren(Class, org.apache.wicket.util.visit.IVisitor) instead.

Parameters:

clazz - Filter condition

Returns:

A iterator which iterators over all children and grand-children the Component, returning only components which implement (instanceof) the provided clazz.

internalInitialize

public final void internalInitialize()

THIS METHOD IS NOT PART OF THE PUBLIC API, DO NOT CALL IT Overrides Component.internalInitialize() to call Component.fireInitialize() for itself and for all its children.

Overrides:

internalInitialize in class Component

See Also:

Component.fireInitialize()

get

public final Component get(int index)

Returns child component at the specified index

Parameters:

index -

Returns:

child component at the specified index

Throws:

ArrayIndexOutOfBoundsException

renderNext

protected boolean renderNext(MarkupStream markupStream)

THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE OR OVERWRITE IT. Renders the next element of markup in the given markup stream.

Parameters:

markupStream - The markup stream

Returns:

true, if element was rendered as RawMarkup

onComponentTagBody

public void onComponentTagBody(MarkupStream markupStream,
                      ComponentTag openTag)

Handle the container's body. If your override of this method does not advance the markup stream to the close tag for the openTag, a runtime exception will be thrown by the framework.

Overrides:

onComponentTagBody in class Component

Parameters:

markupStream - The markup stream

openTag - The open tag for the body

onRender

protected void onRender()

Description copied from class: Component

Implementation that renders this component.

Specified by:

onRender in class Component

See Also:

Component.onRender()

renderAll

protected final void renderAll(MarkupStream markupStream,
             ComponentTag openTag)

Loop through the markup in this container

Parameters:

markupStream -

openTag -

onAfterRenderChildren

protected void onAfterRenderChildren()

Overrides:

onAfterRenderChildren in class Component

swap

public final void swap(int idx1,
        int idx2)

Swaps position of children. This method is particularly useful for adjusting positions of repeater's items without rebuilding the component hierarchy

Parameters:

idx1 - index of first component to be swapped

idx2 - index of second component to be swapped