http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc b/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc new file mode 100644 index 0000000..e17bd3b --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/testing/testing_3.adoc @@ -0,0 +1,67 @@ + + + +If we need to test component markup at a more fine-grained level, we can use class _TagTester_ from package _org.apache.wicket.util.tester_. + +This test class allows to check if the generated markup contains one or more tags having a given attribute with a given value. TagTester can not be directly instantiated but it comes with three factory methods that return one or more TagTester matching the searching criteria. In the following test case (from project _TagTesterExample_) we retrieve the first tag of the home page (a <span> tag) having attribute class equal to myClass: + +*HomePage markup:* + +[source,html] +---- +<html xmlns:wicket="http://wicket.apache.org";> + <head> + <meta charset="utf-8" /> + <title></title> + </head> + <body> + <span class="myClass"></span> + <div class="myClass"></div> + </body> +</html> +---- + +*Test method:* + +[source,java] +---- +@Test +public void homePageMarkupTest() +{ + //start and render the test page + tester.startPage(HomePage.class); + //retrieve response's markup + String responseTxt = tester.getLastResponse().getDocument(); + + TagTester tagTester = TagTester.createTagByAttribute(responseTxt, "class", "myClass"); + + Assert.assertNotNull(tagTester); + Assert.assertEquals("span", tagTester.getName()); + + List<TagTester> tagTesterList = TagTester.createTagsByAttribute(responseTxt, + "class", "myClass", false); + + Assert.assertEquals(2, tagTesterList.size()); +} +---- + +The name of the tag found by TagTester can be retrieved with its method getName. Method _createTagsByAttribute_ returns all the tags that have the given value on the class attribute. In the code above we have used this method to test that our markup contains two tags having attribute class equal to myClass. + +Another utility class that comes in handy when we want to test components markup is _ComponentRenderer_ in package _org.apache.wicket.core.util.string_. The purpose of this class is to render a page or a component in isolation with its static methods _renderComponent_ and _renderPage_. Both methods return the generated markup as _CharSequence_: + +[source,java] +---- +@Test +public void customComponentMarkupTest() +{ + //instantiate MyComponent + MyComponent myComponent = //... + + //render and save component markup + String componentMarkup = ComponentRenderer.renderComponent(myComponent); + + //perform test operations + //... +} +---- +
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/testing/testing_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/testing/testing_4.adoc b/wicket-user-guide/src/main/asciidoc/testing/testing_4.adoc new file mode 100644 index 0000000..e8ff64f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/testing/testing_4.adoc @@ -0,0 +1,12 @@ + + + +With a component-oriented framework we can test our pages and components as we use to do with any other Java entity. Wicket offers a complete support for writing testing code, offering built-in tools to test nearly all the elements that build up our applications (pages, containers, links, behaviors, etc...). + +The main entity discussed in this chapter has been class _WicketTester_ which can be used to write unit tests and acceptance tests for our application, but we have also seen how to test forms with _FormTester_ and how to inspect markup with _TagTester_. + +In addition to learning how to use the utility classes provided by Wicket for testing, we have also experienced the innovative approach of Wicket to web testing that allows to test components in isolation without the need of running our tests with a web server and depending only on JUnit as testing framework. + + + + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/testingspring.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/testingspring.adoc b/wicket-user-guide/src/main/asciidoc/testingspring.adoc new file mode 100644 index 0000000..54a0662 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/testingspring.adoc @@ -0,0 +1,3 @@ + +Since the development of many web applications is mostly based on the Spring framework for dependency injection and application configuration in general, it's especially important to get these two frameworks running together smoothly not only when deployed on a running server instance itself but rather during the execution of JUnit based integration tests as well. Thanks to the _WicketTester_ API provided by the Wicket framework itself, one can easily build high-quality web applications while practicing test driven development and providing a decent set of unit and integration tests to be executed with each build. As already mentioned previously, integration and configuration of our web applications is based on a lightweight Spring container meaning that the integration of Spring's _ApplicationContext_ and a WicketTester API is essential to get our integration tests running. In order to explain how to achieve that integration in an easy and elegant fashion in your integration test environment, we'll first take a look at a configuration of these 2 framework beauties in a runtime environment. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_1.adoc b/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_1.adoc new file mode 100644 index 0000000..b77358f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_1.adoc @@ -0,0 +1,94 @@ + + + +In order to get the Wicket framework up to speed when your server is up and running, you usually configure a _WicketFilter_ instance in your web application deployment descriptor file (_web.xml_) while passing it a single init parameter called _applicationClassName_ that points to your main implementation class extending _org.apache.wicket.protocol.http.WebApplication_ where all of your application-wide settings and initialization requirements are dealt with: + +[source,xml] +---- +<filter> + <filter-name>wicketfilter</filter-name> + <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class> + <init-param> + <param-name>applicationClassName</param-name> + <param-value>com.comsysto.webapp.MyWebApplication</param-value> + </init-param> +</filter> +---- + +In case you want to get Wicket application up and running while leaving the application configuration and dependency injection issues to the Spring container, the configuration to be provided within the deployment descriptor looks slightly different though: + +[source,xml] +---- +<web-app> + <filter> + <filter-name>wicketfilter</filter-name> + <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class> + <init-param> + <param-name>applicationFactoryClassName</param-name> + <param-value>org.apache.wicket.spring.SpringWebApplicationFactory</param-value> + </init-param> + </filter> + <listener> + <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> + </listener> + <context-param> + <param-name>contextConfigLocation</param-name> + <param-value>/WEB-INF/applicationContext.xml</param-value> + </context-param> +</web-app> +---- + +The additional configuration part containing listener and context parameter definition is a usual Spring container related configuration detail. ContextLoaderListener is an implementation of standard Servlet API ServletContextListener interface provided by the Spring framework itself and is responsible for looking up an according bean definition file(s) specified by the context param above and creating an ApplicationContext instance during servlet context initialization accordingly. When integrating an ApplicationContext instance with Wicket, one of the beans defined in the above mentioned Spring bean definition file has to be your own specific extension of _org.apache.wicket.protocol.http.WebApplication_. You can either define a suitable bean in the bean definition file itself: + +[source,xml] +---- +<beans> + <bean id="myWebApp" class="com.comsysto.webapp.MyWebApplication"/> +</beans> +---- + +or use powerful classpath scanning feature of the Spring framework and annotate the MyWebApplication implementation with the appropriate _\_Component_ annotation accordingly while enabling the Spring container to scan the according package(s) of your application for relevant bean definitions: + +[source,xml] +---- +<beans> + <context:component-scan base-package="com.comsysto.webapp" /> + <context:component-scan base-package="com.comsysto.webapp.service" /> + <context:component-scan base-package="com.comsysto.webapp.repository" /> +</beans> +---- + +Either way, if everything goes well, you'll get a pre-configured ApplicationContext all set up during the startup of your web container. One of the beans in the ApplicationContext will be your own extension of Wicket's WebApplication type. SpringWebApplicationFactory implementation provided by the Wicket framework itself that you have defined as the _applicationFactoryClassName_ in the configuration of your WicketFilter will then be used in order to retrieve that very same WebApplication bean out of your Spring ApplicationContext. The Factory expects one and only one extension of Wicket's very own WebApplication type to be found within the ApplicationContext instance at runtime. If no such bean or more than one bean extending WebApplication is found in the given ApplicationContext an according IllegalStateException will be raised and initialization of your web application will fail: + +[source,java] +---- +Map<?,?> beans = BeanFactoryUtils.beansOfTypeIncludingAncestors(ac,WebApplication.class, false, false); +if (beans.size() == 0) +{ + throw new IllegalStateException("bean of type [" + WebApplication.class.getName() + + "] not found"); +} +if (beans.size() > 1) +{ + throw new IllegalStateException("more than one bean of type [" + + WebApplication.class.getName() + "] found, must have only one"); +} +---- + +After the WebApplication bean has been successfully retrieved from the ApplicationContext via SpringWebApplicationFactory, WicketFilter will then, as part of its own initialization process, trigger both internalInit() and init() methods of the WebApplication bean. The latter one is the exact spot where the last piece of the runtime configuration puzzle between Wicket and Spring is to be placed : + +[source,java] +---- +@Component +public class MyWebApplication extends WebApplication { + @Override + protected void init() { + super.init(); + + getComponentInstantiationListeners().add(new SpringComponentInjector(this)); + } + +} +---- + +SpringComponentInjector provided by the Wicket framework enables you to get dependencies from the ApplicationContext directly injected into your Wicket components by simply annotating these with the according _\_SpringBean_ annotation. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_2.adoc b/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_2.adoc new file mode 100644 index 0000000..f72d4ec --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_2.adoc @@ -0,0 +1,139 @@ + + + +One of the main features of Apache Wicket framework is the ability to easily write and run plain unit tests for your Pages and all other kinds of Components that even include the verification of the rendering process itself by using JUnit framework and the WicketTester API only. When using Spring framework for application configuration together with Wicket, as we do, you can even use the same tools to easily write and run full blown integration tests for your web application as well. All you have to do is use http://docs.spring.io/spring/docs/3.0.x/spring-framework-reference/html/testing.html#testcontext-framework[Spring's TestContext] framework additionally to configure and run your JUnit based integration tests. The Spring Framework provides a set of Spring specific annotations that you can use in your integration tests in conjunction with the TestContext framework itself in order to easily configure an according ApplicationContext instance for your tests as well as for appropria te transaction management before, during and after your test execution. Following code snippet represents a simple JUnit 4 based test case using Spring's specific annotations in order to initialize an ApplicationContext instance prior to executing the test itself: + +[source,java] +---- +@RunWith(SpringJUnit4ClassRunner.class) +@ContextConfiguration(locations = {"classpath:WEB-INF/applicationContext.xml"}) +@TransactionConfiguration(transactionManager = "txManager", defaultRollback = false) +public class LoginPageTest { + + private WicketTester tester; + + @Autowired + private ApplicationContext ctx; + + @Autowired + private MyWebApplication myWebApplication; + + @Before + public void setUp() { + tester = new WicketTester(myWebApplication); + } + + @Test + @Transactional + @Rollback(true) + public void testRenderMyPage() { + tester.startPage(LoginPage.class); + tester.assertRenderedPage(LoginPage.class); + tester.assertComponent("login", LoginComponent.class); + } +} +---- + +By defining three annotations on the class level (see code snippet above) in your test, Spring's TestContext framework takes care of preparing and initializing an ApplicationContext instance having all the beans defined in the according Spring context file as well as the transaction management in case your integration test includes some kind of database access. Fields marked with _\_Autowired_ annotation will be automatically dependency injected as well so that you can easily access and use these for your testing purposes. Since MyWebApplication, which extends Wicket's WebApplication type and represents the main class of our web application, is also a bean within the ApplicationContext managed by Spring, it will also be provided to us by the test framework itself and can be easily used in order to initialize a WicketTester instance later on during the execution of the test's setUp() method. With this kind of simple, annotation based test configuration we are able to run an integrati on test that verifies whether a LoginPage gets started and initialized, whether the rendering of the page runs smoothly and whether the page itself contains a LoginComponent that we possibly need in order to process user's login successfully. + +When you run this test though, you'll unfortunately get the following exception raised: + +[source,java] +---- +java.lang.IllegalStateException: No WebApplicationContext found: no ContextLoaderListener registered? + at org.springframework.web.context.support.WebApplicationContextUtils. + getRequiredWebApplicationContext(WebApplicationContextUtils.java:84) + at org.apache.wicket.spring.injection.annot. + SpringComponentInjector.<init>(SpringComponentInjector.java:72) + at com.comsysto.serviceplatform.uiwebapp.MyWebApplication. + initializeSpringComponentInjector(MyWebApplication.java:59) + at com.comsysto.serviceplatform.uiwebapp.MyWebApplication. + init(MyWebApplication.java:49) + at org.apache.wicket.protocol.http.WicketFilter. + init(WicketFilter.java:719) + at org.apache.wicket.protocol.http.MockWebApplication. + <init>(MockWebApplication.java:168) + at org.apache.wicket.util.tester.BaseWicketTester. + <init>(BaseWicketTester.java:219) + at org.apache.wicket.util.tester.WicketTester. + <init>(WicketTester.java:325) + at org.apache.wicket.util.tester.WicketTester. + <init>(WicketTester.java:308) +---- + +As you can see above, the Exception gets raised during the initialization of the _WicketTester_ instance even before the actual test method gets executed. Even though we have applied rather cool and simple annotation based test configuration already described and passed in perfectly well prepared ApplicationContext instance to the WicketTester instance in the constructor, somewhere down the rabbit hole someone complained that no WebApplicationContext instance could have been found which seems to be required in order to initialize the WicketTester properly. + +image::../img/description-of-illegalstate.jpg[] + +The problem that we run against here is due to the fact that SpringComponentInjector during its own initialization is trying to get hold of an according Spring's ApplicationContext instance that would normally be there in a runtime environment but does not find any since we are running in a test environment currently. SpringComponentInjector delegates to Spring's own WebApplicationContextUtils class to retrieve the instance of ApplicationContext out of the ServletContext which is perfectly fine for a runtime environment but is unfortunately failing in a test environment: + +[source,java] +---- +public static WebApplicationContext getRequiredWebApplicationContext(ServletContext sc) + throws IllegalStateException { + + WebApplicationContext wac = getWebApplicationContext(sc); + if (wac == null) { + throw new IllegalStateException("No WebApplicationContext found: no ContextLoaderListener registered?"); + } + return wac; +} +---- + +If you still remember we defined a ContextLoaderListener in our web.xml file as part of the configuration of our runtime environment that makes sure an according WebApplicationContext instance gets initialized and registered against the ServletContext properly. Luckily, this problem can easily be solved if we slightly change the way we initialize SpringComponentInjector in our main MyWebApplication class. Apart from the constructor that we have used so far, there is another constructor in the SpringComponentInjector class that expects the caller to provide it with an according ApplicationContext instance rather than trying to resolve one on its own: + +[source,java] +---- +public SpringComponentInjector(WebApplication webapp, ApplicationContext ctx, + boolean wrapInProxies) +{ + if (webapp == null) + { + throw new IllegalArgumentException("Argument [[webapp]] cannot be null"); + } + + if (ctx == null) + { + throw new IllegalArgumentException("Argument [[ctx]] cannot be null"); + } + + // store context in application's metadata ... + webapp.setMetaData(CONTEXT_KEY, new ApplicationContextHolder(ctx)); + + // ... and create and register the annotation aware injector + InjectorHolder.setInjector(new AnnotSpringInjector(new ContextLocator(), wrapInProxies)); +} +---- + +In order to use this constructor instead of the one we used previously, we now obviously need to get hold of the _ApplicationContext_ instance on our own in our _MyWebApplication_ implementation. The easiest way to do this is to use Spring's own concept of http://docs.spring.io/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-aware[lifecycle callbacks] provided to the beans managed by the Spring container. Since our _MyWebApplication_ is also a bean managed by the Spring container at runtime (enabled by the classpath scanning and _\_Component_ annotation on a type level), we can declare it to implement _ApplicationContextAware_ interface which ensures that it gets provided with the _ApplicationContext_ instance that it runs in by the Spring container itself during startup. + +[source,java] +---- +public interface ApplicationContextAware { + + void setApplicationContext(ApplicationContext applicationContext) throws BeansException; + +} +---- + +So the relevant parts of _MyWebApplication_ type will now look something like the following code snippet: + +[source,java] +---- +@Component +public class MyWebApplication extends WebApplication implements ApplicationContextAware { + @Override + protected void init() { + addComponentInstantiationListener(new SpringComponentInjector(this, ctx, true)); + } + + public void setApplicationContext(ApplicationContext applicationContext) throws BeansException { + this.ctx = applicationContext; + } +} +---- + +For additional clarification of how _MyWebApplication_ now relates to both Wicket and Spring framework here is an according class diagram: + +image::../img/mywebapp-class-diagramm.jpg[] + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_3.adoc b/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_3.adoc new file mode 100644 index 0000000..08ba48e --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/testingspring/testingspring_3.adoc @@ -0,0 +1,4 @@ + + + +With the configuration outlined above, no additional modifications are required to the test itself. It's going to turn green now. This way you can use exactly the same Spring context configuration that you'd use in your runtime environment for running your JUnit based integration tests as well. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/urls.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/urls.adoc b/wicket-user-guide/src/main/asciidoc/urls.adoc new file mode 100644 index 0000000..069c83b --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/urls.adoc @@ -0,0 +1,7 @@ + +Up to now we used component Link to move from a page to another and we have seen that it is quiet similar to a âclickâ event handler (see <<helloWorld.adoc#_wicket_links,paragraph 4.4>>). + +However this component alone is not enough to build all possible kinds of links we may need in our pages. Therefore, Wicket offers other link components suited for those tasks which can not be accomplished with a basic Link. + +Besides learning new link components, in this chapter we will also see how to customize the page URL generated by Wicket using the encoding facility provided by the framework and the page parameters that can be passed to a target page. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/urls/urls_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/urls/urls_1.adoc b/wicket-user-guide/src/main/asciidoc/urls/urls_1.adoc new file mode 100644 index 0000000..af25221 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/urls/urls_1.adoc @@ -0,0 +1,115 @@ + + + +A common practice in web development is to pass data to a page using query string parameters (like ?paramName1=paramValu1¶mName2=paramValue2...). Wicket offers a more flexible and object oriented way to do this with models (we will see them in the next chapter). However, even if we are using Wicket, we still need to use query string parameters to exchange data with other Internet-based services. Consider for example a classic confirmation page which is linked inside an email to let users confirm important actions like password changing or the subscription to a mailing list. This kind of page usually expects to receive a query string parameter containing the id of the action to confirm. + +Query string parameters can also be referred to as named parameters. In Wicket they are handled with class _org.apache.wicket.request.mapper.parameter.PageParameters_. Since named parameters are basically name-value pairs, PageParameters works in much the same way as Java Map providing two methods to create/modify a parameter (add(String name, Object value) and set(String name, Object value)), one method to remove an existing parameter (remove(String name)) and one to retrieve the value of a given parameter (get(String name)) . Here is a snippet to illustrate the usage of PageParameters: + +[source,java] +---- +PageParameters pageParameters = new PageParameters(); +//add a couple of parameters +pageParameters.add("name", "John"); +pageParameters.add("age", 28); +//retrieve the value of 'age' parameter +pageParameters.get("age"); +---- + +Now that we have seen how to work with page parameters, let's see how to use them with our pages. + +=== PageParameters and bookmarkable pages + +Base class Page comes with a constructor which takes as input a PageParameters instance. If we use this superclass constructor in our page, PageParameters will be used to build the page URL and it can be retrieved at a later time with the Page's getPageParameters() method. + +In the following example taken from the PageParametersExample project we have a home page with a link to a second page that uses a version of setResponsePage method that takes as input also a PageParameters to build the target page (named PageWithParameters). The code for the link and for the target page is the following: + +Link code: + +[source,java] +---- +add(new Link("pageWithIndexParam") { + + @Override + public void onClick() { + + PageParameters pageParameters = new PageParameters(); + pageParameters.add("foo", "foo"); + pageParameters.add("bar", "bar"); + + setResponsePage(PageWithParameters.class, pageParameters); + } + +}); +---- + +Target page code: + +[source,java] +---- +public class PageWithParameters extends WebPage { + //Override superclass constructor + public PageWithParameters(PageParameters parameters) { + super(parameters); + } + } +---- + +The code is quite straightforward and itâs more interesting to look at the URL generated for the target page: + +[source,html] +---- +<app root>/PageParametersExample/wicket/bookmarkable/ + org.wicketTutorial.PageWithParameters?foo=foo&bar=bar +---- + +At first glance the URL above could seem a little weird, except for the last part which contains the two named parameters used to build the target page. + +The reason for this âstrangeâ URL is that, as we explained in paragraph 8.3, when a page is instantiated using a constructor with no argument or using a constructor that accepts only a PageParameters, Wicket will try to generate a static URL for it, with no session-relative informations. This kind of URL is called bookmarkable because it can be saved by the users as a bookmark and accessed at a later time. + +A bookmarkable URL is composed by a fixed prefix (which by default is bookmarkable) and the qualified name of the page class (org.wicketTutorial.PageWithParameters in our example). Segment wicket is another fixed prefix added by default during URL generation. In paragraph 10.6 we will see how to customize fixed prefixes with a custom implementation of IMapperContext interface. + +=== Indexed parameters + +Besides named parameters, Wicket also supports indexed parameters. These kinds of parameters are rendered as URL segments placed before named parameters. Let's consider for example the following URL: + +[source,html] +---- +<application path>/foo/bar?1&baz=baz +---- + +The URL above contains two indexed parameters (foo and bar) and a query string consisting of the page id and a named parameter (baz). Just like named parameters also indexed parameters are handled by the PageParameters class. The methods provided by PageParameters for indexed parameters are set(int index, Object object) (to add/modify a parameter), remove(int index)(to remove a parameter) and get(int index) (to read a parameter). + +As their name suggests, indexed parameters are identified by a numeric index and they are rendered following the order in which they have been added to the PageParameters. The following is an example of indexed parameters: + +[source,java] +---- +PageParameters pageParameters = new PageParameters(); +//add a couple of parameters +pageParameters.set(0, "foo"); +pageParameters.set(1, "bar"); +//retrieve the value of the second parameter ("bar") +pageParameters.get(1); +---- + +Project PageParametersExample comes also with a link to a page with both indexed parameters and a named parameter: + +[source,java] +---- +add(new Link("pageWithNamedIndexParam") { + + @Override + public void onClick() { + + PageParameters pageParameters = new PageParameters(); + pageParameters.set(0, "foo"); + pageParameters.set(1, "bar"); + pageParameters.add("baz", "baz"); + + setResponsePage(PageWithParameters.class, pageParameters); + } + +}); +---- + +The URL generated for the linked page (PageWithParameters) is the one seen at the beginning of the paragraph. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/urls/urls_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/urls/urls_2.adoc b/wicket-user-guide/src/main/asciidoc/urls/urls_2.adoc new file mode 100644 index 0000000..a03ddb9 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/urls/urls_2.adoc @@ -0,0 +1,11 @@ + + + +A link to a bookmarkable page can be built with the link component _org.apache.wicket.markup.html.link.BookmarkablePageLink_: + +[source,java] +---- +BookmarkablePageLink bpl=new BookmarkablePageLink(PageWithParameters.class, pageParameters); +---- + +The specific purpose of this component is to provide an anchor to a bookmarkable page, hence we don't have to implement any abstract method like we do with Link component. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc b/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc new file mode 100644 index 0000000..ca52430 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/urls/urls_3.adoc @@ -0,0 +1,75 @@ + + + +Bookmarkable pages can be linked directly inside markup files without writing any Java code. Using <wicket:link> tag we ask Wicket to automatically add bookmarkable links for the anchors wrapped inside it. Here is an example of usage of <wicket:link> tag taken from the home page of the project BookmarkablePageAutoLink: + +[source,html] +---- +<!DOCTYPE html> +<html xmlns:wicket="http://wicket.apache.org";> + <head> + <meta charset="utf-8" /> + <title>Apache Wicket Quickstart</title> + </head> + <body> + <div id="bd"> + <wicket:link> + <a href="HomePage.html">HomePage</a><br/> + <a href="anotherPackage/SubPackagePage.html">SubPackagePage</a> + </wicket:link> + </div> + </body> +</html> +---- + +The key part of the markup above is the href attribute which must contain the package-relative path to a page. The home page is inside package org.wicketTutorial which in turns contains the sub package anotherPackage. This package hierarchy is reflected by the href attributes: in the first anchor we have a link to the home page itself while the second anchor points to page SubPackagePage which is placed into sub package anotherPackage. Absolute paths are supported as well and we can use them if we want to specify the full package of a given page. For example the link to SubPackagePage could have been written in the following (more verbose) way: + +[source,html] +---- +<a href="/org/wicketTutorial/anotherPackage/SubPackagePage.html"> SubPackagePage</a> +---- + +If we take a look also at the markup of SubPackagePage we can see that it contains a link to the home page which uses the parent directory selector (relative path): + +[source,html] +---- +<!DOCTYPE html> +<html xmlns:wicket="http://wicket.apache.org";> + <head> + <meta charset="utf-8" /> + <title>Apache Wicket Quickstart</title> + </head> + <body> + <div id="bd"> + <wicket:link> + <a href="../HomePage.html">HomePage</a><br/> + <a href="SubPackagePage.html">SubPackagePage</a> + </wicket:link> + </div> + </body> +</html> +---- + +Please note that any link to the current page (aka self link) is disabled. For example in the home page the self link is rendered like this: + +[source,html] +---- +<span><em>HomePage</em></span> +---- + +The markup used to render disabled links can be customized using the markup settings (class org.apache.wicket.settings.MarkupSettings) available in the application class: + +[source,java] +---- +@Override +public void init() +{ + super.init(); + //wrap disabled links with <b> tag + getMarkupSettings().setDefaultBeforeDisabledLink("<b>"); + getMarkupSettings().setDefaultAfterDisabledLink("</b>"); +} +---- + +The purpose of <wicket:link> tag is not limited to just simplifying the usage of bookmarkable pages. As we will see in chapter 13, this tag can also be adopted to manage web resources like pictures, CSS files, JavaScript files and so on. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/urls/urls_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/urls/urls_4.adoc b/wicket-user-guide/src/main/asciidoc/urls/urls_4.adoc new file mode 100644 index 0000000..c4c7f98 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/urls/urls_4.adoc @@ -0,0 +1,58 @@ + + + +Since Wicket uses plain HTML markup files as templates, we can place an anchor to an external page directly inside the markup file. When we need to dynamically generate external anchors, we can use link component _org.apache.wicket.markup.html.link.ExternalLink_. In order to build an external link we must specify the value of the href attribute using a model or a plain string. In the next snippet, given an instance of Person, we generate a Google search query for its full name: + +Html: + +[source,html] +---- +<a wicket:id="externalSite">Search me on Google!</a> +---- + +Java code: + +[source,java] +---- +Person person = new Person("John", "Smith"); +String fullName = person.getFullName(); +//Space characters must be replaced by character '+' +String googleQuery = "http://www.google.com/search?q="; + fullName.replace(" ", "+"); +add(new ExternalLink("externalSite", googleQuery)); +---- + +Generated anchor: + +[source,html] +---- +<a href="http://www.google.com/search?q=John+Smith";>Search me on Google!</a> +---- + +If we need to specify a dynamic value for the text inside the anchor, we can pass it as an additional constructor parameter: + +Html: + +[source,html] +---- +<a wicket:id="externalSite">Label goes here...</a> +---- + +Java code: + +[source,java] +---- +Person person = new Person("John", "Smith"); +String fullName = person.getFullName(); +String googleQuery = "http://www.google.com/search?q="; + fullName.replace(" ", "+"); +String linkLabel = "Search '" + fullName + "' on Google."; + +add(new ExternalLink("externalSite", googleQuery, linkLabel)); +---- + +Generated anchor: + +[source,html] +---- +<a href="http://www.google.com/search?q=John+Smith";>Search 'John Smith' on Google.</a> +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/urls/urls_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/urls/urls_5.adoc b/wicket-user-guide/src/main/asciidoc/urls/urls_5.adoc new file mode 100644 index 0000000..262ebeb --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/urls/urls_5.adoc @@ -0,0 +1,35 @@ + + + +Component Link has a stateful nature, hence it cannot be used with stateless pages. To use links with these kinds of pages Wicket provides the convenience _org.apache.wicket.markup.html.link.StatelessLink_ component which is basically a subtype of Link with the stateless hint set to true. + +Please keep in mind that Wicket generates a new instance of a stateless page also to serve stateless links, so the code inside the onClick() method can not depend on instance variables. To illustrate this potential issue let's consider the following code (from the project StatelessPage) where the value of the variable index is used inside onclick(): + +[source,java] +---- +public class StatelessPage extends WebPage { + private int index = 0; + + public StatelessPage(PageParameters parameters) { + super(parameters); + } + + @Override + protected void onInitialize() { + super.onInitialize(); + setStatelessHint(true); + + add(new StatelessLink("statelessLink") { + + @Override + public void onClick() { + //It will always print zero + System.out.println(index++); + } + + }); + } +} +---- + +The printed value will always be zero because a new instance of the page is used every time the user clicks on the statelessLink link. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/urls/urls_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/urls/urls_6.adoc b/wicket-user-guide/src/main/asciidoc/urls/urls_6.adoc new file mode 100644 index 0000000..2692bb9 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/urls/urls_6.adoc @@ -0,0 +1,229 @@ + + + +Having structured URLs in our site is a basic requirement if we want to build an efficient SEO strategy, but it also contributes to improve user experience with more intuitive URLs. Wicket provides two different ways to control URL generation. The first (and simplest) is to âmountâ one or more pages to an arbitrary path, while a more powerful technique is to use custom implementations of IMapperContext and IPageParametersEncoder interfaces. In the next paragraphs we will learn both of these two techniques. + +=== Mounting a single page + +With Wicket we can mount a page to a given path in much the same way as we map a servlet filter to a desired path inside file web.xml (see <<helloWorld.adoc#_configuration_of_wicket_applications,paragraph 4.2>>). Using mountPage(String path, Class <T> pageClass) method of the WepApplication class we tell Wicket to respond with a new instance of pageClass whenever a user navigates to the given path. In the application class of the project MountedPagesExample we mount MountedPage to the [/pageMount] path: + +[source,java] +---- +@Override +public void init() +{ + super.init(); + mountPage("/pageMount", MountedPage.class); + //Other initialization code... +} +---- + +The path provided to mountPage will be used to generate the URL for any page of the specified class: + +[source,java] +---- +//it will return "/pageMount" +RequestCycle.get().urlFor(MountedPage.class); +---- + +Under the hood the mountPage method mounts an instance of the request mapper _org.apache.wicket.request.mapper.MountedMapper_ configured for the given path: + +[source,java] +---- +public final <T extends Page> void mountPage(final String path,final Class<T> pageClass) { + mount(new MountedMapper(path, pageClass)); +} +---- + +Request mappers and the Application's method mount have been introduced in the previous chapter (<<requestProcessing.adoc#_the_director_of_request_processing_requestcycle,paragraph 9.3>>). + +=== Using parameter placeholders with mounted pages + +The path specified for mounted pages can contain dynamic segments which are populated with the values of the named parameters used to build the page. These segments are declared using special segments called parameter placeholders. Consider the path used in the following example: + +[source,java] +---- +mountPage("/pageMount/${foo}/otherSegm", MountedPageWithPlaceholder.class); +---- + +The path used above is composed by three segments: the first and the last are fixed while the second will be replaced by the value of the named parameter foo that must be provided when the page MountedPageWithPlaceholder is instantiated: + +Java code: + +[source,java] +---- +PageParameters pageParameters = new PageParameters(); +pageParameters.add("foo", "foo"); + +setResponsePage(MountedPageWithPlaceholder.class, pageParameters) +---- + +Generated URL: + +[source,html] +---- +<Application path>/pageMount/foo/otherSegm +---- + +On the contrary if we manually insert an URL like '<web app path>/pageMount/bar/otherSegm', we can read value 'bar' retrieving the named parameter foo inside our page. + +Place holders can be declared as optional using the '1.' character in place of '$': + +[source,java] +---- +mountPage("/pageMount/#{foo}/otherSegm", MountedPageOptionalPlaceholder.class); +---- + +If the named parameter for an optional placeholder is missing, the corresponding segment is removed from the final URL: + +Java code: + +[source,java] +---- +PageParameters pageParameters = new PageParameters(); +setResponsePage(MountedPageWithPlaceholder.class, pageParameters); +---- + +Generated URL: + +[source,html] +---- +<Application path>/pageMount/otherSegm +---- + +=== Mounting a package + +In addition to mounting a single page, Wicket allows to mount all of the pages inside a package to a given path. Method mountPackage(String path, Class<T> pageClass) of class WepApplication will mount every page inside pageClass's package to the specified path. + +The resulting URL for package-mounted pages will have the following structure: + +[source,html] +---- +<Application path>/mountedPath/<PageClassName>[optional query string] +---- + +For example in the MountedPagesExample project we have mounted all pages inside the subpackage org.tutorialWicket.subPackage with this line of code: + +[source,java] +---- +mountPackage("/mountPackage", StatefulPackageMount.class); +---- + +StatefulPackageMount is one of the pages placed into the desired package and its URL will be: + +[source,html] +---- +<Application path>/mountPackage/StatefulPackageMount?1 +---- + +Similarly to what is done by the mountPage method, the implementation of the mountPackage method mounts an instance of _org.apache.wicket.request.mapper.PackageMapper_ to the given path. + +=== Providing custom mapper context to request mappers + +Interface _org.apache.wicket.request.mapper.IMapperContext_ is used by request mappers to create new page instances and to retrieve static URL segments used to build and parse page URLs. Here is the list of these segments: + +* Namespace: it's the first URL segment of non-mounted pages. By default its value is wicket. +* Identifier for non-bookmarkable URLs: it's the segment that identifies non bookmarkable pages. By default its value is page. +* Identifier for bookmarkable URLs: it's the segment that identifies bookmarkable pages. By default its value is bookmarkable (as we have seen before in <<urls.adoc#_pageparameters,paragraph 10.1.1>>). +* Identifier for resources: it's the segment that identifies Wicket resources. Its default value is resources. The topic of resource management will be covered in +<<_resource_management_with_wicket,chapter 16>>. + +IMapperContext provides a getter method for any segment listed above. By default Wicket uses class _org.apache.wicket.DefaultMapperContext_ as mapper context. + +Project CustomMapperContext is an example of customization of mapper context where we use index as identifier for non-bookmarkable pages and staticURL as identifier for bookmarkable pages. In this project, instead of implementing our mapper context from scratch, we used DefaultMapperContext as base class overriding just the two methods we need to achieve the desired result (getBookmarkableIdentifier() and getPageIdentifier()). The final implementation is the following: + +[source,java] +---- +public class CustomMapperContext extends DefaultMapperContext{ + + @Override + public String getBookmarkableIdentifier() { + return "staticURL"; + } + + @Override + public String getPageIdentifier() { + return "index"; + } +} +---- + +Now to use a custom mapper context in our application we must override the newMapperContext() method declared in the Application class and make it return our custom implementation of IMapperContext: + +[source,java] +---- +@Override +protected IMapperContext newMapperContext() { + return new CustomMapperContext(); +} +---- + +=== Controlling how page parameters are encoded with IPageParametersEncoder + +Some request mappers (like MountedMapper and PackageMapper) can delegate page parameters encoding/decoding to interface _org.apache.wicket.request.mapper.parameter.IPage ParametersEncoder_. This entity exposes two methods: encodePageParameters() and decodePageParameters(): the first one is invoked to encode page parameters into an URL while the second one extracts parameters from the URL. + +Wicket comes with a built-in implementation of this interface which encodes named page parameters as URL segments using the following pattern: /paramName1/paramValue1/paramName2/param Value2... + +This built-in encoder is _org.apache.wicket.request.mapper.parameter.UrlPathPageParametersEncoder_ class. In the _PageParametersEncoderExample_ project we have manually mounted a _MountedMapper_ that takes as input also an _UrlPathPageParametersEncoder_: + +[source,java] +---- +@Override +public void init() { + super.init(); + mount(new MountedMapper("/mountedPath", MountedPage.class, new UrlPathPageParametersEncoder())); +} +---- + +The home page of the project contains just a link to the MountedPage web page. The code of the link and the resulting page URL are: + +Link code: + +[source,java] +---- +add(new Link("mountedPage") { + + @Override + public void onClick() { + + PageParameters pageParameters = new PageParameters(); + pageParameters.add("foo", "foo"); + pageParameters.add("bar", "bar"); + + setResponsePage(MountedPage.class, pageParameters); + } +}); +---- + +Generated URL: + +[source,html] +---- +<Application path>/mountedPath/foo/foo/bar/bar?1 +---- + +=== Encrypting page URLs + +Sometimes URLs are a doubleâedged sword for our site because they can expose too many details about the internal structure of our web application making it more vulnerable to malicious users. + +To avoid this kind of security threat we can use the _CryptoMapper_ request mapper which wraps an existing mapper and encrypts the original URL producing a single encrypted segment: + +image::../img/url-encrypted.png[] + +Typically, _CryptoMapper_ is registered into a Wicket application as the root request mapper wrapping the default one: + +[source,java] +---- +@Override +public void init() { + super.init(); + setRootRequestMapper(new CryptoMapper(getRootRequestMapper(), this)); + //pages and resources must be mounted after we have set CryptoMapper + mountPage("/foo/", HomePage.class); +---- + +As pointed out in the code above, pages and resources must be mounted after having set _CryptoMapper_ as root mapper, otherwise the mounted paths will not work. + +WARNING: By default _CryptoMapper_ encrypts page URLs with a cipher that might not be strong enough for production environment. Paragraph +<<_security_with_wicket,"Security with Wicket">> will provide a more detailed description of how Wicket encrypts page URLs and we will see how to use stronger ciphers. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/urls/urls_7.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/urls/urls_7.adoc b/wicket-user-guide/src/main/asciidoc/urls/urls_7.adoc new file mode 100644 index 0000000..74e8153 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/urls/urls_7.adoc @@ -0,0 +1,6 @@ + + + +Links and URLs are not trivial topics as they may seem and in Wicket they are strictly interconnected. Developers must choose the right trade-off between producing structured URLs and avoiding to make them verbose and vulnerable. + +In this chapter we have explored the tools provided by Wicket to control how URLs are generated. We have started with static URLs for bookmarkable pages and we have seen how to pass parameters to target pages with PageParameters. In the second part of the chapter we focused on mounting pages to a specific path and on controlling how parameters are encoded by Wicket. Finally, we have also seen how to encrypt URLs to prevent security vulnerabilities. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/versioningCaching.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/versioningCaching.adoc b/wicket-user-guide/src/main/asciidoc/versioningCaching.adoc new file mode 100644 index 0000000..e11358d --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/versioningCaching.adoc @@ -0,0 +1,2 @@ + +This chapter explains how Wicket manages page instances, underlining the difference between stateful and stateless pages. The chapter also introduces some advanced topics like Java Serialization and multi-level cache. However, to understand what you will read you are not required to be familiar with these concepts. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_1.adoc b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_1.adoc new file mode 100644 index 0000000..97a0561 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_1.adoc @@ -0,0 +1,10 @@ + + + +Wicket pages can be divided into two categories: stateful and stateless pages. Stateful pages are those which rely on user session to store their internal state and to keep track of user interaction. +On the contrary stateless pages are those which don't change their internal state during their lifecycle and they don't need to occupy space into user session. + +From Wicket's point of view the biggest difference between these two types of page is that stateful pages are versioned, meaning that they will be saved into user session every time their internal state has changed. Wicket automatically assigns a session to the user the first time a stateful page is requested. Page versions are stored into user session using Java Serialization mechanism. +Stateless pages are never versioned and that's why they don't require a valid user session. If we want to know whether a page is stateless or not, we can call the isPageStateless() method of class Page. + +In order to build a stateless page we must comply with some rules to ensure that the page won't need to use user session. These rules are illustrated in paragraph 8.3 but before talking about stateless pages we must first understand how stateful pages are handled and why they are versioned. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc new file mode 100644 index 0000000..6693ba2 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc @@ -0,0 +1,145 @@ + + + +Stateful pages are versioned in order to support browser's back button: when this button is pressed Wicket must respond by rendering the same page instance previously used. + +A new page version is created when a stateful page is requested for the first time or when an existing instance is modified (for example changing its component hierarchy). To identify each page version Wicket uses a session-relative identifier called page id. This is a unique number and it is increased every time a new page version is created. + +In the final example of the previous chapter (project LifeCycleStages), you may have noticed the number appended at the end of URL. This number is the page id we are talking about: + +image::../img/page-id.png[] + +In this chapter we will use a revised version of this example project where the component hierarchy is modified inside the Link's onClick()method. This is necessary because Wicket creates a new page version only if the page is modified before its method onBeforeRender() is invoked. The code of the new home page is the following: + +[source,java] +---- +public class HomePage extends WebPage +{ + private static final long serialVersionUID = 1L; + private Label firstLabel; + private Label secondLabel; + + public HomePage(){ + firstLabel = new Label("label", "First label"); + secondLabel = new Label("label", "Second label"); + + add(firstLabel); + + add(new Link("reload"){ + @Override + public void onClick() { + if(getPage().contains(firstLabel, true)) + getPage().replace(secondLabel); + else + getPage().replace(firstLabel); + } + }); + + } +} +---- + +Now if we run the new example (project LifeCycleStagesRevisited) and we click on the âReloadâ button, a new page version is created and the page id is increased by one: + +image::../img/reload-page.png[] + +If we press the back button the page version previously rendered (and serialized) will be retrieved (i.e. deserialized) and it will be used again to respond to our request (and page id is decremented): + +image::../img/browser-back.png[] + +NOTE: For more details about page storing you can take a look at paragraph [Page storing] from chapter [Wicket Internals] The content of this paragraph is from wiki page https://cwiki.apache.org/confluence/display/WICKET/Page+Storage. + +As we have stated at the beginning of this chapter, page versions are stored using Java serialization, therefore every object referenced inside a page must be serializable. In <<modelsforms.adoc#_detachable_models,paragraph 11.6>> we will see how to overcome this limit and work with non-serializable objects in our components using detachable Wicket models. + +=== Using a specific page version with PageReference + +To retrieve a specific page version in our code we can use class _org.apache.wicket.PageReference_ by providing its constructor with the corresponding page id: + +[source,java] +---- +//load page version with page id = 3 +PageReference pageReference = new PageReference(3); +//load the related page instance +Page page = pageReference.getPage(); +---- + +To get the related page instance we must use the method getPage. + +=== Turning off page versioning + +If for any reason we need to switch off versioning for a given page, we can call its method setVersioned(false). + +=== Pluggable serialization + +Starting from version 1.5 it is possible to choose which implementation of Java serialization will be used by Wicket to store page versions. Wicket serializes pages using an implementation of interface _org.apache.wicket.serialize.ISerializer_. The default implementation is _org.apache.wicket.serialize.java.JavaSerializer_ and it uses the standard Java serialization mechanism based on classes ObjectOutputStream and ObjectInputStream. However on Internet we can find other interesting serialization libraries like https://github.com/EsotericSoftware/kryo[Kryo] + +We can access this class inside the method _init_ of the class Application using the getFrameworkSettings() method : + +[source,java] +---- +@Override +public void init() +{ + super.init(); + getFrameworkSettings().setSerializer(yourSerializer); +} +---- + +A serializer based on Kryo library and another one based on Fast are provided by the WicketStuff project. You can find more information on this project, as well as the instructions to use its modules, in Appendix B. + +=== Page caching + +By default Wicket persists versions of pages into a session-relative file on disk, but it uses a two-levels cache to speed up this process. The first level of the cache uses a http session attribute called âwicket:persistentPageManagerData-<APPLICATION_NAME>â to store pages. The second level cache stores pages into application-scoped variables which are identified by a session id and a page id. + +The following picture is an overview of these two caching levels: + +image::../img/wicket-cache.png[] + +The session-scoped cache is faster then the other memory levels but it contains only the pages used to serve the last request. Wicket allows us to set the maximum amount of memory allowed for the application-scoped cache and for the page store file. Both parameters can be configured via setting class _org.apache.wicket.settings.StoreSettings_. + +This interface provides the setMaxSizePerSession(Bytes bytes) method to set the size for page store file. The Bytes parameter is the maximum size allowed for this file: + +[source,java] +---- +@Override +public void init() +{ + super.init(); + getStoreSettings().setMaxSizePerSession(Bytes.kilobytes(500)); +} +---- + +Class _org.apache.wicket.util.lang.Bytes_ is an utility class provided by Wicket to express size in bytes (for further details refer to the JavaDoc). +For the second level cache we can use the setInmemoryCacheSize(int inmemoryCacheSize) method. The integer parameter is the maximum number of page instances that will be saved into application-scoped cache: + +[source,java] +---- +@Override +public void init() +{ + super.init(); + getStoreSettings().setInmemoryCacheSize(50); +} +---- + +=== Page expiration + +Page instances are not kept in the user session forever. They can be discarded when the limit set with the setMaxSizePerSession method is reached or (more often) when user session expires. When we ask Wicket for a page id corresponding to a page instance removed from the session, we bump into a PageExpiredException and we get the following default error page: + +image::../img/page-expired.png[] + +This error page can be customized with the _setPageExpiredErrorPage_ method of class _org.apache.wicket.settings.ApplicationSettings_: + +[source,java] +---- +@Override +public void init() +{ + super.init(); + getApplicationSettings().setPageExpiredErrorPage( + CustomExpiredErrorPage.class); +} +---- + +The page class provided as custom error page must have a public constructor with no argument or a constructor that takes as input a single PageParameters argument (the page must be bookmarkable as described in <<urls.adoc#_pageparameters,paragraph 10.1.1>>). + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_3.adoc b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_3.adoc new file mode 100644 index 0000000..461d2bf --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_3.adoc @@ -0,0 +1,48 @@ + + + +Wicket makes it very easy to build stateful pages, but sometimes we might want to use an âold schoolâ stateless page that doesn't keep memory of its state in the user session. For example consider the public area of a site or a login page: in those cases a stateful page would be a waste of resources or even a security threat, as we will see in paragraph [paragraph 12.10|guide:forms2_10]. + +In Wicket a page can be stateless only if it satisfies the following requirements: + +1. it has been instantiated by Wicket (i.e. we don't create it with operator new) using a constructor with no argument or a constructor that takes as input a single PageParameters argument (class PageParameters will be covered in <<urls.adoc#_pageparameters,chapter 10.1>>). +2. All its children components (and behaviors) are in turn stateless, which means that their method isStateless must return true. + +The first requirement implies that, rather than creating a page by hand, we should rely on Wicket's capability of resolving page instances, like we do when we use method setResponsePage(Class page). + +In order to comply with the second requirement it could be helpful to check if all children components of a page are stateless. To do this we can leverage method visitChildren and the visitor pattern to iterate over components and test if their method isStateless actually returns true: + +[source,java] +---- +@Override +protected void onInitialize() { + super.onInitialize(); + + visitChildren(new IVisitor<Component, Void>() { + @Override + public void component(Component component, IVisit<Void> arg1) { + if(!component.isStateless()) + System.out.println("Component " + component.getId() + " is not stateless"); + } + }); + } +---- + +Alternatively, we could use the _StatelessComponent_ utility annotation along with the _StatelessChecker_ class (they are both in package _org.apache.wicket.devutils.stateless_). _StatelessChecker_ will throw an _IllegalArgumentException_ if a component annotated with _StatelessComponent_ doesn't respect the requirements for being stateless. To use _StatelessComponent_ annotation we must first add the _StatelessChecker_ to our application as a component render listener: + +[source,java] +---- +@Override +public void init() +{ + super.init(); + getComponentPostOnBeforeRenderListeners().add(new StatelessChecker()); +} +---- + +NOTE: Most of the Wicket's built-in components are stateful, hence they can not be used with a stateless page. However some of them have also a stateless version which can be adopted when we need to keep a page stateless. In the rest of the guide we will point out when a built-in component comes also with a stateless version. + +A page can be also explicitly declared as stateless setting the appropriate flag to true with the setStatelessHint(true) method. This method will not prevent us from violating the requirements for a stateless page, but if we do so we will get the following warning log message: + +WARNING: Page '<page class>' is not stateless because of component with path '<component path>' + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_4.adoc b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_4.adoc new file mode 100644 index 0000000..a1ebdd2 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_4.adoc @@ -0,0 +1,8 @@ + + + +In this chapter we have seen how page instances are managed by Wicket. We have learnt that pages can be divided into two families: stateless and stateful pages. Knowing the difference between the two types of pages is important to build the right page for a given task. + +However, to complete the discussion about stateless pages we still have to deal with two topics we have just outlined in this chapter: class PageParameters and bookmarkable pages. The first part of +<<_wicket_links_and_url_generation,chapter 10>> will cover these missing topics. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/whyLearn.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/whyLearn.adoc b/wicket-user-guide/src/main/asciidoc/whyLearn.adoc new file mode 100644 index 0000000..a987b67 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/whyLearn.adoc @@ -0,0 +1,7 @@ + +Software development is a challenging activity and developers must keep their skills up-to-date with new technologies. + +But before starting to learn the last âcoolestâ framework we should always ask ourself if it is the right tool for us and how it can improve our everyday job. +Java's ecosystem is already full of many well-known web frameworks, so why should we spend our time learning Wicket? + +This chapter will show you how Wicket is different from other web frameworks you may know and it will explain also how it can improve your life as web developer. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_1.adoc b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_1.adoc new file mode 100644 index 0000000..1922670 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_1.adoc @@ -0,0 +1,11 @@ + +...but we all hate spaghetti code! That's why in the first half of the 2000s we have seen the birth of so many web frameworks. Their mission was to separate our business code from presentation layer (like JSP pages). + +Some of theme (like Struts, Spring MVC, Velocity, etc...) have become widely adopted and they made the MVC pattern very popular among developers. +However, none of these frameworks offers a real object-oriented (OO) abstraction for web pages and we still have to take care of web-related tasks such as HTTP request/response handling, URLs mapping, storing data into user session and so on. + +The biggest limit of MVC frameworks is that they don't do much to overcome the impedance mismatch between the stateless nature of HTTP protocol and the need of our web applications of handling a (very complex) state. + +To overcome these limits developers have started to adopt a new generation of component oriented web frameworks designed to provide a completely different approach to web development. + + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_2.adoc b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_2.adoc new file mode 100644 index 0000000..b1d2bd2 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_2.adoc @@ -0,0 +1,16 @@ + +Component oriented frameworks differ from classic web frameworks in that they build a model of requested page on the server side and the HTML sent back to the client is generated according to this model. You can think of the model as if it was an âinverseâ JavaScript DOM, meaning that: + +1. is built on server-side +2. is built before HTML is sent to client +3. HTML code is generated using this model and not vice versa. + + image::../img/requesthandling-general.png[] + + _General schema of page request handling for a component oriented framework_ + +With this kind of framework our web pages and their HTML components (forms, input controls, links, etc...), are pure class instances. +Since pages are class instances they live inside the JVM heap and we can handle them as we do with any other Java class. +This approach is very similar to what GUI frameworks (like Swing or SWT) do with desktop windows and their components. Wicket and the other component oriented frameworks bring to web development the same kind of abstraction that GUI frameworks offer when we build a desktop application. Most of those kind of frameworks hide the details of the HTTP protocol and naturally solve the problem of its stateless nature. + + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_3.adoc b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_3.adoc new file mode 100644 index 0000000..5e69458 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_3.adoc @@ -0,0 +1,10 @@ + +At this point some people may still wonder why OOP is so important also for web development and what benefits it can bring to developers. +Let's quickly review the main advantages that this paradigm can offer us: + +* *Web pages are objects*: web pages are not just text files sent back to the client. They are object instances and we can harness OOP to design web pages and their components. With Wicket we can also apply inheritance to HTML markup in order to build a consistent graphic layout for our applications (we will see markup inheritance in <<layout.adoc#_here_comes_the_inheritance,chapter 4.2>>). +* *We don't have to worry about application's state*: pages and components can be considered stateful entities. They are Java objects and they can keep a state inside them and reference other objects. We can stop worrying about keeping track of user data stored inside the _HttpSession_ and we can start managing them in a natural and transparent way. +* *Testing web applications is much easier*: since pages and components are pure objects, you can use JUnit to test their behavior and to ensure that they render as expected. Wicket has a set of utility classes for unit testing that simulate user interaction with web pages, hence we can write acceptance tests using just JUnit without any other test framework (unit testing is covered in +<<_test_driven_development_with_wicket,chapter 23>>). + + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_4.adoc b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_4.adoc new file mode 100644 index 0000000..e27362b --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_4.adoc @@ -0,0 +1,13 @@ + +Wicket is not the only component oriented framework available in the Java ecosystem. Among its competitors we can find GWT (from Google), JSF (from Oracle), Vaadin (from Vaadin Ltd.), etc... Even if Wicket and all those other frameworks have their pros and cons, there are good reasons to prefer Wicket over them: + +* *Wicket is 100% open source*: Wicket is a top Apache project and it doesn't depend on any private company. You don't have to worry about future licensing changes, Wicket will always be released under Apache license 2.0 and freely available. + +* *Wicket is a community driven project*: The Wicket team supports and promotes the dialogue with the framework's users through two mailing lists http://wicket.apache.org/help/email.html[(one for users and another one for framework developers)] and an https://issues.apache.org/jira/browse/WICKET[Apache JIRA] (the issue tracking system). Moreover, as any other Apache project, Wicket is developed paying great attention to user feedbacks and to suggested features. + +* *Wicket is just about Java and good old HTML*: almost all web frameworks force users to adopt special tags or to use server side code inside HTML markup. This is clearly in contrast with the concept of separation between presentation and business logic and it leads to a more confusing code in our pages. In Wicket we don't have to take care of generating HTML inside the page itself, and we won't need to use any tag other than standard HTML tags. All we have to do is to attach our components (Java instances) to the HTML tags using a simple tag attribute called _wicket:id_ (we will shortly see how to use it). + +* *With Wicket we can easily use JavaBeans and http://en.wikipedia.org/wiki/Plain_Old_Java_Object[POJO] in our web tier*: one of the most annoying and error-prone task in web development is collecting user input through a form and keeping form fields updated with previously inserted values. This usually requires a huge amount of code to extract input from request parameters (which are strings), parse them to Java types and store them into some kind of variable. And this is just half of the work we have to do as we must implement the inverse path (load data from Java to the web form).Moreover, most of the times our forms will use a JavaBean or a POJO as backing object, meaning that we must manually map form fields with the corresponding object fields and vice versa. Wicket comes with an intuitive and flexible mechanism that does this mapping for us without any configuration overhead (using a convention over configuration approach) and in a transparent way. +<<_wicket_models_and_forms,Chapter 10>> will introduce the concept of Wicket model and we will learn how to harness this entity with forms. + +* *No complex XML needed*: Wicket was designed to minimize the amount of configuration files needed to run our applications. No XML file is required except for the standard deployment descriptor web.xml (unless you are using Servlet 3 or a later version. See <<whyLearn.adoc#_component_oriented_frameworks_an_overview,Chapter 4>> for more details). http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/wicketstuff.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/wicketstuff.adoc b/wicket-user-guide/src/main/asciidoc/wicketstuff.adoc new file mode 100644 index 0000000..139597f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/wicketstuff.adoc @@ -0,0 +1,2 @@ + + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_1.adoc b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_1.adoc new file mode 100644 index 0000000..6d3633d --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_1.adoc @@ -0,0 +1,20 @@ + + + +WicketStuff is an umbrella project that gathers different Wicket-related projects developed and maintained by the community. The project is hosted on GitHub at https://github.com/wicketstuff/core[https://github.com/wicketstuff/core] . +Every module is structured as a parent Maven project containing the actual project that implements the new functionality and an example project that illustrates how to use it in our code. The resulting directory structure of each module is the following: + +[source,java] +---- +\<module name>-parent + | + +---<module name> + \---<module name>-examples +---- + +So far we have introduced only modules Kryo Serializer and JavaEE Inject, but WicketStuff comes with many other modules that can be used in our applications. Some of them come in handy to improve the user experience of our pages with complex components or integrating some popular web services (like http://maps.google.com/[Google Maps] ) and JavaScript libraries (like http://www.tinymce.com/[TinyMCE] ). + +This appendix provides a quick overview of what WicketStuff offers to enhance the usability and the visually-appealing of our pages. + +NOTE: Every WicketStuff module can be downloaded as JAR archive at http://mvnrepository.com[http://mvnrepository.com] . This site provides also the XML fragment needed to include it as a dependency into our pom.xml file. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_2.adoc b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_2.adoc new file mode 100644 index 0000000..eef717c --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_2.adoc @@ -0,0 +1,50 @@ + + + +Module tinymce offers integration with the namesake JavaScript library that turns our âhumbleâ text-areas into a full-featured HTML WYSIWYG editor: + +image::../img/tinymce.png[] + +To âtinyfyâ a textarea component we must use behavior TinyMceBehavior: + +[source,java] +---- +TextArea textArea = new TextArea("textArea", new Model("")); +textArea.add(new TinyMceBehavior()); +---- + +By default TinyMceBehavior adds only a basic set of functionalities to our textarea: + +image::../img/tinymce_basic.png[] + +To add more functionalities we must use class TinyMCESettings to register additional TinyMCE plugins and to customize the toolbars buttons. The following code is an excerpt from example page FullFeaturedTinyMCEPage: + +[source,java] +---- +TinyMCESettings settings = new TinyMCESettings( + TinyMCESettings.Theme.advanced); +//... +// first toolbar +//... +settings.add(Button.newdocument, TinyMCESettings.Toolbar.first, + TinyMCESettings.Position.before); +settings.add(Button.separator, TinyMCESettings.Toolbar.first, + TinyMCESettings.Position.before); +settings.add(Button.fontselect, TinyMCESettings.Toolbar.first, + TinyMCESettings.Position.after); +//... +// other settings +settings.setToolbarAlign( + TinyMCESettings.Align.left); +settings.setToolbarLocation( + TinyMCESettings.Location.top); +settings.setStatusbarLocation( + TinyMCESettings.Location.bottom); +settings.setResizing(true); +//... +TextArea textArea = new TextArea("ta", new Model(TEXT)); +textArea.add(new TinyMceBehavior(settings)); +---- + +For more configuration examples see pages inside package wicket.contrib.examples.tinymce in the example project of the module. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_3.adoc b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_3.adoc new file mode 100644 index 0000000..a138b58 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_3.adoc @@ -0,0 +1,35 @@ + + + +Module wicketstuff-gmap3 integrates http://maps.google.com[Google Maps] service with Wicket providing component org.wicketstuff.gmap.GMap. If we want to embed Google Maps into one of our pages we just need to add component GMap inside the page. The following snippet is taken from example page SimplePage: + +*HTML:* + +[source,html] +---- +... +<body> + <div wicket:id="map">Map</div> +</body> +... +---- + +*Java code:* + +[source,java] +---- +public class SimplePage extends WicketExamplePage +{ + public SimplePage() + { + GMap map = new GMap("map"); + map.setStreetViewControlEnabled(false); + map.setScaleControlEnabled(true); + map.setScrollWheelZoomEnabled(true); + map.setCenter(new GLatLng(52.47649, 13.228573)); + add(map); + } +} +---- + +The component defines a number of setters to customize its behavior and appearance. More info can be found on wiki page https://github.com/wicketstuff/core/wiki/Gmap3[https://github.com/wicketstuff/core/wiki/Gmap3] . http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_4.adoc b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_4.adoc new file mode 100644 index 0000000..9ac116f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_4.adoc @@ -0,0 +1,35 @@ + + + +To integrate the https://developers.google.com/chart/[Google Chart] tool into our pages we can use module wicketstuff-googlecharts. To display a chart we must combine the following entities: component Chart, interface IChartData and class ChartProvider, all inside package org.wicketstuff.googlecharts. The following snippet is taken from example page Home: + +*HTML:* + +[source,html] +---- +... + <h2>Hello World</h2> + <img wicket:id="helloWorld"/> +... +---- + +*Java code:* + +[source,java] +---- +IChartData data = new AbstractChartData(){ + public double[][] getData(){ + return new double[][] { { 34, 22 } }; + } +}; + +ChartProvider provider = new ChartProvider(new Dimension(250, 100), ChartType.PIE_3D, data); +provider.setPieLabels(new String[] { "Hello", "World" }); +add(new Chart("helloWorld", provider)); +---- + +*Displayed chart:* + +image::../img/googlechart.png[] + +As we can see in the snippet above, component Chart must be used with <img> tag while the input data returned by IChartData must be a two-dimensional array of double values. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_5.adoc b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_5.adoc new file mode 100644 index 0000000..37d889f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_5.adoc @@ -0,0 +1,44 @@ + + + +Module wicketstuff-inmethod-grid implements a sophisticated grid-component with class com. inmethod.grid.datagrid.DataGrid. + +Just like pageable repeaters (seen in <<repeaters.adoc#_pageable_repeaters,paragraph 13.4>>) DataGrid provides data pagination and uses interface IDataProvider as data source. In addition the component is completely ajaxified: + +image::../img/inmethod-grid1.png[] + +DataGrid supports also editable cells and row selection: + +image::../img/inmethod-grid2.png[] + +The following snippet illustrate how to use DataGrid and is taken from wiki page https://github.com/wicketstuff/core/wiki/InMethodGrid[https://github.com/wicketstuff/core/wiki/InMethodGrid] : + +*HTML:* + +[source,html] +---- +... + <div wicket:id="grid">Grid</div> +... +---- + +*Java code:* + +[source,java] +---- +final List<Person> personList = //load a list of Persons +final ListDataProvider listDataProvider = new ListDataProvider(personList); +//define grid's columns +List<IGridColumn> cols = (List) Arrays.asList( + new PropertyColumn(new Model("First Name"), "firstName"), + new PropertyColumn(new Model("Last Name"), "lastName")); + +DataGrid grid = new DefaultDataGrid("grid", new DataProviderAdapter(listDataProvider), cols); +add(grid); +---- + +In the code above we have used convenience class DefaultDataGrid that is a subclass of DataGrid and it already comes with a navigation toolbar. + +The example pages are under package com.inmethod.grid.examples.pages in the example project which is hosted at http://www.wicket-library.com/inmethod-grid/data-grid/simple[http://www.wicket-library.com/inmethod-grid/data-grid/simple] . + + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_6.adoc b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_6.adoc new file mode 100644 index 0000000..0a834df --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_6.adoc @@ -0,0 +1,82 @@ + +REST-based API are becoming more and more popular around the web and the number of services based on this architecture is constantly increasing. + +Wicket is well-known for its capability of transparently handling the state of web applications on server side, but it can be also easily adopted to create RESTful services. +WicketStuff module for REST provides a special resource class and a set of annotations to implement REST APIs/services in much the same way as we do it with Spring MVC or with the standard JAX-RS. + +The module provides class _AbstractRestResource_ as generic abstract class to implement a Wicket resource that handles the request and the response using a particular data format (XML, JSON, etc...). +Subclassing _AbstractRestResource_ we can create custom resources and map their pubblic methods to a given subpath with annotation _MethodMapping_. The following snippet is taken from resource _PersonsRestResource_ inside module _'restannotations-examples'_: + +[source,java] +---- + @MethodMapping("/persons") + public List<PersonPojo> getAllPersons() { + //method mapped at subpath "/persons" and HTTP method GET + } + + @MethodMapping(value = "/persons/{personIndex}", httpMethod = HttpMethod.DELETE) + public void deletePerson(int personIndex) { + //method mapped at subpath "/persons/{personIndex}" and HTTP method DELETE. + //Segment {personIndex} will contain an integer value as index. + } + + @MethodMapping(value = "/persons", httpMethod = HttpMethod.POST) + public void createPerson(@RequestBody PersonPojo personPojo) { + //creates a new instance of PersonPojo reading it from request body + } +---- + +_MethodMapping_ requires to specify the subpath we want to map the method to. In addition we can specify also the HTTP method that must be used to invoke the method via REST (GET, POST, DELETE, PATCH, etc...). This value can be specified with enum class _HttpMethod_ and is GET by default. +In the code above we can see annotation _RequestBody_ which is used to extract the value of a method parameter from the request body (method createPerson). +To write/read objects to response/from request, _AbstractRestResource_ uses an implementation of interface _IWebSerialDeserial_ which defines the following methods: + +[source,java] +---- + + public interface IWebSerialDeserial { + + public void objectToResponse(Object targetObject, WebResponse response, String mimeType) throws Exception; + + public <T> T requestToObject(WebRequest request, Class<T> argClass, String mimeType) throws Exception; + + public boolean isMimeTypeSupported(String mimeType); + } +---- + +To convert segments value (which are strings) to parameters type, _AbstractRestResource_ uses the standard Wicket mechanism based on the application converter locator: + +[source,java] +---- + + //return the converter for type clazz + IConverter converter = Application.get().getConverterLocator().getConverter(clazz); + //convert string to object + return converter.convertToObject(value, Session.get().getLocale()); +---- + +In order to promote the principle of convention over configuration, we don't need to use any annotation to map method parameters to path parameters if they are declared in the same order. If we need to manually bind method parameters to path parameters we can use annotation _PathParam_. + +[source,java] +---- + @MethodMapping(value = "/variable/{p1}/order/{p2}", produces = RestMimeTypes.PLAIN_TEXT) + public String testParamOutOfOrder(@PathParam("p2") String textParam, @PathParam("p1") int intParam) { + //method parameter textParam is taken from path param 'p2', while intParam uses 'p1' + } +---- + +As JSON is de-facto standard format for REST API, the project comes also with a ready-to-use resource (_GsonRestResource_) and a serial/deserial (_GsonSerialDeserial_) that work with JSON format (both inside module _'restannotations-json'_). These classes use Gson as JSON library. + +_AbstractRestResource_ supports role-based authorizations for mapped method with annotation _AuthorizeInvocation_: + +[source,java] +---- + @MethodMapping(value = "/admin", httpMethod = HttpMethod.GET) + @AuthorizeInvocation("ROLE_ADMIN") + public void testMethodAdminAuth() { + + } +---- + +To use annotation _AuthorizeInvocation_ we must specify in the resource construcor an instance of Wicket interface _IRoleCheckingStrategy_. + +To read the complete documentation of the module and to discover more advanced feature please refer to the https://github.com/wicketstuff/core/tree/master/wicketstuff-restannotations-parent[project homepage]
