org.apache.wicket
Class MarkupContainer

java.lang.Object
  org.apache.wicket.Component
      org.apache.wicket.MarkupContainer

All Implemented Interfaces:

IClusterable, IConverterLocator, java.io.Serializable

Direct Known Subclasses:

AbstractOutputTransformerContainer, Page, WebMarkupContainer

public abstract class MarkupContainer

extends Component

A MarkupContainer holds a map of child components.

• Children - Children can be added by calling the add() method, and they can be looked up using a dotted 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 Component.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 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() to load the markup associated with the page. Since Page is at the top of the container hierarchy, it is guaranteed that findMarkupStream will always return a valid markup stream.

  Author:

  Jonathan Locke

  See Also:

  MarkupStream, Serialized Form

  Nested Class Summary

  Nested classes inherited from class org.apache.wicket.Component

  Component.ComponentModelChange, Component.EnabledChange, Component.IVisitor, Component.VisibilityChange

  Field Summary

  Fields inherited from class org.apache.wicket.Component

  ENABLE, FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4, FLAG_RESERVED5, FLAG_RESERVED6, FLAG_RESERVED7, FLAG_RESERVED8, PATH_SEPARATOR, RENDER

  Constructor Summary

  MarkupContainer(java.lang.String id)
  

  MarkupContainer(java.lang.String id, IModel model)
  

  Method Summary

  MarkupContainer	add(Component child) Adds a child component to this container.
  MarkupContainer	addOrReplace(Component child) 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) Deprecated. since 1.3 Please use autoAdd(Component, MarkupStream) instead
  boolean	autoAdd(Component component, MarkupStream markupStream) This method allows a component to be added by an auto-resolver such as AutoComponentResolver or AutoLinkResolver.
  boolean	contains(Component component, boolean recurse)
  protected MarkupStream	findMarkupStream() Get the markup stream for this component.
  Component	get(java.lang.String path) Get a child component by looking it up with the given path.
  MarkupStream	getAssociatedMarkupStream(boolean throwException) Gets a fresh markup stream that contains the (immutable) markup resource for this class.
  MarkupStream	getMarkupStream() Get the markup stream set on this container.
  java.lang.String	getMarkupType() Get the type of associated markup for this component.
  boolean	hasAssociatedMarkup()
  void	internalAdd(Component child) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  boolean	isTransparentResolver() Some MarkupContainers (e.g.
  java.util.Iterator	iterator()
  java.util.Iterator	iterator(java.util.Comparator comparator)
  IResourceStream	newMarkupResourceStream(java.lang.Class containerClass) NOT USED ANYMORE; it's here for helping people migrate from Wicket 1.2 to Wicket 1.3
  protected void	onComponentTagBody(MarkupStream markupStream, ComponentTag openTag) Handle the container's body.
  protected void	onRender(MarkupStream markupStream) Renders this component.
  void	remove(Component component)
  void	remove(java.lang.String id) Removes the given component
  void	removeAll() Removes all children from this container.
  protected void	renderAll(MarkupStream markupStream) Renders this component and all sub-components using the given markup stream.
  void	renderAssociatedMarkup(java.lang.String openTagName, java.lang.String exceptionMessage) Renders the entire associated markup stream for a container such as a Border or Panel.
  protected void	renderComponentTagBody(MarkupStream markupStream, ComponentTag openTag) Renders markup for the body of a ComponentTag from the current position in the given markup stream.
  MarkupContainer	replace(Component child) Replaces a child component of this container with another
  protected void	setMarkupStream(MarkupStream markupStream) Set markup stream for this container.
  Component	setModel(IModel model) Sets the given model.
  int	size() Get the number of children in this container.
  java.lang.String	toString() Gets the string representation of this component.
  java.lang.String	toString(boolean detailed)
  java.lang.Object	visitChildren(java.lang.Class clazz, Component.IVisitor visitor) Traverses all child components of the given class in this container, calling the visitor's visit method at each one.
  java.lang.Object	visitChildren(Component.IVisitor 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, callOnBeforeRenderIfNotVisible, checkComponentTag, checkComponentTagAttribute, checkHierarchyChange, continueToOriginalDestination, debug, detach, detachBehaviors, detachModel, detachModels, error, exceptionMessage, fatal, findPage, findParent, findParentWithAssociatedMarkup, getApplication, getBehaviors, getBehaviors, getClassRelativePath, getComponentBorder, getConverter, getConverter, getEscapeModelStrings, getFeedbackMessage, getFlag, getFlag, getId, getInnermostModel, getInnermostModel, getLocale, getLocalizer, getMarkupAttributes, getMarkupId, getMarkupId, getMetaData, getModel, getModelComparator, getModelObject, getModelObjectAsString, getModelObjectAsString, getOutputMarkupId, getOutputMarkupPlaceholderTag, getPage, getPageFactory, getPageRelativePath, getParent, getPath, getRenderBodyOnly, getRequest, getRequestCycle, getResponse, getSession, getSizeInBytes, getStatelessHint, getString, getString, getString, getStyle, getVariation, hasBeenRendered, hasErrorMessage, hasFeedbackMessage, info, initModel, internalAttach, internalDetach, internalOnAttach, internalOnDetach, internalOnModelChanged, isActionAuthorized, isAncestorOf, isAttached, isBehaviorAccepted, isEnableAllowed, isEnabled, isIgnoreAttributeModifier, isRenderAllowed, isStateless, isVersioned, isVisible, isVisibleInHierarchy, locateMarkupStream, markAttached, markRendering, modelChanged, modelChanging, newPage, newPage, onAfterRender, onAttach, onBeforeRender, onBeginRequest, onComponentTag, onDetach, onEndRequest, onModelChanged, onModelChanging, prepareForRender, redirectToInterceptPage, remove, remove, render, render, renderComponent, renderComponent, renderComponentTag, rendered, renderHead, replaceComponentTagBody, replaceWith, sameInnermostModel, sameInnermostModel, setAuto, setComponentBorder, setEnabled, setEscapeModelStrings, setFlag, setFlag, setIgnoreAttributeModifier, setMarkupId, setMetaData, setModelObject, setOutputMarkupId, setOutputMarkupPlaceholderTag, setRedirect, setRenderBodyOnly, setResponsePage, setResponsePage, setResponsePage, setVersioned, setVisible, urlFor, urlFor, urlFor, urlFor, urlFor, urlFor, 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(java.lang.String id)

  See Also:

  Component.Component(String)

  MarkupContainer

  public MarkupContainer(java.lang.String id,
                         IModel model)

  See Also:

  Component.Component(String, IModel)

  Method Detail

  add

  public final MarkupContainer add(Component child)

  Adds a child component to this container.

  Parameters:

  child - The child

  Returns:

  This

  Throws:

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

  addOrReplace

  public final MarkupContainer addOrReplace(Component child)

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

  Parameters:

  child - The child

  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 AutoComponentResolver or 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

  autoAdd

  public final boolean autoAdd(Component component)

  Deprecated. since 1.3 Please use autoAdd(Component, MarkupStream) instead

  Parameters:

  component - The component to add

  Returns:

  True, if component has been added

  contains

  public final 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(java.lang.String path)

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

  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

  getMarkupStream

  public final MarkupStream getMarkupStream()

  Get the markup stream set on this container.

  Returns:

  Returns the markup stream set on this container.

  getMarkupType

  public java.lang.String 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.

  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:

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

  isTransparentResolver

  public boolean isTransparentResolver()

  Some MarkupContainers (e.g. HtmlHeaderContainer) have to be transparent with respect to their child components. A transparent container gets its children from its parent container.

  Returns:

  false. By default a MarkupContainer is not transparent.

  See Also:

  ParentResolver

  iterator

  public final java.util.Iterator iterator()

  Returns:

  Iterator that iterates through children in the order they were added

  iterator

  public final java.util.Iterator iterator(java.util.Comparator comparator)

  Parameters:

  comparator - The comparator

  Returns:

  Iterator that iterates over children in the order specified by comparator

  newMarkupResourceStream

  public final IResourceStream newMarkupResourceStream(java.lang.Class containerClass)

  NOT USED ANYMORE; it's here for helping people migrate from Wicket 1.2 to Wicket 1.3

  Parameters:

  containerClass -

  Returns:

  nothing

  Throws:

  java.lang.IllegalStateException - throws an IllegalStateException

  remove

  public void remove(Component component)

  Parameters:

  component - Component to remove from this container

  remove

  public final void remove(java.lang.String id)

  Removes the given component

  Parameters:

  id - The id of the component to remove

  removeAll

  public final void removeAll()

  Removes all children from this container.

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

  renderAssociatedMarkup

  public final void renderAssociatedMarkup(java.lang.String openTagName,
                                           java.lang.String exceptionMessage)

  Renders the entire associated markup stream 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 final MarkupContainer replace(Component child)

  Replaces a child component of this container with another

  Parameters:

  child - The child

  Returns:

  This

  Throws:

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

  setModel

  public Component setModel(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:

  setModel in class Component

  Parameters:

  model - The model

  Returns:

  This

  See Also:

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

  size

  public final int size()

  Get the number of children in this container.

  Returns:

  Number of children in this container

  toString

  public java.lang.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 java.lang.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 java.lang.Object visitChildren(java.lang.Class clazz,
                                              Component.IVisitor visitor)

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

  Parameters:

  clazz - The class of child to visit, or null to visit all children

  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 java.lang.Object visitChildren(Component.IVisitor visitor)

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

  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

  findMarkupStream

  protected final MarkupStream findMarkupStream()

  Get the markup stream for this component.

  Overrides:

  findMarkupStream in class Component

  Returns:

  The markup stream for this component, or if it doesn't have one, the markup stream for the nearest parent which does have one

  onComponentTagBody

  protected 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(MarkupStream markupStream)

  Renders this component. This implementation just calls renderComponent.

  Specified by:

  onRender in class Component

  Parameters:

  markupStream -

  renderAll

  protected void renderAll(MarkupStream markupStream)

  Renders this component and all sub-components using the given markup stream.

  Parameters:

  markupStream - The markup stream

  renderComponentTagBody

  protected final void renderComponentTagBody(MarkupStream markupStream,
                                              ComponentTag openTag)

  Renders markup for the body of a ComponentTag from the current position in the given markup stream. If the open tag passed in does not require a close tag, nothing happens. Markup is rendered until the closing tag for openTag is reached.

  Parameters:

  markupStream - The markup stream

  openTag - The open tag

  setMarkupStream

  protected final void setMarkupStream(MarkupStream markupStream)

  Set markup stream for this container.

  Overrides:

  setMarkupStream in class Component

  Parameters:

  markupStream - The markup stream

  See Also:

  Component.findMarkupStream(), getMarkupStream()

  hasAssociatedMarkup

  public boolean hasAssociatedMarkup()

  Returns:

  True if this markup container has associated markup