You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by ad...@apache.org on 2015/04/05 18:09:40 UTC
[05/11] wicket git commit: Added sub-module wicket-user-guide to
integrate the user guide generation with Maven workflow
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/repeaters/repeaters_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/repeaters/repeaters_3.gdoc b/wicket-user-guide/src/docs/guide/repeaters/repeaters_3.gdoc
new file mode 100644
index 0000000..20e9801
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/repeaters/repeaters_3.gdoc
@@ -0,0 +1,50 @@
+
+
+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:*
+{code: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>
+...
+{code}
+
+*Java Code (Page Constructor):*
+{code}
+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();
+}
+ });
+}
+{code}
+
+h3. 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@.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/repeaters/repeaters_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/repeaters/repeaters_4.gdoc b/wicket-user-guide/src/docs/guide/repeaters/repeaters_4.gdoc
new file mode 100644
index 0000000..4a7496b
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/repeaters/repeaters_4.gdoc
@@ -0,0 +1,112 @@
+
+
+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 paragraph 11.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).
+
+h3. 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:*
+{code: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>
+{code}
+
+*Java Code:*
+{code}
+//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);
+{code}
+
+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.
+
+h3. 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:
+
+!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:*
+{code: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>
+{code}
+
+*Java Code:*
+{code}
+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));
+}
+{code}
+
+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 it's 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 "http://www.wicket-library.com/wicket-examples/repeater/":http://www.wicket-library.com/wicket-examples/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 repeaters even if it doesn't use interface IDataProvider as data source.
+{note}
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/repeaters/repeaters_5.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/repeaters/repeaters_5.gdoc b/wicket-user-guide/src/docs/guide/repeaters/repeaters_5.gdoc
new file mode 100644
index 0000000..b81cf0b
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/repeaters/repeaters_5.gdoc
@@ -0,0 +1,7 @@
+
+
+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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/requestProcessing.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/requestProcessing.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing.gdoc
new file mode 100644
index 0000000..d5e22b7
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/requestProcessing.gdoc
@@ -0,0 +1,4 @@
+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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_1.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_1.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_1.gdoc
new file mode 100644
index 0000000..b8d64c9
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_1.gdoc
@@ -0,0 +1,5 @@
+
+
+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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_2.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_2.gdoc
new file mode 100644
index 0000000..f211513
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_2.gdoc
@@ -0,0 +1,5 @@
+
+
+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()@.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_3.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_3.gdoc
new file mode 100644
index 0000000..f94fe54
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_3.gdoc
@@ -0,0 +1,92 @@
+
+
+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 paragraph 2.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.
+{note}
+
+Class @org.apache.wicket.Component@ provides the @getRequestCycle()@ method which is a convenience method that internally invokes @RequestCycle.get()@:
+
+{code}
+public final RequestCycle getRequestCycle() {
+ return RequestCycle.get();
+}
+{code}
+
+h3. 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.
+{note}
+
+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@:
+
+!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.
+
+h3. 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 chapter 13).
+
+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).
+
+h3. Method setResponsePage
+
+The @RequestCycle@ class contains the implementation of the @setResponsePage@ method we use to redirect a user to a specific page (see paragraph 2.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:
+
+{code}
+public final void setResponsePage(final Page page) {
+ getRequestCycle().setResponsePage(page);
+}
+{code}
+
+h3. 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:
+
+{code}
+@Override
+public void init() {
+
+ super.init();
+
+ IRequestCycleListener myListener;
+ //listener initialization...
+ getRequestCycleListeners().add(myListener)
+}
+{code}
+
+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 "Composite pattern":http://en.wikipedia.org/wiki/Composite_pattern .
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_4.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_4.gdoc
new file mode 100644
index 0000000..f852071
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_4.gdoc
@@ -0,0 +1,154 @@
+
+
+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.
+
+h3. 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:
+
+{code}
+@Override
+public void init(){
+
+ super.init();
+
+ //listener initialization...
+ ISessionListener myListener;
+ //add a custom session listener
+ getSessionListeners().add(myListener)
+
+}
+{code}
+
+h3. 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().
+
+h3. 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:
+
+{code}
+HttpSession session = ((ServletWebRequest)RequestCycle.get()
+ .getRequest()).getContainerRequest().getSession();
+{code}
+
+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:
+
+!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:
+
+{code}
+HttpSession session = ((ServletWebRequest)RequestCycle.get().
+ getRequest()).getContainerRequest().getSession();
+
+session.setAttribute("Locale", "ENGLISH");
+session.setAttribute("userName", "Mr BadGuy");
+{code}
+
+h3. 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:
+
+{code}
+Session.get().isTemporary();
+{code}
+
+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:
+{code}
+public class HomePage extends WebPage {
+ public HomePage(final PageParameters parameters) {
+ Session.get().setAttribute("username", "tommy");
+ Session.get().bind();
+
+ setResponsePage(DisplaySessionParameter.class);
+ }
+}
+{code}
+
+Target page:
+
+{code}
+public class DisplaySessionParameter extends WebPage {
+
+ public DisplaySessionParameter() {
+ super();
+ add(new Label("username", (String) Session.get().getAttribute("username")));
+ }
+}
+{code}
+
+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.
+
+h3. 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.
+{warning}
+
+h3. 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:
+{code}
+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}
+
+Code to get the object from the metadata:
+
+{code}
+Connection connection = Application.get().getMetaData(MetaDataApp.connectionKey);
+{code}
+
+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/93dca376/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_5.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_5.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_5.gdoc
new file mode 100644
index 0000000..42c06cb
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_5.gdoc
@@ -0,0 +1,35 @@
+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:
+
+{code}
+getApplicationSettings().setInternalErrorPage(MyInternalErrorPage.class);
+{code}
+
+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:
+
+{code}
+//show default developer page
+getExceptionSettings().setUnexpectedExceptionDisplay( IExceptionSettings.SHOW_EXCEPTION_PAGE );
+//show internal error page
+getExceptionSettings().setUnexpectedExceptionDisplay( IExceptionSettings.SHOW_INTERNAL_ERROR_PAGE );
+//show no exception page when an unexpected exception is thrown
+getExceptionSettings().setUnexpectedExceptionDisplay( IExceptionSettings.SHOW_NO_EXCEPTION_PAGE );
+{code}
+
+Developers can also decide to use a custom exception mapper instead of @DefaultExceptionMapper@. To do this we must override @Application@'s method @getExceptionMapperProvider@:
+
+{code}
+@Override
+public IProvider<IExceptionMapper> getExceptionMapperProvider()
+{
+ //...
+}
+{code}
+
+The method returns an instance of @org.apache.wicket.util.IProvider@ that should return our custom exception mapper.
+
+h3. Ajax requests
+
+To control the behavior in Ajax requests the application may use @org.apache.wicket.settings.IExceptionSettings# setAjaxErrorHandlingStrategy(IExceptionSettings.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.IExceptionSettings. AjaxErrorStrategy#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/93dca376/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_6.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_6.gdoc b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_6.gdoc
new file mode 100644
index 0000000..9cd6a4c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/requestProcessing/requestProcessing_6.gdoc
@@ -0,0 +1,5 @@
+
+
+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 chapter 20.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources.gdoc b/wicket-user-guide/src/docs/guide/resources.gdoc
new file mode 100644
index 0000000..1274817
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources.gdoc
@@ -0,0 +1,5 @@
+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 paragraph 4.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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_1.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_1.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_1.gdoc
new file mode 100644
index 0000000..1c47376
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_1.gdoc
@@ -0,0 +1,9 @@
+
+
+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 13.6, developers can build custom resources extending base class @org.apache.wicket.request.resource.AbstractResource@.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_10.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_10.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_10.gdoc
new file mode 100644
index 0000000..f7fe0d9
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_10.gdoc
@@ -0,0 +1,48 @@
+
+
+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 paragraph 13.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:
+
+{code}
+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()...
+}
+{code}
+
+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@:
+
+{code}
+add(new ResourceLink("rssLink", new RSSProducerResource()));
+{code}
+
+In the next paragraphs we will see how to register a resource at application-level and how to mount it to an arbitrary URL.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_11.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_11.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_11.gdoc
new file mode 100644
index 0000000..89eee07
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_11.gdoc
@@ -0,0 +1,37 @@
+
+
+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 paragraph 8.6.1:
+
+{code}
+@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);
+}
+{code}
+
+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:
+
+{code}
+@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);
+}
+{code}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_12.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_12.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_12.gdoc
new file mode 100644
index 0000000..550dabe
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_12.gdoc
@@ -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:
+
+{code}
+ //init application's method
+ @Override
+ public void init(){
+ RSSProducerResource rssResource = new RSSProducerResource();
+ // ...
+ getSharedResources().add("globalRSSProducer", rssResource);
+ }
+{code}
+
+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:
+
+{code}
+add(new ResourceLink("globalRssLink", new SharedResourceReference("globalRSSProducer")));
+{code}
+
+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}
+
+{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@.
+{note}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_13.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_13.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_13.gdoc
new file mode 100644
index 0000000..a1a0890
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_13.gdoc
@@ -0,0 +1,45 @@
+
+
+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 interface @IResourceSettings@:
+
+{code}
+ //init application's method
+ @Override
+ public void init(){
+ //get the resource locator
+ getResourceSettings().getResourceStreamLocator();
+ //set the resource locator
+ getResourceSettings().setResourceStreamLocator(myLocator);
+ }
+{code}
+
+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:
+
+!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:
+
+{code}
+@Override
+public void init()
+{
+ getResourceSettings().getResourceFinders().add(
+ new WebApplicationPath(getServletContext(), "markupFolder"));
+}
+{code}
+
+Method getResourceFinders() defined by setting interface IResourceSettings 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:
+
+!package-structure-resource-folder.png!
+
+This folder can be used to store resource files without writing any configuration code.
+{note}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_14.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_14.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_14.gdoc
new file mode 100644
index 0000000..946456a
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_14.gdoc
@@ -0,0 +1,69 @@
+
+
+Introduced in Wicket 6.20.0 / Wicket 7.0.0 there is a default way to be used in which the output of all CssHeaderItems / JavaScriptHeaderItems is modified before they are cached and delivered to the client. You can add a so called Compressor by receiving the resource settings and invoke #setJavaScriptCompressor(...) / #setJavaScriptCompressor(...). If you want to add several Compressors use @org.apache.wicket.resource.CompositeCssCompressor@ or @org.apache.wicket.resource.CompositeJavaScriptCompressor@
+
+*Java Code:*
+{code}
+...
+ public class WicketApplication extends WebApplication
+ {
+ @Override
+ public Class<? extends WebPage> getHomePage()
+ {
+ return HomePage.class;
+ }
+
+ @Override
+ public void init()
+ {
+ super.init();
+ getResourceSettings().setCssCompressor(new CssUrlReplacer());
+ }
+ }
+...
+{code}
+
+In the previous example you see that a @org.apache.wicket.resource.CssUrlReplacer@ is added which does not compress the content, but replaces all urls in CSS files and applies a Wicket representation for them by automatically wrapping them into PackageResourceReferences. Here is an example where you can see what Wicket does with the url representation.
+
+HomePage (in package my/company/):
+*Java Code:*
+{code}
+...
+response.render(CssReferenceHeaderItem.forReference(new PackageResourceReference(HomePage.class, "res/css/mycss.css")));
+...
+{code}
+
+mycss.css (in package my/company/res/css/):
+*CSS:*
+{code}
+...
+body{
+ background-image:url('../images/some.png');
+}
+...
+{code}
+
+some.png (in package my/company/res/images/):
+<blob>
+
+Output of mycss.css:
+*CSS:*
+{code}
+...
+body{
+ background-image:url('../images/some-ver-1425904170000.png');
+}
+...
+{code}
+
+If you add a url which looks like this background-image:url('../images/some.png?embedBase64'); Wicket is going to embed the complete image as base64 string with its corresponding mime type into the css file. It looks like the following code block demonstrates.
+
+Output of mycss.css:
+*CSS:*
+{code}
+...
+body{
+ background-image: url(data:image/png;base64,R0lGODlh1wATAX....);
+}
+...
+{code}
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_15.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_15.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_15.gdoc
new file mode 100644
index 0000000..f522ac9
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_15.gdoc
@@ -0,0 +1,7 @@
+
+
+In this chapter we have learnt how to manage resources with the built-in mechanism provided by Wicket. With this mechanism we handle resources from Java code and Wicket will automatically take care of generating a valid URL for them. We have also seen how resources can be bundled as package resources with a component that depends on them to make it self-contained.
+
+Then, in the second part of the chapter, we have built a custom resource and we have learnt how to mount it to an arbitrary URL and how to make it globally available as shared resource.
+
+Finally, in the last part of the paragraph we took a peek at the mechanism provided by the framework to customize the locations where the resource-lookup algorithm searches for resources.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_2.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_2.gdoc
new file mode 100644
index 0000000..771d594
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_2.gdoc
@@ -0,0 +1,3 @@
+
+
+Most of the times in Wicket we won't directly instantiate a resource but rather we will use a reference to it. Resource references are represented by abstract class @org.apache.wicket.request.resource.ResourceReference@ which returns a concrete resource with factory method getResource(). In this way we can lazy-initialize resources loading them only the first time they are requested.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_3.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_3.gdoc
new file mode 100644
index 0000000..f24c24d
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_3.gdoc
@@ -0,0 +1,79 @@
+
+
+With HTML we use to include static resources in our pages using tags like <script>, <link> or <img>. This is what we have done so far writing our custom panels and pages. However, when we work with a component-oriented framework like Wicket, this classic approach becomes inadequate because it makes custom components hardly reusable. This happens when a component depends on a big number of resources. In such a case, if somebody wanted to use our custom component in his application, he would be forced to know which resources it depends on and make them available.
+
+To solve this problem Wicket allows us to place static resource files into component package (like we do with markup and properties files) and load them from component code.
+
+These kinds of resources are called package resources (a CSS and a JavaScript file in this screenshot):
+
+!package-resources.png!
+
+With package resources custom components become independent and self-contained and client code can use them without worrying about their dependencies.
+
+To load package resources Wicket provides class @org.apache.wicket.request.resource.PackageResourceReference@.
+
+To identify a package resource we need to specify a class inside the target package and the name of the desired resource (most of the times this will be a file name).
+
+In the following example taken from project ImageAsPackageRes, CustomPanel loads a picture file available as package resource and it displays it in a <img> tag using the built-in component @org.apache.wicket.markup.html.image.Image@:
+
+*HTML:*
+{code:html}
+<html>
+<head>...</head>
+<body>
+<wicket:panel>
+ Package resource image: <img wicket:id="packageResPicture"/>
+</wicket:panel>
+</body>
+</html>
+{code}
+
+*Jave Code:*
+{code}
+public class CustomPanel extends Panel {
+
+ public CustomPanel(String id) {
+ super(id);
+ PackageResourceReference resourceReference =
+ new PackageResourceReference(getClass(), "calendar.jpg");
+ add(new Image("packageResPicture", resourceReference));
+ }
+}
+{code}
+
+Wicket will take care of generating a valid URL for file calendar.jpg. URLs for package resources have the following structure:
+
+@<path to application root>/wicket/resource/<fully qualified classname>/<resource file name>-<ver-<id>>(.file extension)@
+
+In our example the URL for our picture file calendar.jpg is the following:
+
+@./wicket/resource/org.wicketTutorial.CustomPanel/calendar-ver-1297887542000.jpg@
+
+The first part of the URL is the relative path to the application root. In our example our page is already at the application's root so we have only a single-dotted segment. The next two segments, wicket and resource, are respectively the namespace and the identifier for resources seen in paragraph 8.6.4.
+
+The fourth segment is the fully qualified name of the class used to locate the resource and it is the scope of the package resource. In the last segment of the URL we can find the name of the resource (the file name).
+
+As you can see Wicket has automatically appended to the file name a version identifier (ver-1297887542000). When Wicket runs in DEVELOPMENT mode this identifier contains the timestamp in millisecond indicating the last time the resource file was modified. This can be useful when we are developing our application and resource files are frequently modified. Appending the timestamp to the original name we are sure that our browser will use always the last version of the file and not an old, out of date, cached version.
+
+When instead Wicket is running in DEPLOYMENT mode, the version identifier will contain the MD5 digest of the file instead of the timestamp. The digest is computed only the first time the resource is requested. This perfectly makes sense as static resources don't change so often when our application runs into production environment and when this appends the application is redeployed.
+
+{note}
+Package resources can be localized following the same rules seen for resource bundles and markup files:
+
+!package-resource-localization.png!
+
+In the example illustrated in the picture above, if we try to retrieve package resource calendar.jpg when the current locale is set to French, the actual file returned will be calendar_fr.jpg.
+{note}
+
+
+h3. Using package resources with tag <wicket:link>
+
+In paragraph 8.3 we have used tag <wicket:link> to automatically create links to bookmarkable pages. The same technique can be used also for package resources in order to use them directly from markup file. Let's assume for example that we have a picture file called icon.png placed in the same package of the current page. Under these conditions we can display the picture file using the following markup fragment:
+
+{code:html}
+<wicket:link>
+ <img src="icon.png"/>
+</wicket:link>
+{code}
+
+In the example above Wicket will populate the attribute src with the URL corresponding to the package resource icon.png. <wicket:link> supports also tag <link> for CSS files and tag <script> for JavaScript files.
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_4.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_4.gdoc
new file mode 100644
index 0000000..7645c9b
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_4.gdoc
@@ -0,0 +1,32 @@
+
+
+Wicket comes with interface @org.apache.wicket.markup.html.IHeaderContributor@ which allows components and behaviors (which will be introduced later in paragraph 15.1) to contribute to the header section of their page. The only method defined in this interface is @renderHead(IHeaderResponse response)@ where @IHeaderResponse@ is an interface which defines method @render(HeaderItem item)@ to write static resources or free-form text into the header section of the page.
+
+Header entries are instances of abstract class @org.apache.wicket.markup.head.HeaderItem@. Wicket provides a set of built-in implementations of this class suited for the most common types of resources. With the exception of @PriorityHeaderItem@, every implementation of @HeaderItem@ is an abstract factory class:
+
+* *CssHeaderItem:* represents a CSS resource. Factory methods provided by this class are @forReference@ which takes in input a resource reference, @forUrl@ which creates an CSS item from a given URL and @forCSS@ which takes in input an arbitrary CSS string and an optional id value to identify the resource.
+* *JavaScriptHeaderItem:* represents a JavaScript resource. Just like @CssHeaderItem@ it provides factory methods @forReference@ and @forUrl@ along with method @forScript@ which takes in input an arbitrary string representing the script and an optional id value to identify the resource. Method @forReference@ also supports boolean parameter @defer@ which renders the namesake attribute in the script tag (@defer@ attribute indicates that our script must be execute only after the page has loaded).
+* *OnDomReadyHeaderItem:* it adds JavaScript code that will be executed after the DOM has been built, but before external files (such as picture, CSS, etc...) have been loaded. The class provides a factory method @forScript@ which takes in input an arbitrary string representing the script to execute.
+* *OnEventHeaderItem:* the JavaScript code added with this class is executed when a specific JavaScript event is triggered on a given DOM element. The factory method is @forScript(String target, String event, CharSequence javaScript)@, where target is the id of a DOM element (or the element itself), event is the event that must trigger our code and javaScript is the code to execute.
+* *OnLoadHeaderItem:* the JavaScript code added with this class is executed after the whole page is loaded, external files included. The factory method is @forScript(CharSequence javaScript)@.
+* *PriorityHeaderItem:* it wraps another header item and ensures that it will have the priority over the other items during rendering phase.
+* *StringHeaderItem:* with this class we can add an arbitrary text to the header section. Factory method is @forString(CharSequence string)@.
+* *MetaDataHeaderItem:* starting from version 6.17.0, Wicket provides this class to handle meta informations such as <meta> tags or [canonical link element|http://en.wikipedia.org/wiki/Canonical_link_element]. The available factory methods are @forLinkTag@ and @forMetaTag@ which can be used to create respectively a <link> tag or a <meta> one. We can add tag attribute to an existing instance of @MetaDataHeaderItem@ with method @addTagAttribute(String attributeName, Object attributeValue)@. See JavaDoc for further details on this class.
+* *HtmlImportHeaderItem:* introduced in Wicket 6.19.0, provides a HTML5 functionality to include other wicket pages (other html files) into the current generated. Factory methods provided by this class are @forImportLinkTag@ which takes the page class or the url of the page / html to be included.
+
+
+In the following example our custom component loads a CSS file as a package resource (placed in the same package) and it adds it to header section.
+
+{code}
+public class MyComponent extends Component{
+
+ @Override
+ public void renderHead(IHeaderResponse response) {
+ PackageResourceReference cssFile =
+ new PackageResourceReference(this.getClass(), "style.css");
+ CssHeaderItem cssItem = CssHeaderItem.forReference(cssFile);
+
+ response.render(cssItem);
+ }
+}
+{code}
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_5.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_5.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_5.gdoc
new file mode 100644
index 0000000..256b108
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_5.gdoc
@@ -0,0 +1,37 @@
+In web applications, it's quite common to have one or more root context folders containing css/js files. These resources are normally referenced with an absolute path inside link/script tags:
+
+{code:html}
+<script src="/misc/js/jscript.js"></script>
+<link type="text/css" rel="stylesheet" href="/misc/css/themes/style.css" />
+{code}
+
+To handle this kind of resources from code we can use resource reference class @org.apache.wicket.request.resource.ContextRelativeResourceReference@. To build a new instance of this class we must specify the root context path of the resource we want to use:
+
+{code}
+ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js");
+{code}
+
+By default when our application runs in DEPLOYMENT mode @ContextRelativeResourceReference@ will automatically load the minified version of the specified resource using 'min' as postfix. In the example above it will load '/misc/js/jscript.min.js'. We can force @ContextRelativeResourceReference@ to always use the not-minified resource passing an additional flag to class constructor:
+
+{code}
+//it will always use '/misc/js/jscript.js'
+ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", false);
+{code}
+
+The minified postfix can be customized with an optional string parameter:
+
+{code}
+//it will use '/misc/js/jscript.minified.js' in DEPLOYMENT mode
+ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", "minified");
+{code}
+
+@ContextRelativeResourceReference@ is usually used with the header item classes we have seen before in this chapter to create entries for the page header section.
+
+h3. Picture files
+
+For picture files Wicket provides a specific component with class @org.apache.wicket.markup.html.image.ContextImage@ which is meant to be used with tag <img>
+
+{code}
+//build the component specifying its id and picture's context path
+ContextImage image = new ContextImage("myPicture", "/misc/imgs/mypic.png");
+{code}
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_6.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_6.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_6.gdoc
new file mode 100644
index 0000000..1cf2d0e
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_6.gdoc
@@ -0,0 +1,25 @@
+
+
+Class @ResourceReference@ allows to specify the resources it depends on overriding method @getDependencies()@. The method returns an iterator over the set of @HeaderItems@ that must be rendered before the resource referenced by @ResourceReference@ can be used. This can be really helpful when our resources are JavaScript or CSS libraries that in turn depend on other libraries.
+
+For example we can use this method to ensure that a custom reference to JQueryUI library will find JQuery already loaded in the page:
+
+{code}
+Url jqueyuiUrl = Url.parse("https://ajax.googleapis.com/ajax/libs/jqueryui/" +
+ "1.10.2/jquery-ui.min.js");
+
+UrlResourceReference jqueryuiRef = new UrlResourceReference(jqueyuiUrl){
+ @Override
+ public Iterable<? extends HeaderItem> getDependencies() {
+ Application application = Application.get();
+ ResourceReference jqueryRef = application.getJavaScriptLibrarySettings().
+ getJQueryReference();
+
+ return Arrays.asList(JavaScriptHeaderItem.forReference(jqueryRef));
+ }
+};
+{code}
+
+Please note that in the code above we have built a resource reference using a URL to the desired library instead of a package resource holding the physical file.
+
+The same method @getDependencies()@ is defined also for class @HeaderItem@.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_7.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_7.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_7.gdoc
new file mode 100644
index 0000000..c9da469
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_7.gdoc
@@ -0,0 +1,25 @@
+One of the best practices to make our web application faster and reduce its latency is to reduce the number of requests to the server to load page resources like JavaScript or CSS files. To achieve this goal some JavaScript-based build tools (like Grunt) allow to merge multiple files used in a page into a single file that can be loaded in a single request. Wicket provides class @org.apache.wicket.ResourceBundles@ to aggregate multiple resource references into a single one. A resource bundle can be declared during application initialization listing all the resources that compose it:
+
+{code}
+@Override
+public void init() {
+ super.init();
+
+ getResourceBundles().addJavaScriptBundle(WicketApplication.class,
+ "jqueryUiJs",
+ jqueryJsReference,
+ jqueryUiJsReference);
+
+ getResourceBundles().addCssBundle(WicketApplication.class,
+ "jqueryUiCss",
+ jqueryCssReference,
+ jqueryUiCssReference);
+
+}
+{code}
+
+To declare a new resource bundle we need to provide a _scope_ class (@WicketApplication.class@ in our example) and an unique name. Now, when one of the resources included in the bundle is requested, the entire bundle is rendered instead.
+
+{note}
+A specific resource reference can not be shared among different resource bundles (i.e. it can be part of only one bundle).
+{note}
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_8.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_8.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_8.gdoc
new file mode 100644
index 0000000..eb7c255
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_8.gdoc
@@ -0,0 +1,103 @@
+Some web developers prefer to put their <script> tags at the end of page body instead of inside the <head> tags:
+
+{code:html}
+
+<html>
+
+<head>
+//no <script> tag here...
+</head>
+
+<body>
+...
+<script>
+//one or more <script> tags at the end of the body
+</script>
+</body>
+</html>
+
+{code}
+
+
+In Wicket we can achieve this result providing a custom @IHeaderResponseDecorator@ to a our application and using Wicket tag <wicket:container/> to indicate where we want to render our scripts inside the page. Interface @IHeaderResponseDecorator@ defines method @IHeaderResponse decorate(IHeaderResponse response)@ which allows to decorate or add funtionalities to Wicket @IHeaderResponse@. Our custom @IHeaderResponseDecorator@ can be registered in the application with method @setHeaderResponseDecorator@. Anytime Wicket creates an instance of @IHeaderResponse@, it will call the registered @IHeaderResponseDecorator@ to decorate the header response.
+
+In the example project @ScriptInsideBody@ we can find a custom @IHeaderResponseDecorator@ that renders CSS into the usual <head> tag and put JavaScricpt header items into a specific container (tag <wicket:container/>)
+Wicket already comes with class @JavaScriptFilteredIntoFooterHeaderResponse@ which wraps a @IHeaderResponse@ and renders in a given container all the instances of @JavaScriptHeaderItem@.
+The following code is taken from the Application class of the project:
+
+{code}
+
+ //...
+ @Override
+ public void init()
+ {
+ setHeaderResponseDecorator(new JavaScriptToBucketResponseDecorator("footer-container"));
+ }
+
+ /**
+ * Decorates an original IHeaderResponse and renders all javascript items
+ * (JavaScriptHeaderItem), to a specific container in the page.
+ */
+ static class JavaScriptToBucketResponseDecorator implements IHeaderResponseDecorator
+ {
+
+ private String bucketName;
+
+ public JavaScriptToBucketResponseDecorator(String bucketName) {
+ this.bucketName = bucketName;
+ }
+
+ @Override
+ public IHeaderResponse decorate(IHeaderResponse response) {
+ return new JavaScriptFilteredIntoFooterHeaderResponse(response, bucketName);
+ }
+
+ }
+{code}
+
+As you can see in the code above the "bucket" that will contain JavaScript tags is called @"footer-container"@. To make a use of it the developer have to add a special component called @HeaderResponseContainer@ in his page:
+
+{code}
+add(new HeaderResponseContainer("someId", "filterName"));
+{code}
+
+Please note that @HeaderResponseContainer@'s needs also a name for the corresponding header response's filter. The markup of our page will look like this:
+
+{code:html}
+
+<html>
+
+<header>
+//no <script> tag here...
+</header>
+
+<body>
+<!-- here we will have our JavaScript tags -->
+<wicket:container wicket:id="someId"/>
+</body>
+</html>
+
+{code}
+
+The code of the home page is the following:
+
+{code}
+ public HomePage(final PageParameters parameters) {
+ super(parameters);
+
+ add(new HeaderResponseContainer("footer-container", "footer-container"));
+ }
+
+ @Override
+ public void renderHead(IHeaderResponse response) {
+ response.render(JavaScriptHeaderItem.forReference(new PackageResourceReference(getClass(),
+ "javasciptLibrary.js")));
+
+ response.render(OnEventHeaderItem.forScript("'logo'", "click", "alert('Clicked me!')"));
+ }
+{code}
+
+Looking at the code above you can note that our page adds two script to the header section: the first is an instance of @JavaScriptHeaderItem@ and will be rendered in the @HeaderResponseContainer@ while the second will follow the usual behavior and will be rendered inside <head> tag.
+
+
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/resources/resources_9.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/resources/resources_9.gdoc b/wicket-user-guide/src/docs/guide/resources/resources_9.gdoc
new file mode 100644
index 0000000..0d3a2c2
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/resources/resources_9.gdoc
@@ -0,0 +1,15 @@
+Starting from version 6.15.0 we can specify where header contributors must be rendered inside <head> tag using the placeholder tag @<wicket:header-items/>@:
+
+{code:html}
+<head>
+ <meta chartset="UTF-8"/>
+ <wicket:header-items/>
+ <script src="my-monkey-patch-of-wicket-ajax.js"></script>
+</head>
+{code}
+
+With the code above all header contributions done by using IHeaderResponse in your Java code or the special @<wicket:head>@ tag will be put between the <meta> and <script> elements, i.e. in the place of @<wicket:header-items/>@.
+
+This way you can make sure that some header item is always before or after the header items managed by Wicket.
+
+@<wicket:header-items/>@ can be used only in the page's <head> element and there could be at most one instance of it.
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/security.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/security.gdoc b/wicket-user-guide/src/docs/guide/security.gdoc
new file mode 100644
index 0000000..06a537d
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/security.gdoc
@@ -0,0 +1,3 @@
+Security is one of the most important non-functional requirements we must implement in our applications. This is particularly true for enterprise applications as they usually support multiple concurrent users, and therefore they need to have an access control policy.
+
+In this chapter we will explore the security infrastructure provided by Wicket and we will learn how to use it to implement authentication and authorizations in our web applications.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/93dca376/wicket-user-guide/src/docs/guide/security/security_1.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/security/security_1.gdoc b/wicket-user-guide/src/docs/guide/security/security_1.gdoc
new file mode 100644
index 0000000..4f1655c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/security/security_1.gdoc
@@ -0,0 +1,172 @@
+
+
+The first step in implementing a security policy is assigning a trusted identity to our users, which means that we must authenticate them. Web applications usually adopt a form-based authentication with a login form that asks user for a unique username and the relative password:
+
+!wikipedia-login-form.png!
+
+Wicket supports form-based authentication with session class @AuthenticatedWebSession@ and application class @AuthenticatedWebApplication@, both placed inside package @org.apache.wicket.authroles.authentication@.
+
+h3. AuthenticatedWebSession
+
+Class AuthenticatedWebSession comes with the following set of public methods to manage user authentication:
+
+* *authenticate(String username, String password)*: this is an abstract method that must be implemented by every subclass of @AuthenticatedWebSession@. It should contain the actual code that checks for user's identity. It returns a boolean value which is true if authentication has succeeded or false otherwise.
+* *signIn(String username, String password)*: this method internally calls authenticate and set the flag signedIn to true if authentication succeeds.
+* *isSignedIn()*:getter method for flag signedIn.
+* *signOut()*: sets the flag signedIn to false.
+* *invalidate()*: calls signOut and invalidates session.
+
+{warning}
+Remember that signOut does not discard any session-relative data. If we want to get rid of these data, we must invoke method invalidate instead of signOut.
+{warning}
+
+Another abstract method we must implement when we use @AuthenticatedWebSession@ is getRoles which is inherited from parent class @AbstractAuthenticatedWebSession@. This method can be ignored for now as it will be discussed later when we will talk about role-based authorization.
+
+h3. AuthenticatedWebApplication
+
+Class AuthenticatedWebApplication provides the following methods to support form-based authentication:
+
+* *getWebSessionClass()*: abstract method that returns the session class to use for this application. The returned class must be a subclass of @AbstractAuthenticatedWebSession@.
+* *getSignInPageClass()*: abstract method that returns the page to use as sign in page when a user must be authenticated.
+* *restartResponseAtSignInPage()*: forces the current response to restart at the sign in page. After we have used this method to redirect a user, we can make her/him return to the original page calling @Componet@'s method @continueToOriginalDestination()@.
+
+The other methods implemented inside @AuthenticatedWebApplication@ will be introduced when we will talk about authorizations.
+
+h3. A basic example of authentication
+
+Project @BasicAuthenticationExample@ is a basic example of form-based authentication implemented with classes @AuthenticatedWebSession@ and @AuthenticatedWebApplication@.
+
+The homepage of the project contains only a link to page @AuthenticatedPage@ which can be accessed only if user is signed in. The code of @AuthenticatedPage@ is this following:
+
+{code}
+public class AuthenticatedPage extends WebPage {
+ @Override
+ protected void onConfigure() {
+ super.onConfigure();
+ AuthenticatedWebApplication app = (AuthenticatedWebApplication)Application.get();
+ //if user is not signed in, redirect him to sign in page
+ if(!AuthenticatedWebSession.get().isSignedIn())
+ app.restartResponseAtSignInPage();
+ }
+
+ @Override
+ protected void onInitialize() {
+ super.onInitialize();
+ add(new Link("goToHomePage") {
+
+ @Override
+ public void onClick() {
+ setResponsePage(getApplication().getHomePage());
+ }
+ });
+
+ add(new Link("logOut") {
+
+ @Override
+ public void onClick() {
+ AuthenticatedWebSession.get().invalidate();
+ setResponsePage(getApplication().getHomePage());
+ }
+ });
+ }
+}
+{code}
+
+Page @AuthenticatedPage@ checks inside onConfigure if user is signed in and if not, it redirects her/him to the sign in page with method @restartResponseAtSignInPage@. The page contains also a link to the homepage and another link that signs out user.
+
+The sign in page is implemented in class @SignInPage@ and contains the form used to authenticate users:
+
+{code}
+public class SignInPage extends WebPage {
+ private String username;
+ private String password;
+
+ @Override
+ protected void onInitialize() {
+ super.onInitialize();
+
+ StatelessForm form = new StatelessForm("form"){
+ @Override
+ protected void onSubmit() {
+ if(Strings.isEmpty(username))
+ return;
+
+ boolean authResult = AuthenticatedWebSession.get().signIn(username, password);
+ //if authentication succeeds redirect user to the requested page
+ if(authResult)
+ continueToOriginalDestination();
+ }
+ };
+
+ form.setDefaultModel(new CompoundPropertyModel(this));
+
+ form.add(new TextField("username"));
+ form.add(new PasswordTextField("password"));
+
+ add(form);
+ }
+}
+{code}
+
+The form is responsible for handling user authentication inside its method onSubmit. The username and password are passed to @AuthenticatedWebSession@'s method @signIn(username, password)@ and if authentication succeeds, the user is redirected to the original page with method @continueToOriginalDestination@.
+
+The session class and the application class used in the project are reported here:
+
+*Session class:*
+
+{code}
+public class BasicAuthenticationSession extends AuthenticatedWebSession {
+
+ public BasicAuthenticationSession(Request request) {
+ super(request);
+ }
+
+ @Override
+ public boolean authenticate(String username, String password) {
+ //user is authenticated if both username and password are equal to 'wicketer'
+ return username.equals(password) && username.equals("wicketer");
+ }
+
+ @Override
+ public Roles getRoles() {
+ return null;
+ }
+}
+{code}
+
+*Application class:*
+
+{code}
+public class WicketApplication extends AuthenticatedWebApplication{
+ @Override
+ public Class<HomePage> getHomePage(){
+ return HomePage.class;
+ }
+
+ @Override
+ protected Class<? extends AbstractAuthenticatedWebSession> getWebSessionClass(){
+ return BasicAuthenticationSession.class;
+ }
+
+ @Override
+ protected Class<? extends WebPage> getSignInPageClass() {
+ return SignInPage.class;
+ }
+}
+{code}
+
+The authentication logic inside authenticate has been kept quite trivial in order to make the code as clean as possible. Please note also that session class must have a constructor that accepts an instance of class @Request@.
+
+h3. Redirecting user to an intermediate page
+
+Method @restartResponseAtSignInPage@ is an example of redirecting user to an intermediate page before allowing him to access to the requested page. This method internally throws exception @org.apache.wicket.RestartResponseAtInterceptPageException@ which saves the URL of the requested page into session metadata and then redirects user to the page passed as constructor parameter (the sign in page).
+
+Component's method @redirectToInterceptPage(Page)@ works in much the same way as @restartResponseAtSignInPage@ but it allows us to specify which page to use as intermediate page:
+
+{code}
+ redirectToInterceptPage(intermediatePage);
+{code}
+
+{note}
+Since both @restartResponseAtSignInPage@ and @redirectToInterceptPage@ internally throw an exception, the code placed after them will not be executed.
+{note}