You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by so...@apache.org on 2018/01/22 03:22:19 UTC
[4/5] wicket git commit: WICKET-6503 update component lifecycle
WICKET-6503 update component lifecycle
Project: http://git-wip-us.apache.org/repos/asf/wicket/repo
Commit: http://git-wip-us.apache.org/repos/asf/wicket/commit/eb9f6c9c
Tree: http://git-wip-us.apache.org/repos/asf/wicket/tree/eb9f6c9c
Diff: http://git-wip-us.apache.org/repos/asf/wicket/diff/eb9f6c9c
Branch: refs/heads/WICKET-6518-quickstart-logback
Commit: eb9f6c9cf3f5b644f9107558751cc38c0a47abc8
Parents: 1617e2b
Author: Sven Meier <sv...@apache.org>
Authored: Fri Jan 19 16:54:19 2018 +0100
Committer: Sven Meier <sv...@apache.org>
Committed: Fri Jan 19 16:54:36 2018 +0100
----------------------------------------------------------------------
.../componentLifecycle_1.adoc | 11 +++++----
.../componentLifecycle_2.adoc | 9 ++++----
.../componentLifecycle_3.adoc | 6 +++--
.../componentLifecycle_4.adoc | 23 +++++++++++++++----
.../componentLifecycle_5.adoc | 6 ++---
.../componentLifecycle_6.adoc | 3 ++-
.../componentLifecycle_7.adoc | 5 ++++
.../main/asciidoc/img/component-lifecycle.png | Bin 10587 -> 34960 bytes
wicket-user-guide/src/main/asciidoc/single.adoc | 8 +++++--
9 files changed, 49 insertions(+), 22 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/wicket/blob/eb9f6c9c/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_1.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_1.adoc
index bc38266..a2c778a 100644
--- a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_1.adoc
+++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_1.adoc
@@ -1,17 +1,18 @@
-During its life a Wicket component goes through three basic stages:
+During its life a Wicket component goes through the following stages:
-1. *Initialization:* a component is instantiated by Wicket and prepared for the rendering phase.
-2. *Rendering:* in this stage Wicket generates component markup. If a component contains children (i.e. is a subclass of _MarkupContainer_) it must first wait for them to be rendered before starting its own rendering.
-3. *Removing:* this stage is triggered when a component is explicitly removed from its component hierarchy, i.e. when its parent invokes _remove(component)_ on it. This stage is facultative and is never triggered for pages.
+1. *Initialization:* a component is instantiated and initialized by Wicket.
+2. *Rendering:* components are prepared for rendering and generate markup. If a component contains children (i.e. is a subclass of _MarkupContainer_) their rendering result is included in the resulting markup.
+3. *Removed:* this stage is triggered when a component is explicitly removed from its component hierarchy, i.e. when its parent invokes _remove(component)_ on it. This stage is facultative and is never triggered for pages.
+3. *Detached:* after request processing has ended all components are notified to detach any state that is no longer needed.
The following picture shows the state diagram of component lifecycle:
image::../img/component-lifecycle.png[]
-Once a component has been removed it can be added again to a container, but the initialization stage won't be executed again.
+Once a component has been removed it could be added again to a container, but the initialization stage won't be executed again - it is easier to just create a new component instance instead.
NOTE: If you read the JavaDoc of class _Component_ you will find a more detailed description of component lifecycle.
However this description introduces some advanced topics we didn't covered yet hence, to avoid confusion, in this chapter some details have been omitted and they will be covered later in the next chapters.
http://git-wip-us.apache.org/repos/asf/wicket/blob/eb9f6c9c/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_2.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_2.adoc
index 7eda2e2..0224dbd 100644
--- a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_2.adoc
+++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_2.adoc
@@ -6,9 +6,10 @@ In the following table these methods are grouped according to the stage in which
|===
|*Cycle stage* | *Involved methods*
-|Initialization | onInitialize
-|Rendering | onConfigure, onBeforeRender, onRender, onComponentTag, onComponentTagBody, onAfterRenderChildren, onAfterRender
-|Removing | onRemove
+|Initialization | constructor, onInitialize()
+|Rendering | onConfigure(), onBeforeRender(), renderHead(), onRender(), onComponentTag(), onComponentTagBody(), onAfterRender()
+|Removed | onRemove()
+|Detached | onDetach()
|===
-Now let's take a closer look at each stage and to at hook methods.
+Now let's take a closer look at each stage and its hook methods.
http://git-wip-us.apache.org/repos/asf/wicket/blob/eb9f6c9c/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_3.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_3.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_3.adoc
index cb6593b..5c7a6cd 100644
--- a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_3.adoc
+++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_3.adoc
@@ -1,6 +1,8 @@
-This stage is performed at the beginning of the component lifecycle. During initialization, the component has already been inserted into its component hierarchy so we can safely access to its parent container or to its page with methods _getParent()_ or _getPage()_. The only method triggered during this stage is _onInitialize()_. This method is a sort of “special” constructor where we can execute a custom initialization of our component.
+This stage is the beginning of the component lifecycle.
-Since _onInitialize_ is similar to a regular constructor, when we override this method we have to call _super.onInitialize_ inside its body, usually as first instruction.
+A component is instantiated by application code (or by Wicket in case of bookmarkable page) and added to a parental component. As soon as the component is contained in a component tree rooted in a page, a “post”-constructor _onInitialize()_ is called where we can execute custom initialization of our component.
+
+When we override this method we have to call _super.onInitialize()_, usually before anything else in that method.
http://git-wip-us.apache.org/repos/asf/wicket/blob/eb9f6c9c/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc
index a5425d8..4cdd672 100644
--- a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc
+++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc
@@ -1,15 +1,17 @@
-This stage is triggered each time a component is rendered by Wicket, typically when its page is requested or when it is refreshed via AJAX.
+This stage is reached each time a component is rendered, typically when a page is requested or when the component or one of its ancestors is refreshed via AJAX.
=== Method onConfigure
-Method _onConfigure()_ has been introduced in order to provide a good point to manage the component states such as its visibility or enabled state. This method is called before the render phase starts. As stated in <<_hiding_or_disabling_a_component,chapter 6.1>>, _isVisible_ and _isEnabled_ are called multiple times when a page or a component is rendered, so it's highly recommended not to directly override these method, but rather to use _onConfigure_ to change component states. On the contrary method _onBeforeRender_ (see the next paragraph) is not indicated for this task because it will not be invoked if component visibility is set to false.
+Method _onConfigure()_ has been introduced in order to provide a good point to manage the component states such as its visibility or enabled state. This method is called an all components whose parent is visible.
+
+As stated in <<_hiding_or_disabling_a_component,chapter 6.1>>, _isVisible()_ and _isEnabled()_ are called multiple times when a page or a component is rendered, so it's highly recommended not to directly override these method, but rather to use _onConfigure()_ to change component states. On the contrary method _onBeforeRender_ (see the next paragraph) is not indicated for this task because it will not be invoked if component visibility is set to false.
=== Method onBeforeRender
-The most important hook method of this stage is probably _onBeforeRender()_. This method is called before a component starts its rendering phase and it is our last chance to change its children hierarchy.
+The most important hook method of this stage is probably _onBeforeRender()_. This method is called on all visible components before any of them are rendered. It is our last chance to change a component's state prior to rendering - no change to a component's state is allowed afterwards.
-If we want add/remove children components this is the right place to do it. In the next example (project LifeCycleStages) we will create a page which alternately displays two different labels, swapping between them each time it is rendered:
+If we want to add/remove child components this is the right place to do it. In the next example (project LifeCycleStages) we will create a page which alternately displays two different labels, swapping between them each time it is rendered:
[source,java]
----
@@ -51,10 +53,17 @@ Please note that in the example above we can trigger the rendering stage pressin
WARNING: If we forget to call superclass version of methods _onInitialize()_ or _onBeforeRender()_, Wicket will throw an _IllegalStateException_ with the following message: +
`_java.lang.IllegalStateException: org.apache.wicket.Component has not been properly initialized. Something in the hierarchy of <page class name> has not called super.onInitialize()/onBeforeRender() in the override of onInitialize()/ onBeforeRender() method_`
+=== Method renderHead
+
+This method gives all components the possibility to add items to the page header through its argument of type _org.apache.wicket.markup.head.IHeaderResponse_
+
+=== Method onRender
+
+This method does the actual rendering - you will rarely have to implement it, since most components already contain a specific implementation to produce their markup.
=== Method onComponentTag
-Method _onComponentTag(ComponentTag)_ is called to process component tag, which can be freely manipulated through its argument of type _org.apache.wicket.markup.ComponentTag_. For example we can add/remove tag attributes with methods _put(String key, String value)_ and _remove(String key)_, or we can even decide to change the tag or rename it with method _setName(String)_ (the following code is taken from project OnComponentTagExample):
+Method _onComponentTag(ComponentTag)_ is called to process a component tag, which can be freely manipulated through its argument of type _org.apache.wicket.markup.ComponentTag_. For example we can add/remove tag attributes with methods _put(String key, String value)_ and _remove(String key)_, or we can even decide to change the tag or rename it with method _setName(String)_ (the following code is taken from project OnComponentTagExample):
*Markup code:*
@@ -132,3 +141,7 @@ public class HomePage extends WebPage {
----
Note that the original version of _onComponentTagBody_ is invoked only when we want to preserve the standard rendering mechanism for the tag's body (in our example this happens when the component is enabled).
+
+=== Methods onAfterRender
+
+Called on each rendered component immediately after it has been rendered - _onAfterRender()_ will even be called when rendering failed with an exception.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/eb9f6c9c/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_5.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_5.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_5.adoc
index 5f13e16..c08351b 100644
--- a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_5.adoc
+++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_5.adoc
@@ -1,8 +1,8 @@
-This stage is triggered when a component is removed from its container hierarchy. The only hook method for this phase is _onRemove()_. If our component still holds some resources needed during rendering phase, we can override this method to release them.
+This stage is entered when a component is removed from its container hierarchy. The only hook method for this phase is _onRemove()_. If our component still holds some resources needed during rendering phase, we can override this method to release them.
-Once a component has been removed we are free to add it again to the same container or to a different one. Starting from version 6.18.0 Wicket added a further hook method called _onReAdd()_ which is triggered every time a previously removed component is re-added to a cointainer.
-Please note that while _onInitialize_ is called only the very first time a component is added, _onReAdd_ is called every time it is re-added after having been removed.
+Once a component has been removed we are free to add it again to the same container or to a different one. Starting from version 6.18.0 Wicket added a further hook method called _onReAdd()_ which is triggered every time a previously removed component is re-added to a container.
+Please note that while _onInitialize()_ is called only the very first time a component is added, _onReAdd()_ is called every time it is re-added after having been removed.
http://git-wip-us.apache.org/repos/asf/wicket/blob/eb9f6c9c/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_6.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_6.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_6.adoc
index 50fbb17..ff1da28 100644
--- a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_6.adoc
+++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_6.adoc
@@ -1,5 +1,6 @@
-In this chapter we have seen which stages compose the lifecycle of Wicket components and which hook methods they provide. Overriding these methods we can dynamically modify the component hierarchy and we can enrich the behavior of our custom components.
+When a request has finished, the page and all its contained components move a the detached stage:
+The hook method _onDetach()_ notifies each component that it should release all held resources no longer needed until the next request.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/eb9f6c9c/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_7.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_7.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_7.adoc
new file mode 100644
index 0000000..50fbb17
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_7.adoc
@@ -0,0 +1,5 @@
+
+
+
+In this chapter we have seen which stages compose the lifecycle of Wicket components and which hook methods they provide. Overriding these methods we can dynamically modify the component hierarchy and we can enrich the behavior of our custom components.
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/eb9f6c9c/wicket-user-guide/src/main/asciidoc/img/component-lifecycle.png
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/img/component-lifecycle.png b/wicket-user-guide/src/main/asciidoc/img/component-lifecycle.png
index 52e09fd..601639a 100644
Binary files a/wicket-user-guide/src/main/asciidoc/img/component-lifecycle.png and b/wicket-user-guide/src/main/asciidoc/img/component-lifecycle.png differ
http://git-wip-us.apache.org/repos/asf/wicket/blob/eb9f6c9c/wicket-user-guide/src/main/asciidoc/single.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/single.adoc b/wicket-user-guide/src/main/asciidoc/single.adoc
index 4fc1464..0974694 100644
--- a/wicket-user-guide/src/main/asciidoc/single.adoc
+++ b/wicket-user-guide/src/main/asciidoc/single.adoc
@@ -153,14 +153,18 @@ include::componentLifecycle/componentLifecycle_3.adoc[leveloffset=+1]
include::componentLifecycle/componentLifecycle_4.adoc[leveloffset=+1]
-=== Removing stage
+=== Removed stage
include::componentLifecycle/componentLifecycle_5.adoc[leveloffset=+1]
-=== Summary
+=== Detached stage
include::componentLifecycle/componentLifecycle_6.adoc[leveloffset=+1]
+=== Summary
+
+include::componentLifecycle/componentLifecycle_7.adoc[leveloffset=+1]
+
== Page versioning and caching
include::versioningCaching.adoc[]