Component (Wicket 1.4-m1 API)

Javadoc hosting sponsored by DD Poker and Donohoe Digital LLC.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.wicket
Class Component<T>

java.lang.Object
  org.apache.wicket.Component<T>


Type Parameters:: T - Model object type

All Implemented Interfaces:: java.io.Serializable, IClusterable, IConverterLocator

Direct Known Subclasses:: MarkupContainer, WebComponent

public abstract class Component<T>
extends java.lang.Object
implements IClusterable, IConverterLocator
extends java.lang.Object
implements IClusterable, IConverterLocator

Component serves as the highest level abstract base class for all components.

Identity - All Components must have a non-null id which is retrieved by calling getId(). The id must be unique within the MarkupContainer that holds the Component, but does not have to be globally unique or unique within a Page's component hierarchy.
Hierarchy - A component has a parent which can be retrieved with getParent(). If a component is an instance of MarkupContainer, it may have children. In this way it has a place in the hierarchy of components contained on a given page.
Component Paths - The path from the Page at the root of the component hierarchy to a given Component is simply the concatenation with dot separators of each id along the way. For example, the path "a.b.c" would refer to the component named "c" inside the MarkupContainer named "b" inside the container named "a". The path to a component can be retrieved by calling getPath(). This path is an absolute path beginning with the id of the Page at the root. Pages bear a PageMap/Session-relative identifier as their id, so each absolute path will begin with a number, such as "0.a.b.c". To get a Component path relative to the page that contains it, you can call getPageRelativePath().
LifeCycle - Components participate in the following lifecycle phases:
- Construction - A Component is constructed with the Java language new operator. Children may be added during construction if the Component is a MarkupContainer.
- Request Handling - An incoming request is processed by a protocol request handler such as WicketServlet. An associated Application object creates Session, Request and Response objects for use by a given Component in updating its model and rendering a response. These objects are stored inside a container called RequestCycle which is accessible via getRequestCycle(). The convenience methods getRequest(), getResponse() and getSession() provide easy access to the contents of this container.
- Listener Invocation - If the request references a listener on an existing Component, that listener is called, allowing arbitrary user code to handle events such as link clicks or form submits. Although arbitrary listeners are supported in Wicket, the need to implement a new class of listener is unlikely for a web application and even the need to implement a listener interface directly is highly discouraged. Instead, calls to listeners are routed through logic specific to the event, resulting in calls to user code through other overridable methods. For example, the IFormSubmitListener.onFormSubmitted() method implemented by the Form class is really a private implementation detail of the Form class that is not designed to be overridden (although unfortunately, it must be public since all interface methods in Java must be public). Instead, Form subclasses should override user-oriented methods such as onValidate(), onSubmit() and onError() (although only the latter two are likely to be overridden in practice).
- onBeginRequest - The onBeginRequest() method is called.
- Form Submit - If a Form has been submitted and the Component is a FormComponent, the component's model is validated by a call to FormComponent.validate().
- Form Model Update - If a valid Form has been submitted and the Component is a FormComponent, the component's model is updated by a call to FormComponent.updateModel().
- Rendering - A markup response is generated by the Component via render(), which calls subclass implementation code contained in onRender(org.apache.wicket.markup.MarkupStream). Once this phase begins, a Component becomes immutable. Attempts to alter the Component will result in a WicketRuntimeException.
- onEndRequest () - The onEndRequest() method is called.
Component Models - The primary responsibility of a component is to use its model (an object that implements IModel), which can be set via setModel(IModel model) and retrieved via getModel(), to render a response in an appropriate markup language, such as HTML. In addition, form components know how to update their models based on request information. Since the IModel interface is a wrapper around an actual model object, a convenience method getModelObject() is provided to retrieve the model Object from its IModel wrapper. A further convenience method, getModelObjectAsString(), is provided for the very common operation of converting the wrapped model Object to a String.
Visibility - Components which have setVisible(false) will return false from isVisible() and will not render a response (nor will their children).
Page - The Page containing any given Component can be retrieved by calling getPage(). If the Component is not attached to a Page, an IllegalStateException will be thrown. An equivalent method, findPage() is available for special circumstances where it might be desirable to get a null reference back instead.
Session - The Page for a Component points back to the Session that contains the Page. The Session for a component can be accessed with the convenience method getSession(), which simply calls getPage().getSession().
Locale - The Locale for a Component is available through the convenience method getLocale(), which is equivalent to getSession().getLocale().
String Resources - Components can have associated String resources via the Application's Localizer, which is available through the method getLocalizer(). The convenience methods getString(String key) and getString(String key, IModel model) wrap the identical methods on the Application Localizer for easy access in Components.
Style - The style ("skin") for a component is available through getStyle(), which is equivalent to getSession().getStyle(). Styles are intended to give a particular look to a Component or Resource that is independent of its Locale. For example, a style might be a set of resources, including images and markup files, which gives the design look of "ocean" to the user. If the Session's style is set to "ocean" and these resources are given names suffixed with "_ocean", Wicket's resource management logic will prefer these resources to other resources, such as default resources, which are not as good of a match.
Variation - Whereas Styles are Session (user) specific, variations are component specific. E.g. if the Style is "ocean" and the Variation is "NorthSea", than the resources are given the names suffixed with "_ocean_NorthSea".
AttributeModifiers - You can add one or more AttributeModifiers to any component if you need to programmatically manipulate attributes of the markup tag to which a Component is attached.
Application, ApplicationSettings and ApplicationPages - The getApplication() method provides convenient access to the Application for a Component via getSession().getApplication(). The getApplicationSettings() method is equivalent to getApplication().getSettings(). The getApplicationPages is equivalent to getApplication().getPages().
Feedback Messages - The debug(String), info(String), warn(String), error(java.io.Serializable) and fatal(String) methods associate feedback messages with a Component. It is generally not necessary to use these methods directly since Wicket validators automatically register feedback messages on Components. Any feedback message for a given Component can be retrieved with getFeedbackMessage().
Page Factory - It is possible to change the way that Pages are constructed by overriding the getPageFactory() method, returning your own implementation of IPageFactory.
Versioning - Pages are the unit of versioning in Wicket, but fine-grained control of which Components should participate in versioning is possible via the setVersioned(boolean) method. The versioning participation of a given Component can be retrieved with isVersioned().

