This documentation is for an old version of fiftyfive-wicket (2.0.9).


fiftyfive.wicket.util
Class ParameterSpec<T>

java.lang.Object
  extended by fiftyfive.wicket.util.ParameterSpec<T>
All Implemented Interfaces:
Serializable

public class ParameterSpec<T>
extends Object
implements Serializable

Applies the DRY principle to Wicket bookmarkable links and page parameters. ParameterSpec lets you define your properties and parameters once; it then takes care of link construction and page parameter parsing so you don't have to do tedious PageParameters.put() and get() calls.

For pages that require only a single parameter this class is overkill. However it is appropriate for detail pages or search pages where there are many parameters that have to be parsed from the URL in order to construct the page. In short, the ParameterSpec does two things:

  1. Given a model bean, ParameterSpec can construct a bookmarkable link with parameters taken from property values of that bean. For example, if your detail page requires an "id" and a "slug", this will pull getId() and getSlug() from your model bean on the fly to construct the link.
  2. Going the other direction, ParameterSpec can parse the PageParameters of a page request and populate a bean with the appropriate properties. So if the URL contained "1" for the id parameter and "foo" for the slug parameter, your DetailBean would have its setId() and setSlug() call with those values. You could then send that bean to the backend for loading, etc.

Recommended usage: define a SPEC static instance on your page.

 public class PersonDetailPage extends WebPage
 {
    public static final ParameterSpec<Person> SPEC = new ParameterSpec<Person>(
        PersonDetailPage.class, "id", "slug"
    );
    ...
 }

Now when other parts of the application want add a link to this page, it is as easy as this:

 add(PersonDetailPage.SPEC.createLink("link", personModel));

To parse the parameters of a request, use this:

 Person person = new Person();
 SPEC.parseParameters(getPageParameters(), person);
 // person bean has now been populated based on page parameters

Author:
Matt Brictson
See Also:
Serialized Form

Constructor Summary
ParameterSpec(Class<? extends WebPage> page, String... expressions)
          Construct a ParameterSpec that will build links to the specified WebPage.
 
Method Summary
 BookmarkablePageLink createLink(String id, IModel<T> model)
          Creates a BookmarkablePageLink to the page managed by this ParameterSpec.
 PageParameters createParameters(T bean)
          Creates a PageParameters map populated with the parameters dictated in the ParameterSpec constructor or registerParameter() calls.
 void parseParameters(PageParameters params, T beanToPopulate)
          Use this method in your page constructor to parse the PageParameters.
 void parseParameters(PageParameters params, T beanToPopulate, boolean throw404OnParseError)
          Use this method in your page constructor to parse the PageParameters.
 void redirect(IModel<T> model)
          Immediately halt the request cycle and force a 302 redirect to the bookmarkable page managed by this ParameterSpec.
 ParameterSpec registerParameter(String parameter, String propExpr)
          Register a parameter that is required by bookmarkable links to your page.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ParameterSpec

public ParameterSpec(Class<? extends WebPage> page,
                     String... expressions)
Construct a ParameterSpec that will build links to the specified WebPage. If any String arguments are specified, they will be used as property expressions for extracting parameter values. It is assumed that the property expression and PageParameters key are identical.

For example, if your PersonPage is mounted at "/person" and you want URLs to look like "/person/[id]/[slug]", where id and slug are provided by PersonBean.getId() and PersonBean.getSlug(), you would mount the page using MixedParamUrlCodingStrategy and then construct the ParameterSpec like this:

 new ParameterSpec(PersonPage.class, "id", "slug");

Which is the same as:

 ParameterSpec spec = new ParameterSpec(PersonPage.class);
 spec.registerParameter("id", "id");
 spec.registerParameter("slug", "slug");

Parameters:
page - The target page of links created by this ParameterSpec
expressions - Bean property expressions (e.g. "slug", "id") that will be used to populate URLs to the page
Method Detail

registerParameter

public ParameterSpec registerParameter(String parameter,
                                       String propExpr)
Register a parameter that is required by bookmarkable links to your page. For example, if your URL is "/search?q=[terms]" and the terms come from a getTerms() property of your model bean, then you would use this code:
 registerParameter("q", "terms")

Parameters:
parameter - The page parameter key (this may appear in the URL depending on the coding strategy)
propExpr - Bean property that will be used to populate URLs when building links

createLink

public BookmarkablePageLink createLink(String id,
                                       IModel<T> model)
Creates a BookmarkablePageLink to the page managed by this ParameterSpec. The link will have parameters dictated by the ParameterSpec constructor or registerParameter() calls. The values of those parameters will be taken from properties of the specified model bean. For example, the link may require "id" and "slug" values, meaning getId() and getSlug() will be called on the model object at render time to populate the parameters of the link.

Parameters:
id - The wicket:id of the link in the HTML markup
model - A model representing the bean that will be used to populate the parameters of the link

redirect

public void redirect(IModel<T> model)
Immediately halt the request cycle and force a 302 redirect to the bookmarkable page managed by this ParameterSpec. Page parameters will be passed to the page based on the specified model.

Throws:
RestartResponseException - to force Wicket to halt the request

createParameters

public PageParameters createParameters(T bean)
Creates a PageParameters map populated with the parameters dictated in the ParameterSpec constructor or registerParameter() calls. For each parameter, the property expression will be evaluated against the given bean to retreive the value. For example, if "id" is one of the expressions, bean.getId() will be used to retrieve its value and place it in the PageParameters.


parseParameters

public void parseParameters(PageParameters params,
                            T beanToPopulate)
Use this method in your page constructor to parse the PageParameters. The specified bean will be populated by calling the appropriate setters as defined by this ParameterSpec. For example, if the ParameterSpec has been created parameters that map "id" and "slug" properties, the setId() and setSlug() methods of the bean will be called with values taken from the PageParameters.

Parameters:
params - Values will be taken from these PageParameters
beanToPopulate - Values will be set using appropriate setters on this bean
Throws:
AbortWithWebErrorCodeException - with a 404 status code if a parsing exception occurs. For example, this could happen if the bean property for "id" is of type Long, but the parameter value being parsed is not numeric.

parseParameters

public void parseParameters(PageParameters params,
                            T beanToPopulate,
                            boolean throw404OnParseError)
Use this method in your page constructor to parse the PageParameters. The specified bean will be populated by calling the appropriate setters as defined by this ParameterSpec. For example, if the ParameterSpec has been created parameters that map "id" and "slug" properties, the setId() and setSlug() methods of the bean will be called with values taken from the PageParameters.

Parameters:
params - Values will be taken from these PageParameters
beanToPopulate - Values will be set using appropriate setters on this bean
Throws:
AbortWithWebErrorCodeException - with a 404 status code if throw404OnParseError is true and a parsing exception occurs. For example, this could happen if the bean property for "id" is of type Long, but the parameter value being parsed is not numeric. If throw404OnParseError is false, skip past properties with parsing errors.


Copyright © 2011 55 Minutes. All Rights Reserved.