http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/monitoring.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/monitoring.adoc b/wicket-user-guide/src/main/asciidoc/monitoring.adoc new file mode 100644 index 0000000..40fb294 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/monitoring.adoc @@ -0,0 +1,10 @@ + +The wicket-metrics module is available since Wicket 7.3.0 and contains a life measurement implementation to collect data of applications and visualize it. + +You can see how many request your application served, how often components are created, initalized, configured or their detach method has been invoked and a lot of other additional information. + +The module itself is using https://dropwizard.github.io/metrics/3.1.0/[Metrics of dropwizard] and https://eclipse.org/aspectj/[AspectJ] so that if you turn of the measurement it has no longer any effect + +to your web application. + +Keep in mind that AspectJ is licensed under the Eclipse Public License and you should provide the required license information.
http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_1.adoc b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_1.adoc new file mode 100644 index 0000000..a30477a --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_1.adoc @@ -0,0 +1,86 @@ + +This is a little example how to setup wicket-metrics within a Apache Tomcat. + +(1) Add the maven dependency to your project +[source,java] +---- +<dependency> + <groupId>org.apache.wicket.experimental.wicket8</groupId> + <artifactId>wicket-metrics</artifactId> + <version>0.X-SNAPSHOT</version> +</dependency> +---- + +(2) Just drop the jars of aspectjrt and aspectjweaver into the tomcat lib folder - you can download it from here http://mvnrepository.com/artifact/org.aspectj/[http://mvnrepository.com/artifact/org.aspectj/] (the metrics dependency is shipped with the project) + +(3) Add the java agent to the jvm start options of your tomcat: -javaagent:/pathToServer/lib/aspectjweaver-x.x.x.jar + +(4) Add an aop.xml to your project's META-INF folder at the root of your classpath with the metrics you want to use (aspect tags) - if you don't want to enable a metrics just remove the aspect tag: +[source,java] +---- +<!DOCTYPE aspectj PUBLIC "-//AspectJ//DTD//EN" "http://www.eclipse.org/aspectj/dtd/aspectj.dtd";> +<aspectj> + <weaver options="-nowarn"> + <include within="org.apache.wicket..*"/> + </weaver> + <aspects> + <!-- required --> + <aspect name="org.apache.wicket.metrics.aspects.WicketFilterInitAspect" /> + + <!-- optional --> + <aspect name="org.apache.wicket.metrics.aspects.model.LoadableDetachableModelLoadAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.requesthandler.IRequestHandlerDetachAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.requesthandler.IRequestHandlerRespondAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.resource.IResourceCreateAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.behavior.BehaviorCreateAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.component.ComponentCreateAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.component.ComponentOnConfigureAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.component.ComponentOnDetachAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.component.ComponentOnInitializeAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.component.ComponentOnRenderAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.component.ComponentSetResponsePageAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.ajax.IPartialPageRequestHandlerAddAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.ajax.IPartialPageRequestHandlerAppendJavaScriptAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.ajax.IPartialPageRequestHandlerPrependJavaScriptAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.resource.ResourceReferenceCreateAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.markup.WicketTagCreateAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.request.WicketFilterRequestCycleUrlAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.request.WicketFilterRequestCycleAspect" /> + <aspect name="org.apache.wicket.metrics.aspects.session.SessionCountListenerAspect" /> + </aspects> +</aspectj> +---- + +* If you use the SessionCountListenerAspect you have to ensure that metadata-complete= [false] is set otherwise you have to add the listener yourself: +[source,java] +---- +<listener> + <listener-class> + org.apache.wicket.metrics.aspects.session.SessionCountListener + </listener-class> +</listener> +---- + +(5 - optional) To enable the JMX measurement write the following line into your init method of your Application (Now you are able to connect with jvisualvm to your server and have a look at the data): +[source,java] +---- +WicketMetrics.getSettings().startJmxReporter(); +---- + +To deactivate: +[source,java] +---- +WicketMetrics.getSettings().stopJmxReporter(); +---- + +To disable measurement: +[source,java] +---- +WicketMetrics.getSettings().setEnabled(false); +---- + +*IMPORTANT INFORMATION* +** It is only possible to collect metrics for *one wicket filter per webapp* - don't declare more then one if you want to use wicket-metrics +** The WicketFilterInitAspect is required so that the application can be resolved - otherwise runtime exceptions will be thrown +** If you use the SessionCountListener you have to clear the session store if you restart the server - otherwise physically stored session will corrupt the data, because the count is initialized with 0. +** If you have set wicket-metrics as dependency you can open [wicket-metrics.template.xml] to get a full template of the [aop.xml] ** For the weaver options refer to the AspectJ LTW configuration documentation: https://eclipse.org/aspectj/doc/next/devguide/ltw-configuration.html http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_2.adoc b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_2.adoc new file mode 100644 index 0000000..7244fb8 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_2.adoc @@ -0,0 +1,88 @@ + +To visualize the metrics with Graphite a little additional configuration is required: + +(1) Add the additional maven dependency to your project: +[source,java] +---- +<dependency> + <groupId>io.dropwizard.metrics</groupId> + <artifactId>metrics-graphite</artifactId> + <version>${metrics.graphite.version}</version> +</dependency> +---- + +* the metrics.graphite.version should be the same as the metrics version of the wicket-metrics dependency. Check the Maven dependencies to ensure +this. + +(2) Add the following code to your Application's init method: +[source,java] +---- + private GraphiteReporter reporter; + + @Override + protected void init() + { + MetricRegistry metricRegistry = WicketMetrics.getMetricRegistry(); + final Graphite graphite = new Graphite(new InetSocketAddress("127.0.0.1", 2003)); + reporter = GraphiteReporter.forRegistry(metricRegistry).prefixedWith("WebApplications") + .convertRatesTo(TimeUnit.SECONDS).convertDurationsTo(TimeUnit.MILLISECONDS) + .filter(MetricFilter.ALL).build(graphite); + + // Collects data every 5 seconds + reporter.start(5, TimeUnit.SECONDS); + } + + @Override + protected void onDestroy() + { + super.onDestroy(); + reporter.stop(); + } +---- + +(3) Install and setup graphite on your system. Example installation for Mac (beware that this is only a quickstart setup!): + +- (1) Install homebrew: http://brew.sh/[brew] +- (2) Install https://git-scm.com/[Git] + +- (3) brew install python + +- (4) brew install cairo + +- (5) brew install py2cairo + +- (6) pip install Django==1.5 + +- (7) pip install [django-tagging<0.4] +- (8) sudo pip install carbon + +- (9) pip install whisper + +- (10) sudo pip install graphite-web + +- (11) sudo pip install Twisted==11.1.0 + +- (12) sudo chown -R <your username>:staff /opt/graphite + +- (13) cp /opt/graphite/conf/carbon.conf{.example,} + +- (14) cp /opt/graphite/conf/storage-schemas.conf{.example,} + +- (15) cd /opt/graphite/webapp/graphite + +- (16) cp local_settings.py{.example,} + +- (17) python manage.py syncdb + +- (18) python /opt/graphite/bin/carbon-cache.py start + +- (19) python /opt/graphite/bin/run-graphite-devel-server.py /opt/graphite + +- (20) Go to http://localhost:8080 + +* (18) and (19) have to be executed if the mac has been restarted + +(4) Now start your tomcat server configured like mentioned in the previous chapter. + +image::../img/wicket_metrics_graphite.png[] + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_3.adoc b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_3.adoc new file mode 100644 index 0000000..5e655fc --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_3.adoc @@ -0,0 +1,20 @@ + +The data which is going to be measured depends on the wicket-metrics implementation. So it doesn't make any sense to collect time data + +about setResponsePage, but it does for the constructor of components, to see if a component needs a long time to be created. You can + +get the information about which data has been collected from out of the mbeans. + +Here are some information about them: + +* max - the maximal time for a task (created, initialized, etc.) + +* min - the minimal time for a task (created, initialized, etc.) + +* count - how often something happened (request count) + +The structure is separated in the way that under core there are the kind of components measured and below that the type of operation + +(created, initialized, detached). In this category every component is listed dynamically. + + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_4.adoc b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_4.adoc new file mode 100644 index 0000000..e199e1e --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_4.adoc @@ -0,0 +1,42 @@ + +There are only a two steps required to write own measurements for life data statistics in Wicket: + +(1) Write a class which is named very close to what it measures. This class should extends WicketMetrics and should annotated with _Aspect and provide one method with a join point scanning for the target signature. +[source,java] +---- + @Aspect + public class MySpecialAspect extends WicketMetrics + { + @Around("execution(* my.package.MyClass.myMethod(..))") + public Object aroundRequestProcessed(ProceedingJoinPoint joinPoint) throws Throwable + { + return measureTime("mycategory/someinformation/", joinPoint); + } + } +---- +* To measure time you need _Around because measureTime of WicketMetrics requires the joinPoint - the class name is appended with a slash at the end + +* To only mark that a method is called you can use mark of WicketMetrics and apply null as a second parameter - if you apply a join point to mark the class name is appended with a slash at the end + +(2) Add the class to your aop.xml and of course the package to scan for classes that are target for your measurements: +[source,java] +---- +<!DOCTYPE aspectj PUBLIC "-//AspectJ//DTD//EN" "http://www.eclipse.org/aspectj/dtd/aspectj.dtd";> +<aspectj> + <weaver options="-nowarn"> + <include within="org.apache.wicket..*"/> + <include within="my.components.package..*"/> + </weaver> + <aspects> + <!-- required --> + <aspect name="org.apache.wicket.metrics.aspects.WicketFilterInitAspect" /> + + <!-- own aspects --> + <aspect name="my.aspect.package.MySpecialAspect" /> + + <!-- wickets own metrics --> + ..... + </aspects> +</aspectj> +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/nativewebsockets.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets.adoc new file mode 100644 index 0000000..aff2803 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets.adoc @@ -0,0 +1,10 @@ + +http://en.wikipedia.org/wiki/WebSocket[WebSockets] +This means that once the browser establish a web socket connection to the server the server can push data back to the browser without the browser explicitly asking again and again whether there is something new for it. + +Wicket Native WebSockets modules provide functionality to integrate with the non-standard APIs provided by different web containers (like http://tomcat.apache.org/[Apache Tomcat] + +WARNING: Native WebSocket works only when both the browser and the web containers support WebSocket technology. There are no plans to add support to fallback to long-polling, streaming or any other technology that simulates two way communication. Use it only if you really know that you will run your application in an environment that supports WebSockets. +Currently supported web containers are Jetty 7.5+ , Tomcat 7.0.27+ and JBoss WildFly 8.0.0+. +Supported browsers can be found at http://caniuse.com/#search=websocket[caniuse.com] + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_1.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_1.adoc new file mode 100644 index 0000000..b960ffe --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_1.adoc @@ -0,0 +1,10 @@ + +Each of the modules provide a specialization of _org.apache.wicket.protocol.http.WicketFilter_ that registers implementation specific endpoint when an HTTP request is http://en.wikipedia.org/wiki/WebSocket#WebSocket_protocol_handshake[upgraded] + +WebSockets communication can be used in a Wicket page by using _org.apache.wicket.protocol.ws.api.WebSocketBehavior_ or in a IResource by exteding _org.apache.wicket.protocol.ws.api.WebSocketResource_. +When a client is connected it is being registered in a application scoped registry using as a key the application name, the client http session id, and the id of the page or the resource name that registered it. Later when the server needs to push a message it can use this registry to filter out which clients need to receive the message. + +When a message is received from the client Wicket wraps it in _IWebSocketMessage_ and calls WebSocketBehavior1.*onMessage()* or WebSocketResource1.*onMessage()* where the application logic can react on it. +The server can push plain text and binary data to the client, but it can also add components for re-render, prepend/append JavaScript as it can do with +<<_working_with_ajax,Ajax>>. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_2.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_2.adoc new file mode 100644 index 0000000..1e72b12 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_2.adoc @@ -0,0 +1,125 @@ + +* *Classpath dependency* + +Depending on the web container that is used the application has to add a dependency to either: + +- for Jetty 9.0.x +[source,java] +---- +<dependency> + <groupId>org.apache.wicket</groupId> + <artifactId>wicket-native-websocket-jetty9</artifactId> + <version>...</version> +</dependency> +---- + +- for Tomcat 7.0.27+ (the old, non-JSR356 implementation) +[source,java] +---- +<dependency> + <groupId>org.apache.wicket</groupId> + <artifactId>wicket-native-websocket-tomcat</artifactId> + <version>...</version> +</dependency> +---- + +- for JSR356 complaint implementations (at the moment are supported: Tomcat 8.0+, Tomcat 7.0.47+, Jetty 9.1.0+ and JBoss Wildfly 8.0.0+) +[source,java] +---- +<dependency> + <groupId>org.apache.wicket</groupId> + <artifactId>wicket-native-websocket-javax</artifactId> + <version>...</version> +</dependency> +---- + +NOTE: All web containers providing JSR356 implementation are built with Java 7. This is the reason why _wicket-native-websocket-javax_ module is available only with Wicket 7.x+. If your application runs with JRE 7.x then you can +use _wicket-native-websocket-javax_ together with the latest version of Wicket 6.x. Beware that the API/implementation of _wicket-native-websocket-javax_ may change before Wicket 7.0.0 is released! + +NOTE: The examples above show snippets for Maven's pom.xml but the application can use any other dependency management tool like http://www.gradle.org/[Gradle] + +* *web.xml* + +In _WEB-INF/web.xml_ replace the usage of *WicketFilter* with any of the following depending on the web container that is used: + +For Jetty 9.0.x: +[source,java] +---- +<filter-class>org.apache.wicket.protocol.ws.jetty9.Jetty9WebSocketFilter</filter-class> +---- + +For Jetty 7.5+ and 8.x: +[source,java] +---- +<filter-class>org.apache.wicket.protocol.ws.jetty7.Jetty7WebSocketFilter</filter-class> +---- + +For Tomcat 7.0.27+ (old implementation): +[source,java] +---- +<filter-class>org.apache.wicket.protocol.ws.tomcat7.Tomcat7WebSocketFilter</filter-class> +---- + +For JSR356 complaint web containers (at the moment: Tomcat 7.0.47+, Tomcat 8.x and Jetty 9.1.x): +[source,java] +---- +<filter-class>org.apache.wicket.protocol.ws.javax.JavaxWebSocketFilter</filter-class> +---- + + + +* *WebSocketBehavior* + +_org.apache.wicket.protocol.ws.api.WebSocketBehavior_ is similar to Wicket Ajax behaviors that you may have used. +Add WebSocketBehavior to the page (or to any component in the page) that will use web socket communication: + +[source,java] +---- +public class MyPage extends WebPage { + + public MyPage() + { + add(new WebSocketBehavior() { + @Override + protected void onMessage(WebSocketRequestHandler handler, TextMessage message) + { + String msg = message.getText(); + // do something with msg + } + }); + } +} +---- + +Use _message.getText()_ to read the message sent by the client and use _handler.push(String)_ to push a text message to the connected client. Additionally you can use _handler.add(Component...)_ to add Wicket components for re-render, _handler1.prependJavaScript(CharSequence)_ and _handler1.appendJavaScript(CharSequence)_ as you do with _AjaxRequestTarget_. + +* *WebSocketResource* + +Wicket allows one thread at a time to use a page instance to simplify the usage of the pages in multithreaded enviroment. When a WebSocket message is sent to a page Wicket needs to acquire the lock to that page to be able to pass the _IWebSocketMessage_ to the _WebSocketBehavior_. This may be problematic when the application needs to send many messages from the client to the server. +For this reason Wicket provides _WebSocketResource_ - an IResource implemetation that provides the same APIs as _WebSocketBehavior_. The benefit is that there is no need of synchronization as with the pages and the drawback is that _WebSocketRequesthandler1.add(Component...)_ method cannot be used because there is no access to the components in an _IResource_. + +To register such WebSocket resource add such line to _YourApplication1.init()_ method: +[source,java] +---- +getSharedResources().add("someName", new MyWebSocketResource()); +---- + +and +[source,java] +---- + page.add(new BaseWebSocketBehavior("someName")); +---- +to any page. This will prepare the JavaScript connection for you. + +* *WebSocket connection registry* + +To push data to one or more clients the application can use the _IWebSocketConnectionRegistry_ to find all registered connections and send data to all/any of them: + +[source,java] +---- +Application application = Application.get(applicationName); +WebSocketSettings webSocketSettings = WebSocketSettings.Holder.get(application); +IWebSocketConnectionRegistry webSocketConnectionRegistry = webSocketSettings.getConnectionRegistry(); +IWebSocketConnection connection = webSocketConnectionRegistry.getConnection(application, sessionId, key); +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_3.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_3.adoc new file mode 100644 index 0000000..01b57b5 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_3.adoc @@ -0,0 +1,34 @@ + +By adding a _(Base)WebSocketBehavior_ to your component(s) Wicket will contribute _wicket-websocket-jquery.js_ library which provides some helper functions to write your client side code. There is a default websocket connection per Wicket Page opened for you which you can use like: +[source,java] +---- +Wicket.WebSocket.send('{msg: "my message"}'). +---- + +To close the default connection: +[source,java] +---- +Wicket.WebSocket.close() +---- + +Wicket.WebSocket is a simple wrapper around the native window.WebSocket API which is used to intercept the calls and to fire special JavaScript events (Wicket.Event PubSub). +Once a page that contributes _(Base)WebSocketBehavior_ is rendered the client may react on messages pushed by the server by subscribing to the _'/websocket/message'_ event: + +[source,java] +---- +Wicket.Event.subscribe("/websocket/message", function(jqEvent, message) { + var data = JSON.parse(message); + processData(data); // does something with the pushed message +}); +---- + +Here is a table of all events that the application can subscribe to: +|=== +|Event name | Arguments | Description +|/websocket/open | jqEvent | A WebSocket connection has been just opened +|/websocket/message | jqEvent, message | A message has been received from the server +|/websocket/closed | jqEvent | A WebSocket connection has been closed +|/websocket/error | jqEvent | An error occurred in the communication. The connection will be closed +|=== + + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_4.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_4.adoc new file mode 100644 index 0000000..db869d5 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_4.adoc @@ -0,0 +1,4 @@ + +The module provides _org.apache.wicket.protocol.ws.util.tester.WebSocketTester_ which gives you the possibility to emulate sending and receiving messages without the need to run in a real web container, as WicketTester does this for HTTP requests. +Check https://github.com/apache/wicket/blob/master/wicket-native-websocket/wicket-native-websocket-core/src/test/java/org/apache/wicket/protocol/ws/util/tester/WebSocketTesterBehaviorTest.java?source=c[WebSocketTesterBehaviorTest] + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_5.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_5.adoc new file mode 100644 index 0000000..73611d3 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_5.adoc @@ -0,0 +1,3 @@ + +Wicket-Atmosphere experimental module provides integration with https://github.com/Atmosphere/atmosphere[Atmosphere] + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_6.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_6.adoc new file mode 100644 index 0000000..5a1396a --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_6.adoc @@ -0,0 +1,3 @@ + +1. Request and session scoped beans do not work. +The Web Socket communication is not processed by Servlet Filters and Listeners and thus the Dependency Injection libraries have no chance to export the request and session bean proxies. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/redirects.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/redirects.adoc b/wicket-user-guide/src/main/asciidoc/redirects.adoc new file mode 100644 index 0000000..4691234 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/redirects.adoc @@ -0,0 +1,79 @@ + +Quite a few teams have already got stuck into the following problem when working with wicket forms in a clustered environment while having 2 (or more) tomcat server with enabled session replication running. + +In case of invalid data being submitted with a form instance for example, it seemed like according error messages wouldnât be presented when the same form page gets displayed again. Sometimes! And sometimes they would! One of those nightmares of rather deterministic programmerâs life. This so called Lost In Redirection problem, even if it looks like a wicket bug at first, is rather a result of a default setting in wicket regarding the processing of form submissions in general. In order to prevent another wide known problem of double form submissions, Wicket uses a so called REDIRECT_TO_BUFFER strategy for dealing with rendering a page after web formâs processing (_see RequestCycleSettings1.RenderStrategy). + +What does the default RenderStrategy actually do? + +Both logical parts of a single HTTP request, an action and a render part get processed within the same request, but instead of streaming the render result to the browser directly, the result is cached on the server first. + +image::../img/lost-in-redirection-mockup.png[] + +Wicket will create an according BufferedHttpServletResponse instance that will be used to cache the resulting HttpServletResponse within the WebApplication. + +image::../img/lost-in-redirection-mockup2.png[] + +After the buffered response is cached the HTTP status code of 302 getâs provided back to the browser resulting in an additional GET request to the redirect URL (which Wicket sets to the URL of the Form itself). There is a special handling code for this case in the WicketFilter instance that then looks up a Map of buffered responses within the WebApplication accordingly. If an appropriate already cached response for the current request is found, it getâs streamed back to the browser immediately. No additional form processing happens now. The following is a code snippet taken from WicketFilter: + +[source,java] +---- +// Are we using REDIRECT_TO_BUFFER? +if (webApplication.getRequestCycleSettings().getRenderStrategy() == RequestCycleSettings.REDIRECT_TO_BUFFER) +{ + // Try to see if there is a redirect stored + // try get an existing session + ISessionStore sessionStore = webApplication.getSessionStore(); + String sessionId = sessionStore.getSessionId(request, false); + if (sessionId != null) + { + BufferedHttpServletResponse bufferedResponse = null; + String queryString = servletRequest.getQueryString(); + // look for buffered response + if (!Strings.isEmpty(queryString)) + { + bufferedResponse = webApplication.popBufferedResponse(sessionId, + queryString); + } + else + { + bufferedResponse = webApplication.popBufferedResponse(sessionId, + relativePath); + } + // if a buffered response was found + if (bufferedResponse != null) + { + bufferedResponse.writeTo(servletResponse); + // redirect responses are ignored for the request + // logger... + return true; + } + } +} +---- + +So what happens in case you have 2 server running your application with session replication and load balancing turned on while using the default RenderStrategy described above? + +Since a Map of buffered responses is cached within a WebApplication instance that does not get replicated between the nodes obviously, a redirect request that is suppose to pick up the previously cached response (having possibly form violation messages inside) potentially getâs directed to the second node in your cluster by the load balancer. The second node does not have any responses already prepared and cached for your user. The node therefore handles the request as a completely new request for the same form page and displays a fresh new form page instance to the user accordingly. + +image::../img/lost-in-redirection-mockup3.png[] + +Unfortunately, there is currently no ideal solution to the problem described above. The default RenderStrategy used by Apache Wicket simply does not work well in a fully clustered environment with load balancing and session replication turned on. One possibility is to change the default render strategy for your application to a so called ONE_PASS_RENDER RenderStrategy which is the more suitable option to use when you want to do sophisticated (non-sticky session) clustering. This is easily done in the init method of your own subclass of Wicketâs WebApplication : + +[source,java] +---- +@Override +protected void init() { + getRequestCycleSettings().setRenderStrategy( + RequestCycleSettings.ONE_PASS_RENDER); +} +---- + +ONE_PASS_RENDER RenderStrategy does not solve the double submit problem though! So this way youâd only be trading one problem for another one actually. + +You could of course turn on the session stickiness between your load balancer (apache server) and your tomcat server additionally to the session replication which would be the preferred solution in my opinion. + +image::../img/lost-in-redirection-mockup4.png[] + +Session replication would still provide you with failover in case one of the tomcat server dies for whatever reason and sticky sessions would ensure that the Lost In Redirection problem does not occur any more. + + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/repeaters.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/repeaters.adoc b/wicket-user-guide/src/main/asciidoc/repeaters.adoc new file mode 100644 index 0000000..06b593b --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/repeaters.adoc @@ -0,0 +1,24 @@ + +A common task for web applications is to display a set of items. The most typical scenario where we need such kind of visualization is when we have to display some kind of search result. With the old template-based technologies (like JSP) we used to accomplish this task using classic for or while loops: + +[source,html] +---- +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>Insert title here</title> +</head> +<body> + <% + for(int i = 12; i<=32; i++) { + %> + <div>Hello! I'm index n°<%= %></div> + <% + } + %> +</body> +---- + +To ease this task Wicket provides a number of special-purpose components called repeaters which are designed to use their related markup to display the items of a given set in a more natural and less chaotic way. + +In this chapter we will see some of the built-in repeaters that come with Wicket. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_1.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_1.adoc new file mode 100644 index 0000000..e367b87 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_1.adoc @@ -0,0 +1,35 @@ + + + +Component _org.apache.wicket.markup.repeater.RepeatingView_ is a container which renders its children components using the tag it is bound to. It can contain an arbitrary number of children elements and we can obtain a new valid id for a new child calling its method newChildId(). This component is particularly suited when we have to repeat a simple markup fragment, for example when we want to display some items as a HTML list: + +*HTML:* +[source,html] +---- +<ul> + <li wicket:id="listItems"></li> +</ul> +---- + +*Java Code:* +[source,java] +---- +RepeatingView listItems = new RepeatingView("listItems"); + +listItems.add(new Label(listItems.newChildId(), "green")); +listItems.add(new Label(listItems.newChildId(), "blue")); +listItems.add(new Label(listItems.newChildId(), "red")); +---- + +*Generated markup:* +[source,html] +---- +<ul> + <li>green</li> + <li>blue</li> + <li>red</li> +</ul> +---- + +As we can see in this example, each child component has been rendered using the parent markup as if it was its own. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc new file mode 100644 index 0000000..4108d41 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_2.adoc @@ -0,0 +1,52 @@ + + + +As its name suggests, component _org.apache.wicket.markup.html.list.ListView_ is designed to display a given list of objects which can be provided as a standard Java List or as a model containing the concrete List. ListView iterates over the list and creates a child component of type _org.apache.wicket.markup.html.list.ListItem_ for every encountered item. + +Unlike RepeatingView this component is intended to be used with complex markup fragments containing nested components. + +To generate its children, ListView calls its abstract method populateItem(ListItem<T> item) for each item in the list, so we must provide an implementation of this method to tell the component how to create its children components. In the following example we use a ListView to display a list of Person objects: + +*HTML:* +[source,html] +---- +... + <body> + <div id="bd" style="display: table;"> + <div wicket:id="persons" style="display: table-row;"> + <div style="display: table-cell;"><b>Full name: </b></div> + <div wicket:id="fullName" style="display: table-cell;"></div> + </div> + </div> + </body> +... +---- + +*Java Code (Page Constructor):* +[source,java] +---- +public HomePage(final PageParameters parameters) { + List<Person> persons = Arrays.asList(new Person("John", "Smith"), + new Person("Dan", "Wong")); + + add(new ListView<Person>("persons", persons) { + @Override + protected void populateItem(ListItem<Person> item) { + item.add(new Label("fullName", new PropertyModel(item.getModel(), "fullName"))); + } + }); +} +---- + +*Screenshot of generated page:* + +image::../img/simple-listview-screenshot.png[] + +In this example we have displayed the full name of two Person's instances. The most interesting part of the code is the implementation of method populateItem where parameter item is the current child component created by ListView and its model contains the corresponding element of the list. Please note that inside populateItem we must add nested components to the _item_ object and not directly to the _ListView_. + +=== ListView and Form + +By default _ListView_ replaces its children components with new instances every time is rendered. Unfortunately this behavior is a problem if _ListView_ is inside a form and it contains form components. The problem is caused by the fact that children components are replaced by new ones before form is rendered, hence they can't keep their input value if validation fails and, furthermore, their feedback messages can not be displayed. + +To avoid this kind of problem we can force _ListView_ to reuse its children components using its method setReuseItems and passing true as parameter. If for any reason we need to refresh children components after we have invoked setReuseItems(true), we can use MarkupContainer's method _removeAll()_ to force _ListView_ to rebuild them. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_3.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_3.adoc new file mode 100644 index 0000000..60bc8d7 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_3.adoc @@ -0,0 +1,54 @@ + + + +Component _org.apache.wicket.markup.repeater.RefreshingView_ is a subclass of RepeatingView that comes with a customizable rendering strategy for its children components. + +RefreshingView defines abstract methods populateItem(Item) and getItemModels(). The first method is similar to the namesake method seen for ListView, but it takes in input an instance of class _org.apache.wicket.markup.repeater.Item_ which is a subclass of _ListItem_. RefreshingView is designed to display a collection of models containing the actual items. An iterator over these models is returned by the other abstract method getItemModels. + +The following code is a version of the previous example that uses _RefreshingView_ in place of _ListView_: + +*HTML:* +[source,html] +---- +... + <body> + <div id="bd" style="display: table;"> + <div wicket:id="persons" style="display: table-row;"> + <div style="display: table-cell;"><b>Full name: </b></div> + <div wicket:id="fullName" style="display: table-cell;"></div> + </div> + </div> + </body> +... +---- + +*Java Code (Page Constructor):* +[source,java] +---- +public HomePage(final PageParameters parameters) { + //define the list of models to use + final List<IModel<Person>> persons = new ArrayList<IModel<Person>>(); + + persons.add(Model.of(new Person("John", "Smith"))); + persons.add(Model.of(new Person("Dan", "Wong"))); + + add(new RefreshingView<Person>("persons") { + @Override + protected void populateItem(Item<Person> item) { + item.add(new Label("fullName", new PropertyModel(item.getModel(), "fullName"))); + } + + @Override + protected Iterator<IModel<Person>> getItemModels() { + return persons.iterator(); + } + }); +} +---- + +=== Item reuse strategy + +Similar to _ListView_, the default behavior of the _RefreshingView_ is to replace its children with new instances every time is rendered. The strategy that decides if and how children components must be refreshed is returned by method _getItemReuseStrategy_. This strategy is an implementation of interface IItemReuseStrategy. The default implementation used by _RefreshingView_ is class _DefaultItemReuseStrategy_ but Wicket provides also strategy _ReuseIfModelsEqualStrategy_ which reuses an item if its model has been returned by the iterator obtained with method _getItemModels_. + +To set a custom strategy we must use method _setItemReuseStrategy_. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_4.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_4.adoc new file mode 100644 index 0000000..58d8358 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_4.adoc @@ -0,0 +1,117 @@ + + + +Wicket offers a number of components that should be used when we have to display a big number of items (for example the results of a select SQL query). + +All these components implement interface _org.apache.wicket.markup.html.navigation.paging.IPageable_ and use interface _IDataProvider_ (placed in package _org.apache.wicket.markup.repeater.data_) as data source. This interface is designed to support data paging. We will see an example of data paging later in <<repeaters.adoc#_pageable_repeaters,paragraph 13.4.2>>. + +The methods defined by IDataProvider are the following: +* iterator(long first, long count): returns an iterator over a subset of the entire dataset. The subset starts from the item at position first and includes all the next count items (i.e. it's the closed interval <<_first,first+count>> +). +* size(): gets the size of the entire dataset. +* model(T object): this method is used to wrap an item returned by the iterator with a model. This can be necessary if, for example, we need to wrap items with a detachable model to prevent them from being serialized. + +Wicket already provides implementations of IDataProvider to work with a List as data source (ListDataProvider) and to support data sorting (SortableDataProvider). + +=== Component DataView + +Class _org.apache.wicket.markup.repeater.data.DataView_ is the simplest pageable repeater shipped with Wicket. DataView comes with abstract method populateItem(Item) that must be implemented to configure children components. In the following example we use a DataView to display a list of Person objects in a HTML table: + +*HTML:* +[source,html] +---- +<table> + <tr> + <th>Name</th><th>Surename</th><th>Address</th><th>Email</th> + </tr> + <tr wicket:id="rows"> + <td wicket:id="dataRow"></td> + </tr> +</table> +---- + +*Java Code:* +[source,java] +---- +//method loadPersons is defined elsewhere +List<Person> persons = loadPersons(); +ListDataProvider<Person> listDataProvider = new ListDataProvider<Person>(persons); + +DataView<Person> dataView = new DataView<Person>("rows", listDataProvider) { + + @Override + protected void populateItem(Item<Person> item) { + Person person = item.getModelObject(); + RepeatingView repeatingView = new RepeatingView("dataRow"); + + repeatingView.add(new Label(repeatingView.newChildId(), person.getName())); + repeatingView.add(new Label(repeatingView.newChildId(), person.getSurename())); + repeatingView.add(new Label(repeatingView.newChildId(), person.getAddress())); + repeatingView.add(new Label(repeatingView.newChildId(), person.getEmail())); + item.add(repeatingView); + } +}; +add(dataView); +---- + +Please note that in the code above we have used also a RepeatingView component to populate the rows of the table. + +In the next paragraph we will see a similar example that adds support for data paging. + +=== Data paging + +To enable data paging on a pageable repeater, we must first set the number of items to display per page with method setItemsPerPage(long items). Then, we must attach the repeater to panel PagingNavigator (placed in package _org.apache.wicket.markup.html.navigation.paging_) which is responsible for rendering a navigation bar containing the links illustrated in the following picture: + +image::../img/paging-navigator.png[] + +Project PageDataViewExample mixes a DataView component with a PagingNavigator to display the list of all countries of the world sorted by alphabetical order. Here is the initialization code of the project home page: + +*HTML:* +[source,html] +---- +<table> + <tr> + <th>ISO 3166-1</th><th>Name</th><th>Long name</th><th>Capital</th><th>Population</th> + </tr> + <tr wicket:id="rows"> + <td wicket:id="dataRow"></td> + </tr> +</table> +---- + +*Java Code:* +[source,java] +---- +public HomePage(final PageParameters parameters) { + super(parameters); + //method loadCountriesFromCsv is defined elsewhere in the class. + //It reads countries data from a csv file and returns each row as an array of Strings. + List<String[]> countries = loadCountriesFromCsv(); + ListDataProvider<String[]> listDataProvider = new ListDataProvider<String[]>(countries); + + DataView<String[]> dataView = new DataView<String[]>("rows", listDataProvider) { + @Override + protected void populateItem(Item<String[]> item) { + String[] countriesArr = item.getModelObject(); + RepeatingView repeatingView = new RepeatingView("dataRow"); + + for (int i = 0; i < countriesArr.length; i++){ + repeatingView.add(new Label(repeatingView.newChildId(), countriesArr[i])); + } + item.add(repeatingView); + } + }; + + dataView.setItemsPerPage(15); + + add(dataView); + add(new PagingNavigator("pagingNavigator", dataView)); +} +---- + +The data of a single country (ISO code, name, long name, capital and population) are handled with an array of strings. The usage of PagingNavigator is quite straightforward as we need to simply pass the pageable repeater to its constructor. + +To explore the other pageable repeaters shipped with Wicket you can visit the page at {externalink:wicket.examples.url_repeater} where you can find live examples of these components. + +NOTE: Wicket provides also component PageableListView which is a sublcass of ListView that implements interface IPageable, hence it can be considered a pageable repeater even if it doesn't use interface IDataProvider as data source. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_5.adoc b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_5.adoc new file mode 100644 index 0000000..e15f04e --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/repeaters/repeaters_5.adoc @@ -0,0 +1,8 @@ + + + +In this chapter we have explored the built-in set of components called repeaters which are designed to repeat their own markup in output to display a set of items. We have started with component _RepeatingView_ which can be used to repeat a simple markup fragment. + +Then, we have seen components _ListView_ and _RefreshingView_ which should be used when the markup to repeat contains nested components to populate. + +Finally, we have discussed those repeaters that support data paging and that are called pageable repeaters. We ended the chapter looking at an example where a pageable repeater is used with panel PagingNavigator to make its dataset navigable by the user. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/requestProcessing.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing.adoc new file mode 100644 index 0000000..64aaaab --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/requestProcessing.adoc @@ -0,0 +1,5 @@ + +Although Wicket was born to provide a reliable and comprehensive object oriented abstraction for web development, sometimes we might need to work directly with ârawâ web entities such as user session, web request, query parameters, and so on. For example this is necessary if we want to store an arbitrary parameter in the user session. + +Wicket provides wrapper classes that allow us to easily access to web entities without the burden of using the low-level APIs of Java Servlet Specification. However it will always be possible to access standard classes (like HttpSession, HttpServletRequest, etc...) that lay under our Wicket application. +This chapter will introduce these wrapper classes and it will explain how Wicket uses them to handle the web requests initiated by the user's browser. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_1.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_1.adoc new file mode 100644 index 0000000..6cbf9da --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_1.adoc @@ -0,0 +1,6 @@ + + + +Beside configuring and initializing our application, the Application class is responsible for creating the internal entities used by Wicket to process a request. These entities are instances of the following classes: RequestCycle, Request, Response and Session. + +The next paragraphs will illustrate each of these classes, explaining how they are involved into request processing. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc new file mode 100644 index 0000000..24ec9e0 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc @@ -0,0 +1,6 @@ + + + +The _Request_ and _Response_ classes are located in package _org.apache.wicket.request_ and they provide an abstraction of the concrete request and response used by our web application. + +Both classes are declared as abstract but if our application class inherits from _WebApplication_ it will use their sub classes _ServletWebRequest_ and _ServletWebResponse_, both of them located inside the package _org.apache.wicket.protocol.http.servlet.ServletWebRequest_ and _ServletWebResponse_ wrap respectively a _HttpServletRequest_ and a _HttpServletResponse_ object. If we need to access to these low-level objects we can call _Request_'s method _getContainerRequest()_ and _Response_'s method _getContainerResponse()_. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_3.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_3.adoc new file mode 100644 index 0000000..1868ee7 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_3.adoc @@ -0,0 +1,94 @@ + + + +Class _org.apache.wicket.request.cycle.RequestCycle_ is the entity in charge of serving a web request. Our application class creates a new _RequestCycle_ on every request with its method _createRequestCycle(request, response)_. + +Method _createRequestCycle_ is declared as final, so we can't override it to return a custom subclass of _RequestCycle_. Instead, we must build a request cycle provider implementing interface _org.apache.wicket.IRequestCycleProvider_, and then we must tell our application class to use it via the _setRequestCycleProvider_ method. + +The current running request cycle can be retrieved at any time by calling its static method _RequestCycle.get()_. Strictly speaking this method returns the request cycle associated with the current (or local) thread, which is the thread that is serving the current request. A similar _get()_ method is also implemented in classes _org.apache.wicket.Application_ (as we have seen in <<helloWorld.adoc#_configuration_of_wicket_applications,paragraph 4.2.2>>) and _org.apache.wicket.Session_ in order to get the application and the session in use by the current thread. + +NOTE: The implementation of the get method takes advantage of the standard class _java.lang.ThreadLocal_. See its JavaDoc for an introduction to local-thread variables. + +Class _org.apache.wicket.Component_ provides the _getRequestCycle()_ method which is a convenience method that internally invokes _RequestCycle.get()_: + +[source,java] +---- +public final RequestCycle getRequestCycle() { + return RequestCycle.get(); +} +---- + +=== RequestCycle and request processing + +NOTE: This paragraph will provide just the basic informations about what happens behind the scenes of request processing. When you work with Wicket it's unlikely to have a need for customizing this process, so we won't cover this topic in detail. + +In order to process a request, _RequestCycle_ delegates the task to another entity which implements interface _org.apache.wicket.request.IRequestHandler_. There are different implementations of this interface, each suited for a particular type of requested resource (a page to render, an AJAX request, an URL to an external page, etc.). + +To resolve the right handler for a given HTTP request, the _RequestCycle_ uses a set of objects implementing the _org.apache.wicket.request.IRequestMapper_ interface. The mapping interface defines the _getCompatibilityScore(Request request)_ method which returns a score indicating how compatible the request mapper is for the current request. _RequestCycle_ will choose the mapper with the highest score and it will call its _mapRequest(Request request)_ method to get the proper handler for the given request. Once _RequestCycle_ has resolved a request handler, it invokes its method _respond(IRequestCycle requestCycle)_ to start request processing. + +The following sequence diagram recaps how a request handler is resolved by the _RequestCycle_: + +image::../img/request-cycle-handler.png[] + +Developers can create additional implementations of IRequestMapper and add them to their application via the mount(IRequestMapper mapper) method of the WebApplication class. In paragraph 10.6 we will see how Wicket uses this method to add built-in mappers for mounted pages. + +=== Generating URL with the urlFor and mapUrlFor methods + +The RequestCycle is also responsible for generating the URL value (as CharSequence) for the following entities: + +* a page class, via the _urlFor(Class<C> pageClass, PageParameters parameters)_ method +* an IRequestHandler via the _urlFor(IRequestHandler handler)_ method +* a ResourceReference via the _urlFor(ResourceReference reference, PageParameters params)_ method (resource entities will be introduced in +<<_resource_management_with_wicket,chapter 19>>). + +The overloaded _urlFor_ method from above also has a corresponding version that returns an instance of _org.apache.wicket.request.Url_ instead of a _CharSequence_. This version has the prefix 'map' in its name (i.e. it has _mapUrlFor_ as full name). + +=== Method setResponsePage + +The _RequestCycle_ class contains the implementation of the _setResponsePage_ method we use to redirect a user to a specific page (see <<helloWorld.adoc#_wicket_links,paragraph 4.4>>). The namesake method of class _org.apache.wicket.Component_ is just a convenience method that internally invokes the actual implementation on current request cycle: + +[source,java] +---- +public final void setResponsePage(final Page page) { + getRequestCycle().setResponsePage(page); +} +---- + +=== RequestCycle's hook methods and listeners + +The RequestCycle comes with some hook methods which can be overridden to perform custom actions when request handling reaches a specific stage. These methods are: +* *onBeginRequest():* called when the RequestCycle is about to start handling the request. +* *onEndRequest():* called when the RequestCycle has finished to handle the request +* *onDetach():* called after the request handling has completed and the RequestCycle is about to be detached from its thread. The default implementation of this method invokes detach() on the current session (the Session class will be shortly discussed in paragraph 9.4). + +Methods onBeforeRequest and onEndRequest can be used if we need to execute custom actions before and after business code is executed, such as opening a Hibernate/JPA session and closing it when code has terminated. + +A more flexible way to interact with the request processing is to use the listener interface _org.apache.wicket.request.cycle.IRequestCycleListener_. In addition to the three methods already seen for RequestCycle, this interface offers further hooks into request processing: +* *onBeginRequest(RequestCycle cycle):* (see the description above) +* *onEndRequest(RequestCycle cycle):* (see the description above) +* *onDetach(RequestCycle cycle):* (see the description above) +* *onRequestHandlerResolved(RequestCycle cycle, IRequestHandler handler):* called when an IRequestHandler has been resolved. +* *onRequestHandlerScheduled(RequestCycle cycle, IRequestHandler handler):* called when an IRequestHandler has been scheduled for execution. +* *onRequestHandlerExecuted(RequestCycle cycle, IRequestHandler handler):* called when an IRequestHandler has been executed. +* *onException(RequestCycle cycle, Exception ex):* called when an exception has been thrown during request processing. +* *onExceptionRequestHandlerResolved(RequestCycle rc, IRequestHandler rh, Exception ex):* called when an IRequestHandler has been resolved and will be used to handle an exception. +* *onUrlMapped(RequestCycle cycle, IRequestHandler handler, Url url):* called when an URL has been generated for an IRequestHandler object. + +To use the request cycle listeners we must add them to our application which in turn will pass them to the new _RequestCycle_'s instances created with _createRequestCycle_ method: + +[source,java] +---- +@Override +public void init() { + + super.init(); + + IRequestCycleListener myListener; + //listener initialization... + getRequestCycleListeners().add(myListener) +} +---- + +The _getRequestCycleListeners_ method returns an instance of class _org.apache.wicket.request.cycle.RequestCycleListenerCollection_. This class is a sort of typed collection for _IRequestCycleListener_ and it also implements the http://en.wikipedia.org/wiki/Composite_pattern[Composite pattern] . + + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc new file mode 100644 index 0000000..3e30614 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc @@ -0,0 +1,162 @@ + + + +In Wicket we use class _org.apache.wicket.Session_ to handle session-relative informations such as client informations, session attributes, session-level cache (seen in paragraph 8.2), etc... + +In addition, we know from paragraph 8.1 that Wicket creates a user session to store versions of stateful pages. Similarly to what happens with RequestCycle, the new Session's instances are generated by the _Application_ class with the _newSession(Request request, Response response)_ method. This method is not declared as final, hence it can be overridden if we need to use a custom implementation of the Session class. + +By default if our custom application class is a subclass of WebApplication, method newSession will return an instance of class _org.apache.wicket.protocol.http.WebSession_. As we have mentioned talking about _RequestCycle_, also class Session provides a static _get()_ method which returns the session associated to the current thread. + +=== Session and listeners + +Similar to the _RequestCycle_, class _org.apache.wicket.Session_ also offers support for listener entities. With Session these entities must implement the callback interface _org.apache.wicket.ISessionListener_ which exposes only the _onCreated(Session session)_ method. As you might guess from its name, this method is called when a new session is created. Session listeners must be added to our application using a typed collection, just like we have done before with request cycle listeners: + +[source,java] +---- +@Override +public void init(){ + + super.init(); + + //listener initialization... + ISessionListener myListener; + //add a custom session listener + getSessionListeners().add(myListener) + +} +---- + +=== Handling session attributes + +The Session class handles session attributes in much the same way as the standard interface javax.servlet.http.HttpSession. The following methods are provided to create, read and remove session attributes: + +* *setAttribute(String name, Serializable value):* creates an attribute identified by the given name. If the session already contains an attribute with the same name, the new value will replace the existing one. The value must be a serializable object. +* *getAttribute(String name):* returns the value of the attribute identified by the given name, or null if the name does not correspond to any attribute. +* *removeAttribute(String name):* removes the attribute identified by the given name. + +By default class WebSession will use the underlying HTTP session to store attributes. Wicket will automatically add a prefix to the name of the attributes. This prefix is returned by the WebApplication's method getSessionAttributePrefix(). + +=== Accessing to the HTTP session + +If for any reason we need to directly access to the underlying HttpSession object, we can retrieve it from the current request with the following code: + +[source,java] +---- +HttpSession session = ((ServletWebRequest)RequestCycle.get() + .getRequest()).getContainerRequest().getSession(); +---- + +Using the raw session object might be necessary if we have to set a session attribute with a particular name without the prefix added by Wicket. Let's say for example that we are working with Tomcat as web server. One of the administrative tools provided by Tomcat is a page listing all the active user sessions of a given web application: + +image::../img/tomcat-admin-sessions.png[] + +Tomcat allows us to set the values that will be displayed in columns âGuessed localeâ and âGuessed User nameâ. One possible way to do this is to use session attributes named âLocaleâ and âuserNameâ but we can't create them via Wicket's Session class because they would not have exactly the name required by Tomcat. Instead, we must use the raw HttpSession and set our attributes on it: + +[source,java] +---- +HttpSession session = ((ServletWebRequest)RequestCycle.get(). + getRequest()).getContainerRequest().getSession(); + +session.setAttribute("Locale", "ENGLISH"); +session.setAttribute("userName", "Mr BadGuy"); +---- + +=== Temporary and permanent sessions + +Wicket doesn't need to store data into user session as long as the user visits only stateless pages. Nonetheless, even under these conditions, a temporary session object is created to process each request but it is discarded at the end of the current request. To know if the current session is temporary, we can use the isTemporary() method: + +[source,java] +---- +Session.get().isTemporary(); +---- + +If a session is not temporary (i.e. it is permanent), it's identified by an unique id which can be read calling the getId() method. This value will be null if the session is temporary. + +Although Wicket is able to automatically recognize when it needs to replace a temporary session with a permanent one, sometimes we may need to manually control this process to make our initially temporary session permanent. + +To illustrate this possible scenario let's consider project BindSessionExample where we have a stateless home page which sets a session attribute inside its constructor and then it redirects the user to another page which displays with a label the session attribute previously created. The code of the two pages is as follows: + +Home page: +[source,java] +---- +public class HomePage extends WebPage { + public HomePage(final PageParameters parameters) { + Session.get().setAttribute("username", "tommy"); + Session.get().bind(); + + setResponsePage(DisplaySessionParameter.class); + } +} +---- + +Target page: + +[source,java] +---- +public class DisplaySessionParameter extends WebPage { + + public DisplaySessionParameter() { + super(); + add(new Label("username", (String) Session.get().getAttribute("username"))); + } +} +---- + +Again, we kept page logic very simple to not over-bloat the example with unnecessary code. In the snippet above we have also bolded Session's bind() method which converts temporary session into a permanent one. If the home page has not invoked this method, the session with its attribute would have been discarded at the end of the request and the page DisplaySessionParameter would have displayed an empty value in its label. + +=== Discarding session data + +Once a user has finished using our web application, she must be able to log out and clean any session data. To be sure that a permanent session will be discarded at the end of the current request, class Session provides the invalidate() method. If we want to immediately invalidate a given session without waiting for the current request to complete, we can invoke the invalidateNow() method. + +WARNING: Remember that invalidateNow() will immediately remove any instance of components (and pages) from the session, meaning that once we have called this method we won't be able to work with them for the rest of the request process. + +=== Storing arbitrary objects with metadata + +JavaServer Pages Specification1 defines 4 scopes in which a page can create and access a variable. These scopes are: + +* *request:* variables declared in this scope can be seen only by pages processing the same request. The lifespan of these variables is (at most) equal to the one of the related request. They are discarded when the full response has been generated or when the request is forwarded somewhere else. +* *page:* variables declared in this scope can be seen only by the page that has created them. +* *session:* variables in session scope can be created and accessed by every page used in the same session where they are defined. +* *application:* this is the widest scope. Variables declared in this scope can be used by any page of a given web application. + +Although Wicket doesn't implement the JSP Specification (it is rather an alternative to it), it offers a feature called metadata which resembles scoped variables but is much more powerful. Metadata is quite similar to a Java Map in that it stores pairs of key-value objects where the key must be unique. In Wicket each of the following classes has its own metadata store: RequestCycle, Session, Application and Component. + +The key used for metadata is an instance of class _org.apache.wicket.MetaDataKey<T>_. To put an arbitrary object into metadata we must use the setMetaData method which takes two parameters as input: the key used to store the value and the value itself. If we are using metadata with classes Session or Component, data object must be serializable because Wicket serializes both session and component instances. This constraint is not applied to metadata of classes Application and RequestCycle which can contain a generic object. In any case, the type of data object must be compatible with the type parameter T specified by the key. + +To retrieve a previously inserted object we must use the _getMetaData(MetaDataKey<T> key)_ method. In the following example we set a _java.sql.Connection_ object in the application's metadata so it can be used by any page of the application: + +Application class code: +[source,java] +---- +public static MetaDataApp extends WebApplication{ + //Do some stuff... + /** + * Metadata key definition + */ + public static MetaDataKey<Connection> connectionKey = new MetaDataKey<Connection> (){}; + + /** + * Application's initialization + */ + @Override + public void init(){ + + super.init(); + Connection connection; + //connection initialization... + setMetaData(connectionKey, connection); + //Do some other stuff.. + + } +} +---- + +Code to get the object from the metadata: + +[source,java] +---- +Connection connection = Application.get().getMetaData(MetaDataApp.connectionKey); +---- + +Since MetaDataKey<T> class is declared as abstract, we must implement it with a subclass or with an anonymous class (like we did in the example above). + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_5.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_5.adoc new file mode 100644 index 0000000..30ef66a --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_5.adoc @@ -0,0 +1,40 @@ + +Wicket uses a number of custom exceptions during the regular running of an application. We have already seen _PageExpiredException_ raised when a page version is expired. Other examples of such exceptions are _AuthorizationException_ and _RestartResponseException_. We will see them later in the next chapters. +All the other exceptions raised during rendering phase are handled by an implementation of _org.apache.wicket.request.IExceptionMapper_ which by default is class _org.apache.wicket.DefaultExceptionMapper_. If we are working in DEVELOPMENT mode this mapper will redirect us to a page that shows the exception stacktrace (page _ExceptionErrorPage_). On the contrary, if application is running in DEPLOYMENT mode _DefaultExceptionMapper_ will display an internal error page which by default is _org.apache.wicket.markup.html.pages.InternalErrorPage_. +To use a custom internal error page we can change application settings like this: + +[source,java] +---- +getApplicationSettings().setInternalErrorPage(MyInternalErrorPage.class); +---- + +We can also manually set if Wicket should display the exception with _ExceptionErrorPage_ or if we want to use the internal error page or if we don't want to display anything at all when an unexpected exception is thrown: + +[source,java] +---- +//show default developer page +getExceptionSettings().setUnexpectedExceptionDisplay( ExceptionSettings.SHOW_EXCEPTION_PAGE ); +//show internal error page +getExceptionSettings().setUnexpectedExceptionDisplay( ExceptionSettings.SHOW_INTERNAL_ERROR_PAGE ); +//show no exception page when an unexpected exception is thrown +getExceptionSettings().setUnexpectedExceptionDisplay( ExceptionSettings.SHOW_NO_EXCEPTION_PAGE ); +---- + +Developers can also decide to use a custom exception mapper instead of _DefaultExceptionMapper_. To do this we must override _Application_'s method _getExceptionMapperProvider_: + +[source,java] +---- +@Override +public IProvider<IExceptionMapper> getExceptionMapperProvider() +{ + //... +} +---- + +The method returns an instance of _org.apache.wicket.util.IProvider_ that should return our custom exception mapper. + +=== Ajax requests + +To control the behavior in Ajax requests the application may use _org.apache.wicket.settings.ExceptionSettings1. setAjaxErrorHandlingStrategy(ExceptionSettings.AjaxErrorStrategy)_. By default if an error occurs during the +processing of an Ajax request Wicket will render the configured error page. By configuring _org.apache.wicket.settings.ExceptionSettings. AjaxErrorStrategy2.INVOKE_FAILURE_HANDLER_ as the default strategy the application will call the JavaScript _onFailure_ callback(s) instead. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_6.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_6.adoc new file mode 100644 index 0000000..fd937e7 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_6.adoc @@ -0,0 +1,8 @@ + + + +In this chapter we had a look at how Wicket internally handles a web request. Even if most of the time we won't need to customize this internal process, knowing how it works is essential to use the framework at 100%. + +Entities like Application and Session will come in handy again when we will tackle the topic of security in +<<_security_with_wicket,chapter 23>>. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources.adoc b/wicket-user-guide/src/main/asciidoc/resources.adoc new file mode 100644 index 0000000..fbe7212 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources.adoc @@ -0,0 +1,7 @@ + +One of the biggest challenge for a web framework is to offer an efficient and consistent mechanism to handle internal resources such as CSS/JavaScript files, picture files, pdf and so on. Resources can be static (like an icon used across the site) or dynamic (they can be generated on the fly) and they can be made available to users as a download or as a simple URL. + +In <<keepControl.adoc#_adding_header_contents_to_the_final_page,paragraph 6.6>> we have already seen how to add CSS and JavaScript contents to the header section of the page. In the first half of this chapter we will learn a more sophisticated technique that allows us to manage static resources directly from code and âpackâ them with our custom components. + +Then, in the second part of the chapter we will see how to implement custom resources to enrich our web application with more complex and dynamic functionalities. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_1.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_1.adoc new file mode 100644 index 0000000..92aa46e --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_1.adoc @@ -0,0 +1,11 @@ + + + +In Wicket a resource is an entity that can interact with the current request and response and It must implement interface _org.apache.wicket.request.resource.IResource_. This interface defines just method respond(IResource.Attributes attributes) where the nested class IResource. Attributes provides access to request, response and page parameters objects. + +Resources can be static or dynamic. Static resources don't entail any computational effort to be generated and they generally correspond to a resource on the filesystem. On the contrary dynamic resources are generated on the fly when they are requested, following a specific logic coded inside them. + +An example of dynamic resource is the built-in class CaptchaImageResource in package _org.apache.wicket.extensions.markup.html.captcha_ which generates a captcha image each time is rendered. + +As we will see in [paragraph 16.10|guide:resources_10], developers can build custom resources extending base class _org.apache.wicket.request.resource.AbstractResource_. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_10.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_10.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_10.adoc new file mode 100644 index 0000000..0147138 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_10.adoc @@ -0,0 +1,52 @@ + + + +In Wicket the best way to add dynamic functionalities to our application (such as csv export, a pdf generated on the fly, etc...) is implementing a custom resource. In this paragraph as example of custom resource we will build a basic RSS feeds generator which can be used to publish feeds on our site (project CustomResourceMounting). Instead of generating a RSS feed by hand we will use Rome framework and its utility classes. + +As hinted above in <<resources.adoc#_static_vs_dynamic_resources,paragraph 16.1>>, class _AbstractResource_ can be used as base class to implement new resources. This class defines abstract method _newResourceResponse_ which is invoked when the resource is requested. The following is the code of our RSS feeds generator: + +[source,java] +---- +public class RSSProducerResource extends AbstractResource { + + @Override + protected ResourceResponse newResourceResponse(Attributes attributes) { + ResourceResponse resourceResponse = new ResourceResponse(); + resourceResponse.setContentType("text/xml"); + resourceResponse.setTextEncoding("utf-8"); + + resourceResponse.setWriteCallback(new WriteCallback() + { + @Override + public void writeData(Attributes attributes) throws IOException + { + OutputStream outputStream = attributes.getResponse().getOutputStream(); + Writer writer = new OutputStreamWriter(outputStream); + SyndFeedOutput output = new SyndFeedOutput(); + try { + output.output(getFeed(), writer); + } catch (FeedException e) { + throw new WicketRuntimeException("Problems writing feed to response..."); + } + } + }); + + return resourceResponse; + } + // method getFeed()... +} +---- + +Method _newResourceResponse_ returns an instance of _ResourceResponse_ representing the response generated by the custom resource. Since RSS feeds are based on XML, in the code above we have set the type of the response to text/xml and the text encoding to utf-8. + +To specify the content that will be returned by our resource we must also provide an implementation of inner class _WriteCallback_ which is responsible for writing content data to response's output stream. In our project we used class SyndFeedOutput from Rome framework to write our feed to response. Method _getFeed()_ is just an utility method that generates a sample RSS feed (which is an instance of interface _com.sun.syndication.feed.synd.SyndFeed_). + +Now that we have our custom resource in place, we can use it in the home page of the project. The easiest way to make a resource available to users is to expose it with link component _ResourceLink_: + +[source,java] +---- +add(new ResourceLink("rssLink", new RSSProducerResource())); +---- + +In the next paragraphs we will see how to register a resource at application-level and how to mount it to an arbitrary URL. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_11.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_11.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_11.adoc new file mode 100644 index 0000000..7ad43b7 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_11.adoc @@ -0,0 +1,41 @@ + + + +Just like pages also resources can be mounted to a specific path. Class _WebApplication_ provides method _mountResource_ which is almost identical to _mountPage_ seen in <<urls.adoc#_generating_structured_and_clear_urls,paragraph 10.6.1>>: + +[source,java] +---- +@Override +public void init() { + super.init(); + //resource mounted to path /foo/bar + ResourceReference resourceReference = new ResourceReference("rssProducer"){ + RSSReaderResource rssResource = new RSSReaderResource(); + @Override + public IResource getResource() { + return rssResource; + }}; + mountResource("/foo/bar", resourceReference); +} +---- + +With the configuration above (taken from project _CustomResourceMounting_) every request to /foo/bar will be served by the custom resource built in the previous paragraph. + +Parameter placeholders are supported as well: + +[source,java] +---- +@Override +public void init() { + super.init(); + //resource mounted to path /foo with a required indexed parameter + ResourceReference resourceReference = new ResourceReference("rssProducer"){ + RSSReaderResource rssResource = new RSSReaderResource(); + @Override + public IResource getResource() { + return rssResource; + }}; + mountResource("/bar/${baz}", resourceReference); +} +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_12.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_12.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_12.adoc new file mode 100644 index 0000000..ac45594 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_12.adoc @@ -0,0 +1,33 @@ + + + +Resources can be added to a global registry in order to share them at application-level. Shared resources are identified by an application-scoped key and they can be easily retrieved at a later time using reference class _SharedResourceReference_. The global registry can be accessed with _Application_'s method _getSharedResources_. In the following excerpt of code (taken again from project _CustomResourceMounting_) we register an instance of our custom RSS feeds producer as application-shared resource: + +[source,java] +---- + //init application's method + @Override + public void init(){ + RSSProducerResource rssResource = new RSSProducerResource(); + // ... + getSharedResources().add("globalRSSProducer", rssResource); + } +---- + +Now to use an application-shared resource we can simply retrieve it using class _SharedResourceReference_ and providing the key previously used to register the resource: + +[source,java] +---- +add(new ResourceLink("globalRssLink", new SharedResourceReference("globalRSSProducer"))); +---- + +The URL generated for application shared resources follows the same pattern seen for package resources: + +_./wicket/resource/org.apache.wicket.Application/globalRSSProducer_ + +The last segment of the URL is the key of the resource while the previous segment contains the scope of the resource. For application-scoped resources the scope is always the fully qualified name of class _Application_. This should not be surprising since global resources are visible at application level (i.e. the scope is the application). + +NOTE: Package resources are also application-shared resources but they don't need to be explicitly registered. + +NOTE: Remember that we can get the URL of a resource reference using method _urlFor(ResourceReference resourceRef, PageParameters params )_ available with both class _RequestCycle_ and class _Component_. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_13.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_13.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_13.adoc new file mode 100644 index 0000000..13d5246 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_13.adoc @@ -0,0 +1,47 @@ + + + +Wicket loads application's resources delegating this task to a resource locator represented by interface _org.apache.wicket.core.util.resource.locator.IResourceStreamLocator_. To retrieve or modify the current resource locator we can use the getter and setter methods defined by setting class _ResourceSettings_: + +[source,java] +---- + //init application's method + @Override + public void init(){ + //get the resource locator + getResourceSettings().getResourceStreamLocator(); + //set the resource locator + getResourceSettings().setResourceStreamLocator(myLocator); + } +---- + +The default locator used by Wicket is class _ResourceStreamLocator_ which in turn tries to load a requested resource using a set of implementations of interface _IResourceFinder_. This interface defines method _find(Class class, String pathname)_ which tries to resolve a resource corresponding to the given class and path. + +The default implementation of _IResourceFinder_ used by Wicket is _ClassPathResourceFinder_ which searches for resources into the application class path. This is the implementation we have used so far in our examples. However some developers may prefer storing markup files and other resources in a separate folder rather than placing them side by side with Java classes. + +To customize resource loading we can add further resource finders to our application in order to extend the resource-lookup algorithm to different locations. Wicket already comes with two other implementations of IResourceFinder designed to search for resources into a specific folder on the file system. The first is class _Path_ and it's defined in package _org.apache.wicket.util.file_. The constructor of this class takes in input an arbitrary folder that can be expressed as a string path or as an instance of Wicket utility class _Folder_ (in package _org.apache.wicket.util.file_). The second implementation of interface _IResourceFinder_ is class _WebApplicationPath_ which looks into a folder placed inside webapp's root path (but not inside folder WEB-INF). + +Project CustomFolder4MarkupExample uses _WebApplicationPath_ to load the markup file and the resource bundle for its home page from a custom folder. The folder is called markupFolder and it is placed in the root path of the webapp. The following picture illustrates the file structure of the project: + +image::../img/package-structure-custom-folder.png[] + +As we can see in the picture above, we must preserve the package structure also in the custom folder used as resource container. The code used inside application class to configure WebApplicationPath is the following: + +[source,java] +---- +@Override +public void init() +{ + getResourceSettings().getResourceFinders().add( + new WebApplicationPath(getServletContext(), "markupFolder")); +} +---- + +Method getResourceFinders() defined by setting class ResourceSettings returns the list of resource finders defined in our application. The constructor of WebApplicationPath takes in input also an instance of standard interface javax.servlet.ServletContext which can be retrieved with WebApplication's method getServletContext(). + +NOTE: By default, if resource files can not be found inside application classpath, Wicket will search for them inside âresourcesâ folder. You may have noted this folder in the previous picture. It is placed next to the folder âjavaâ containing our source files: + +image::../img/package-structure-resource-folder.png[] + +This folder can be used to store resource files without writing any configuration code. +
