Repository: wicket
Updated Branches:
  refs/heads/wicket-7.x 200c7f34f -> 47bc8a8d7


Documentaion for  events infrastructure has been moved to its own paragraph


Project: http://git-wip-us.apache.org/repos/asf/wicket/repo
Commit: http://git-wip-us.apache.org/repos/asf/wicket/commit/47bc8a8d
Tree: http://git-wip-us.apache.org/repos/asf/wicket/tree/47bc8a8d
Diff: http://git-wip-us.apache.org/repos/asf/wicket/diff/47bc8a8d

Branch: refs/heads/wicket-7.x
Commit: 47bc8a8d73cbf68cf63a06e0ab0104481253915b
Parents: 200c7f3
Author: Andrea Del Bene <adelb...@apache.org>
Authored: Thu Sep 15 12:12:28 2016 +0200
Committer: Andrea Del Bene <adelb...@apache.org>
Committed: Thu Sep 15 12:31:55 2016 +0200

----------------------------------------------------------------------
 .../src/docs/guide/advanced/advanced_2.gdoc     |  39 -----
 .../docs/guide/advanced/advanced_2.gdoc.orig    | 171 +++++++++++++++++++
 .../src/docs/guide/advanced/advanced_3.gdoc     |  53 +++---
 .../src/docs/guide/advanced/advanced_4.gdoc     |  43 +++--
 .../src/docs/guide/advanced/advanced_5.gdoc     |  85 +++------
 .../src/docs/guide/advanced/advanced_6.gdoc     |  75 ++++++--
 .../src/docs/guide/advanced/advanced_7.gdoc     |  17 ++
 wicket-user-guide/src/docs/guide/toc.yml        |   9 +-
 8 files changed, 331 insertions(+), 161 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/wicket/blob/47bc8a8d/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc 
b/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc
index 1d1dda0..83b6629 100644
--- a/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc
+++ b/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc
@@ -127,42 +127,3 @@ public final void onLinkClicked()
 }
 {code}
 
-h3. Wicket events infrastructure
-
-Starting from version 1.5 Wicket offers an event-based infrastructure for 
inter-component communication. The infrastructure is based on two simple 
interfaces (both in package @org.apache.wicket.event@) : @IEventSource@ and 
@IEventSink@. 
-
-The first interface must be implemented by those entities that want to 
broadcast en event while the second interface must be implemented by those 
entities that want to receive a broadcast event.
-
-The following entities already implement both these two interfaces (i.e. they 
can be either sender or receiver): @Component@, @Session@, @RequestCycle@ and 
@Application@.
-@IEventSource@ exposes a single method named send which takes in input three 
parameters:
-
-* *sink*: an implementation of @IEventSink@ that will be the receiver of the 
event. 
-* *broadcast*: a @Broadcast@ enum which defines the broadcast method used to 
dispatch the event to the sink and to other entities such as sink children, 
sink containers, session object, application object and the current request 
cycle. It has four possible values:
-{table}
-*Value* | *Description*
-BREADTH | The event is sent first to the specified sink and then to all its 
children components following a breadth-first order.
-DEPTH | The event is sent to the specified sink only after it has been 
dispatched to all its children components following a depth-first order.
-BUBBLE | The event is sent first to the specified sink and then to its parent 
containers.
-EXACT | The event is sent only to the specified sink.
-{table}
-* *payload*: a generic object representing the data sent with the event.
-
-Each broadcast mode has its own traversal order for @Session@, @RequestCycle@ 
and @Application@. See JavaDoc of class @Broadcast@ for further details about 
this order.
-
-Interface @IEventSink@ exposes callback method @onEvent(IEvent<?> event)@ 
which is triggered when a sink receives an event. The interface @IEvent@ 
represents the received event and provides getter methods to retrieve the event 
broadcast type, the source of the event and its payload. Typically the received 
event is used checking the type of its payload object:
-
-{code}
-@Override
-public void onEvent(IEvent event) {
-  //if the type of payload is MyPayloadClass perform some actions 
-  if(event.getPayload() instanceof MyPayloadClass) {
-     //execute some business code.
-  }else{
-     //other business code
-  }            
-}
-{code}
-
-Project @InterComponetsEventsExample@ provides a concrete example of sending 
an event to a component (named 'container in the middle') using all the 
available broadcast methods:
-
-!InterComponentsEventsExample-screenshot.png!

