Repository: wicket Updated Branches: refs/heads/master d4f0bba42 -> c04f2b00b
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/c04f2b00 Tree: http://git-wip-us.apache.org/repos/asf/wicket/tree/c04f2b00 Diff: http://git-wip-us.apache.org/repos/asf/wicket/diff/c04f2b00 Branch: refs/heads/master Commit: c04f2b00bc08756a5d19aeed5e7a3287ac688192 Parents: d4f0bba 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:12:28 2016 +0200 ---------------------------------------------------------------------- .../src/docs/guide/advanced/advanced_2.gdoc | 39 --------- .../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 ++- 7 files changed, 160 insertions(+), 161 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/wicket/blob/c04f2b00/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 e9b0cab..5934ffc 100644 --- a/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc +++ b/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc @@ -115,42 +115,3 @@ The home page of project @CallbackURLExample@ contains a @DropDownChoice@ and a Implementing interface @IRequestListener@ makes a behavior stateful because its callback URL is specific for a given instance of component. {note} -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/c04f2b00/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/c04f2b00/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/c04f2b00/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/c04f2b00/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/c04f2b00/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/c04f2b00/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 0d0b336..b02bf80 100644 --- a/wicket-user-guide/src/docs/guide/toc.yml +++ b/wicket-user-guide/src/docs/guide/toc.yml @@ -143,10 +143,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
