Package org.apache.wicket

Class Component

  • All Implemented Interfaces:
    Serializable, IEventSink, IEventSource, IFeedbackContributor, IConverterLocator, IMetadataContext<Serializable,​Component>, IHeaderContributor, IRequestableComponent, IHierarchical<Component>, IClusterable
    Direct Known Subclasses:
    MarkupContainer, WebComponent
    public abstract class Component
extends Object
implements IClusterable, IConverterLocator, IRequestableComponent, IHeaderContributor, IHierarchical<Component>, IEventSink, IEventSource, IMetadataContext<Serializable,​Component>, IFeedbackContributor
    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.

      The path from the Page at the root of the component hierarchy to a given Component is simply the concatenation with colon 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(). 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. IComponentInstantiationListeners are notified of component instantiation.

        onInitialize() is called on the component as soon as the component is part of a page's component tree. At this state the component is able to access its markup.

      • Request Handling - An incoming request is processed by a protocol request handler such as WicketFilter. 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 an IRequestListener on an existing Component (or one of its Behaviors, see below), that listener is notified, 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. See Form for an example of a component which listens for events via IRequestListener.
      • Rendering - Before a page or part of a page (in case of Ajax updates) is rendered, all containing components are able to prepare for rendering via two hook methods: onConfigure() (regardless whether they are visible or not) and onBeforeRender() (if visible only) .
        A markup response is generated by the Component via render(), which calls subclass implementation code contained in onRender(). Once this phase begins, a Component becomes immutable. Attempts to alter the Component will result in a WicketRuntimeException.
      • Detachment - Each request cycle finishes by detaching all touched components. Subclasses should clean up their state by overriding onDetach() or more specifically detachModels() if they keep references to models beside the default model.
    • Visibility - If a component is not visible (see setVisible(boolean)) it will not render a response (nor will their children).
    • Enabling - Component subclasses take into account their enabled state (see setEnabled(boolean) when rendering, and in case of a FormComponent will not not update its model while the request is handled.
    • Models - The primary responsibility of a component is to use its model (an object that implements IModel) to render a response in an appropriate markup language, such as HTML. In addition, FormComponents know how to update their models based on request information, see FormComponent.updateModel(). Since the IModel interface is a wrapper around another object, a convenience method getDefaultModelObject() is provided to retrieve the object from its IModel wrapper. A further convenience method, getDefaultModelObjectAsString(), is provided for the very common operation of converting the wrapped object to a String.
      The component's model can be passed in the constructor or set via setDefaultModel(IModel). In neither case a model can be created on demand with initModel().
      Note that a component can have more models besides its default model.
    • Behaviors - You can add multiple Behaviors to any component if you need to dynamically alter the behavior of components, e.g. manipulate attributes of the markup tag to which a Component is attached. Behaviors take part in the component's lifecycle through various callback methods.
    • Locale - The Locale for a Component is available through getLocale(), which delegates to its parent's locale, finally consulting the Session's locale.
    • Style - The Session's style ("skin") is available through getStyle(). Styles are intended to give a particular look to all components or resources in a session 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 getVariation() returnss "NorthSea", than the resources are given the names suffixed with "_ocean_NorthSea".
    • 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.
    • Feedback Messages - The debug(Serializable), info(Serializable), warn(Serializable), error(java.io.Serializable) and fatal(Serializable) 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. Feedback message for a given Component can be retrieved with getFeedbackMessages().
    • 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().
    • 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.
    • Application - The getApplication() method provides convenient access to the Application for a Component.
    • AJAX support- Components can be re-rendered after the whole Page has been rendered at least once by calling doRender().
    • Security - All components are subject to an IAuthorizationStrategy which controls instantiation, visibility and enabling. See SimplePageAuthorizationStrategy for a simple implementation.
    Author:
    Jonathan Locke, Chris Turner, Eelco Hillenius, Johan Compagner, Juergen Donnerstag, Igor Vaynberg (ivaynberg)
    See Also:
    Serialized Form

    • 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.

      • 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.

      • RFLAG_CONTAINER_HAS_REMOVALS

        protected static final short RFLAG_CONTAINER_HAS_REMOVALS
        This flag tracks if removals have been set on this component. Clearing this key is an expensive operation. With this flag this expensive call can be avoided.
        See Also:
        Constant Field Values

    • Constructor Detail

      • Component

        public Component​(String id)
        Constructor. All components have names. A component's id cannot be null. This is the minimal constructor of component. It does not register a model.
        Parameters:
        id - The non-null id of this component
        Throws:
        WicketRuntimeException - Thrown if the component has been given a null id.

      • Component

        public Component​(String id,
                 IModel<?> model)
        Constructor. All components have names. A component's id cannot be null. This constructor includes a model.
        Parameters:
        id - The non-null id of this component
        model - The component's model
        Throws:
        WicketRuntimeException - Thrown if the component has been given a null id.

    • Method Detail

      • getMarkup

        public IMarkupFragment getMarkup()
        Get the Markup associated with the Component. If not subclassed, the parent container is asked to return the markup of this child component.

        Components like Panel and Border should return the "calling" markup fragment, e.g. <span wicket:id="myPanel">body</span>. You may use Panel/Border/Enclosure.getMarkup(null) to return the associated markup file. And Panel/Border/Enclosure.getMarkup(child) will search the child in the appropriate markup fragment.

        Returns:
        The markup fragment
        See Also:
        MarkupContainer.getMarkup(Component)

      • setMarkup

        public final Component setMarkup​(IMarkupFragment markup)
        Set the markup for the component. Note that the component's markup variable is transient and thus must only be used for one render cycle. E.g. auto-component are using it. You may also it if you subclassed getMarkup().
        Parameters:
        markup -

      • onConfigure

        protected void onConfigure()
        Called on all components before any component is rendered. This method should be used to configure such things as visibility and enabled flags.

        Overrides must call super.onConfigure(), usually before any other code

        NOTE: Component hierarchy should not be modified inside this method, instead it should be done in onBeforeRender()

        NOTE: Why this method is preferrable to directly overriding isVisible() and isEnabled()? Because those methods are called multiple times even for processing of a single request. If they contain expensive logic they can slow down the response time of the entire page. Further, overriding those methods directly on form components may lead to inconsistent or unexpected state depending on when those methods are called in the form processing workflow. It is a better practice to push changes to state rather than pull.

        NOTE: If component's visibility or another property depends on another component you may call other.configure() followed by other.isVisible() as mentioned in configure() javadoc.

        NOTE: Why should onBeforeRender() not be used for this? Because if a component's visibility is controlled inside onBeforeRender(), once invisible the component will never become visible again.

      • onInitialize

        protected void onInitialize()
        This method is meant to be used as an alternative to initialize components. Usually the component's constructor is used for this task, but sometimes a component cannot be initialized in isolation, it may need to access its parent component or its markup in order to fully initialize. This method is invoked once per component's lifecycle when a path exists from this component to the Page thus providing the component with an atomic callback when the component's environment is built out.

        Overrides must call super#onInitialize(). Usually this should be the first thing an override does, much like a constructor.

        Parent containers are guaranteed to be initialized before their children

        It is safe to use getPage() in this method

        NOTE:The timing of this call is not precise, the contract is that it is called sometime before onBeforeRender().

      • isInitialized

        public final boolean isInitialized()
        Checks if the component has been initialized - onInitialize() has been called
        Returns:
        true if component has been initialized

      • beforeRender

        public final void beforeRender()
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT! Called on all components before any component is rendered. Calls hooks configure() and (if visible) onBeforeRender() and delegates to beforeRender() of all child components.

      • configure

        public final void configure()
        Triggers onConfigure() to be invoked on this component if it has not already during this request.

        This method should be invoked before any calls to isVisible() or isEnabled(). Usually this method will be called by the framework before the component is rendered and so users should not need to call it; however, in cases where visibility or enabled or other state of one component depends on the state of another this method should be manually invoked on the other component by the user. EG to link visiliby of two markup containers the following should be done: 

         final WebMarkupContainer source=new WebMarkupContainer("a") {
        protected void onConfigure() {
    setVisible(Math.rand()>0.5f);
  }
 };
 
 WebMarkupContainer linked=new WebMarkupContainer("b") {
        protected void onConfigure() {
                source.configure(); // make sure source is configured
                setVisible(source.isVisible());
  }
 }

      • continueToOriginalDestination

        public final void continueToOriginalDestination()
        Redirects to any intercept page previously specified by a call to redirectToInterceptPage(Page). The redirect is done by throwing an exception. If there is no intercept page no exception will be thrown and the program flow will continue uninterrupted. Example: 
         add(new Link("login")
 {
        protected void onClick()
        {
                if (authenticate())
                {
                        continueToOriginalDestination();
                        // if we reach this line there was no intercept page, so go to home page
                        setResponsePage(WelcomePage.class);
                }
        }
 });
        See Also:
        redirectToInterceptPage(Page)

      • clearOriginalDestination

        public final void clearOriginalDestination()
        Clears any data about previously intercepted page.

      • debug

        public final void debug​(Serializable message)
        Registers a debug feedback message for this component
        Specified by:
        debug in interface IFeedbackContributor
        Parameters:
        message - The feedback message

      • detach

        public final void detach()
        Detaches the component. This is called at the end of the request for all the pages that are touched in that request.
        Specified by:
        detach in interface IRequestableComponent

      • detachModels

        public void detachModels()
        Detaches all models

      • error

        public final void error​(Serializable message)
        Registers an error feedback message for this component
        Specified by:
        error in interface IFeedbackContributor
        Parameters:
        message - The feedback message

      • fatal

        public final void fatal​(Serializable message)
        Registers a fatal feedback message for this component
        Specified by:
        fatal in interface IFeedbackContributor
        Parameters:
        message - The feedback message

      • findParent

        public final <Z> Z findParent​(Class<Z> c)
        Finds the first container parent of this component of the given class.
        Type Parameters:
        Z - type of parent
        Parameters:
        c - MarkupContainer class to search for
        Returns:
        First container parent that is an instance of the given class, or null if none can be found

      • getApplication

        public final Application getApplication()
        Gets interface to application that this component is a part of.
        Returns:
        The application associated with the session that this component is in.
        See Also:
        Application

      • createConverter

        protected IConverter<?> createConverter​(Class<?> type)
        Factory method for converters to be used by this component, returns null by default.
        Parameters:
        type - The type to convert to
        Returns:
        a converter to be used by this component

      • getEscapeModelStrings

        public final boolean getEscapeModelStrings()
        Gets whether model strings should be escaped.
        Returns:
        Returns whether model strings should be escaped

      • getLocale

        public Locale getLocale()
        Gets the locale for this component. By default, it searches its parents for a locale. If no parents (it's a recursive search) returns a locale, it gets one from the session.
        Returns:
        The locale to be used for this component
        See Also:
        Session.getLocale()

      • getLocalizer

        public final Localizer getLocalizer()
        Convenience method to provide easy access to the localizer object within any component.
        Returns:
        The localizer object

      • getMarkupTag

        protected final ComponentTag getMarkupTag()
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT! Get the first component tag in the associated markup
        Returns:
        first component tag

      • getMarkupAttributes

        public final ValueMap getMarkupAttributes()
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT! Get a copy of the markup's attributes which are associated with the component.

        Modifications to the map returned don't change the tags attributes. It is just a copy.

        Note: The component must have been added (directly or indirectly) to a container with an associated markup file (Page, Panel or Border).

        Returns:
        markup attributes

      • getMarkupId

        public String getMarkupId​(boolean createIfDoesNotExist)
        Retrieves id by which this component is represented within the markup. This is either the id attribute set explicitly via a call to setMarkupId(String), id attribute defined in the markup, or an automatically generated id - in that order.

        If no id is set and createIfDoesNotExist is false, this method will return null. Otherwise it will generate an id value which by default will be unique in the page. This is the preferred way as there is no chance of id collision. This will also enable setOutputMarkupId(boolean).

        Note: This method should only be called after the component or its parent have been added to the page.

        Parameters:
        createIfDoesNotExist - When there is no existing markup id, determines whether it should be generated or whether null should be returned.
        Returns:
        markup id of the component

      • getMarkupId

        public String getMarkupId()
        Retrieves id by which this component is represented within the markup. This is either the id attribute set explicitly via a call to setMarkupId(String), id attribute defined in the markup, or an automatically generated id - in that order.

        If no explicit id is set this function will generate an id value that will be unique in the page. This is the preferred way as there is no chance of id collision. This will also enable setOutputMarkupId(boolean).

        Note: This method should only be called after the component or its parent have been added to the page.

        Returns:
        markup id of the component

      • getDefaultModel

        public final IModel<?> getDefaultModel()
        Gets the model. It returns the object that wraps the backing model.
        Returns:
        The model

      • getDefaultModelObject

        public final Object getDefaultModelObject()
        Gets the backing model object. Unlike getDefaultModel().getObject(), this method returns null for a null model.
        Returns:
        The backing model object

      • getOutputMarkupId

        public final boolean getOutputMarkupId()
        Gets whether or not component will output id attribute into the markup. id attribute will be set to the value returned from getMarkupId().
        Returns:
        whether or not component will output id attribute into the markup

      • getOutputMarkupPlaceholderTag

        public final boolean getOutputMarkupPlaceholderTag()
        Gets whether or not an invisible component will render a placeholder tag.
        Returns:
        true if a placeholder tag should be rendered

      • getPath

        public final String getPath()
        Gets this component's path.
        Returns:
        Colon separated path to this component in the component hierarchy

      • getRenderBodyOnly

        public final boolean getRenderBodyOnly()
        If false the component's tag will be printed as well as its body (which is default). If true only the body will be printed, but not the component's tag.
        Returns:
        If true, the component tag will not be printed

      • getRequest

        public final Request getRequest()
        Returns:
        The request for this component's active request cycle

      • getRequestCycle

        public final RequestCycle getRequestCycle()
        Gets the active request cycle for this component
        Returns:
        The request cycle

      • getResponse

        public final Response getResponse()
        Returns:
        The response for this component's active request cycle

      • getSession

        public Session getSession()
        Gets the current Session object.
        Returns:
        The Session that this component is in

      • getSizeInBytes

        public long getSizeInBytes()
        Returns:
        Size of this Component in bytes. Returns 0 - if the size cannot be calculated for some reason

      • getString

        public final String getString​(String key)
        Parameters:
        key - Key of string resource in property file
        Returns:
        The String
        See Also:
        Localizer

      • getString

        public final String getString​(String key,
                              IModel<?> model)
        Parameters:
        key - The resource key
        model - The model
        Returns:
        The formatted string
        See Also:
        Localizer

      • getString

        public final String getString​(String key,
                              IModel<?> model,
                              String defaultValue)
        Parameters:
        key - The resource key
        model - The model
        defaultValue - A default value if the string cannot be found
        Returns:
        The formatted string
        See Also:
        Localizer

      • getStyle

        public final String getStyle()
        A convenience method to access the Sessions's style.
        Returns:
        The style of this component respectively the style of the Session.
        See Also:
        Session.getStyle()

      • getVariation

        public String getVariation()
        Gets the variation string of this component that will be used to look up markup for this component. Subclasses can override this method to define by an instance what markup variation should be picked up. By default it will return null or the value of a parent.
        Returns:
        The variation of this component.

      • hasBeenRendered

        public final boolean hasBeenRendered()
        Gets whether this component was rendered at least once.
        Returns:
        true if the component has been rendered before, false if it is merely constructed

      • hasErrorMessage

        public final boolean hasErrorMessage()
        Returns:
        True if this component has an error message

      • hasFeedbackMessage

        public final boolean hasFeedbackMessage()
        Returns:
        True if this component has some kind of feedback message

      • info

        public final void info​(Serializable message)
        Registers an informational feedback message for this component
        Specified by:
        info in interface IFeedbackContributor
        Parameters:
        message - The feedback message

      • isActionAuthorized

        public final boolean isActionAuthorized​(Action action)
        Authorizes an action for a component.
        Parameters:
        action - The action to authorize
        Returns:
        True if the action is allowed
        Throws:
        AuthorizationException - Can be thrown by implementation if action is unauthorized

      • isEnableAllowed

        public final boolean isEnableAllowed()
        Returns:
        true if this component is authorized to be enabled, false otherwise

      • isEnabled

        public boolean isEnabled()
        Gets whether this component is enabled. Specific components may decide to implement special behavior that uses this property, like web form components that add a disabled='disabled' attribute when enabled is false.
        Returns:
        Whether this component is enabled.

      • isRenderAllowed

        public final boolean isRenderAllowed()
        Checks the security strategy if the RENDER action is allowed on this component
        Returns:
        true if RENDER action is allowed, false otherwise

      • isStateless

        public final boolean isStateless()
        Returns if the component is stateless or not. It checks the stateless hint if that is false it returns directly false. If that is still true it checks all its behaviors if they can be stateless.
        Returns:
        whether the component is stateless.

      • isVersioned

        public boolean isVersioned()
        Returns:
        true if this component should notify its holding page about changes in its state. If a Page is not versioned then it wont track changes in its components and will use the same Page.getPageId() during its lifetime

      • isVisible

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

        WARNING: this method can be called multiple times during a request. If you override this method, it is a good idea to keep it cheap in terms of processing. Alternatively, you can call setVisible(boolean).

        Returns:
        True if component and any children are visible

      • isVisibleInHierarchy

        public final boolean isVisibleInHierarchy()
        Checks if the component itself and all its parents are visible.
        Returns:
        true if the component and all its parents are visible.

      • markRendering

        public final void markRendering​(boolean setRenderingFlag)
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT! Sets the RENDERING flag and removes the PREPARED_FOR_RENDER flag on component and it's children.
        Parameters:
        setRenderingFlag - if this is false only the PREPARED_FOR_RENDER flag is removed from component, the RENDERING flag is not set.

      • modelChanged

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

      • modelChanging

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

      • remove

        public final void remove()
        Removes this component from its parent. It's important to remember that a component that is removed cannot be referenced from the markup still.

        You must not use this method in your callback to any of the MarkupContainer.visitChildren(IVisitor) methods. See WICKET-3329.

      • renderPart

        public final void renderPart()
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT!

        Renders this component as a part of a response - the caller has to make sure that this component is prepared for render.

        See Also:
        beforeRender()

      • render

        public final void render()
        Render this component and all its children. Always calls hook onAfterRender() regardless of any exception.

      • getAjaxRegionMarkupId

        public final String getAjaxRegionMarkupId()
        Returns the id of the markup region that will be updated via ajax. This can be different to the markup id of the component if a IAjaxRegionMarkupIdProvider behavior has been added.
        Returns:
        the markup id of the region to be updated via ajax.

      • internalRenderComponent

        protected final void internalRenderComponent()
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT!

        Renders the component at the current position in the given markup stream. The method onComponentTag() is called to allow the component to mutate the start tag. The method onComponentTagBody() is then called to permit the component to render its body.

      • rendered

        public final void rendered()
        Called to indicate that a component has been rendered. This method should only very rarely be called at all. Some components may render its children without calling render() on them. These components need to call rendered() to indicate that its child components were actually rendered, the framework would think they had never been rendered, and in development mode this would result in a runtime exception.

      • newMarkupSourcingStrategy

        protected IMarkupSourcingStrategy newMarkupSourcingStrategy()
        If getMarkupSourcingStrategy() returns null, this method will be called. By default it returns null, which means that a default markup strategy will be attached to the component.

        Please note that markup source strategies are not persisted. Instead they get re-created by calling this method again. That's ok since markup sourcing strategies usually do not maintain a state.

        Returns:
        Markup sourcing strategy

      • replaceWith

        public Component replaceWith​(Component replacement)
        Replaces this component with another. The replacing component must have the same component id as this component. This method serves as a shortcut to this.getParent().replace(replacement) and provides a better context for errors.

        Usage: component = component.replaceWith(replacement);

        Parameters:
        replacement - component to replace this one
        Returns:
        the component which replaced this one
        Since:
        1.2.1

      • sameInnermostModel

        public final boolean sameInnermostModel​(Component component)
        Parameters:
        component - The component to compare with
        Returns:
        True if the given component's model is the same as this component's model.

      • sameInnermostModel

        public final boolean sameInnermostModel​(IModel<?> model)
        Parameters:
        model - The model to compare with
        Returns:
        True if the given component's model is the same as this component's model.

      • setEnabled

        public final Component setEnabled​(boolean enabled)
        Sets whether this component is enabled. Specific components may decide to implement special behavior that uses this property, like web form components that add a disabled='disabled' attribute when enabled is false. If it is not enabled, it will not be allowed to call any listener method on it (e.g. Link.onClick) and the model object will be protected (for the common use cases, not for programmer's misuse)
        Parameters:
        enabled - whether this component is enabled
        Returns:
        This

      • setEscapeModelStrings

        public final Component setEscapeModelStrings​(boolean escapeMarkup)
        Sets whether model strings should be escaped.
        Parameters:
        escapeMarkup - True is model strings should be escaped
        Returns:
        This

      • setMarkupIdImpl

        public final void setMarkupIdImpl​(Object markupId)
        Set markup ID, which must be String or Integer
        Parameters:
        markupId -

      • setMarkupId

        public Component setMarkupId​(String markupId)
        Sets this component's markup id to a user defined value. It is up to the user to ensure this value is unique.

        The recommended way is to let wicket generate the value automatically, this method is here to serve as an override for that value in cases where a specific id must be used.

        If null is passed in the user defined value is cleared and markup id value will fall back on automatically generated value

        Parameters:
        markupId - markup id value or null to clear any previous user defined value
        Returns:
        this for chaining
        See Also:
        getMarkupId()

      • setDefaultModel

        public Component setDefaultModel​(IModel<?> model)
        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.

        Parameters:
        model - The model
        Returns:
        This

      • setDefaultModelObject

        public final Component setDefaultModelObject​(Object object)
        Sets the backing model object. Unlike getDefaultModel().setObject(object), this method checks authorisation and model comparator, and invokes modelChanging and modelChanged if the value really changes.
        Parameters:
        object - The object to set
        Returns:
        This
        Throws:
        IllegalStateException - If the component has neither its own model nor any of its parents uses IComponentInheritedModel

      • setOutputMarkupId

        public final Component setOutputMarkupId​(boolean output)
        Sets whether or not component will output id attribute into the markup. id attribute will be set to the value returned from getMarkupId().
        Parameters:
        output - True if the component will output the id attribute into markup. Please note that the default behavior is to use the same id as the component. This means that your component must begin with [a-zA-Z] in order to generate a valid markup id according to: http://www.w3.org/TR/html401/types.html#type-name
        Returns:
        this for chaining

      • setOutputMarkupPlaceholderTag

        public final Component setOutputMarkupPlaceholderTag​(boolean outputTag)
        Render a placeholder tag when the component is not visible. The tag is of form: <componenttag hidden="" id="markupid"/>. This method will also call setOutputMarkupId(true). This is useful, for example, in ajax situations where the component starts out invisible and then becomes visible through an ajax update. With a placeholder tag already in the markup you do not need to repaint this component's parent, instead you can repaint the component directly. When this method is called with parameter false the outputmarkupid flag is not reverted to false.
        Parameters:
        outputTag -
        Returns:
        this for chaining

      • setRenderBodyOnly

        public final Component setRenderBodyOnly​(boolean renderTag)
        If false the component's tag will be printed as well as its body (which is default). If true only the body will be printed, but not the component's tag.
        Parameters:
        renderTag - If true, the component tag will not be printed
        Returns:
        This

      • setVersioned

        public Component setVersioned​(boolean versioned)
        Parameters:
        versioned - True to turn on versioning for this component, false to turn it off for this component and any children.
        Returns:
        This

      • setVisible

        public final Component setVisible​(boolean visible)
        Sets whether this component and any children are visible.
        Parameters:
        visible - True if this component and any children should be visible
        Returns:
        This

      • toString

        public String toString()
        Gets the string representation of this component.
        Overrides:
        toString in class Object
        Returns:
        The path to this component

      • toString

        public String toString​(boolean detailed)
        Parameters:
        detailed - True if a detailed string is desired
        Returns:
        The string

      • visitParents

        public final <R,​C extends MarkupContainer> R visitParents​(Class<C> parentClass,
                                                                IVisitor<C,​R> visitor)
        Traverses all parent components of the given class in this parentClass, calling the visitor's visit method at each one.
        Type Parameters:
        R - the type of the result object
        Parameters:
        parentClass - Class
        visitor - The visitor to call at each parent of the given type
        Returns:
        First non-null value returned by visitor callback

      • visitParents

        public final <R,​C extends MarkupContainer> R visitParents​(Class<C> parentClass,
                                                                IVisitor<C,​R> visitor,
                                                                IVisitFilter filter)
        Traverses all parent components of the given class in this parentClass, calling the visitor's visit method at each one.
        Type Parameters:
        R - the type of the result object
        Parameters:
        parentClass - the class of the parent component
        visitor - The visitor to call at each parent of the given type
        filter - a filter that adds an additional logic to the condition whether a parent container matches
        Returns:
        First non-null value returned by visitor callback

      • warn

        public final void warn​(Serializable message)
        Registers a warning feedback message for this component.
        Specified by:
        warn in interface IFeedbackContributor
        Parameters:
        message - The feedback message

      • addStateChange

        protected final void addStateChange()
        TODO WICKET-NG rename to something more useful - like componentChanged(), this method used to be called with a Change object Adds state change to page.

      • checkComponentTag

        protected final void checkComponentTag​(ComponentTag tag,
                                       String name)
        Checks whether the given type has the expected name.
        Parameters:
        tag - The tag to check
        name - The expected tag name
        Throws:
        MarkupException - Thrown if the tag is not of the right name

      • checkComponentTagAttribute

        protected final void checkComponentTagAttribute​(ComponentTag tag,
                                                String key,
                                                String... values)
        Checks that a given tag has a required attribute value.
        Parameters:
        tag - The tag
        key - The attribute key
        values - The required value for the attribute key
        Throws:
        MarkupException - Thrown if the tag does not have the required attribute value

      • checkHierarchyChange

        protected void checkHierarchyChange​(Component component)
        Checks whether the hierarchy may be changed at all, and throws an exception if this is not the case.
        Parameters:
        component - the component which is about to be added or removed

      • detachModel

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

      • exceptionMessage

        protected final String exceptionMessage​(String message)
        Suffixes an exception message with useful information about this. component.
        Parameters:
        message - The message
        Returns:
        The modified message

      • findMarkupStream

        protected final MarkupStream findMarkupStream()
        Finds the markup stream for this component.
        Returns:
        The markup stream for this component. Since a Component cannot have a markup stream, we ask this component's parent to search for it.

      • findPage

        protected final Page findPage()
        If this Component is a Page, returns self. Otherwise, searches for the nearest Page parent in the component hierarchy. If no Page parent can be found, null is returned.
        Returns:
        The Page or null if none can be found

      • getBehaviors

        public <M extends Behavior> List<M> getBehaviors​(Class<M> type)
        Gets the subset of the currently coupled Behaviors that are of the provided type as an unmodifiable list. Returns an empty list if there are no behaviors coupled to this component.
        Type Parameters:
        M - A class derived from Behavior
        Parameters:
        type - The type or null for all
        Returns:
        The subset of the currently coupled behaviors that are of the provided type as an unmodifiable list

      • getFlag

        protected final boolean getFlag​(int flag)
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT!
        Parameters:
        flag - The flag to test
        Returns:
        True if the flag is set

      • getRequestFlag

        protected final boolean getRequestFlag​(short flag)
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT!
        Parameters:
        flag - The flag to test
        Returns:
        True if the flag is set

      • getInnermostModel

        protected final IModel<?> getInnermostModel​(IModel<?> model)
        Finds the innermost IModel object for an IModel that might contain nested IModel(s).
        Parameters:
        model - The model
        Returns:
        The innermost (most nested) model

      • getModelComparator

        public IModelComparator getModelComparator()
        Gets the component's current model comparator. Implementations can be used for testing the current value of the components model data with the new value that is given.
        Returns:
        the value defaultModelComparator

      • getStatelessHint

        protected boolean getStatelessHint()
        Returns whether the component can be stateless. Also the component behaviors must be stateless, otherwise the component will be treat as stateful. In order for page to be stateless (and not to be stored in session), all components (and component behaviors) must be stateless.
        Returns:
        whether the component can be stateless

      • internalOnModelChanged

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

        Called anytime a model is changed via setModel or setModelObject.

      • isBehaviorAccepted

        protected boolean isBehaviorAccepted​(Behavior behavior)
        Components are allowed to reject behavior modifiers.
        Parameters:
        behavior -
        Returns:
        False, if the component should not apply this behavior

      • isIgnoreAttributeModifier

        protected final boolean isIgnoreAttributeModifier()
        If true, all attribute modifiers will be ignored
        Returns:
        True, if attribute modifiers are to be ignored

      • onAfterRender

        protected void onAfterRender()
        Called immediately after a component and all its children have been rendered, regardless of any exception.

      • onBeforeRender

        protected void onBeforeRender()
        Called on all visible components before any component is rendered.

        NOTE: If you override this, you *must* call super.onBeforeRender() within your implementation. Because this method is responsible for cascading onBeforeRender() call to its children it is strongly recommended that super call is made at the end of the override.

        Changes to the component tree can be made only before calling super.onBeforeRender().
        See Also:
        MarkupContainer.addOrReplace(Component...)

      • onComponentTag

        protected void onComponentTag​(ComponentTag tag)
        Processes the component tag. Overrides of this method most likely should call the super implementation.
        Parameters:
        tag - Tag to modify

      • onDetach

        protected void onDetach()
        Called to allow a component to detach resources after use. Overrides of this method MUST call the super implementation, the most logical place to do this is the last line of the override method.

      • onRemove

        protected void onRemove()
        Called to notify the component it is being removed from the component hierarchy Overrides of this method MUST call the super implementation, the most logical place to do this is the last line of the override method.

      • onModelChanged

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

      • onModelChanging

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

      • onRender

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

      • renderComponentTag

        protected final void renderComponentTag​(ComponentTag tag)
        Writes a simple tag out to the response stream. Any components that might be referenced by the tag are ignored. Also undertakes any tag attribute modifications if they have been added to the component.
        Parameters:
        tag - The tag to write

      • setAuto

        protected final Component setAuto​(boolean auto)
        Parameters:
        auto - True to put component into auto-add mode

      • setFlag

        protected final Component setFlag​(int flag,
                                  boolean set)
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT!
        Parameters:
        flag - The flag to set
        set - True to turn the flag on, false to turn it off

      • setIgnoreAttributeModifier

        protected final Component setIgnoreAttributeModifier​(boolean ignore)
        If true, all attribute modifiers will be ignored
        Parameters:
        ignore - If true, all attribute modifiers will be ignored
        Returns:
        This

      • wrap

        protected final <V> IModel<V> wrap​(IModel<V> model)
        Type Parameters:
        V - The model type
        Parameters:
        model - The model to wrap if need be
        Returns:
        The wrapped model

      • get

        public Component get​(String path)
        Gets the component at the given path.
        Specified by:
        get in interface IRequestableComponent
        Parameters:
        path - Path to component
        Returns:
        The component at the path

      • isAuto

        public final boolean isAuto()
        Returns:
        True if this component or any of its parents is in auto-add mode

      • setParent

        public final void setParent​(MarkupContainer parent)
        THIS IS A WICKET INTERNAL API. DO NOT USE IT. Sets the parent of a component. Typically what you really want is parent.add(child).

        Note that calling setParent() and not parent.add() will connect the child to the parent, but the parent will not know the child. This might not be a problem in some cases, but e.g. child.onDetach() will not be invoked (since the parent doesn't know it is his child).

        Parameters:
        parent - The parent container

      • isVisibilityAllowed

        public final boolean isVisibilityAllowed()
        Gets whether or not visibility is allowed on this component. See setVisibilityAllowed(boolean) for details.
        Returns:
        true if this component is allowed to be visible, false otherwise.

      • isEnabledInHierarchy

        public boolean isEnabledInHierarchy()
        Calculates enabled state of the component taking its hierarchy into account. A component is enabled iff it is itself enabled (isEnabled() and isEnableAllowed() both return true), and all of its parents are enabled.
        Returns:
        true if this component is enabled

      • isRendering

        public final boolean isRendering()
        Says if the component is rendering currently.
        Returns:
        true if this component is rendering, false otherwise.

      • canCallListener

        public boolean canCallListener()
        Checks whether or not an IRequestListener can be invoked on this component. Usually components deny these invocations if they are either invisible or disabled in hierarchy.

        WARNING: be careful when overriding this method because it may open security holes - such as allowing a user to click on a link that should be disabled.

        Example usecase for overriding: Suppose you are building an component that displays images. The component generates a callback to itself using IRequestListener interface and uses this callback to stream image data. If such a component is placed inside a disabled WebMarkupContainer we still want to allow the invocation of the request listener callback method so that image data can be streamed. Such a component would override this method and return true.

        Returns:
        true iff the listener method can be invoked on this component

      • send

        public final <T> void send​(IEventSink sink,
                           Broadcast type,
                           T payload)
        Sends an event
        Specified by:
        send in interface IEventSource
        Type Parameters:
        T - type of payload
        Parameters:
        sink - object that will receive the event
        type - if the object that receives the event needs to broadcast it to others, this is the type of broadcast that should be used
        payload - event payload

      • remove

        public Component remove​(Behavior... behaviors)
        Removes behavior from component
        Parameters:
        behaviors - behaviors to remove
        Returns:
        this (to allow method call chaining)

      • getBehaviorId

        public final int getBehaviorId​(Behavior behavior)
        Gets a stable id for the specified non-temporary behavior. The id remains stable from the point this method is first called for the behavior until the behavior has been removed from the component. This includes from one request to the next, when the component itself is retained for the next request (i.e. is stateful). Note that the bookkeeping required for these stable ids increases the memory footprint of the component.
        Specified by:
        getBehaviorId in interface IRequestableComponent
        Returns:
        a stable id for the specified behavior

      • add

        public Component add​(Behavior... behaviors)
        Adds a behavior modifier to the component.
        Parameters:
        behaviors - The behavior modifier(s) to be added
        Returns:
        this (to allow method call chaining)

      • getBehaviors

        public final List<? extends Behavior> getBehaviors()
        Gets the currently coupled Behaviors as an unmodifiable list. Returns an empty list rather than null if there are no behaviors coupled to this component.
        Returns:
        The currently coupled behaviors as an unmodifiable list

      • onReAdd

        protected void onReAdd()
        This method is called whenever a component is re-added to the page's component tree, if it had been removed at some earlier time, i.e., if it is already initialized (see isInitialized()). This is similar to onInitialize, but only comes after the component has been removed and then added again:
        • onInitialize is only called the very first time a component is added
        • onReAdd is not called the first time, but every time it is re-added after having been removed
        You can think of it as the opposite of onRemove. A component that was once removed will not be re-initialized but only re-added. Subclasses that override this must call super.onReAdd().