AJAX support- Components can be re-rendered after the whole Page has been rendered at least once by calling doRender().

Author:: Jonathan Locke, Chris Turner, Eelco Hillenius, Johan Compagner, Juergen Donnerstag, Igor Vaynberg (ivaynberg)
See Also:: Serialized Form

Nested Class Summary
`class`	`Component.ComponentModelChange` Change record of a model.
`protected static class`	`Component.EnabledChange` A enabled change operation.
`static interface`	`Component.IVisitor<T extends Component<?>>` Generic component visitor interface for component traversals.
`protected static class`	`Component.VisibilityChange` A visibility change operation.

Field Summary
`static Action`	`ENABLE` Action used with IAuthorizationStrategy to determine whether a component is allowed to be enabled.
`protected static int`	`FLAG_RESERVED1` Reserved subclass-definable flag bit
`protected static int`	`FLAG_RESERVED2` Reserved subclass-definable flag bit
`protected static int`	`FLAG_RESERVED3` Reserved subclass-definable flag bit
`protected static int`	`FLAG_RESERVED4` Reserved subclass-definable flag bit
`protected static int`	`FLAG_RESERVED5` Reserved subclass-definable flag bit
`protected static int`	`FLAG_RESERVED6` Reserved subclass-definable flag bit
`protected static int`	`FLAG_RESERVED7` Reserved subclass-definable flag bit
`protected static int`	`FLAG_RESERVED8` Reserved subclass-definable flag bit
`static char`	`PATH_SEPARATOR` Separator for component paths
`static Action`	`RENDER` Action used with IAuthorizationStrategy to determine whether a component and its children are allowed to be rendered.

Constructor Summary
`Component(java.lang.String id)` Constructor.
`Component(java.lang.String id, IModel<T> model)` Constructor.

Method Summary

Component<T> add(IBehavior... behaviors)
Adds an behavior modifier to the component.

protected void addStateChange(Change change)
Adds state change to page.

void afterRender()
Called on very component after the page is rendered.

void beforeRender()
Called for every component when the page is getting to be rendered.

protected boolean callOnBeforeRenderIfNotVisible()
Override this method if you want onBeforeRender to be called even when your component is not visible.

protected void checkComponentTag(ComponentTag tag, java.lang.String name)
Checks whether the given type has the expected name.

protected void checkComponentTagAttribute(ComponentTag tag, java.lang.String key, java.lang.String value)
Checks that a given tag has a required attribute value.

