http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_5.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_5.adoc new file mode 100644 index 0000000..6abf760 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_5.adoc @@ -0,0 +1,44 @@ + +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: + +[source,html] +---- +<script src="/misc/js/jscript.js"></script> +<link type="text/css" rel="stylesheet" href="/misc/css/themes/style.css" /> +---- + +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: + +[source,java] +---- +ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js"); +---- + +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: + +[source,java] +---- +//it will always use '/misc/js/jscript.js' +ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", false); +---- + +The minified postfix can be customized with an optional string parameter: + +[source,java] +---- +//it will use '/misc/js/jscript.minified.js' in DEPLOYMENT mode +ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", "minified"); +---- + +_ContextRelativeResourceReference_ is usually used with the header item classes we have seen before in this chapter to create entries for the page header section. + +=== 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> + +[source,java] +---- +//build the component specifying its id and picture's context path +ContextImage image = new ContextImage("myPicture", "/misc/imgs/mypic.png"); +---- +
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_6.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_6.adoc new file mode 100644 index 0000000..b40d8b4 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_6.adoc @@ -0,0 +1,30 @@ + + + +Class _ResourceReference_ allows to specify the resources it depends on overriding method _getDependencies()_. The method returns a list of _HeaderItem_s 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: + +[source,java] +---- +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 List<HeaderItem> getDependencies() { + Application application = Application.get(); + ResourceReference jqueryRef = application.getJavaScriptLibrarySettings(). + getJQueryReference(); + + return Arrays.asList(JavaScriptHeaderItem.forReference(jqueryRef)); + } +}; +---- + +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. + +NOTE: Wicket already provides base class _org.apache.wicket.resource.JQueryPluginResourceReference_ for those JavaScript resources that depend on JQuery. This class uses the JQuery version bundled with Wicket. + +NOTE: The same method _getDependencies()_ is defined also for class _HeaderItem_. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_7.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_7.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_7.adoc new file mode 100644 index 0000000..0c8a330 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_7.adoc @@ -0,0 +1,26 @@ + +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: + +[source,java] +---- +@Override +public void init() { + super.init(); + + getResourceBundles().addJavaScriptBundle(WicketApplication.class, + "jqueryUiJs", + jqueryJsReference, + jqueryUiJsReference); + + getResourceBundles().addCssBundle(WicketApplication.class, + "jqueryUiCss", + jqueryCssReference, + jqueryUiCssReference); + +} +---- + +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). + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc new file mode 100644 index 0000000..cde2c40 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc @@ -0,0 +1,110 @@ + +Some web developers prefer to put their <script> tags at the end of page body and not inside the <head> tags: + +[source,html] +---- + +<html> + +<head> +//no <script> tag here... +</head> + +<body> +... +<script> +//one or more <script> tags at the end of the body +</script> +</body> +</html> + +---- + + +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 functionalities 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: + +[source,java] +---- + + //... + @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); + } + + } +---- + +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: + +[source,java] +---- +add(new HeaderResponseContainer("someId", "filterName")); +---- + +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: + +[source,html] +---- + +<html> + +<header> +//no <script> tag here... +</header> + +<body> +<!-- here we will have our JavaScript tags --> +<wicket:container wicket:id="someId"/> +</body> +</html> + +---- + +The code of the home page is the following: + +[source,java] +---- + 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!')")); + } +---- + +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/7eba9998/wicket-user-guide/src/main/asciidoc/resources/resources_9.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_9.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_9.adoc new file mode 100644 index 0000000..ce2c65b --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_9.adoc @@ -0,0 +1,18 @@ + +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/>_: + +[source,html] +---- +<head> + <meta charset="UTF-8"/> + <wicket:header-items/> + <script src="my-monkey-patch-of-wicket-ajax.js"></script> +</head> +---- + +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/7eba9998/wicket-user-guide/src/main/asciidoc/security.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security.adoc b/wicket-user-guide/src/main/asciidoc/security.adoc new file mode 100644 index 0000000..f499eb1 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security.adoc @@ -0,0 +1,4 @@ + +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. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/security/security_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_1.adoc b/wicket-user-guide/src/main/asciidoc/security/security_1.adoc new file mode 100644 index 0000000..fbea82b --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_1.adoc @@ -0,0 +1,175 @@ + + + +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: + +image::../img/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_. + +=== 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. + +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. + +=== 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. + +=== 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: + +[source,java] +---- +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()); + } + }); + } +} +---- + +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: + +[source,java] +---- +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); + } +} +---- + +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:* + +[source,java] +---- +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; + } +} +---- + +*Application class:* + +[source,java] +---- +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; + } +} +---- + +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_. + +=== 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: + +[source,java] +---- + redirectToInterceptPage(intermediatePage); +---- + +NOTE: Since both _restartResponseAtSignInPage_ and _redirectToInterceptPage_ internally throw an exception, the code placed after them will not be executed. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/security/security_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_2.adoc b/wicket-user-guide/src/main/asciidoc/security/security_2.adoc new file mode 100644 index 0000000..025971d --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_2.adoc @@ -0,0 +1,288 @@ + + + +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_): + +[source,java] +---- +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; + } + }; +} +---- + +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 (class _SecuritySettings_) during initialization phase with method setAuthorization Strategy: + +[source,java] +---- + //Application class code... + @Override + public void init() + { + super.init(); + getSecuritySettings(). + setAuthorizationStrategy(myAuthorizationStrategy); + } +//... +---- + +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. + +=== 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: + +[source,java] +---- +SimplePageAuthorizationStrategy authorizationStrategy = new SimplePageAuthorizationStrategy( + PageClassToCheck.class, SignInPage.class) +{ + protected boolean isAuthorized() + { + //Authentication 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. + +=== Role-based strategies + +At the end of <<security.adoc#_authentication,paragraph 22.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: + +[source,java] +---- +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; + } +} +---- + +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 <<security.adoc#_authorizations,paragraph 22.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. + +==== 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:* + +[source,java] +---- +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); + } +} +---- + +*Session class:* + +[source,java] +---- +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; + } +} +---- + +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: + +image::../img/authorization-access-denied.png[] + +The access-denied page can be customized using method _setAccessDeniedPage(Class<? extends Page>)_ of setting class _ApplicationSettings_: + +[source,java] +---- + //Application class code... + @Override + public void init(){ + getApplicationSettings().setAccessDeniedPage( + MyCustomAccessDeniedPage.class); + } +---- + +Just like custom âPage expiredâ page (see <<versioningCaching.adoc#_stateful_pages,chapter 8.2.5>>), also custom âAccess deniedâ page must be bookmarkable. + +==== 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: + +[source,java] +---- +@AuthorizeInstantiation("SIGNED_IN") +@AuthorizeAction(action = "ENABLE", roles = {"ADMIN"}) +public class MyPage extends WebPage { + //Page class 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: + +[source,java] +---- +@AuthorizeInstantiation("ADMIN") +public class AdminOnlyPage extends WebPage { + //Page class code... +} +---- + +=== 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 _setUnauthorizedComponentInstantiationListener_ defined by setting class _SecuritySettings_. 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: + +[source,java] +---- +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); + } + }); + } +} +---- + +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. + +=== 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/7eba9998/wicket-user-guide/src/main/asciidoc/security/security_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_3.adoc b/wicket-user-guide/src/main/asciidoc/security/security_3.adoc new file mode 100644 index 0000000..f667b8f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_3.adoc @@ -0,0 +1,61 @@ + + + +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 <<urls.adoc#_generating_structured_and_clear_urls,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: + +[source,java] +---- +//Application class code... +@Override +public void init(){ + setRootRequestMapper(new HttpsMapper(getRootRequestMapper(), + new HttpsConfig(8080, 443))); +} +---- + +Now we can use annotation RequireHttps to specify which pages must be served using HTTPS: + +[source,java] +---- +@RequireHttps +public class HomePage extends WebPage { + public HomePage(final PageParameters parameters) { + super(parameters); + } +} +---- + +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: + +[source,java] +---- +// 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... +} +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/security/security_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_4.adoc b/wicket-user-guide/src/main/asciidoc/security/security_4.adoc new file mode 100644 index 0000000..c91c3d0 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_4.adoc @@ -0,0 +1,53 @@ + +In chapter <<urls.adoc#_generating_structured_and_clear_urls,10.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: + +[source,java] +---- +public interface ICrypt +{ + String encryptUrlSafe(final String plainText); + + String decryptUrlSafe(final String encryptedText); + + ... +} +---- + +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 http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html[Policy Files] + +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.SecuritySettings1.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: + +[source,java] +---- +public interface IProvider<T> +{ + T get(); +} +---- + +* The second option is to register a cipher factory at application level with method _setCryptFactory(ICryptFactory cryptFactory)_ of class _SecuritySettings_: + +[source,java] +---- +@Override +public void init() { + super.init(); + getSecuritySettings().setCryptFactory(new SomeCryptFactory()); + setRootRequestMapper(new CryptoMapper(getRootRequestMapper(), this)); +} +---- + + +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 https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)[CSRF] +for each user of the application. The url itself serves as https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet#Encrypted_Token_Pattern[encrypted token] + +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. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/security/security_4_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_4_1.adoc b/wicket-user-guide/src/main/asciidoc/security/security_4_1.adoc new file mode 100644 index 0000000..ce801ba --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_4_1.adoc @@ -0,0 +1,21 @@ + + +_CryptoMapper_ helps preventing CSRF attacks by making the urls impossible to be guessed by an attacker but still there is some theoretical chance this to happen. + +To further help against this kind of vulnerability Wicket provides _CsrfPreventionRequestCycleListener_ - a _IRequestCycleListener_ that forbids requests made from a different origin. By default only actions are forbidden, i.e. a request coming from different origin cannot execute _Link1.onClick()_ or submit forms (_Form1.onSubmit()_). Any request to render pages are still allowed so Wicket pages could be easily embedded in other applications. + +MyApplication.java +[source,java] +---- + @Override + protected void init() { + super.init(); + getRequestCycleListeners().add(new CsrfPreventionRequestCycleListener()); + // ... + } +---- + +_CsrfPreventionRequestCycleListener_ is highly configurable. It allows to define a whitelist of allowed origins via _addAcceptedOrigin(String acceptedOrigin)_, to enable/disable it dynamically by overriding _isEnabled()_, to define different kind of actions when a request is rejected or allowed, to set custom error message and code for the rejected requests. + +_CsrfPreventionRequestCycleListener_ is not an alternative to _CryptoMapper_! Both of them could be used separately or in tandem to prevent CSRF attacks depending on the application requirements. + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/security/security_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_5.adoc b/wicket-user-guide/src/main/asciidoc/security/security_5.adoc new file mode 100644 index 0000000..ed02541 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_5.adoc @@ -0,0 +1,44 @@ + + + +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): + +|=== +|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 +|=== + +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: + +[source,java] +---- +//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"); + } +} +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/security/security_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_6.adoc b/wicket-user-guide/src/main/asciidoc/security/security_6.adoc new file mode 100644 index 0000000..c7993f9 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_6.adoc @@ -0,0 +1,44 @@ + +Since Mozilla released their site to check if web pages have security issues named https://observatory.mozilla.org[Mozilla Observatory] +a few things which can be done to get a high grade within this ranking without using further frameworks. + +Add a request cycle listener to your web application and adjust the headers to fit your requirements: +[source,java] +---- +@Override +protected void init() +{ + super.init(); + + getRequestCycleListeners().add(new AbstractRequestCycleListener(){ + + @Override + public void onEndRequest(RequestCycle cycle) + { + WebResponse response = (WebResponse) cycle.getResponse(); + response.setHeader("X-XSS-Protection", "1; mode=block"); + response.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains; preload"); + response.setHeader("X-Content-Type-Options", "nosniff"); + response.setHeader("X-Frame-Options", "sameorigin"); + response.setHeader("Content-Security-Policy", "default-src https:"); + } + }); +} +---- + +Add this configuration to your web.xml (or let your server redirect to https): +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<security-constraint> + <web-resource-collection> + <web-resource-name>Entire Application</web-resource-name> + <url-pattern>/*</url-pattern> + </web-resource-collection> + <user-data-constraint> + <transport-guarantee>CONFIDENTIAL</transport-guarantee> + </user-data-constraint> +</security-constraint> +---- + +After this changes you have to check if your web application continues to work because it fits the requirements given with this header files. For example that resources must not requested from other domains anymore. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/security/security_7.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_7.adoc b/wicket-user-guide/src/main/asciidoc/security/security_7.adoc new file mode 100644 index 0000000..b36dfd5 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_7.adoc @@ -0,0 +1,16 @@ + + + + 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/7eba9998/wicket-user-guide/src/main/asciidoc/single.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/single.adoc b/wicket-user-guide/src/main/asciidoc/single.adoc new file mode 100644 index 0000000..ba4ea7e --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/single.adoc @@ -0,0 +1,853 @@ += Wicket 7.x Reference Guide +The Apache Software Foundation +:toc: left +:icons: font +:sectlinks: + +//custom variables used inside the guide +:wicket_examples_url: http://examples7x.wicket.apache.org +:wicket_tutorial_examples_url: http://examples-wickettutorial.rhcloud.com/ + +:sectnums: + +== Introduction + +include::introduction.adoc[] + +== How to use the example code + +include::howToSource.adoc[] + +== Why should I learn Wicket? + +include::whyLearn.adoc[] + +=== We all like spaghetti :-) ... + +include::whyLearn/whyLearn_1.adoc[leveloffset=+1] + +=== Component oriented frameworks - an overview + +include::whyLearn/whyLearn_2.adoc[leveloffset=+1] + +=== Benefits of component oriented frameworks for web development + +include::whyLearn/whyLearn_3.adoc[leveloffset=+1] + +=== Wicket vs the other component oriented frameworks + +include::whyLearn/whyLearn_4.adoc[leveloffset=+1] + +== Wicket says âHello world!â + +include::helloWorld.adoc[] + +=== Wicket distribution and modules + +include::helloWorld/helloWorld_1.adoc[leveloffset=+1] + +=== Configuration of Wicket applications + +include::helloWorld/helloWorld_2.adoc[leveloffset=+1] + +=== The HomePage class + +include::helloWorld/helloWorld_3.adoc[leveloffset=+1] + +=== Wicket Links + +include::helloWorld/helloWorld_4.adoc[leveloffset=+1] + +=== Summary + +include::helloWorld/helloWorld_5.adoc[leveloffset=+1] + +== Wicket as page layout manager + +include::layout.adoc[] + +=== Header, footer, left menu, content, etc... + +include::layout/layout_1.adoc[leveloffset=+1] + +=== Here comes the inheritance! + +include::layout/layout_2.adoc[leveloffset=+1] + +=== Divide et impera! + +include::layout/layout_3.adoc[leveloffset=+1] + +=== Markup inheritance with the wicket:extend tag + +include::layout/layout_4.adoc[leveloffset=+1] + +=== Summary + +include::layout/layout_5.adoc[leveloffset=+1] + +== Keeping control over HTML + +include::keepControl.adoc[] + +=== Hiding or disabling a component + +include::keepControl/keepControl_1.adoc[leveloffset=+1] + +=== Modifing tag attributes + +include::keepControl/keepControl_2.adoc[leveloffset=+1] + +=== Generating tag attribute 'id' + +include::keepControl/keepControl_3.adoc[leveloffset=+1] + +=== Creating in-line panels with WebMarkupContainer + +include::keepControl/keepControl_4.adoc[leveloffset=+1] + +=== Working with markup fragments + +include::keepControl/keepControl_5.adoc[leveloffset=+1] + +=== Adding header contents to the final page + +include::keepControl/keepControl_6.adoc[leveloffset=+1] + +=== Using stub markup in our pages/panels + +include::keepControl/keepControl_7.adoc[leveloffset=+1] + +=== How to render component body only + +include::keepControl/keepControl_8.adoc[leveloffset=+1] + +=== Hiding decorating elements with the wicket:enclosure tag + +include::keepControl/keepControl_9.adoc[leveloffset=+1] + +=== Surrounding existing markup with Border + +include::keepControl/keepControl_10.adoc[leveloffset=+1] + +=== Summary + +include::keepControl/keepControl_11.adoc[leveloffset=+1] + +== Components lifecycle + +include::componentLifecycle.adoc[] + +=== Lifecycle stages of a component + +include::componentLifecycle/componentLifecycle_1.adoc[leveloffset=+1] + +=== Hook methods for component lifecycle + +include::componentLifecycle/componentLifecycle_2.adoc[leveloffset=+1] + +=== Initialization stage + +include::componentLifecycle/componentLifecycle_3.adoc[leveloffset=+1] + +=== Rendering stage + +include::componentLifecycle/componentLifecycle_4.adoc[leveloffset=+1] + +=== Removing stage + +include::componentLifecycle/componentLifecycle_5.adoc[leveloffset=+1] + +=== Summary + +include::componentLifecycle/componentLifecycle_6.adoc[leveloffset=+1] + +== Page versioning and caching + +include::versioningCaching.adoc[] + +=== Stateful pages vs stateless + +include::versioningCaching/versioningCaching_1.adoc[leveloffset=+1] + +=== Stateful pages + +include::versioningCaching/versioningCaching_2.adoc[leveloffset=+1] + +=== Stateless pages + +include::versioningCaching/versioningCaching_3.adoc[leveloffset=+1] + +=== Summary + +include::versioningCaching/versioningCaching_4.adoc[leveloffset=+1] + +== Under the hood of the request processing + +include::requestProcessing.adoc[] + +=== Class Application and request processing + +include::requestProcessing/requestProcessing_1.adoc[leveloffset=+1] + +=== Request and Response classes + +include::requestProcessing/requestProcessing_2.adoc[leveloffset=+1] + +=== The âdirectorâ of request processing - RequestCycle + +include::requestProcessing/requestProcessing_3.adoc[leveloffset=+1] + +=== Session Class + +include::requestProcessing/requestProcessing_4.adoc[leveloffset=+1] + +=== Exception handling + +include::requestProcessing/requestProcessing_5.adoc[leveloffset=+1] + +=== Summary + +include::requestProcessing/requestProcessing_6.adoc[leveloffset=+1] + +== Wicket Links and URL generation + +include::urls.adoc[] + +=== PageParameters + +include::urls/urls_1.adoc[leveloffset=+1] + +=== Bookmarkable links + +include::urls/urls_2.adoc[leveloffset=+1] + +=== Automatically creating bookmarkable links with tag wicket:link + +include::urls/urls_3.adoc[leveloffset=+1] + +=== External links + +include::urls/urls_4.adoc[leveloffset=+1] + +=== Stateless links + +include::urls/urls_5.adoc[leveloffset=+1] + +=== Generating structured and clear URLs + +include::urls/urls_6.adoc[leveloffset=+1] + +=== Summary + +include::urls/urls_7.adoc[leveloffset=+1] + +== Wicket models and forms + +include::modelsforms.adoc[] + +=== What is a model? + +include::modelsforms/modelsforms_1.adoc[leveloffset=+1] + +=== Models and JavaBeans + +include::modelsforms/modelsforms_2.adoc[leveloffset=+1] + +=== Wicket forms + +include::modelsforms/modelsforms_3.adoc[leveloffset=+1] + +=== Component DropDownChoice + +include::modelsforms/modelsforms_4.adoc[leveloffset=+1] + +=== Model chaining + +include::modelsforms/modelsforms_5.adoc[leveloffset=+1] + +=== Detachable models + +include::modelsforms/modelsforms_6.adoc[leveloffset=+1] + +=== Using more than one model in a component + +include::modelsforms/modelsforms_7.adoc[leveloffset=+1] + +=== Use models! + +include::modelsforms/modelsforms_8.adoc[leveloffset=+1] + +=== Summary + +include::modelsforms/modelsforms_9.adoc[leveloffset=+1] + +== Wicket forms in detail + +include::forms2.adoc[] + +=== Default form processing + +include::forms2/forms2_1.adoc[leveloffset=+1] + +=== Form validation and feedback messages + +include::forms2/forms2_2.adoc[leveloffset=+1] + +=== Input value conversion + +include::forms2/forms2_3.adoc[leveloffset=+1] + +=== Validation with JSR 303 + +include::forms2/forms2_4.adoc[leveloffset=+1] + +=== Submit form with an IFormSubmittingComponent + +include::forms2/forms2_5.adoc[leveloffset=+1] + +=== Nested forms + +include::forms2/forms2_6.adoc[leveloffset=+1] + +=== Multi-line text input + +include::forms2/forms2_7.adoc[leveloffset=+1] + +=== File upload + +include::forms2/forms2_8.adoc[leveloffset=+1] + +=== Creating complex form components with FormComponentPanel + +include::forms2/forms2_9.adoc[leveloffset=+1] + +=== Stateless form + +include::forms2/forms2_10.adoc[leveloffset=+1] + +=== Working with radio buttons and checkboxes + +include::forms2/forms2_11.adoc[leveloffset=+1] + +=== Selecting multiple values with ListMultipleChoices and Palette + +include::forms2/forms2_12.adoc[leveloffset=+1] + +=== Summary + +include::forms2/forms2_13.adoc[leveloffset=+1] + +== Displaying multiple items with repeaters + +include::repeaters.adoc[] + +=== The RepeatingView Component + +include::repeaters/repeaters_1.adoc[leveloffset=+1] + +=== The ListView Component + +include::repeaters/repeaters_2.adoc[leveloffset=+1] + +=== The RefreshingView Component + +include::repeaters/repeaters_3.adoc[leveloffset=+1] + +=== Pageable repeaters + +include::repeaters/repeaters_4.adoc[leveloffset=+1] + +=== Summary + +include::repeaters/repeaters_5.adoc[leveloffset=+1] + +== Component queueing + +include::componentQueueing.adoc[] + +=== Markup hierarchy and code + +include::componentQueueing/componentQueueing_1.adoc[leveloffset=+1] + +=== Improved auto components + +include::componentQueueing/componentQueueing_2.adoc[leveloffset=+1] + +=== When are components dequeued? + +include::componentQueueing/componentQueueing_3.adoc[leveloffset=+1] + +=== Restrictions of queueing + +include::componentQueueing/componentQueueing_4.adoc[leveloffset=+1] + +=== Summary + +include::componentQueueing/componentQueueing_5.adoc[leveloffset=+1] + +== Internationalization with Wicket + +include::i18n.adoc[] + +=== Localization + +include::i18n/i18n_1.adoc[leveloffset=+1] + +=== Localization in Wicket + +include::i18n/i18n_2.adoc[leveloffset=+1] + +=== Bundles lookup algorithm + +include::i18n/i18n_3.adoc[leveloffset=+1] + +=== Localization of component's choices + +include::i18n/i18n_4.adoc[leveloffset=+1] + +=== Internationalization and Models + +include::i18n/i18n_5.adoc[leveloffset=+1] + +=== Summary + +include::i18n/i18n_6.adoc[leveloffset=+1] + +== Resource management with Wicket + +include::resources.adoc[] + +=== Static vs dynamic resources + +include::resources/resources_1.adoc[leveloffset=+1] + +=== Resource references + +include::resources/resources_2.adoc[leveloffset=+1] + +=== Package resources + +include::resources/resources_3.adoc[leveloffset=+1] + +=== Adding resources to page header section + +include::resources/resources_4.adoc[leveloffset=+1] + +=== Context-relative resources + +include::resources/resources_5.adoc[leveloffset=+1] + +=== Resource dependencies + +include::resources/resources_6.adoc[leveloffset=+1] + +=== Aggregate multiple resources with resource bundles + +include::resources/resources_7.adoc[leveloffset=+1] + +=== Put JavaScript inside page body + +include::resources/resources_8.adoc[leveloffset=+1] + +=== Header contributors positioning + +include::resources/resources_9.adoc[leveloffset=+1] + +=== Custom resources + +include::resources/resources_10.adoc[leveloffset=+1] + +=== Mounting resources + +include::resources/resources_11.adoc[leveloffset=+1] + +=== Shared resources + +include::resources/resources_12.adoc[leveloffset=+1] + +=== Customizing resource loading + +include::resources/resources_13.adoc[leveloffset=+1] + +=== CssHeaderItem and JavaScriptHeaderItem compression + +include::resources/resources_14.adoc[leveloffset=+1] + +=== NIO resources + +include::resources/resources_15.adoc[leveloffset=+1] + +=== Resourcen derived through models + +include::resources/resources_16.adoc[leveloffset=+1] + +=== Summary + +include::resources/resources_17.adoc[leveloffset=+1] + +== An example of integration with JavaScript + +include::jsintegration.adoc[] + +=== What we want to do... + +include::jsintegration/jsintegration_1.adoc[leveloffset=+1] + +=== ...and how we will do it + +include::jsintegration/jsintegration_2.adoc[leveloffset=+1] + +=== Summary + +include::jsintegration/jsintegration_3.adoc[leveloffset=+1] + +== Wicket advanced topics + +include::advanced.adoc[] + +=== Enriching components with behaviors + +include::advanced/advanced_1.adoc[leveloffset=+1] + +=== Generating callback URLs with IRequestListener + +include::advanced/advanced_2.adoc[leveloffset=+1] + +=== Wicket events infrastructure + +include::advanced/advanced_3.adoc[leveloffset=+1] + +=== Initializers + +include::advanced/advanced_4.adoc[leveloffset=+1] + +=== Using JMX with Wicket + +include::advanced/advanced_5.adoc[leveloffset=+1] + +=== Generating HTML markup from code + +include::advanced/advanced_6.adoc[leveloffset=+1] + +=== Summary + +include::advanced/advanced_7.adoc[leveloffset=+1] + +== Working with AJAX + +include::ajax.adoc[] + +=== How to use AJAX components and behaviors + +include::ajax/ajax_1.adoc[leveloffset=+1] + +=== Build-in AJAX components + +include::ajax/ajax_2.adoc[leveloffset=+1] + +=== Built-in AJAX behaviors + +include::ajax/ajax_3.adoc[leveloffset=+1] + +=== Using an activity indicator + +include::ajax/ajax_4.adoc[leveloffset=+1] + +=== AJAX request attributes and call listeners + +include::ajax/ajax_5.adoc[leveloffset=+1] + +=== Creating custom AJAX call listener + +include::ajax/ajax_6.adoc[leveloffset=+1] + +=== Stateless AJAX components/behaviors + +include::ajax/ajax_7.adoc[leveloffset=+1] + +=== Summary + +include::ajax/ajax_8.adoc[leveloffset=+1] + +== Integration with enterprise containers + +include::jee.adoc[] + +=== Integrating Wicket with EJB + +include::jee/jee_1.adoc[leveloffset=+1] + +=== Integrating Wicket with Spring + +include::jee/jee_2.adoc[leveloffset=+1] + +=== JSR-330 annotations + +include::jee/jee_3.adoc[leveloffset=+1] + +=== Summary + +include::jee/jee_4.adoc[leveloffset=+1] + +== Native WebSockets + +include::nativewebsockets.adoc[] + +=== How does it work ? + +include::nativewebsockets/nativewebsockets_1.adoc[leveloffset=+1] + +=== How to use + +include::nativewebsockets/nativewebsockets_2.adoc[leveloffset=+1] + +=== Client-side APIs + +include::nativewebsockets/nativewebsockets_3.adoc[leveloffset=+1] + +=== Testing + +include::nativewebsockets/nativewebsockets_4.adoc[leveloffset=+1] + +=== Differences with Wicket-Atmosphere module. + +include::nativewebsockets/nativewebsockets_5.adoc[leveloffset=+1] + +=== FAQ + +include::nativewebsockets/nativewebsockets_6.adoc[leveloffset=+1] + +== Security with Wicket + +include::security.adoc[] + +=== Authentication + +include::security/security_1.adoc[leveloffset=+1] + +=== Authorizations + +include::security/security_2.adoc[leveloffset=+1] + +=== Using HTTPS protocol + +include::security/security_3.adoc[leveloffset=+1] + +=== URLs encryption in detail + +include::security/security_4.adoc[leveloffset=+1] + +=== CSRF protection + +include::security/security_4_1.adoc[leveloffset=+1] + +=== Package Resource Guard + +include::security/security_5.adoc[leveloffset=+1] + +=== External Security Checks + +include::security/security_6.adoc[leveloffset=+1] + +=== Summary + +include::security/security_7.adoc[leveloffset=+1] + +== Test Driven Development with Wicket + +include::testing.adoc[] + +=== Utility class WicketTester + +include::testing/testing_1.adoc[leveloffset=+1] + +=== Testing Wicket forms + +include::testing/testing_2.adoc[leveloffset=+1] + +=== Testing markup with TagTester + +include::testing/testing_3.adoc[leveloffset=+1] + +=== Summary + +include::testing/testing_4.adoc[leveloffset=+1] + +== Test Driven Development with Wicket and Spring + +include::testingspring.adoc[] + +=== Configuration of the runtime environment + +include::testingspring/testingspring_1.adoc[leveloffset=+1] + +=== Configuration of the JUnit based integration test environment + +include::testingspring/testingspring_2.adoc[leveloffset=+1] + +=== Summary + +include::testingspring/testingspring_3.adoc[leveloffset=+1] + +== Wicket Best Practices + +include::bestpractices.adoc[] + +=== Encapsulate components correctly + +include::bestpractices/bestpractices_1.adoc[leveloffset=+1] + +=== Put models and page data in fields + +include::bestpractices/bestpractices_2.adoc[leveloffset=+1] + +=== Correct naming for Wicket IDs + +include::bestpractices/bestpractices_3.adoc[leveloffset=+1] + +=== Avoid changes at the component tree + +include::bestpractices/bestpractices_4.adoc[leveloffset=+1] + +=== Implement visibilities of components correctly + +include::bestpractices/bestpractices_5.adoc[leveloffset=+1] + +=== Always use models + +include::bestpractices/bestpractices_6.adoc[leveloffset=+1] + +=== Do not unwrap models within the constructor hierarchy + +include::bestpractices/bestpractices_7.adoc[leveloffset=+1] + +=== Pass models extended components + +include::bestpractices/bestpractices_8.adoc[leveloffset=+1] + +=== Validators must not change any data or models + +include::bestpractices/bestpractices_9.adoc[leveloffset=+1] + +=== Do not pass components to constructors + +include::bestpractices/bestpractices_10.adoc[leveloffset=+1] + +=== Use the Wicket session only for global data + +include::bestpractices/bestpractices_11.adoc[leveloffset=+1] + +=== Do not use factories for components + +include::bestpractices/bestpractices_12.adoc[leveloffset=+1] + +=== Every page and component must be tested + +include::bestpractices/bestpractices_13.adoc[leveloffset=+1] + +=== Avoid interactions with other servlet filters + +include::bestpractices/bestpractices_14.adoc[leveloffset=+1] + +=== Cut small classes and methods + +include::bestpractices/bestpractices_15.adoc[leveloffset=+1] + +=== The argument "Bad documentation" + +include::bestpractices/bestpractices_16.adoc[leveloffset=+1] + +=== Summary + +include::bestpractices/bestpractices_17.adoc[leveloffset=+1] + +== Wicket Internals + +include::internals.adoc[] + +=== Page storing + +include::internals/pagestoring.adoc[leveloffset=+1] + +=== Markup parsing and Autocomponents + +include::internals/autocomponents.adoc[leveloffset=+1] + +== Wicket Metrics Monitoring (Experimental) + +include::monitoring.adoc[] + +=== Example setup + +include::monitoring/monitoring_1.adoc[leveloffset=+1] + +=== Visualization with Graphite + +include::monitoring/monitoring_2.adoc[leveloffset=+1] + +=== Measured data + +include::monitoring/monitoring_3.adoc[leveloffset=+1] + +=== Write own measurements + +include::monitoring/monitoring_4.adoc[leveloffset=+1] + +[appendix] +== Working with Maven + +include::maven.adoc[] + +=== Switching Wicket to DEPLOYMENT mode + +include::maven/maven_1.adoc[leveloffset=+1] + +=== Creating a Wicket project from scratch and importing it into our favourite IDE + +include::maven/maven_2.adoc[leveloffset=+1] + +[appendix] +== Project WicketStuff + +include::wicketstuff.adoc[] + +=== What is project WicketStuff + +include::wicketstuff/wicketstuff_1.adoc[leveloffset=+1] + +=== Module tinymce + +include::wicketstuff/wicketstuff_2.adoc[leveloffset=+1] + +=== Module wicketstuff-gmap3 + +include::wicketstuff/wicketstuff_3.adoc[leveloffset=+1] + +=== Module wicketstuff-googlecharts + +include::wicketstuff/wicketstuff_4.adoc[leveloffset=+1] + +=== Module wicketstuff-inmethod-grid + +include::wicketstuff/wicketstuff_5.adoc[leveloffset=+1] + +=== Module wicketstuff-rest-annotations + +include::wicketstuff/wicketstuff_6.adoc[leveloffset=+1] + +=== Module stateless + +include::wicketstuff/wicketstuff_7.adoc[leveloffset=+1] + +[appendix] +== Lost In Redirection With Apache Wicket + +include::redirects.adoc[] + +[appendix] +== Contributing to this guide + +include::contributing.adoc[] + + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/testing.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/testing.adoc b/wicket-user-guide/src/main/asciidoc/testing.adoc new file mode 100644 index 0000000..d3f4ab6 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/testing.adoc @@ -0,0 +1,6 @@ + + http://en.wikipedia.org/wiki/Test-driven_development[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. http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/testing/testing_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/testing/testing_1.adoc b/wicket-user-guide/src/main/asciidoc/testing/testing_1.adoc new file mode 100644 index 0000000..e221f3a --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/testing/testing_1.adoc @@ -0,0 +1,287 @@ + + + +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: + +image::../img/mvn-wicket-archetype.png[] + +Here is the content of TestHomePage: + +[source,java] +---- +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); + } +} +---- + +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...). + +=== 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: + +[source,java] +---- +//... +@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"); +} +//... +---- + +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). + +[source,java] +---- +//... +//simulate a click on a button without AJAX support +tester.clickLink("reload", false); +//... +---- + +=== 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: + +[source,java] +---- +//... +@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"); +} +//... +---- + +=== 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: + +[source,java] +---- +//... +@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")); +} +//... +---- + +If test requires a page we can use _startComponentInPage(Component)_ which automatically generates a page for our component. + +=== 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: + +[source,java] +---- +//... +@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()); +} +//... +---- + +To simulate a request to the custom resource we used method _startResource_ which can be used also with resource references. + +=== 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: + +[source,java] +---- +//... +//the resource was mapped at '/foo/bar' +tester.executeUrl("./foo/bar"); +//... +---- + +=== 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_: + +[source,java] +---- +//... +//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"); +---- + +It's also possible to use method _isComponentOnAjaxResponse(Component cmp)_ to know if a component has been added to _AjaxRequestTarget_: + +[source,java] +---- +//... +//test if AjaxRequestTarget does NOT contain amountLabel +assertFalse(tester.isComponentOnAjaxResponse(amountLabel)); +//... +---- + +=== 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:* + +[source,java] +---- +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); + //... + } +} +---- + +*Test method:* + +[source,java] +---- +@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); +} +---- + +=== Testing AJAX behaviors + +To test a generic AJAX behavior we can simulate a request to it using _WicketTester_'s method _executeBehavior(AbstractAjaxBehavior behavior)_: + +[source,java] +---- +//... +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)); +//... +---- + +=== Using a custom servlet context + +In [paragraph 16.13|guide:resources_13] 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_: + +[source,java] +---- +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... +} +---- + +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()_: + +[source,java] +---- +@After +public void tearDown(){ + //clear any side effect occurred during test. + tester.destroy(); +} +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/testing/testing_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/testing/testing_2.adoc b/wicket-user-guide/src/main/asciidoc/testing/testing_2.adoc new file mode 100644 index 0000000..a29e94a --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/testing/testing_2.adoc @@ -0,0 +1,107 @@ + + + +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: + +[source,java] +---- +//... +//create a new form tester without filling its form components with a blank string +FormTester formTester = tester.newFormTester("form", false); +//... +---- + +_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: + +[source,java] +---- +//... +//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"); +---- + +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. + +=== 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_: + +[source,java] +---- +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(); +} +---- + +=== 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: + + +[source,java] +---- +@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"); +} +---- + +=== 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: + +[source,java] +---- +@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()); +} +---- +