http://git-wip-us.apache.org/repos/asf/wicket/blob/47bc8a8d/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc.orig
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc.orig 
b/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc.orig
new file mode 100644
index 0000000..e572fe5
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc.orig
@@ -0,0 +1,171 @@
+
+
+With Wicket it's quite easy to build a callback URL that executes a specific 
method on server side. This method must be defined in a functional interface 
(i.e. an an interface that defines just one method) that inherits from built-in 
@org.apache.wicket.IRequestListener@ and it must be a void method with no 
parameters in input:
+
+{code}
+public interface IMyListener extends IRequestListener
+{
+       /**
+        * Called when the relative callback URL is requested.
+        */
+       void myCallbackMethod();
+}
+{code}
+
+To control how the method will be invoked we must use class 
@org.apache.wicket.RequestListenerInterface@. In Wicket is a common practice to 
instantiate this class as a public static field inside the relative callback 
interface:
+
+{code}
+public interface IMyListener extends IRequestListener
+{
+       /**RequestListenerInterface instance*/
+       public static final RequestListenerInterface INTERFACE = new 
+                               RequestListenerInterface(IMyListener.class);
+       /**
+        * Called when the relative callback URL is requested.
+        */
+       void myCallbackMethod();
+}
+{code}
+
+By default @RequestListenerInterface@ will respond rendering the current page 
after the callback method has been executed (if we have a non-AJAX request). To 
change this behavior we can use setter method 
@setRenderPageAfterInvocation(boolean)@.
+
+Now that our callback interface is complete we can generate a callback URL 
with @Component@'s method @urlFor(RequestListenerInterface, PageParameters)@ or 
with method @urlFor (Behavior, RequestListenerInterface, PageParameters)@ if we 
are using a callback interface with a behavior (see the following example).
+
+Project CallbackURLExample contains a behavior (class 
@OnChangeSingleChoiceBehavior@) that implements a callback interface to update 
the model of an @AbstractSingleSelectChoice@ component when user changes the 
selected option (it provides the same functionality of method 
@wantOnSelectionChangedNotifications@). 
+
+Instead of a custom callback interface, @OnChangeSingleChoiceBehavior@ 
implements built-in interface @org.apache.wicket.behavior.IBehaviorListener@ 
which is designed to generate a callback URL for behaviors. The callback method 
defined in this interface is @onRequest()@ and the following is the 
implementation provided by @OnSelectionChangedNotifications@:
+
+{code}
+@Override
+public void onRequest() {      
+       Request request = RequestCycle.get().getRequest();
+       IRequestParameters requestParameters = request.getRequestParameters();
+       StringValue choiceId = requestParameters.getParameterValue("choiceId");
+       //boundComponent is the component that the behavior it is bound to.
+       boundComponent.setDefaultModelObject( 
convertChoiceIdToChoice(choiceId.toString()));
+}
+{code}
+
+When invoked via URL, the behavior expects to find a request parameter 
(choiceId) containing the id of the selected choice. This value is used to 
obtain the corresponding choice object that must be used to set the model of 
the component that the behavior is bound to (boundComponent). Method 
@convertChoiceIdToChoice@ is in charge of retrieving the choice object given 
its id and it has been copied from class @AbstractSingleSelectChoice@.
+
+Another interesting part of @OnChangeSingleChoiceBehavior@ is its method 
@onComponentTag@ where some JavaScript “magic” is used to move user's 
browser to the callback URL when event “change” occurs on bound component:
+
+{code}
+@Override
+public void onComponentTag(Component component, ComponentTag tag) {
+       super.onComponentTag(component, tag);
+               
+       CharSequence callBackURL = getCallbackUrl();
+       String separatorChar = (callBackURL.toString().indexOf('?') > -1 ? "&" 
: "?");
+               
+       String finalScript = "var isSelect = $(this).is('select');\n" +
+                                "var component;\n" +   
+                                "if(isSelect)\n" +
+                                "      component = $(this);\n" +
+                                "else \n" +
+                                "      component = 
$(this).find('input:radio:checked');\n" +
+                                "window.location.href='" + callBackURL +  
separatorChar + 
+                                "choiceId=' + " + "component.val()";
+               
+       tag.put("onchange", finalScript);
+}
+{code}
+
+The goal of @onComponentTag@ is to build an onchange handler that forces 
user's browser to move to the callback URL (modifing standard property 
window.location.href). Please note that we have appended the expected parameter 
(choiceId) to the URL retrieving its value with a JQuery selector suited for 
the current type of component (a drop-down menu or a radio group). Since we are 
using JQuery in our JavaScript code, the behavior comes also with method 
@renderHead@ that adds the bundled JQuery library to the current page.
+
+Method @getCallbackUrl()@ is used to generate the callback URL for our custom 
behavior and it has been copied from built-in class @AbstractAjaxBehavior@: 
+
+{code}
+public CharSequence getCallbackUrl(){
+       if (boundComponent == null){
+               throw new IllegalArgumentException(
+                       "Behavior must be bound to a component to create the 
URL");
+       }
+
+       final RequestListenerInterface rli;
+
+       rli = IBehaviorListener.INTERFACE;
+
+       return boundComponent.urlFor(this, rli, new PageParameters());
+}
+{code}
+
+Static field @IBehaviorListener.INTERFACE@ is the implementation of 
@RequestListenerInterface@ defined inside callback interface 
@IBehaviorListener@.
+
+The home page of project @CallbackURLExample@ contains a @DropDownChoice@ and 
a @RadioChoice@ which use our custom behavior. There are also two labels to 
display the content of the models of the two components:
+
+!CallbackURLExample-screenshot.png!
+
+{note}
+Implementing interface @IBehaviorListener@ makes a behavior stateful because 
its callback URL is specific for a given instance of component.
+{note}
+
+<<<<<<< HEAD
+As final note it's interesting to see how Wicket internally uses callback URLs 
for its standard link component. Class 
@org.apache.wicket.markup.html.link.Link@ implements interface 
@org.apache.wicket.markup.html.link.ILinkListener@ which in turn extends 
@IRequestListener@:
+
+{code}
+public interface ILinkListener extends IRequestListener
+{
+       /** Listener interface */
+       public static final RequestListenerInterface INTERFACE = new 
RequestListenerInterface(
+               ILinkListener.class);
+
+       /**
+        * Called when a link is clicked.
+        */
+       void onLinkClicked();
+}
+{code}
+
+The implementation of method @onLinkClicked@ simply delegates event handling 
to our custom version of @onClick@:
+
+{code}
+@Override
+public final void onLinkClicked()
+{
+       // Invoke subclass handler
+       onClick();
+}
+{code}
+
+h3. Wicket events infrastructure
+
+Starting from version 1.5 Wicket offers an event-based infrastructure for 
inter-component communication. The infrastructure is based on two simple 
interfaces (both in package @org.apache.wicket.event@) : @IEventSource@ and 
@IEventSink@. 
+
+The first interface must be implemented by those entities that want to 
broadcast en event while the second interface must be implemented by those 
entities that want to receive a broadcast event.
+
+The following entities already implement both these two interfaces (i.e. they 
can be either sender or receiver): @Component@, @Session@, @RequestCycle@ and 
@Application@.
+@IEventSource@ exposes a single method named send which takes in input three 
parameters:
+
+* *sink*: an implementation of @IEventSink@ that will be the receiver of the 
event. 
+* *broadcast*: a @Broadcast@ enum which defines the broadcast method used to 
dispatch the event to the sink and to other entities such as sink children, 
sink containers, session object, application object and the current request 
cycle. It has four possible values:
+{table}
+*Value* | *Description*
+BREADTH | The event is sent first to the specified sink and then to all its 
children components following a breadth-first order.
+DEPTH | The event is sent to the specified sink only after it has been 
dispatched to all its children components following a depth-first order.
+BUBBLE | The event is sent first to the specified sink and then to its parent 
containers.
+EXACT | The event is sent only to the specified sink.
+{table}
+* *payload*: a generic object representing the data sent with the event.
+
+Each broadcast mode has its own traversal order for @Session@, @RequestCycle@ 
and @Application@. See JavaDoc of class @Broadcast@ for further details about 
this order.
+
+Interface @IEventSink@ exposes callback method @onEvent(IEvent<?> event)@ 
which is triggered when a sink receives an event. The interface @IEvent@ 
represents the received event and provides getter methods to retrieve the event 
broadcast type, the source of the event and its payload. Typically the received 
event is used checking the type of its payload object:
+
+{code}
+@Override
+public void onEvent(IEvent event) {
+  //if the type of payload is MyPayloadClass perform some actions 
+  if(event.getPayload() instanceof MyPayloadClass) {
+     //execute some business code.
+  }else{
+     //other business code
+  }            
+}
+{code}
+
+Project @InterComponetsEventsExample@ provides a concrete example of sending 
an event to a component (named 'container in the middle') using all the 
available broadcast methods:
+
+!InterComponentsEventsExample-screenshot.png!
+=======
+>>>>>>> c04f2b0... Documentaion for  events infrastructure has been moved to 
its own paragraph

http://git-wip-us.apache.org/repos/asf/wicket/blob/47bc8a8d/wicket-user-guide/src/docs/guide/advanced/advanced_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/advanced/advanced_3.gdoc 
b/wicket-user-guide/src/docs/guide/advanced/advanced_3.gdoc
index 0c6c3a6..ec8e7a3 100644
--- a/wicket-user-guide/src/docs/guide/advanced/advanced_3.gdoc
+++ b/wicket-user-guide/src/docs/guide/advanced/advanced_3.gdoc
@@ -1,38 +1,37 @@
+Starting from version 1.5 Wicket offers an event-based infrastructure for 
inter-component communication. The infrastructure is based on two simple 
interfaces (both in package @org.apache.wicket.event@) : @IEventSource@ and 
@IEventSink@. 
 
+The first interface must be implemented by those entities that want to 
broadcast en event while the second interface must be implemented by those 
entities that want to receive a broadcast event.
 
-Some components or resources may need to be configured before being used in 
our applications. While so far we used Application's init method to initialize 
these kinds of entities, Wicket offers a more flexible and modular way to 
configure our classes. 
+The following entities already implement both these two interfaces (i.e. they 
can be either sender or receiver): @Component@, @Session@, @RequestCycle@ and 
@Application@.
+@IEventSource@ exposes a single method named send which takes in input three 
parameters:
 
-During application's bootstrap Wicket searches for any properties file placed 
in one of the '/META-INF/wicket/' folder visible to the application classpath. 
When one of these files is found, the initializer defined inside it will be 
executed. An initializer is an implementation of interface 
@org.apache.wicket.IInitializer@ and is defined inside a properties with a line 
like this:
+* *sink*: an implementation of @IEventSink@ that will be the receiver of the 
event. 
+* *broadcast*: a @Broadcast@ enum which defines the broadcast method used to 
dispatch the event to the sink and to other entities such as sink children, 
sink containers, session object, application object and the current request 
cycle. It has four possible values:
+{table}
+*Value* | *Description*
+BREADTH | The event is sent first to the specified sink and then to all its 
children components following a breadth-first order.
+DEPTH | The event is sent to the specified sink only after it has been 
dispatched to all its children components following a depth-first order.
+BUBBLE | The event is sent first to the specified sink and then to its parent 
containers.
+EXACT | The event is sent only to the specified sink.
+{table}
+* *payload*: a generic object representing the data sent with the event.
 
-{code}
-initializer=org.wicketTutorial.MyInitializer
-{code}
+Each broadcast mode has its own traversal order for @Session@, @RequestCycle@ 
and @Application@. See JavaDoc of class @Broadcast@ for further details about 
this order.
 
-The fully qualified class name corresponds to the initializer that must be 
executed. Interface @IInitializer@ defines method init(Application) which 
should contain our initialization code, and method @destroy(Application)@ which 
is invoked when application is terminated:
+Interface @IEventSink@ exposes callback method @onEvent(IEvent<?> event)@ 
which is triggered when a sink receives an event. The interface @IEvent@ 
represents the received event and provides getter methods to retrieve the event 
broadcast type, the source of the event and its payload. Typically the received 
event is used checking the type of its payload object:
 
 {code}
-public class MyInitializer implements IInitializer{
-
-       public void init(Application application) {
-               //initialization code 
-       }
-
-       public void destroy(Application application) {
-               //code to execute when application is terminated
-       }       
+@Override
+public void onEvent(IEvent event) {
+  //if the type of payload is MyPayloadClass perform some actions 
+  if(event.getPayload() instanceof MyPayloadClass) {
+     //execute some business code.
+  }else{
+     //other business code
+  }         
 }
 {code}
 
-Only one initializer can be defined in a single properties file. To overcome 
this limit we can create a main initializer that in turn executes every 
initializer we need:
+Project @InterComponetsEventsExample@ provides a concrete example of sending 
an event to a component (named 'container in the middle') using all the 
available broadcast methods:
 
-{code}
-public class MainInitializer implements IInitializer{
-
-       public void init(Application application) {
-               new AnotherInitializer().init(application);
-               new YetAnotherInitializer().init(application);
-               //... 
-       }
-       //destroy... 
-}
-{code}
+!InterComponentsEventsExample-screenshot.png!
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/wicket/blob/47bc8a8d/wicket-user-guide/src/docs/guide/advanced/advanced_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/advanced/advanced_4.gdoc 
b/wicket-user-guide/src/docs/guide/advanced/advanced_4.gdoc
index 34549c1..0c6c3a6 100644
--- a/wicket-user-guide/src/docs/guide/advanced/advanced_4.gdoc
+++ b/wicket-user-guide/src/docs/guide/advanced/advanced_4.gdoc
@@ -1,27 +1,38 @@
 
 
-JMX (Java Management Extensions) is the standard technology adopted in Java 
for managing and monitoring running applications or Java Virtual Machines. 
Wicket offers support for JMX through module wicket-jmx. In this paragraph we 
will see how we can connect to a Wicket application using JMX. In our example 
we will use JConsole as JMX client. This program is bundled with Java SE since 
version 5 and we can run it typing jconsole in our OS shell. 
+Some components or resources may need to be configured before being used in 
our applications. While so far we used Application's init method to initialize 
these kinds of entities, Wicket offers a more flexible and modular way to 
configure our classes. 
 
-Once JConsole has started it will ask us to establish a new connection to a 
Java process, choosing between a local process or a remote one. In the 
following picture we have selected the process corresponding to the local 
instance of Jetty server we used to run one of our example projects:
+During application's bootstrap Wicket searches for any properties file placed 
in one of the '/META-INF/wicket/' folder visible to the application classpath. 
When one of these files is found, the initializer defined inside it will be 
executed. An initializer is an implementation of interface 
@org.apache.wicket.IInitializer@ and is defined inside a properties with a line 
like this:
 
-!JMX-new-connection.png!
+{code}
+initializer=org.wicketTutorial.MyInitializer
+{code}
 
-After we have established a JMX connection, JConsole will show us the 
following set of tabs:
+The fully qualified class name corresponds to the initializer that must be 
executed. Interface @IInitializer@ defines method init(Application) which 
should contain our initialization code, and method @destroy(Application)@ which 
is invoked when application is terminated:
 
-!JMX-console.png!
+{code}
+public class MyInitializer implements IInitializer{
 
-JMX exposes application-specific informations using special objects called 
MBeans (Manageable Beans), hence if we want to control our application we must 
open the corresponding tab. The MBeans containing the application's 
informations is named @org.apache.wicket.app.<filter/servlet name>@.
+       public void init(Application application) {
+               //initialization code 
+       }
 
-In our example we have used wicket.test as filter name for our application:
+       public void destroy(Application application) {
+               //code to execute when application is terminated
+       }       
+}
+{code}
 
-!JMX-console2.png!
+Only one initializer can be defined in a single properties file. To overcome 
this limit we can create a main initializer that in turn executes every 
initializer we need:
 
-As we can see in the picture above, every MBean exposes a node containing its 
attributes and another node showing the possible operations that can be 
performed on the object. In the case of a Wicket application the available 
operations are clearMarkupCache and clearLocalizerCache:
+{code}
+public class MainInitializer implements IInitializer{
 
-!JMX-console3.png!
-
-With these two operations we can force Wicket to clear the internal caches 
used to load components markup and resource bundles. This can be particularly 
useful if we have our application running in DEPLOYMENT mode and we want to 
publish minor fixes for markup or bundle files (like spelling or typo 
corrections) without restarting the entire application. Without cleaning these 
two caches Wicket would continue to use cached values ignoring any change made 
to markup or bundle files.
-
-Some of the exposed properties are editable, hence we can tune their values 
while the application is running. For example if we look at the properties of 
@ApplicationSettings@ we can set the maximum size allowed for an upload 
modifying the attribute DefaultMaximumUploadSize:
-
-!JMX-console4.png!
\ No newline at end of file
+       public void init(Application application) {
+               new AnotherInitializer().init(application);
+               new YetAnotherInitializer().init(application);
+               //... 
+       }
+       //destroy... 
+}
+{code}

http://git-wip-us.apache.org/repos/asf/wicket/blob/47bc8a8d/wicket-user-guide/src/docs/guide/advanced/advanced_5.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/advanced/advanced_5.gdoc 
b/wicket-user-guide/src/docs/guide/advanced/advanced_5.gdoc
index 0117868..34549c1 100644
--- a/wicket-user-guide/src/docs/guide/advanced/advanced_5.gdoc
+++ b/wicket-user-guide/src/docs/guide/advanced/advanced_5.gdoc
@@ -1,62 +1,27 @@
 
 
-So far, as markup source for our pages/panels we have used a static markup 
file, no matter if it was inherited or directly associated to the component. 
Now we want to investigate a more complex use case where we want to dynamical 
generate the markup directly inside component code.
-
-To become a markup producer, a component must simply implement interface 
@org.apache.wicket.markup.IMarkupResourceStreamProvider@. The only method 
defined in this interface is @getMarkupResourceStream(MarkupContainer, 
Class<?>)@ which returns an utility interface called @IResourceStream@ 
representing the actual markup.
-
-In the following example we have a custom panel without a related markup file 
that generates a simple <div> tag as markup: 
-
-{code}
-public class AutoMarkupGenPanel extends Panel implements 
IMarkupResourceStreamProvider {
-       public AutoMarkupGenPanel(String id, IModel<?> model) {
-               super(id, model);               
-       }
-
-       @Override
-       public IResourceStream getMarkupResourceStream(MarkupContainer 
container,
-                       Class<?> containerClass) {
-               String markup = "<wicket:panel><div>Panel 
markup</div></wicket:panel>";
-               StringResourceStream resourceStream = new 
StringResourceStream(markup);
-               
-               return resourceStream;
-       }
-}
-{code}
-
-Class StringResourceStream is a resource stream that uses a String instance as 
backing object.
-
-h3. Avoiding markup caching
-
-As we have seen in the previous paragraph, Wicket uses an internal cache for 
components markup. This can be a problem if our component dynamical generates 
its markup when it is rendered because once the markup has been cached, Wicket 
will always use the cached version for the specific component. To overwrite 
this default caching policy, a component can implement interface 
@IMarkupCacheKeyProvider@. 
-
-This interface defines method @getCacheKey(MarkupContainer, Class<?>)@ which 
returns a string value representing the key used by Wicket to retrieve the 
markup of the component from the cache. If this value is null the markup will 
not be cached, allowing the component to display the last generated markup each 
time it is rendered:
-
-{code}
-public class NoCacheMarkupPanel extends Panel implements 
IMarkupCacheKeyProvider {
-       public NoCacheMarkupPanel(String id, IModel<?> model) {
-               super(id, model);               
-       }
-       
-       /**
-       * Generate a dynamic HTML markup that changes every time
-       * the component is rendered
-       */
-       @Override
-       public IResourceStream getMarkupResourceStream(MarkupContainer 
container,
-                       Class<?> containerClass) {
-               String markup = "<wicket:panel><div>Panel with current 
nanotime: " + System.nanoTime() +
-                                "</div></wicket:panel>";
-               StringResourceStream resourceStream = new 
StringResourceStream(markup);
-               
-               return resourceStream;
-       }
-
-       /**
-       * Avoid markup caching for this component
-       */
-       @Override
-       public String getCacheKey(MarkupContainer arg0, Class<?> arg1) {
-               return null;
-       }
-}
-{code}
+JMX (Java Management Extensions) is the standard technology adopted in Java 
for managing and monitoring running applications or Java Virtual Machines. 
Wicket offers support for JMX through module wicket-jmx. In this paragraph we 
will see how we can connect to a Wicket application using JMX. In our example 
we will use JConsole as JMX client. This program is bundled with Java SE since 
version 5 and we can run it typing jconsole in our OS shell. 
+
+Once JConsole has started it will ask us to establish a new connection to a 
Java process, choosing between a local process or a remote one. In the 
following picture we have selected the process corresponding to the local 
instance of Jetty server we used to run one of our example projects:
+
+!JMX-new-connection.png!
+
+After we have established a JMX connection, JConsole will show us the 
following set of tabs:
+
+!JMX-console.png!
+
+JMX exposes application-specific informations using special objects called 
MBeans (Manageable Beans), hence if we want to control our application we must 
open the corresponding tab. The MBeans containing the application's 
informations is named @org.apache.wicket.app.<filter/servlet name>@.
+
+In our example we have used wicket.test as filter name for our application:
+
+!JMX-console2.png!
+
+As we can see in the picture above, every MBean exposes a node containing its 
attributes and another node showing the possible operations that can be 
performed on the object. In the case of a Wicket application the available 
operations are clearMarkupCache and clearLocalizerCache:
+
+!JMX-console3.png!
+
+With these two operations we can force Wicket to clear the internal caches 
used to load components markup and resource bundles. This can be particularly 
useful if we have our application running in DEPLOYMENT mode and we want to 
publish minor fixes for markup or bundle files (like spelling or typo 
corrections) without restarting the entire application. Without cleaning these 
two caches Wicket would continue to use cached values ignoring any change made 
to markup or bundle files.
+
+Some of the exposed properties are editable, hence we can tune their values 
while the application is running. For example if we look at the properties of 
@ApplicationSettings@ we can set the maximum size allowed for an upload 
modifying the attribute DefaultMaximumUploadSize:
+
+!JMX-console4.png!
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/wicket/blob/47bc8a8d/wicket-user-guide/src/docs/guide/advanced/advanced_6.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/advanced/advanced_6.gdoc 
b/wicket-user-guide/src/docs/guide/advanced/advanced_6.gdoc
index 564322c..0117868 100644
--- a/wicket-user-guide/src/docs/guide/advanced/advanced_6.gdoc
+++ b/wicket-user-guide/src/docs/guide/advanced/advanced_6.gdoc
@@ -1,17 +1,62 @@
 
 
-In this chapter we have introduced some advanced topics we didn't have the 
chance to cover yet. We have started talking about behaviors and we have seen 
how they can be used to enrich existing components (promoting a 
component-oriented approach). Behaviors are also fundamental to work with AJAX 
in Wicket, as we will see in the next chapter.
-
-After behaviors we have learnt how to generate callback URLs to execute a 
custom method on server side defined inside a specific callback interface.
-
-The third topic of the chapter has been the event infrastructure provided in 
Wicket for inter-component communication which brings to our components a 
desktop-like event-driven architecture.
-
-Then, we have introduced a new entity called initializer which can be used to 
configure resources and component in a modular and self-contained way.
-
-We have also looked at Wicket support for JMX and we have seen how to use this 
technology for monitoring and managing our running applications.
-
-Finally we have introduced a new technique to generate the markup of a 
component from its Java code.
-
-
-
-
+So far, as markup source for our pages/panels we have used a static markup 
file, no matter if it was inherited or directly associated to the component. 
Now we want to investigate a more complex use case where we want to dynamical 
generate the markup directly inside component code.
+
+To become a markup producer, a component must simply implement interface 
@org.apache.wicket.markup.IMarkupResourceStreamProvider@. The only method 
defined in this interface is @getMarkupResourceStream(MarkupContainer, 
Class<?>)@ which returns an utility interface called @IResourceStream@ 
representing the actual markup.
+
+In the following example we have a custom panel without a related markup file 
that generates a simple <div> tag as markup: 
+
+{code}
+public class AutoMarkupGenPanel extends Panel implements 
IMarkupResourceStreamProvider {
+       public AutoMarkupGenPanel(String id, IModel<?> model) {
+               super(id, model);               
+       }
+
+       @Override
+       public IResourceStream getMarkupResourceStream(MarkupContainer 
container,
+                       Class<?> containerClass) {
+               String markup = "<wicket:panel><div>Panel 
markup</div></wicket:panel>";
+               StringResourceStream resourceStream = new 
StringResourceStream(markup);
+               
+               return resourceStream;
+       }
+}
+{code}
+
+Class StringResourceStream is a resource stream that uses a String instance as 
backing object.
+
+h3. Avoiding markup caching
+
+As we have seen in the previous paragraph, Wicket uses an internal cache for 
components markup. This can be a problem if our component dynamical generates 
its markup when it is rendered because once the markup has been cached, Wicket 
will always use the cached version for the specific component. To overwrite 
this default caching policy, a component can implement interface 
@IMarkupCacheKeyProvider@. 
+
+This interface defines method @getCacheKey(MarkupContainer, Class<?>)@ which 
returns a string value representing the key used by Wicket to retrieve the 
markup of the component from the cache. If this value is null the markup will 
not be cached, allowing the component to display the last generated markup each 
time it is rendered:
+
+{code}
+public class NoCacheMarkupPanel extends Panel implements 
IMarkupCacheKeyProvider {
+       public NoCacheMarkupPanel(String id, IModel<?> model) {
+               super(id, model);               
+       }
+       
+       /**
+       * Generate a dynamic HTML markup that changes every time
+       * the component is rendered
+       */
+       @Override
+       public IResourceStream getMarkupResourceStream(MarkupContainer 
container,
+                       Class<?> containerClass) {
+               String markup = "<wicket:panel><div>Panel with current 
nanotime: " + System.nanoTime() +
+                                "</div></wicket:panel>";
+               StringResourceStream resourceStream = new 
StringResourceStream(markup);
+               
+               return resourceStream;
+       }
+
+       /**
+       * Avoid markup caching for this component
+       */
+       @Override
+       public String getCacheKey(MarkupContainer arg0, Class<?> arg1) {
+               return null;
+       }
+}
+{code}

http://git-wip-us.apache.org/repos/asf/wicket/blob/47bc8a8d/wicket-user-guide/src/docs/guide/advanced/advanced_7.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/advanced/advanced_7.gdoc 
b/wicket-user-guide/src/docs/guide/advanced/advanced_7.gdoc
new file mode 100644
index 0000000..564322c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/advanced/advanced_7.gdoc
@@ -0,0 +1,17 @@
+
+
+In this chapter we have introduced some advanced topics we didn't have the 
chance to cover yet. We have started talking about behaviors and we have seen 
how they can be used to enrich existing components (promoting a 
component-oriented approach). Behaviors are also fundamental to work with AJAX 
in Wicket, as we will see in the next chapter.
+
+After behaviors we have learnt how to generate callback URLs to execute a 
custom method on server side defined inside a specific callback interface.
+
+The third topic of the chapter has been the event infrastructure provided in 
Wicket for inter-component communication which brings to our components a 
desktop-like event-driven architecture.
+
+Then, we have introduced a new entity called initializer which can be used to 
configure resources and component in a modular and self-contained way.
+
+We have also looked at Wicket support for JMX and we have seen how to use this 
technology for monitoring and managing our running applications.
+
+Finally we have introduced a new technique to generate the markup of a 
component from its Java code.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/47bc8a8d/wicket-user-guide/src/docs/guide/toc.yml
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/toc.yml 
b/wicket-user-guide/src/docs/guide/toc.yml
index e6b89cf..e11f73c 100644
--- a/wicket-user-guide/src/docs/guide/toc.yml
+++ b/wicket-user-guide/src/docs/guide/toc.yml
@@ -142,10 +142,11 @@ advanced:
   title: Wicket advanced topics
   advanced_1: Enriching components with behaviors
   advanced_2: Generating callback URLs with IRequestListener
-  advanced_3: Initializers
-  advanced_4: Using JMX with Wicket
-  advanced_5: Generating HTML markup from code
-  advanced_6: Summary
+  advanced_3: Wicket events infrastructure
+  advanced_4: Initializers
+  advanced_5: Using JMX with Wicket
+  advanced_6: Generating HTML markup from code
+  advanced_7: Summary
 ajax:
   title: Working with AJAX
   ajax_1: How to use AJAX components and behaviors

Reply via email to