protected void checkHierarchyChange(Component<?> component)
Checks whether the hierarchy may be changed at all, and throws an exception if this is not the case.

boolean continueToOriginalDestination()
Redirects to any intercept page previously specified by a call to redirectToInterceptPage.

void debug(java.lang.String message)
Registers a debug feedback message for this component

void detach()
Detaches the component.

void detachBehaviors()
THIS IS WICKET INTERNAL ONLY.

protected void detachModel()
Detaches the model for this component if it is detachable.

void detachModels()
Detaches all models

boolean determineVisibility()
Determines whether or not a component should be visible, taking into account all the factors: isVisible(), isVisibilityAllowed(), isRenderAllowed()

void error(java.io.Serializable message)
Registers an error feedback message for this component

protected java.lang.String exceptionMessage(java.lang.String message)
Prefixes an exception message with useful information about this.

void fatal(java.lang.String message)
Registers an fatal error feedback message for this component

protected MarkupStream findMarkupStream()
Finds the markup stream for this component.

protected Page findPage()
If this Component is a Page, returns self.





<Z> Z

findParent(java.lang.Class<? super Z> c)
Finds the first container parent of this component of the given class.

MarkupContainer<?> findParentWithAssociatedMarkup()

Application getApplication()
Gets interface to application that this component is a part of.

java.util.List<IBehavior> getBehaviors()
Gets the currently coupled IBehaviors as a unmodifiable list.

protected java.util.List<IBehavior> getBehaviors(java.lang.Class<? extends IBehavior> type)
Gets the subset of the currently coupled IBehaviors that are of the provided type as a unmodifiable list or null if there are no behaviors attached.

java.lang.String getClassRelativePath()

IComponentBorder getComponentBorder()

IConverter<?> getConverter()
Deprecated. To be removed. Please use/ override getConverter(Class) instead.





<Z> IConverter<Z>

getConverter(java.lang.Class<Z> type)
Gets the converter that should be used by this component.

boolean getEscapeModelStrings()
Gets whether model strings should be escaped.

FeedbackMessage getFeedbackMessage()

protected boolean getFlag(int flag)
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.

protected boolean getFlag(short flag)
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.

java.lang.String getId()
Gets the id of this component.

IModel<?> getInnermostModel()

protected IModel<?> getInnermostModel(IModel<?> model)
Finds the innermost IModel object for an IModel that might contain nested IModel(s).

java.util.Locale getLocale()
Gets the locale for this component.

Localizer getLocalizer()
Convenience method to provide easy access to the localizer object within any component.

ValueMap getMarkupAttributes()
THIS IS WICKET INTERNAL ONLY.

java.lang.String getMarkupId()
Retrieves id by which this component is represented within the markup.

java.lang.String getMarkupId(boolean createIfDoesNotExist)
Retrieves id by which this component is represented within the markup.





<M extends java.io.Serializable> 


M

getMetaData(MetaDataKey<M> key)
Gets metadata for this component using the given key.

IModel<T> getModel()
Gets the model.

protected IModelComparator<T> getModelComparator()
Gets the value defaultModelComparator.

T getModelObject()
Gets the backing model object; this is shorthand for getModel().getObject().

java.lang.String getModelObjectAsString()
Gets a model object as a string.

java.lang.String getModelObjectAsString(T modelObject)
Gets a model object as a string.

boolean getOutputMarkupId()
Gets whether or not component will output id attribute into the markup.

boolean getOutputMarkupPlaceholderTag()
Gets whether or not an invisible component will render a placeholder tag.

Page getPage()
Gets the page holding this component.

IPageFactory getPageFactory()

java.lang.String getPageRelativePath()
Gets the path to this component relative to the page it is in.

MarkupContainer<?> getParent()
Gets any parent container, or null if there is none.

java.lang.String getPath()
Gets this component's path.

boolean getRenderBodyOnly()
If false the component's tag will be printed as well as its body (which is default).

Request getRequest()

RequestCycle getRequestCycle()
Gets the active request cycle for this component

Response getResponse()

Session getSession()
Gets the current Session object.

long getSizeInBytes()

protected boolean getStatelessHint()
Returns whether the component can be stateless.

java.lang.String getString(java.lang.String key)

java.lang.String getString(java.lang.String key, IModel<?> model)

