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/22 18:50:34 UTC
[04/19] wicket git commit: Integration of Wicket-User-Guide into
build process
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/security/security_2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/security/security_2.gdoc b/wicket-user-guide/src/docs/guide/security/security_2.gdoc
new file mode 100644
index 0000000..99f51f9
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/security/security_2.gdoc
@@ -0,0 +1,278 @@
+
+
+The authorization support provided by Wicket is built around the concept of authorization strategy which is represented by interface @IAuthorizationStrategy@ (in package @org.apache.wicket.authorization@):
+
+{code}
+public interface IAuthorizationStrategy
+{
+ //interface methods
+ <T extends IRequestableComponent> boolean isInstantiationAuthorized(Class<T> componentClass);
+ boolean isActionAuthorized(Component component, Action action);
+
+ //default authorization strategy that allows everything
+ public static final IAuthorizationStrategy ALLOW_ALL = new IAuthorizationStrategy()
+ {
+ @Override
+ public <T extends IRequestableComponent> boolean isInstantiationAuthorized(final Class<T> c)
+ {
+ return true;
+ }
+ @Override
+ public boolean isActionAuthorized(Component c, Action action)
+ {
+ return true;
+ }
+ };
+}
+{code}
+
+This interface defines two methods:
+
+* isInstantiationAuthorized checks if user is allowed to instantiate a given component.
+* isActionAuthorized checks if user is authorized to perform a given action on a component's instance. The standard actions checked by this method are defined into class Action and are Action.ENABLE and Action.RENDER.
+
+Inside @IAuthorizationStrategy@ we can also find a default implementation of the interface (called ALLOW_ALL) that allows everyone to instantiate every component and perform every possible action on it. This is the default strategy adopted by class @Application@.
+
+To change the authorization strategy in use we must register the desired implementation into security settings (interface @ISecuritySettings@) during initialization phase with method setAuthorization Strategy:
+
+{code}
+ //Application class code...
+ @Override
+ public void init()
+ {
+ super.init();
+ getSecuritySettings().
+ setAuthorizationStrategy(myAuthorizationStrategy);
+ }
+//...
+{code}
+
+If we want to combine the action of two or more authorization strategies we can chain them with strategy @CompoundAuthorizationStrategy@ which implements composite pattern for authorization strategies.
+
+Most of the times we won't need to implement an @IAuthorizationStrategy@ from scratch as Wicket already comes with a set of built-in strategies. In the next paragraphs we will see some of these strategies that can be used to implement an effective and flexible security policy.
+
+h3. SimplePageAuthorizationStrategy
+
+Abstract class SimplePageAuthorizationStrategy (in package @org.apache.wicket.authorization.strategies.page@) is a strategy that checks user authorizations calling abstract method @isAuthorized@ only for those pages that are subclasses of a given supertype. If @isAuthorized@ returns false, the user is redirected to the sign in page specified as second constructor parameter:
+
+{code}
+SimplePageAuthorizationStrategy authorizationStrategy = new SimplePageAuthorizationStrategy(
+ PageClassToCheck.class, SignInPage.class)
+{
+ protected boolean isAuthorized()
+ {
+ //Authentication code...
+ }
+};
+{code}
+
+By default @SimplePageAuthorizationStrategy@ checks for permissions only on pages. If we want to change this behavior and check also other kinds of components, we must override method @isActionAuthorized@ and implement our custom logic inside it.
+
+h3. Role-based strategies
+
+At the end of paragraph 20.1 we have introduced AbstractAuthenticatedWebSession's method getRoles which is provided to support role-based authorization returning the set of roles granted to the current user.
+
+In Wicket roles are simple strings like “BASIC_USER” or “ADMIN” (they don't need to be capitalized) and they are handled with class @org.apache.wicket.authroles.authorization.strategies.role.Roles@. This class extends standard HashSet collection adding some functionalities to check whether the set contains one or more roles. Class @Roles@ already defines roles Roles.USER and Roles.ADMIN.
+
+The session class in the following example returns a custom “SIGNED_IN” role for every authenticated user and it adds an Roles.ADMIN role if username is equal to superuser:
+
+{code}
+class BasicAuthenticationRolesSession extends AuthenticatedWebSession {
+ private String userName;
+
+ public BasicAuthenticationRolesSession(Request request) {
+ super(request);
+ }
+
+ @Override
+ public boolean authenticate(String username, String password) {
+ boolean authResult= false;
+
+ authResult = //some authentication logic...
+
+ if(authResult)
+ userName = username;
+
+ return authResult;
+ }
+
+ @Override
+ public Roles getRoles() {
+ Roles resultRoles = new Roles();
+
+ if(isSignedIn())
+ resultRoles.add("SIGNED_IN");
+
+ if(userName.equals("superuser"))
+ resultRoles.add(Roles.ADMIN);
+
+ return resultRoles;
+ }
+}
+{code}
+
+Roles can be adopted to apply security restrictions on our pages and components. This can be done using one of the two built-in authorization strategies that extend super class @AbstractRoleAuthorizationStrategyWicket@: @MetaDataRoleAuthorizationStrategy@ and @AnnotationsRoleAuthorizationStrategy@
+
+The difference between these two strategies is that @MetaDataRoleAuthorizationStrategy@ handles role-based authorizations with Wicket metadata while @AnnotationsRoleAuthorizationStrategy@ uses Java annotations.
+
+{note}
+Application class @AuthenticatedWebApplication@ already sets @MetaDataRoleAuthorizationStrategy@ and @AnnotationsRoleAuthorizationStrategy@ as its own authorization strategies (it uses a compound strategy as we will see in paragraph 20.2).
+
+The code that we will see in the next examples is for illustrative purpose only. If our application class inherits from @AuthenticatedWebApplication@ we won't need to configure anything to use these two strategies.
+{note}
+
+h4. Using roles with metadata
+
+Strategy @MetaDataRoleAuthorizationStrategy@ uses application and components metadata to implement role-based authorizations. The class defines a set of static methods authorize that can be used to specify which roles are allowed to instantiate a component and which roles can perform a given action on a component.
+
+The following code snippet reports both application and session classes from project @MetaDataRolesStrategyExample@ and illustrates how to use @MetaDataRoleAuthorizationStrategy@ to allow access to a given page (AdminOnlyPage) only to ADMIN role:
+
+*Application class:*
+
+{code}
+public class WicketApplication extends AuthenticatedWebApplication{
+ @Override
+ public Class<? extends WebPage> getHomePage(){
+ return HomePage.class;
+ }
+
+ @Override
+ protected Class<? extends AbstractAuthenticatedWebSession> getWebSessionClass() {
+ return BasicAuthenticationSession.class;
+ }
+
+ @Override
+ protected Class<? extends WebPage> getSignInPageClass() {
+ return SignInPage.class;
+ }
+
+ @Override
+ public void init(){
+ getSecuritySettings().setAuthorizationStrategy(new MetaDataRoleAuthorizationStrategy(this));
+ MetaDataRoleAuthorizationStrategy.authorize(AdminOnlyPage.class, Roles.ADMIN);
+ }
+}
+{code}
+
+*Session class:*
+
+{code}
+public class BasicAuthenticationSession extends AuthenticatedWebSession {
+
+ private String username;
+
+ public BasicAuthenticationSession(Request request) {
+ super(request);
+ }
+
+ @Override
+ public boolean authenticate(String username, String password) {
+ //user is authenticated if username and password are equal
+ boolean authResult = username.equals(password);
+
+ if(authResult)
+ this.username = username;
+
+ return authResult;
+ }
+
+ public Roles getRoles() {
+ Roles resultRoles = new Roles();
+ //if user is signed in add the relative role
+ if(isSignedIn())
+ resultRoles.add("SIGNED_IN");
+ //if username is equal to 'superuser' add the ADMIN role
+ if(username!= null && username.equals("superuser"))
+ resultRoles.add(Roles.ADMIN);
+
+ return resultRoles;
+ }
+
+ @Override
+ public void signOut() {
+ super.signOut();
+ username = null;
+ }
+}
+{code}
+
+The code that instantiates @MetaDataRoleAuthorizationStrategy@ and set it as application's strategy is inside application class method init.
+
+Any subclass of @AbstractRoleAuthorizationStrategyWicket@ needs an implementation of interface @IRoleCheckingStrategy@ to be instantiated. For this purpose in the code above we used the application class itself because its base class @AuthenticatedWebApplication@ already implements interface @IRoleCheckingStrategy@. By default @AuthenticatedWebApplication@ checks for authorizations using the roles returned by the current @AbstractAuthenticatedWebSession@. As final step inside init we grant the access to page @AdminOnlyPage@ to ADMIN role calling method authorize.
+
+The code from session class has three interesting methods. The first is authenticate which considers as valid credentials every pair of username and password having the same value. The second notable method is getRoles which returns role SIGNED_IN if user is authenticated and it adds role ADMIN if username is equal to superuser. Finally, we have method signOut which has been overridden in order to clean the username field used internally to generate roles.
+
+Now if we run the project and we try to access to @AdminOnlyPage@ from the home page without having the ADMIN role, we will be redirected to the default access-denied page used by Wicket:
+
+!authorization-access-denied.png!
+
+The access-denied page can be customized using method @setAccessDeniedPage(Class<? extends Page>)@ of setting interface @IApplicationSettings@:
+
+{code}
+ //Application class code...
+ @Override
+ public void init(){
+ getApplicationSettings().setAccessDeniedPage(
+ MyCustomAccessDeniedPage.class);
+ }
+{code}
+
+Just like custom “Page expired” page (see chapter 6.2.5), also custom “Access denied” page must be bookmarkable.
+
+h4. Using roles with annotations
+
+Strategy @AnnotationsRoleAuthorizationStrategy@ relies on two built-in annotations to handle role-based authorizations. These annotations are @AuthorizeInstantiation@ and @AuthorizeAction@. As their names suggest the first annotation specifies which roles are allowed to instantiate the annotated component while the second must be used to indicate which roles are allowed to perform a specific action on the annotated component.
+
+In the following example we use annotations to make a page accessible only to signed-in users and to enable it only if user has the ADMIN role:
+
+{code}
+@AuthorizeInstantiation("SIGNED_IN")
+@AuthorizeAction(action = "ENABLE", roles = {"ADMIN"})
+public class MyPage extends WebPage {
+ //Page class code...
+}
+{code}
+
+Remember that when a component is not enabled, user can render it but he can neither click on its links nor interact with its forms.
+
+Example project @AnnotationsRolesStrategyExample@ is a revisited version of @MetaDataRolesStrategyExample@ where we use @AnnotationsRoleAuthorizationStrategy@ as authorization strategy. To ensure that page @AdminOnlyPage@ is accessible only to ADMIN role we have used the following annotation:
+
+{code}
+@AuthorizeInstantiation("ADMIN")
+public class AdminOnlyPage extends WebPage {
+ //Page class code...
+}
+{code}
+
+h3. Catching an unauthorized component instantiation
+
+Interface IUnauthorizedComponentInstantiationListener (in package @org.apache.wicket.authorization@) is provided to give the chance to handle the case in which a user tries to instantiate a component without having the permissions to do it. The method defined inside this interface is @onUnauthorizedInstantiation(Component)@ and it is executed whenever a user attempts to execute an unauthorized instantiation.
+
+This listener must be registered into application's security settings with method setUnauthorized @ComponentInstantiationListener@ defined by setting interface @ISecuritySettings@. In the following code snippet we register a listener that redirect user to a warning page if he tries to do a not-allowed instantiation:
+
+{code}
+public class WicketApplication extends AuthenticatedWebApplication{
+ //Application code...
+ @Override
+ public void init(){
+ getSecuritySettings().setUnauthorizedComponentInstantiationListener(
+ new IUnauthorizedComponentInstantiationListener() {
+
+ @Override
+ public void onUnauthorizedInstantiation(Component component) {
+ component.setResponsePage(AuthWarningPage.class);
+ }
+ });
+ }
+}
+{code}
+
+In addition to interface @IRoleCheckingStrategy@, class @AuthenticatedWebApplication@ implements also @IUnauthorizedComponentInstantiationListener@ and registers itself as listener for unauthorized instantiations.
+
+By default @AuthenticatedWebApplication@ redirects users to sign-in page if they are not signed-in and they try to instantiate a restricted component. Otherwise, if users are already signed in but they are not allowed to instantiate a given component, an @UnauthorizedInstantiationException@ will be thrown.
+
+h3. Strategy RoleAuthorizationStrategy
+
+Class @RoleAuthorizationStrategy@ is a compound strategy that combines both @MetaDataRoleAuthorizationStrategy@ and @AnnotationsRoleAuthorizationStrategy@.
+
+This is the strategy used internally by @AuthenticatedWebApplication@.
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/security/security_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/security/security_3.gdoc b/wicket-user-guide/src/docs/guide/security/security_3.gdoc
new file mode 100644
index 0000000..62be06b
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/security/security_3.gdoc
@@ -0,0 +1,56 @@
+
+
+HTTPS is the standard technology adopted on Internet to create a secure communication channel between web applications and their users.
+
+In Wicket we can easily protect our pages with HTTPS mounting a special request mapper called @HttpsMapper@ and using annotation RequireHttps with those pages we want to serve over this protocol. Both these two entities are in package @org.apache.wicket.protocol.https@.
+
+HttpsMapper wraps an existing mapper and redirects incoming requests to HTTPS if the related response must render a page containing annotation @RequireHttps@. Most of the times the wrapped mapper will be the root one, just like we saw before for @CryptoMapper@ in paragraph 10.6.
+
+Another parameter needed to build a @HttpsMapper@ is an instance of class @HttpsConfi@g. This class allows us to specify which ports must be used for HTTPS and HTTP. By default the port numbers used by these two protocols are respectively 443 and 80.
+
+The following code is taken from project @HttpsProtocolExample@ and illustrates how to enable HTTPS in our applications:
+
+{code}
+//Application class code...
+@Override
+public void init(){
+ setRootRequestMapper(new HttpsMapper(getRootRequestMapper(),
+ new HttpsConfig(8080, 443)));
+}
+{code}
+
+Now we can use annotation RequireHttps to specify which pages must be served using HTTPS:
+
+{code}
+@RequireHttps
+public class HomePage extends WebPage {
+ public HomePage(final PageParameters parameters) {
+ super(parameters);
+ }
+}
+{code}
+
+If we want to protect many pages with HTTPS without adding annotation @RequireHttps@ to each of them, we can annotate a marker interface or a base page class and implement/extend it in any page we want to make secure:
+
+{code}
+// Marker interface:
+@RequireHttps
+public interface IMarker{
+}
+
+// Base class:
+@RequireHttps
+public class BaseClass extends WebPage{
+//Page code...
+}
+
+// Secure page inheriting from BaseClass:
+public class HttpsPage extends BaseClass{
+//Page code...
+}
+
+// Secure page implementing IMarker:
+public class HttpsPage implements IMarker{
+//Page code...
+}
+{code}
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/security/security_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/security/security_4.gdoc b/wicket-user-guide/src/docs/guide/security/security_4.gdoc
new file mode 100644
index 0000000..bf10b48
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/security/security_4.gdoc
@@ -0,0 +1,54 @@
+In chapter [10.6|guide:urls_6] we have seen how to encrypt URLs using @CryptoMapper@ request mapper. To encrypt/decrypt page URLs @CryptoMapper@ uses an instance of @org.apache.wicket.util.crypt.ICrypt@ interface:
+
+{code}
+public interface ICrypt
+{
+ String encryptUrlSafe(final String plainText);
+
+ String decryptUrlSafe(final String encryptedText);
+
+ ...
+}
+{code}
+
+The default implementation for this interface is class @org.apache.wicket.util.crypt.SunJceCrypt@. It provides password-based cryptography using @PBEWithMD5AndDES@ algorithm coming with the standard security providers in the Java Runtime Environment.
+
+{note}
+For better security it is recommended to install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction [Policy Files|http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html] for your version of JDK/JRE and use stronger algorithms. See this [example|https://github.com/apache/wicket/blob/42ce1faa57d3617ccaa443045537306fabf4d71a/wicket-util/src/test/java/org/apache/wicket/util/crypt/UnlimitedStrengthJurisdictionPolicyTest.java#L67] of a custom @ICrypt@ implementation for inspiration.
+{note}
+
+By using @CryptoMapper(IRequestMapper wrappedMapper, Application application)@ constructor the mapper will use the configured @org.apache.wicket.util.crypt.ICryptFactory@ from @org.apache.wicket.settings.ISecuritySettings#getCryptFactory()@. To use a stronger cryptography mechanism there are the following options:
+
+* The first option is to use constructor @CryptoMapper(IRequestMapper wrappedMapper, IProvider<ICrypt> cryptProvider)@ and give it an implementation of @org.apache.wicket.util.IProvider@ that returns a custom @org.apache.wicket.util.crypt.ICrypt@.
+
+{note}
+@org.apache.wicket.util.IProvider@ is a single-method interface that acts as object supplier:
+{note}
+
+{code}
+public interface IProvider<T>
+{
+ T get();
+}
+{code}
+
+* The second option is to register a cipher factory at application level with method @setCryptFactory(ICryptFactory cryptFactory)@ of interface @ISecuritySettings@:
+
+{code}
+@Override
+public void init() {
+ super.init();
+ getSecuritySettings().setCryptFactory(new SomeCryptFactory());
+ setRootRequestMapper(new CryptoMapper(getRootRequestMapper(), this));
+}
+{code}
+
+
+Since version 6.19.0 Wicket uses @org.apache.wicket.core.util.crypt.KeyInSessionSunJceCryptFactory@ as a default factory for @ICrypt@ objects. This factory generates a unique key for each user that is stored in her HTTP
+session. This way it helps to protect the application against [CSRF|https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)] attacks - the <form> action url will be encrypted in such way that it will be unique
+for each user of the application. The url itself serves as [encrypted token|https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet#Encrypted_Token_Pattern].
+
+{warning}
+@org.apache.wicket.core.util.crypt.KeyInSessionSunJceCryptFactory@ binds the http session if it is not already bound! If the application needs to run in stateless mode then the application will have to provide a custom
+implementation of @ICryptFactory@ that stores the user specific keys by other means.
+{warning}
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/security/security_5.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/security/security_5.gdoc b/wicket-user-guide/src/docs/guide/security/security_5.gdoc
new file mode 100644
index 0000000..fab204d
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/security/security_5.gdoc
@@ -0,0 +1,41 @@
+
+
+Wicket internally uses an entity called package resource guard to protect package resources from external access. This entity is an implementation of interface @org.apache.wicket.markup.html.IPackageResourceGuard@.
+
+By default Wicket applications use as package resource guard class @SecurePackageResourceGuard@, which allows to access only to the following file extensions (grouped by type):
+
+{table}
+File | Extensions
+*JavaScript files* |.js
+*CSS files* |.css
+*HTML pages* |.html
+*Textual files* |.txt
+*Flash files* |.swf
+*Picture files* |.png, .jpg, .jpeg, .gif, .ico, .cur, .bmp, .svg
+*Web font files* |.eot, .ttf, .woff
+{table}
+
+To modify the set of allowed files formats we can add one or more patterns with method @addPattern(String)@. The rules to write a pattern are the following:
+
+* patterns start with either a "+" or a "-". In the first case the pattern will add one or more file to the set while starting a pattern with a “-” we exclude all the files matching the given pattern. For example pattern “-web.xml” excludes all web.xml files in all directories.
+* wildcard character “\*” is supported as placeholder for zero or more characters. For example pattern “+\*.mp4” adds all the mp4 files inside all directories.
+* subdirectories are supported as well. For example pattern “+documents/\*.pdf” adds all pdf files under “documents” directory. Character “\*” can be used with directories to specify a nesting level. For example “+documents/\*/\*.pdf” adds all pdf files placed one level below “documents” directory.
+* a double wildcard character “\*\*” indicates zero or more subdirectories. For example pattern “+documents/\*\*/\*.pdf” adds all pdf files placed inside “documents” directory or inside any of its subdirectories.
+
+Patterns that allow to access to every file with a given extensions (such as “+\*.pdf”) should be always avoided in favour of more restrictive expressions that contain a directory structure:
+
+{code}
+//Application class code...
+@Override
+public void init()
+{
+ IPackageResourceGuard packageResourceGuard = application.getResourceSettings()
+ .getPackageResourceGuard();
+ if (packageResourceGuard instanceof SecurePackageResourceGuard)
+ {
+ SecurePackageResourceGuard guard = (SecurePackageResourceGuard) packageResourceGuard;
+ //Allow to access only to pdf files placed in the “public” directory.
+ guard.addPattern("+public/*.pdf");
+ }
+}
+{code}
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/security/security_6.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/security/security_6.gdoc b/wicket-user-guide/src/docs/guide/security/security_6.gdoc
new file mode 100644
index 0000000..4ec812f
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/security/security_6.gdoc
@@ -0,0 +1,14 @@
+
+
+ In this chapter we have seen the components and the mechanisms that allow us to implement security policies in our Wicket-based applications. Wicket comes with an out of the box support for both authorization and authentication.
+
+The central element of authorization mechanism is the interface @IAuthorizationStrategy@ which decouples our components from any detail about security strategy. The implementations of this interface must decide if a user is allowed to instantiate a given page or component and if she/he can perform a given action on it.
+
+Wicket natively supports role-based authorizations with strategies @MetaDataRoleAuthorizationStrategy@ and @AnnotationsRoleAuthorizationStrategy@. The difference between these two strategies is that the first offers a programmatic approach for role handling while the second promotes a declarative approach using built-in annotations.
+
+After having explored how Wicket internally implements authentication and authorization, in the last part of the chapter we have learnt how to configure our applications to support HTTPS and how to specify which pages must be served over this protocol.
+
+In the last paragraph we have seen how Wicket protects package resources with a guard entity that allows us to decide which package resources can be accessed from users.
+
+
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/testing.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/testing.gdoc b/wicket-user-guide/src/docs/guide/testing.gdoc
new file mode 100644
index 0000000..d42f91c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/testing.gdoc
@@ -0,0 +1,5 @@
+"Test Driven Development":http://en.wikipedia.org/wiki/Test-driven_development has become a crucial activity for every modern development methodology. This chapter will cover the built-in support for testing provided by Wicket with its rich set of helper and mock classes that allows us to test our components and our applications in isolation (i.e without the need for a servlet container) using JUnit, the de facto standard for Java unit testing.
+
+In this chapter we will see how to write unit tests for our applications and components and we will learn how to use helper classes to simulate user navigation and write acceptance tests without the need of any testing framework other than JUnit.
+
+The JUnit version used in this chapter is 4.x.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/testing/testing_1.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/testing/testing_1.gdoc b/wicket-user-guide/src/docs/guide/testing/testing_1.gdoc
new file mode 100644
index 0000000..04a2eda
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/testing/testing_1.gdoc
@@ -0,0 +1,273 @@
+
+
+A good way to start getting confident with Wicket unit testing support is looking at the test case class @TestHomePage@ that is automatically generated by Maven when we use Wicket archetype to create a new project:
+
+!mvn-wicket-archetype.png!
+
+Here is the content of TestHomePage:
+
+{code}
+public class TestHomePage{
+ private WicketTester tester;
+
+ @Before
+ public void setUp(){
+ tester = new WicketTester(new WicketApplication());
+ }
+ @Test
+ public void homepageRendersSuccessfully(){
+ //start and render the test page
+ tester.startPage(HomePage.class);
+ //assert rendered page class
+ tester.assertRenderedPage(HomePage.class);
+ }
+}
+{code}
+
+The central class in a Wicket testing is @org.apache.wicket.util.tester.WicketTester@. This utility class provides a set of methods to render a component, click links, check if page contains a given component or a feedback message, and so on.
+
+The basic test case shipped with @TestHomePage@ illustrates how @WicketTester@ is typically instantiated (inside method @setUp()@). In order to test our components, WicketTester needs to use an instance of @WebApplication@. Usually, we will use our application class as @WebApplication@, but we can also decide to build WicketTester invoking its no-argument constructor and letting it automatically build a mock web application (an instance of class @org.apache.wicket.mock.MockApplication@).
+
+The code from @TestHomePage@ introduces two basic methods to test our pages. The first is method @startPage@ that renders a new instance of the given page class and sets it as current rendered page for WicketTester. The second method is assertRenderedPage which checks if the current rendered page is an instance of the given class. In this way if TestHomePage succeeds we are sure that page HomePage has been rendered without any problem. The last rendered page can be retrieved with method @getLastRenderedPage@.
+
+That's only a taste of what @WicketTester@ can do. In the next paragraphs we will see how it can be used to test every element that composes a Wicket page (links, models, behaviors, etc...).
+
+h3. Testing links
+
+A click on a Wicket link can be simulated with method @clickLink@ which takes in input the link component or the page-relative path to it.
+
+To see an example of usage of clickLink, let's consider again project @LifeCycleStagesRevisited@. As we know from chapter 5 the home page of the project alternately displays two different labels (“First label” and “Second label”), swapping between them each time button "reload" is clicked. The code from its test case checks that label has actually changed after button "reload" has been pressed:
+
+{code}
+//...
+@Test
+public void switchLabelTest(){
+ //start and render the test page
+ tester.startPage(HomePage.class);
+ //assert rendered page class
+ tester.assertRenderedPage(HomePage.class);
+ //assert rendered label
+ tester.assertLabel("label", "First label");
+ //simulate a click on "reload" button
+ tester.clickLink("reload");
+ //assert rendered label
+ tester.assertLabel("label", "Second label");
+}
+//...
+{code}
+
+In the code above we have used @clickLink@ to click on the "reload" button and force page to be rendered again. In addition, we have used also method @assertLabel@ that checks if a given label contains the expected text.
+
+By default @clickLink@ assumes that AJAX is enabled on client side. To switch AJAX off we can use another version of this method that takes in input the path to the link component and a boolean flag that indicates if AJAX must be enabled (true) or not (false).
+
+{code}
+//...
+//simulate a click on a button without AJAX support
+tester.clickLink("reload", false);
+//...
+{code}
+
+h3. Testing component status
+
+WicketTester provides also a set of methods to test the states of a component. They are:
+
+* *assertEnabled(String path)/assertDisabled(String path)*: they test if a component is enabled or not.
+* *assertVisible(String path)/assertInvisible(String path)*: they test component visibility.
+* *assertRequired(String path)*: checks if a form component is required.
+
+In the test case from project @CustomDatepickerAjax@ we used @assertEnabled@/@assertDisabled@ to check if button "update" really disables our datepicker:
+
+{code}
+//...
+@Test
+public void testDisableDatePickerWithButton(){
+ //start and render the test page
+ tester.startPage(HomePage.class);
+ //assert that datepicker is enabled
+ tester.assertEnabled("form:datepicker");
+ //click on update button to disable datepicker
+ tester.clickLink("update");
+ //assert that datepicker is disabled
+ tester.assertDisabled("form:datepicker");
+}
+//...
+{code}
+
+h3. Testing components in isolation
+
+Method @startComponent(Component)@ can be used to test a component in isolation without having to create a container page for this purpose. The target component is rendered and both its methods @onInitialize()@ and @onBeforeRender()@ are executed. In the test case from project @CustomFormComponentPanel@ we used this method to check if our custom form component correctly renders its internal label:
+
+{code}
+//...
+@Test
+public void testCustomPanelContainsLabel(){
+ TemperatureDegreeField field = new TemperatureDegreeField("field", Model.of(0.00));
+ //Use standard JUnit class Assert
+ Assert.assertNull(field.get("mesuramentUnit"));
+ tester.startComponent(field);
+ Assert.assertNotNull(field.get("mesuramentUnit"));
+}
+//...
+{code}
+
+If test requires a page we can use @startComponentInPage(Component)@ which automatically generates a page for our component.
+
+h3. Testing the response
+
+@WicketTester@ allows us to access to the last response generated during testing with method @getLastResponse@. The returned value is an instance of class MockHttpServletResponse that provides helper methods to extract informations from mocked request.
+
+In the test case from project @CustomResourceMounting@ we extract the text contained in the last response with method @getDocument@ and we check if it is equal to the RSS feed used for the test:
+
+{code}
+//...
+@Test
+public void testMountedResourceResponse() throws IOException, FeedException{tester.startResource(new RSSProducerResource());
+ String responseTxt = tester.getLastResponse().getDocument();
+ //write the RSS feed used in the test into a ByteArrayOutputStream
+ ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
+ Writer writer = new OutputStreamWriter(outputStream);
+ SyndFeedOutput output = new SyndFeedOutput();
+
+ output.output(RSSProducerResource.getFeed(), writer);
+ //the response and the RSS must be equal
+ Assert.assertEquals(responseTxt, outputStream.toString());
+}
+//...
+{code}
+
+To simulate a request to the custom resource we used method @startResource@ which can be used also with resource references.
+
+h3. Testing URLs
+
+@WicketTester@ can be pointed to an arbitrary URL with method @executeUrl(String url)@. This can be useful to test mounted pages, resources or request mappers:
+
+{code}
+//...
+//the resource was mapped at '/foo/bar'
+tester.executeUrl("./foo/bar");
+//...
+{code}
+
+h3. Testing AJAX components
+
+If our application uses AJAX to refresh components markup, we can test if @AjaxRequestTarget@ contains a given component with @WicketTester@'s method @assertComponentOnAjaxResponse@:
+
+{code}
+//...
+//test if AjaxRequestTarget contains a component (using its instance)
+tester.assertComponentOnAjaxResponse(amountLabel);
+//...
+//test if AjaxRequestTarget contains a component (using its path)
+tester.assertComponentOnAjaxResponse("pathToLabel:labelId");
+{code}
+
+It's also possible to use method @isComponentOnAjaxResponse(Component cmp)@ to know if a component has been added to @AjaxRequestTarget@:
+
+{code}
+//...
+//test if AjaxRequestTarget does NOT contain amountLabel
+assertFalse(tester.isComponentOnAjaxResponse(amountLabel));
+//...
+{code}
+
+h3. Testing AJAX events
+
+Behavior @AjaxEventBehavior@ and its subclasses can be tested simulating AJAX events with @WicketTester@'s method @executeAjaxEvent(Component cmp, String event)@. Here is the sample code from project @TestAjaxEventsExample@:
+
+*Home page code:*
+
+{code}
+public class HomePage extends WebPage {
+ public static String INIT_VALUE = "Initial value";
+ public static String OTHER_VALUE = "Other value";
+
+ public HomePage(final PageParameters parameters) {
+ super(parameters);
+ Label label;
+ add(label = new Label("label", INIT_VALUE));
+ label.add(new AjaxEventBehavior("click") {
+
+ @Override
+ protected void onEvent(AjaxRequestTarget target) {
+ //change label's data object
+ getComponent().setDefaultModelObject(
+ OTHER_VALUE);
+ target.add(getComponent());
+ }
+ }).setOutputMarkupId(true);
+ //...
+ }
+}
+{code}
+
+*Test method:*
+
+{code}
+@Test
+public void testAjaxBehavior(){
+ //start and render the test page
+ tester.startPage(HomePage.class);
+ //test if label has the initial expected value
+ tester.assertLabel("label", HomePage.INIT_VALUE);
+ //simulate an AJAX "click" event
+ tester.executeAjaxEvent("label", "click");
+ //test if label has changed as expected
+ tester.assertLabel("label", HomePage.OTHER_VALUE);
+}
+{code}
+
+h3. Testing AJAX behaviors
+
+To test a generic AJAX behavior we can simulate a request to it using @WicketTester@'s method @executeBehavior(AbstractAjaxBehavior behavior)@:
+
+{code}
+//...
+AjaxFormComponentUpdatingBehavior ajaxBehavior =
+ new AjaxFormComponentUpdatingBehavior("change"){
+ @Override
+ protected void onUpdate(AjaxRequestTarget target) {
+ //...
+ }
+};
+component.add(ajaxBehavior);
+//...
+//execute AJAX behavior, i.e. onUpdate will be invoked
+tester.executeBehavior(ajaxBehavior));
+//...
+{code}
+
+h3. Using a custom servlet context
+
+In paragraph 13.9 we have seen how to configure our application to store resource files into a custom folder placed inside webapp root folder (see project @CustomFolder4MarkupExample@).
+
+In order to write testing code for applications that use this kind of customization, we must tell @WicketTester@ which folder to use as webapp root. This is necessary as under test environment we don't have any web server, hence it's impossible for @WicketTester@ to retrieve this parameter from servlet context.
+
+Webapp root folder can be passed to @WicketTester@'s constructor as further parameter like we did in the test case of project @CustomFolder4MarkupExample@:
+
+{code}
+public class TestHomePage{
+ private WicketTester tester;
+
+ @Before
+ public void setUp(){
+ //build the path to webapp root folder
+ File curDirectory = new File(System.getProperty("user.dir"));
+ File webContextDir = new File(curDirectory, "src/main/webapp");
+
+ tester = new WicketTester(new WicketApplication(), webContextDir.getAbsolutePath());
+ }
+ //test methods...
+}
+{code}
+
+{note}
+After a test method has been executed, we may need to clear any possible side effect occurred to the @Application@ and @Session@ objects. This can be done invoking @WicketTester@'s method @destroy()@:
+
+{code}
+@After
+public void tearDown(){
+ //clear any side effect occurred during test.
+ tester.destroy();
+}
+{code}
+{note}
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/testing/testing_2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/testing/testing_2.gdoc b/wicket-user-guide/src/docs/guide/testing/testing_2.gdoc
new file mode 100644
index 0000000..f72813d
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/testing/testing_2.gdoc
@@ -0,0 +1,99 @@
+
+
+Wicket provides utility class FormTester that is expressly designed to test Wicket forms. A new FormTester is returned by @WicketTester@'s method @newFormTester(String, boolean)@ which takes in input the page-relative path of the form we want to test and a boolean flag indicating if its form components must be filled with a blank string:
+
+{code}
+//...
+//create a new form tester without filling its form components with a blank string
+FormTester formTester = tester.newFormTester("form", false);
+//...
+{code}
+
+@FormTester@ can simulate form submission with method submit which takes in input as optional parameter the submitting component to use instead of the default one:
+
+{code}
+//...
+//create a new form tester without filling its form components with a blank string
+FormTester formTester = tester.newFormTester("form", false);
+//submit form with default submitter
+formTester.submit();
+//...
+//submit form using inner component 'button' as alternate button
+formTester.submit("button");
+{code}
+
+If we want to submit a form with an external link component we can use method @submitLink(String path, boolean pageRelative)@ specifying the path to the link.
+
+In the next paragraphs we will see how to use @WicketTester@ and @FormTester@ to interact with a form and with its children components.
+
+h3. Setting form components input
+
+The purpose of a HTML form is to collect user input. @FormTester@ comes with the following set of methods that simulate input insertion into form's fields:
+
+* *setValue(String path, String value)*: inserts the given textual value into the specified component. It can be used with components @TextField@ and @TextArea@. A version of this method that accepts a component instance instead of its path is also available.
+* *setValue(String checkboxId, boolean value)*: sets the value of a given @CheckBox@ component.
+* *setFile(String formComponentId, File file, String contentType)*: sets a @File@ object on a @FileUploadField@ component.
+* *select(String formComponentId, int index)*: selects an option among a list of possible options owned by a component. It supports components that are subclasses of @AbstractChoice@ along with @RadioGroup@ and @CheckGroup@.
+* *selectMultiple(String formComponentId, int[] indexes)*: selects all the options corresponding to the given array of indexes. It can be used with multiple-choice components like @CheckGroup@ or @ListMultipleChoice@.
+
+@setValue@ is used inside method @insertUsernamePassword@ to set the username and password fields of the form used in project @StatelessLoginForm@:
+
+{code}
+protected void insertUsernamePassword(String username, String password) {
+ //start and render the test page
+ tester.startPage(HomePage.class);
+ FormTester formTester = tester.newFormTester("form");
+ //set credentials
+ formTester.setValue("username", username);
+ formTester.setValue("password", password);
+ //submit form
+ formTester.submit();
+}
+{code}
+
+h3. Testing feedback messages
+
+To check if a page contains one or more expected feedback messages we can use the following methods provided by @WicketTester@:
+
+* *assertFeedback(String path, String... messages)*: asserts that a given panel contains the specified messages
+* *assertInfoMessages(String... expectedInfoMessages)*: asserts that the expected info messages are rendered in the page.
+* *assertErrorMessages(String... expectedErrorMessages)*: asserts that the expected error messages are rendered in the page.
+
+@assertInfoMessages@ and @assertErrorMessages@ are used in the test case from project @StatelessLoginForm@ to check that form generates a feedback message in accordance with the login result:
+
+
+{code}
+@Test
+public void testMessageForSuccessfulLogin(){
+ inserUsernamePassword("user", "user");
+ tester.assertInfoMessages("Username and password are correct!");
+}
+
+@Test
+public void testMessageForFailedLogin (){
+ inserUsernamePassword("wrongCredential", "wrongCredential");
+ tester.assertErrorMessages("Wrong username or password");
+}
+{code}
+
+h3. Testing models
+
+Component model can be tested as well. With method @assertModelValue@ we can test if a specific component has the expected data object inside its model.
+
+This method has been used in the test case of project @ModelChainingExample@ to check if the form and the drop-down menu share the same data object:
+
+{code}
+@Test
+public void testFormSelectSameModelObject(){
+ PersonListDetails personListDetails = new PersonListDetails();
+ DropDownChoice dropDownChoice = (DropDownChoice) personListDetails.get("persons");
+ List choices = dropDownChoice.getChoices();
+ //select the second option of the drop-down menu
+ dropDownChoice.setModelObject(choices.get(1));
+
+ //start and render the test page
+ tester.startPage(personListDetails);
+ //assert that form has the same data object used by drop-down menu
+ tester.assertModelValue("form", dropDownChoice.getModelObject());
+}
+{code}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/testing/testing_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/testing/testing_3.gdoc b/wicket-user-guide/src/docs/guide/testing/testing_3.gdoc
new file mode 100644
index 0000000..488301c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/testing/testing_3.gdoc
@@ -0,0 +1,62 @@
+
+
+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:*
+
+{code: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>
+{code}
+
+*Test method:*
+
+{code}
+@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());
+}
+{code}
+
+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@:
+
+{code}
+@Test
+public void customComponentMarkupTest()
+{
+ //instantiate MyComponent
+ MyComponent myComponent = //...
+
+ //render and save component markup
+ String componentMarkup = ComponentRenderer.renderComponent(myComponent);
+
+ //perform test operations
+ //...
+}
+{code}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/testing/testing_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/testing/testing_4.gdoc b/wicket-user-guide/src/docs/guide/testing/testing_4.gdoc
new file mode 100644
index 0000000..c1a233d
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/testing/testing_4.gdoc
@@ -0,0 +1,10 @@
+
+
+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/c1da4aef/wicket-user-guide/src/docs/guide/testingspring.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/testingspring.gdoc b/wicket-user-guide/src/docs/guide/testingspring.gdoc
new file mode 100644
index 0000000..f9955a4
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/testingspring.gdoc
@@ -0,0 +1 @@
+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/c1da4aef/wicket-user-guide/src/docs/guide/testingspring/testingspring_1.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/testingspring/testingspring_1.gdoc b/wicket-user-guide/src/docs/guide/testingspring/testingspring_1.gdoc
new file mode 100644
index 0000000..2434235
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/testingspring/testingspring_1.gdoc
@@ -0,0 +1,85 @@
+
+
+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:
+
+{code: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>
+{code}
+
+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:
+
+{code: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>
+{code}
+
+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:
+
+{code:xml}
+<beans>
+ <bean id="myWebApp" class="com.comsysto.webapp.MyWebApplication"/>
+</beans>
+{code}
+
+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:
+
+{code: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>
+{code}
+
+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:
+
+{code}
+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");
+}
+{code}
+
+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 :
+
+{code}
+@Component
+public class MyWebApplication extends WebApplication {
+ @Override
+ protected void init() {
+ addComponentInstantiationListener(new SpringComponentInjector(this));
+ }
+
+}
+{code}
+
+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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/testingspring/testingspring_2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/testingspring/testingspring_2.gdoc b/wicket-user-guide/src/docs/guide/testingspring/testingspring_2.gdoc
new file mode 100644
index 0000000..36eaf56
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/testingspring/testingspring_2.gdoc
@@ -0,0 +1,131 @@
+
+
+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 "Spring's TestContext":http://docs.spring.io/spring/docs/3.0.x/spring-framework-reference/html/testing.html#testcontext-framework 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:
+
+{code}
+@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);
+ }
+}
+{code}
+
+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:
+
+{code}
+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)
+{code}
+
+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.
+
+!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:
+
+{code}
+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;
+}
+{code}
+
+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:
+
+{code}
+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));
+}
+{code}
+
+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 "lifecycle callbacks":http://docs.spring.io/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-aware 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.
+
+{code}
+public interface ApplicationContextAware {
+
+ void setApplicationContext(ApplicationContext applicationContext) throws BeansException;
+
+}
+{code}
+
+So the relevant parts of @MyWebApplication@ type will now look something like the following code snippet:
+
+{code}
+@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;
+ }
+}
+{code}
+
+For additional clarification of how @MyWebApplication@ now relates to both Wicket and Spring framework here is an according class diagram:
+
+!mywebapp-class-diagramm.jpg!
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/testingspring/testingspring_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/testingspring/testingspring_3.gdoc b/wicket-user-guide/src/docs/guide/testingspring/testingspring_3.gdoc
new file mode 100644
index 0000000..9a58ace
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/testingspring/testingspring_3.gdoc
@@ -0,0 +1,3 @@
+
+
+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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/toc.yml
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/toc.yml b/wicket-user-guide/src/docs/guide/toc.yml
new file mode 100644
index 0000000..c67911d
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/toc.yml
@@ -0,0 +1,221 @@
+introduction:
+ title: Introduction
+howToSource:
+ title: How to use the example code
+whyLearn:
+ title: Why should I learn Wicket?
+ whyLearn_1: We all like spaghetti :-) ...
+ whyLearn_2: Component oriented frameworks - an overview
+ whyLearn_3: Benefits of component oriented frameworks for web development
+ whyLearn_4: Wicket vs the other component oriented frameworks
+helloWorld:
+ title: Wicket says “Hello world!”
+ helloWorld_1: Wicket distribution and modules
+ helloWorld_2: Configuration of Wicket applications
+ helloWorld_3: The HomePage class
+ helloWorld_4: Wicket Links
+ helloWorld_5: Summary
+layout:
+ title: Wicket as page layout manager
+ layout_1: Header, footer, left menu, content, etc...
+ layout_2: Here comes the inheritance!
+ layout_3: Divide et impera!
+ layout_4: Markup inheritance with the wicket:extend tag
+ layout_5: Summary
+keepControl:
+ title: Keeping control over HTML
+ keepControl_1: Hiding or disabling a component
+ keepControl_2: Modifing tag attributes
+ keepControl_3: Generating tag attribute 'id'
+ keepControl_4: Creating in-line panels with WebMarkupContainer
+ keepControl_5: Working with markup fragments
+ keepControl_6: Adding header contents to the final page
+ keepControl_7: Using stub markup in our pages/panels
+ keepControl_8: How to render component body only
+ keepControl_9: Hiding decorating elements with the wicket:enclosure tag
+ keepControl_10: Surrounding existing markup with Border
+ keepControl_11: Summary
+componentLifecycle:
+ title: Components lifecycle
+ componentLifecycle_1: Lifecycle stages of a component
+ componentLifecycle_2: Hook methods for component lifecycle
+ componentLifecycle_3: Initialization stage
+ componentLifecycle_4: Rendering stage
+ componentLifecycle_5: Removing stage
+ componentLifecycle_6: Summary
+versioningCaching:
+ title: Page versioning and caching
+ versioningCaching_1: Stateful pages vs stateless
+ versioningCaching_2: Stateful pages
+ versioningCaching_3: Stateless pages
+ versioningCaching_4: Summary
+requestProcessing:
+ title: Under the hood of the request processing
+ requestProcessing_1: Class Application and request processing
+ requestProcessing_2: Request and Response classes
+ requestProcessing_3: The “director” of request processing - RequestCycle
+ requestProcessing_4: Session Class
+ requestProcessing_5: Exception handling
+ requestProcessing_6: Summary
+urls:
+ title: Wicket Links and URL generation
+ urls_1: PageParameters
+ urls_2: Bookmarkable links
+ urls_3: Automatically creating bookmarkable links with tag wicket:link
+ urls_4: External links
+ urls_5: Stateless links
+ urls_6: Generating structured and clear URLs
+ urls_7: Summary
+modelsforms:
+ title: Wicket models and forms
+ modelsforms_1: What is a model?
+ modelsforms_2: Models and JavaBeans
+ modelsforms_3: Wicket forms
+ modelsforms_4: Component DropDownChoice
+ modelsforms_5: Model chaining
+ modelsforms_6: Detachable models
+ modelsforms_7: Using more than one model in a component
+ modelsforms_8: Use models!
+ modelsforms_9: Summary
+forms2:
+ title: Wicket forms in detail
+ forms2_1: Default form processing
+ forms2_2: Form validation and feedback messages
+ forms2_3: Input value conversion
+ forms2_4: Validation with JSR 303
+ forms2_5: Submit form with an IFormSubmittingComponent
+ forms2_6: Nested forms
+ forms2_7: Multi-line text input
+ forms2_8: File upload
+ forms2_9: Creating complex form components with FormComponentPanel
+ forms2_10: Stateless form
+ forms2_11: Working with radio buttons and checkboxes
+ forms2_12: Selecting multiple values with ListMultipleChoices and Palette
+ forms2_13: Summary
+repeaters:
+ title: Displaying multiple items with repeaters
+ repeaters_1: The RepeatingView Component
+ repeaters_2: The ListView Component
+ repeaters_3: The RefreshingView Component
+ repeaters_4: Pageable repeaters
+ repeaters_5: Summary
+i18n:
+ title: Internationalization with Wicket
+ i18n_1: Localization
+ i18n_2: Localization in Wicket
+ i18n_3: Bundles lookup algorithm
+ i18n_4: Localization of component's choices
+ i18n_5: Internationalization and Models
+ i18n_6: Summary
+resources:
+ title: Resource management with Wicket
+ resources_1: Static vs dynamic resources
+ resources_2: Resource references
+ resources_3: Package resources
+ resources_4: Adding resources to page header section
+ resources_5: Context-relative resources
+ resources_6: Resource dependencies
+ resources_7: Aggregate multiple resources with resource bundles
+ resources_8: Put JavaScript inside page body
+ resources_9: Header contributors positioning
+ resources_10: Custom resources
+ resources_11: Mounting resources
+ resources_12: Shared resources
+ resources_13: Customizing resource loading
+ resources_14: CssHeaderItem and JavaScriptHeaderItem compression
+ resources_15: Summary
+jsintegration:
+ title: An example of integration with JavaScript
+ jsintegration_1: What we want to do...
+ jsintegration_2: ...and how we will do it
+ jsintegration_3: Summary
+advanced:
+ title: Wicket advanced topics
+ advanced_1: Enriching components with behaviors
+ advanced_2: Generating callback URLs with IRequestListener
+ advanced_3: Initializers
+ advanced_4: Using JMX with Wicket
+ advanced_5: Generating HTML markup from code
+ advanced_6: Summary
+ajax:
+ title: Working with AJAX
+ ajax_1: How to use AJAX components and behaviors
+ ajax_2: Build-in AJAX components
+ ajax_3: Built-in AJAX behaviors
+ ajax_4: Using an activity indicator
+ ajax_5: AJAX request attributes and call listeners
+ ajax_6: Creating custom AJAX call listener
+ ajax_7: Summary
+jee:
+ title: Integration with enterprise containers
+ jee_1: Integrating Wicket with EJB
+ jee_2: Integrating Wicket with Spring
+ jee_3: JSR-330 annotations
+ jee_4: Summary
+nativewebsockets:
+ title: Native WebSockets
+ nativewebsockets_1: How does it work ?
+ nativewebsockets_2: How to use
+ nativewebsockets_3: Client-side APIs
+ nativewebsockets_4: Testing
+ nativewebsockets_5: Differences with Wicket-Atmosphere module.
+ nativewebsockets_6: FAQ
+security:
+ title: Security with Wicket
+ security_1: Authentication
+ security_2: Authorizations
+ security_3: Using HTTPS protocol
+ security_4: URLs encryption in detail
+ security_5: Package Resource Guard
+ security_6: Summary
+testing:
+ title: Test Driven Development with Wicket
+ testing_1: Utility class WicketTester
+ testing_2: Testing Wicket forms
+ testing_3: Testing markup with TagTester
+ testing_4: Summary
+testingspring:
+ title: Test Driven Development with Wicket and Spring
+ testingspring_1: Configuration of the runtime environment
+ testingspring_2: Configuration of the JUnit based integration test environment
+ testingspring_3: Summary
+bestpractices:
+ title: Wicket Best Practices
+ bestpractices_1: Encapsulate components correctly
+ bestpractices_2: Put models and page data in fields
+ bestpractices_3: Correct naming for Wicket IDs
+ bestpractices_4: Avoid changes at the component tree
+ bestpractices_5: Implement visibilities of components correctly
+ bestpractices_6: Always use models
+ bestpractices_7: Do not unwrap models within the constructor hierarchy
+ bestpractices_8: Pass models extended components
+ bestpractices_9: Validators must not change any data or models
+ bestpractices_10: Do not pass components to constructors
+ bestpractices_11: Use the Wicket session only for global data
+ bestpractices_12: Do not use factories for components
+ bestpractices_13: Every page and component must be tested
+ bestpractices_14: Avoid interactions with other servlet filters
+ bestpractices_15: Cut small classes and methods
+ bestpractices_16: The argument "Bad documentation"
+ bestpractices_17: Summary
+internals:
+ title: Wicket Internals
+ pagestoring: Page storing
+maven:
+ title: Working with Maven (Appendix)
+ maven_1: Switching Wicket to DEPLOYMENT mode
+ maven_2: Creating a Wicket project from scratch and importing it into our favourite IDE
+wicketstuff:
+ title: Project WicketStuff (Appendix)
+ wicketstuff_1: What is project WicketStuff
+ wicketstuff_2: Module tinymce
+ wicketstuff_3: Module wicketstuff-gmap3
+ wicketstuff_4: Module wicketstuff-googlecharts
+ wicketstuff_5: Module wicketstuff-inmethod-grid
+ wicketstuff_6: Module wicketstuff-rest-annotations
+ wicketstuff_7: Module stateless
+redirects:
+ title: Lost In Redirection With Apache Wicket (Appendix)
+contributing:
+ title: Contributing to this guide (Appendix)
+
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/urls.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/urls.gdoc b/wicket-user-guide/src/docs/guide/urls.gdoc
new file mode 100644
index 0000000..8353113
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/urls.gdoc
@@ -0,0 +1,5 @@
+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 paragraph 2.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/c1da4aef/wicket-user-guide/src/docs/guide/urls/urls_1.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/urls/urls_1.gdoc b/wicket-user-guide/src/docs/guide/urls/urls_1.gdoc
new file mode 100644
index 0000000..2b439ef
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/urls/urls_1.gdoc
@@ -0,0 +1,106 @@
+
+
+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:
+
+{code}
+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");
+{code}
+
+Now that we have seen how to work with page parameters, let's see how to use them with our pages.
+
+h3. 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:
+
+{code}
+add(new Link("pageWithIndexParam") {
+
+ @Override
+ public void onClick() {
+
+ PageParameters pageParameters = new PageParameters();
+ pageParameters.add("foo", "foo");
+ pageParameters.add("bar", "bar");
+
+ setResponsePage(PageWithParameters.class, pageParameters);
+ }
+
+});
+{code}
+
+Target page code:
+
+{code}
+public class PageWithParameters extends WebPage {
+ //Override superclass constructor
+ public PageWithParameters(PageParameters parameters) {
+ super(parameters);
+ }
+ }
+{code}
+
+The code is quite straightforward and it’s more interesting to look at the URL generated for the target page:
+
+{code:html}
+<app root>/PageParametersExample/wicket/bookmarkable/
+ org.wicketTutorial.PageWithParameters?foo=foo&bar=bar
+{code}
+
+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.
+
+h3. 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:
+
+{code:html}
+<application path>/foo/bar?1&baz=baz
+{code}
+
+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:
+
+{code}
+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);
+{code}
+
+Project PageParametersExample comes also with a link to a page with both indexed parameters and a named parameter:
+
+{code}
+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);
+ }
+
+});
+{code}
+
+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/c1da4aef/wicket-user-guide/src/docs/guide/urls/urls_2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/urls/urls_2.gdoc b/wicket-user-guide/src/docs/guide/urls/urls_2.gdoc
new file mode 100644
index 0000000..91a28f2
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/urls/urls_2.gdoc
@@ -0,0 +1,9 @@
+
+
+A link to a bookmarkable page can be built with the link component @org.apache.wicket.markup.html.link.BookmarkablePageLink@:
+
+{code}
+BookmarkablePageLink bpl=new BookmarkablePageLink(PageWithParameters.class, pageParameters);
+{code}
+
+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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/urls/urls_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/urls/urls_3.gdoc b/wicket-user-guide/src/docs/guide/urls/urls_3.gdoc
new file mode 100644
index 0000000..9f85265
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/urls/urls_3.gdoc
@@ -0,0 +1,68 @@
+
+
+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:
+
+{code: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>
+{code}
+
+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:
+
+{code:html}
+<a href="/org/wicketTutorial/anotherPackage/SubPackagePage.html"> SubPackagePage</a>
+{code}
+
+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):
+
+{code: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>
+{code}
+
+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:
+
+{code:html}
+<span><em>HomePage</em></span>
+{code}
+
+The markup used to render disabled links can be customized using the markup settings (interface IMarkupSettings) available in the application class:
+
+{code}
+@Override
+public void init()
+{
+ super.init();
+ //wrap disabled links with <b> tag
+ getMarkupSettings().setDefaultBeforeDisabledLink("<b>");
+ getMarkupSettings().setDefaultAfterDisabledLink("</b>");
+}
+{code}
+
+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/c1da4aef/wicket-user-guide/src/docs/guide/urls/urls_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/urls/urls_4.gdoc b/wicket-user-guide/src/docs/guide/urls/urls_4.gdoc
new file mode 100644
index 0000000..d048898
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/urls/urls_4.gdoc
@@ -0,0 +1,50 @@
+
+
+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:
+
+{code:html}
+<a wicket:id="externalSite">Search me on Google!</a>
+{code}
+
+Java code:
+
+{code}
+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));
+{code}
+
+Generated anchor:
+
+{code:html}
+<a href="http://www.google.com/search?q=John+Smith">Search me on Google!</a>
+{code}
+
+If we need to specify a dynamic value for the text inside the anchor, we can pass it as an additional constructor parameter:
+
+Html:
+
+{code:html}
+<a wicket:id="externalSite">Label goes here...</a>
+{code}
+
+Java code:
+
+{code}
+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));
+{code}
+
+Generated anchor:
+
+{code:html}
+<a href="http://www.google.com/search?q=John+Smith">Search 'John Smith' on Google.</a>
+{code}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/urls/urls_5.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/urls/urls_5.gdoc b/wicket-user-guide/src/docs/guide/urls/urls_5.gdoc
new file mode 100644
index 0000000..ded1c0d
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/urls/urls_5.gdoc
@@ -0,0 +1,33 @@
+
+
+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():
+
+{code}
+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++);
+ }
+
+ });
+ }
+}
+{code}
+
+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.
\ No newline at end of file