java.lang.String getString(java.lang.String key, IModel<?> model, java.lang.String defaultValue)

java.lang.String getStyle()
Gets the style of this component (see Session).

java.lang.String getVariation()
Gets the variation string of this component that will be used to look up markup for this component.

boolean hasBeenRendered()
Gets whether this component was rendered at least once.

boolean hasErrorMessage()

boolean hasFeedbackMessage()

void info(java.lang.String message)
Registers an informational feedback message for this component

protected IModel<T> initModel()
Called when a null model is about to be retrieved in order to allow a subclass to provide an initial model.

void internalAttach()
Deprecated.

void internalDetach()
Deprecated.

protected void internalOnAttach()
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.

protected void internalOnDetach()
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.

protected void internalOnModelChanged()
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.

boolean isActionAuthorized(Action action)
Authorizes an action for a component.

boolean isAncestorOf(Component<?> component)
Deprecated. use getParent().contains(component, false)

protected boolean isAttached()

protected boolean isBehaviorAccepted(IBehavior behavior)
Components are allowed to reject behavior modifiers.

boolean isEnableAllowed()

boolean isEnabled()
Gets whether this component is enabled.

protected boolean isIgnoreAttributeModifier()
If true, all attribute modifiers will be ignored

boolean isRenderAllowed()
Checks the security strategy if the RENDER action is allowed on this component

boolean isStateless()
Returns if the component is stateless or not.

boolean isVersioned()

boolean isVisibilityAllowed()
Gets whether or not visibility is allowed on this component.

boolean isVisible()
Gets whether this component and any children are visible.

boolean isVisibleInHierarchy()
Checks if the component itself and all its parents are visible.

protected MarkupStream locateMarkupStream()

protected void markAttached(boolean attached)
Convenience method that sets the attached flags.

void markRendering()
Sets the RENDERING flag on component and it's children.

void modelChanged()
Called to indicate that the model content for this component has been changed

void modelChanging()
Called to indicate that the model content for this component is about to change

Page newPage(java.lang.Class<? extends Page> c)
Creates a new page using the component's page factory

Page newPage(java.lang.Class<? extends Page> c, PageParameters parameters)
Creates a new page using the component's page factory

protected void onAfterRender()
Called just after a component is rendered.

protected void onAttach()
Deprecated.

protected void onBeforeRender()
Called just before a component is rendered.

protected void onBeginRequest()
Deprecated. use onAttach() instead

protected void onComponentTag(ComponentTag tag)
Processes the component tag.

protected void onComponentTagBody(MarkupStream markupStream, ComponentTag openTag)
Processes the body.

protected void onDetach()
Called to allow a component to detach resources after use.

protected void onEndRequest()
Deprecated. use onDetach() instead

protected void onModelChanged()
Called anytime a model is changed after the change has occurred

protected void onModelChanging()
Called anytime a model is changed, but before the change actually occurs

protected abstract void onRender(MarkupStream markupStream)
Implementation that renders this component.

void prepareForRender()
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.

void redirectToInterceptPage(Page page)
Redirects browser to an intermediate page such as a sign-in page.

void remove()
Removes this component from its parent.

Component<T> remove(IBehavior behavior)
Removes behavior from component

void render()
Performs a render of this component as part of a Page level render process.

void render(MarkupStream markupStream)
Performs a render of this component as part of a Page level render process.

void renderComponent()
Page.renderPage() is used to render a whole page.

void renderComponent(MarkupStream markupStream)
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.

protected void renderComponentTag(ComponentTag tag)
Writes a simple tag out to the response stream.

void rendered()
Called to indicate that a component has been rendered.

void renderHead(HtmlHeaderContainer<?> container)
Print to the web response what ever the component wants to contribute to the head section.

protected void replaceComponentTagBody(MarkupStream markupStream, ComponentTag tag, java.lang.CharSequence body)
Replaces the body with the given one.

void replaceWith(Component<?> replacement)
Replaces this component with another.

boolean sameInnermostModel(Component<?> component)

boolean sameInnermostModel(IModel<?> model)

protected void setAuto(boolean auto)

Component<T> setComponentBorder(IComponentBorder border)
Assigns a component border to this component.

Component<T> setEnabled(boolean enabled)
Sets whether this component is enabled.

Component<T> setEscapeModelStrings(boolean escapeMarkup)
Sets whether model strings should be escaped.

protected void setFlag(int flag, boolean set)
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.

protected void setFlag(short flag, boolean set)
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.

protected Component<T> setIgnoreAttributeModifier(boolean ignore)
If true, all attribute modifiers will be ignored

void setMarkupId(java.lang.String markupId)
Sets this component's markup id to a user defined value.

protected void setMarkupStream(MarkupStream markupStream)
The markup stream will be assigned to the component at the beginning of the component render phase.





<M> void

setMetaData(MetaDataKey<M> key,
            M object)

Sets the metadata for this component using the given key.

Component<T> setModel(IModel<T> model)
Sets the given model.

Component<T> setModelObject(T object)
Sets the backing model object; shorthand for getModel().setObject(object).

Component<T> setOutputMarkupId(boolean output)
Sets whether or not component will output id attribute into the markup.

Component<T> setOutputMarkupPlaceholderTag(boolean outputTag)
Render a placeholder tag when the component is not visible.

void setRedirect(boolean redirect)

Component<T> setRenderBodyOnly(boolean renderTag)
If false the component's tag will be printed as well as its body (which is default).

void setResponsePage(java.lang.Class<? extends Page> cls)
Sets the page that will respond to this request

void setResponsePage(java.lang.Class<? extends Page> cls, PageParameters parameters)
Sets the page class and its parameters that will respond to this request

void setResponsePage(Page page)
Sets the page that will respond to this request

Component<T> setVersioned(boolean versioned)

Component<T> setVisibilityAllowed(boolean allowed)
Sets whether or not this component is allowed to be visible.

Component<T> setVisible(boolean visible)
Sets whether this component and any children are visible.

java.lang.String toString()
Gets the string representation of this component.

java.lang.String toString(boolean detailed)

java.lang.CharSequence urlFor(java.lang.Class<? extends Page> pageClass, PageParameters parameters)
Returns a bookmarkable URL that references a given page class using a given set of page parameters.

java.lang.CharSequence urlFor(IBehavior behaviour, RequestListenerInterface listener)
Gets a URL for the listener interface on a behavior (e.g.

java.lang.CharSequence urlFor(IPageMap pageMap, java.lang.Class<? extends Page> pageClass, PageParameters parameters)
Returns a bookmarkable URL that references a given page class using a given set of page parameters.

java.lang.CharSequence urlFor(IRequestTarget requestTarget)
Returns a URL that references the given request target.

java.lang.CharSequence urlFor(RequestListenerInterface listener)
Gets a URL for the listener interface (e.g.

java.lang.CharSequence urlFor(ResourceReference resourceReference)
Returns a URL that references a shared resource through the provided resource reference.

java.lang.Object visitParents(java.lang.Class<? extends MarkupContainer<?>> c, Component.IVisitor<Component<?>> visitor)
Traverses all parent components of the given class in this container, calling the visitor's visit method at each one.

void warn(java.lang.String message)
Registers a warning feedback message for this component.

protected 



<V> IModel<V>

wrap(IModel<V> model)

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

ENABLE

public static final Action ENABLE

Action used with IAuthorizationStrategy to determine whether a component is allowed to be enabled.

If enabling is authorized, a component may decide by itself (typically using it's enabled property) whether it is enabled or not. If enabling is not authorized, the given component is marked disabled, regardless its enabled property.

When a component is not allowed to be enabled (in effect disabled through the implementation of this interface), Wicket will try to prevent model updates too. This is not completely fail safe, as constructs like:

 User u = (User)getModelObject();
 u.setName("got you there!");

can't be prevented. Indeed it can be argued that any model protection is best dealt with in your model objects to be completely secured. Wicket will catch all normal framework-directed use though.

PATH_SEPARATOR

public static final char PATH_SEPARATOR

Separator for component paths

See Also:: Constant Field Values

RENDER

public static final Action RENDER

Action used with IAuthorizationStrategy to determine whether a component and its children are allowed to be rendered.

There are two uses for this method:

The 'normal' use is for controlling whether a component is rendered without having any effect on the rest of the processing. If a strategy lets this method return 'false', then the target component and its children will not be rendered, in the same fashion as if that component had visibility property 'false'.
The other use is when a component should block the rendering of the whole page. So instead of 'hiding' a component, what we generally want to achieve here is that we force the user to logon/give-credentials for a higher level of authorization. For this functionality, the strategy implementation should throw a AuthorizationException, which will then be handled further by the framework.