Apache Wicket became very popular in the last months and has been used in many projects. Due to the power of Wicket you can develop features very easy and fast. There are many ways to realize these features though. This article provides some cook recipes for the correct, efficient and pertinent usage of Apache Wicket.
This article is addressed to developers, who has already made their first experiences with Apache Wicket. Developer, who get into Wicket often have difficulties with it, because they apply the typical JSF and Struts patterns and approaches. These frameworks primarily use procedural programming methods. In contrast Wicket is strongly based on object oriented patterns. So forget the Struts and JSF patterns, otherwise you won’t have fun with Wicket in the long run.
Encapsulate components correctly
A component should be self-contained. The user of a component should neither have to know nor care about its internal structure. She should just be familiar with its external interfaces and its documentation in order to be able to use it. This means in detail: Every component that extends Wicket’s own Panel type (thus is a Panel itself) must provide its own HTML template. In contrast when a component extends the classes WebMarkupContainer or Form, there is no HTML template. This implicates that you should add components through composition inWebMarkupContainer or Form.
github:99cce2757673d5d667fd
Listing 1 is an example for a poor component. The user of the RegistrationForm must know the internal structure of the markup and component in order to use it.
github:f4669a39cccec37617a4
github:8c4e35e2d8a3516256b1
Listing 2 shows the usage of the poor component in the RegistrationPage. You can see that the input fields firstname, lastname and username get used, even though these components are not added explicitly to the RegistrationPage. Avoid this, because other developers cannot directly see that the components were added in RegistrationPage class.
github:b8fe85a8edc27de097c4
github:4c8d6584a2cf80516db0
Listing 3 shows a cleanly cut input component, which provides its own markup. Furthermore you can see the correct usage of a Wicket Form. The components get added by callingform.add(Component) on the instance variable. On the other hand it is allowed to add behaviours and validators over inheritance, because those do not have markup ids which must be bound.
github:4ba24228dcc6264c39a8
github:4e9f5f910edd9951ee54
Listing 4 shows the usage of the RegistrationInputPanel. There is no markup of another embedded components present anymore, just markup of components, which get directly added. The RegistrationPage provides its own form, that delegates the submit to all Wicket nested forms which are contained in the component tree.
Put models and page data in fields
In contrast to Struts Wicket pages and components are no singletons, they are stateful and session-scoped. This enables us to store user-specific information within pages and components. The information should be stored in fields. This way you can access the information within a class while avoiding long method signatures only for passing this very same information around. Instances of components can exist over several requests. For example a page with a form which gets submitted and produces validation errors uses the same page instance. Furthermore the same page instance gets used when the user presses the back button of the browser and resubmits this formular again. Information which gets passed by the constructor should be assigned to fields (normally this must be models). When storing information in fields you should consider that the information is serializable, because the pages are stored in Wicket’s page map. By default the page map stores the pages on the hard disk. A non serializable object leads to NullPointerExceptions and NonSerializableExceptions. Additionally big data (like binary stuff) should not be stored directly in fields, because this can cause performance losses and memory leaks while serialization and deserialization. In this case you should use the LoadableDetachableModel, which can be assigned to a field, because this provides an efficient mechanism to load and detach data.
Correct naming for Wicket IDs
Naming is for many developers a dispensable thing, but I think it is one of the major topics in software development. With the help of correct naming you identify fastly the business aspects of a software component.
Additionally good naming avoids unneccessary and bad comments.
Bad namings for Wicket-IDs are birthdateTextField, firstnameField and addressPanel. Why? The naming contains two aspects: A technical aspect “TextField” and the business aspect “birthdate“. Relevant is just the business aspect because the HTML template already presents the technical aspect through and the Java code presents it by “new TextField(“birthdate”)“. So the technical aspects are already described. Additionally the incorrect naming adds a lot of effort when you do technical refactorings, e.g. if you have to replace a TextField by a DatePicker, in result of it you have to rename the Wicket ID from birthdateTextField to birthdateDatePicker. Another reason for avoiding technical aspects in Wicket IDs is the CompoundPropertyModel. This model delegates the properties to its child components named by Wicket IDs (see listing 3). For example theTextField username calls automatically setUsername() and getUsername() on the Registrationobject. A naming of the setter setUsernameTextfield() would be very unpracticable here.
Avoid changes at the component tree
You should picture Wicket’s component tree as a constant and fixed skeleton which gets revived when its model is filled with data like a robot without brain. Without brain the robot is not able to do anything and is just dead and a fixed skeleton. However when you fill it with data, it becomes alive and can act. There is no need of changing hardware when filling him with data. Components can decide on the state by its own by viewing on the data, e.g. on its visibility. In Wicket you should manipulate the component tree as little as possible. Consequential you should avoid calling methods like Component.replace(Component) undComponent.remove(Component). Calling these methods indicates missing usage or misusage of Wicket’s models. Furthermore the component trees should not conditionally constructed (see listing 5). This reduces the possibility to reuse the same instance significantly.
github:304716f3f4f2b6e64e30
Instead of constructing LoginBoxPanel conditionally, it is recommend to add the panel always and control the visibility by overriding isVisible(). So the component LoginBoxPanel is responsible for displaying itself. We move the responsibility into the same component, which executes the login. Brilliant! Business logic cleanly encapsulated. There is no decision from outside, the component handles all the logic. You can see another example in “Implement visibilities of components correctly”.
Implement visibilities of components correctly
Visibility of site parts is an important topic. In Wicket you control the visibility of components over the methods isVisible() and setVisible(). These methods are within Wicket’s base classComponent and therefore it regards every component and page. Let’s have a look to a concrete example of LoginBoxPanel. The panel just gets displayed when the user is not logged in.
github:0179a7d96cdecf5809a4
Listing 6 shows a poor implementation, because a decision of visibility is made while instanciating the component. Again in Wicket instances of components exist over several requests. To reuse the same instance you have to call loginBox.setVisible(false). This is very unhandy, because we always have to call setVisible() and manage the visibility. Furthermore you are going to duplicate the states, because visible is equal to “not logged in”. So we have two saved states, one for the business aspect “not logged in” and one for the technical aspect “visible”. Both is always equal. This approach is error-prone and fragile, because we always have to attend that the correct information will be set at every time. But this is often forgotten, because the logic is wide spread over the code. The solution is the Hollywood-Principle: “Don’t call us, we’ll call you.”. Take a look at the diagram, there is an application flow with some calls. We avoid three calls through the Hollywood-Principle and we just have to instanciate theLoginBoxPanel.
github:8d8a29dc4b0ff6650a9d
In listing 7 the control over visibility has got inverted, now the LoginBoxPanel decides over the visibility by its own. On each call of isVisible() there is a refreshed interpretion of the login state. Concluding there is no out-dated information state additionally saved. The logic is centralised in one line code and not spread application wide. Furthermore you can easily identify that the technical aspect isVisible() correlates to the business aspect “logged in”. The same rules can be applied to the method isEnabled(). If isEnabled() returns false the components get displayed gray. Forms which are within an inactive or invisible component do not get executed. Sometimes there are cases you cannot avoid to call the methods setVisible() and setEnable(). An example: The user presses a button to display an inlined registration form. In general you can apply the following rules: Data driven components override these methods and delegates to the data model. User triggered events call the method setVisible(boolean). As well you can override these methods by inline implementations (see listing 8).
github:6cc62de473a29477e792
Note: Some people say that overriding isVisible() is bad: http://goo.gl/6aCUv. The methodisVisible() gets called very often (more than once at each request!), so you have to ensure that the calls within isVisible() are cheap. The main point is that the visibility of a component should be controlled by its own and not be controlled by other components. This avoids a wide-spreaded logic over the whole application. Another way you can realize this is to overrideonConfigure() and set the visibility there. This method gets called once on each request.
Always use models
Always use models! Do not pass raw objects directly to components. Instances of pages and components can exist over several requests. If you use raw objects, you cannot replace them later. An example is an entity which gets loaded at each request within aLoadableDetachableModel. The entity manager creates a new object reference, but the page would keep the obsolete instance. Always pass IModel in the constructor of your components (see listing 9).
github:e71efe0524de3cbe1215
The solution in listing 9 could have every implementation in the model. Beginning with the classModel over the PropertyModel and an own implementation of LoadableDetachableModel, which loads and persists the values automatically. The model implementations get very easy to replace. You – as user – just want to know: If I call IModel.getObject(), I will get an object of typeRegistration. Where the object comes from is the charge of the model implementation and the calling component. For example you can pass the model while instanciating the component. If you avoid using models, you will get the dilemma to modify the component tree sooner or later. Whereby you duplicate states and thus produce unmaintable code. Additionally you should use models by reason of serialization. Objects which get stored in fields of pages and components get serialized and deserialized on each request. This could be inperformant in some cases.
Do not unpack models within the constructor hierarchy
Avoid unpacking models within the constructor hierarchy, that means do not callIModel.getObject() within the constructor hierarchy. As aforementioned a page instance can exist over several page requests, so you can hold an obsolete and redundant infomation. It is allowed to unpack Wicket Models at events (user actions), that are methods like onUpdate(),onClick() or onSubmit() (see listing 10).
github:68acb852785738f3d743
An additional possibility to unpack models is through overriding methods like isVisible(),isEnabled() or onBeforeRender().
Pass-trough models to components of extending class
Pass-through models to the parent component. So you ensure, that at the end of every request the method IModel.detach() get called. Those method is responsible for a data cleanup. Another example: you have your own model implemented which persists the data in the detach()method. So the call of detach() is neccessary that your data gets persisted. You can see an exemplary pass-through to the super constructor at listing 11.
github:d60befa5aeea565f7f92
Validators must not change any data or models
Validators just should validate. For example: a bank account form which has aBankFormValidator. This validator checks the bank data over a webservice and corrects the bank name. Nobody would expect that a validator modifies information. Such logic has to be located in Form.onSubmit() or in the event logic of a button.
Do not pass components to constructors
Do not pass components or pages to constructors of other components.
github:210532c31ba127d4e3fb
See listing 12: The SettingsPage expects in the constructor the page which should be displayed after a successful submit. This solution works, but is very bad style and unflexible. You have to know at the instanciation of SettingsPage where you want to redirect the user. This requires a predetermied order of instanciation. Better it is to order the instanciation after business logic (e.g. the order in the HTML template). Furthermore you need an unnecessary instance of the next page, which could not be displayed. The solution is the hollywood principle again. For this you create an abstract method or a hook (listing 13).
github:082a4c78b57a60c62026
The solution from listing 13 has more code, but is more flexible and significant. We can see there is an event onSettingsChanged() and this event is called after a successful change. Furthermore there is the possibility to execute more code just than set the back page. For example you can display messages or persist information.
Use the Wicket session only for global data
The Wicket session is your own extension from Wicket’s base session. It is fully typed. There is no map structure to store information unlike the servlet session. You just should use Wicket’s session for global data. Authentification is a good example for global data. The login and user information is required on nearly each page. For a blog application it would be good to know, whether the user is an author who is allowed to compose blog entries. So you are able to hide or or show links to edit a blog entry. In general you should store the whole authorization logic in Wicket’s session, because it is a global thing and you would expect it there. Data of forms and flows which span over several pages should not stored in the session. This data can be passed from one page to the next over the constructor (listing 14). As a consequence of this, the models and data have a defined life cycle over the page flow.
github:447642fbb0f8da58490d
As you see in listing 14 you should pass concrete information to the page. All models can be stored in fields, because Wicket pages are userspecific instances and no singletons in contrast to Struts. The big advantage of this approach is, that the data gets automatically cleaned up when user completes or exits the flow early. No manually cleanup anymore! This is quasi a garbage collector for your session.
Do not use factories for components
The factory pattern is an useful pattern, but unsuitable for Wicket components.
github:7d83b68c293a222d5684
The approach in listing 15 for adding a label from the CmsFactory to a page seems to be initially ok, but brings some disadvantages. There is no possibility anymore to use inheritance. Furthermore there is no possibility to override isVisible() and isEnabled(). The factory could be also a spring service which instanciates the component. A better solution is to create a CmsLabel(listing 16).
github:d89a330a0784f65622bc
The label from listing 16 is clearly encapsulated in a component without using a factory. Now you can easily create inline implementations and override isVisible() or other stuff. Now someone could say “I need a factory to initialize some values in the component, e.g. a spring service.”. For this you can create a implementation of IComponentInstantiationListener. This listener gets called on the super-constructor of every component. The most popular implementation of this interface is the SpringComponentInjector which injects spring beans in components when the fields are annotated with @SpringBean. You can easliy write and add your own implementation of IComponentInstantiationListener. So there is no reason using a factory anymore. More information about the instanciation listener is located in Wicket’s javadoc.
Every page and component expects a test
Every page and component should have a test. The simplest test just renders the component and validates its technical correctness. For example a child component should have a matching wicket id in the markup. If the wicket id is not correctly bound – through a typo or it was just forgotten – the test will fail. An advanced test could test a form, where a backend call gets executed and validated over a mock. So you can validate your component’s behaviour. This is a simple way to detect and fix technical and business logic bugs while the build process. For the test driven development approach, you can use wicket quite well. Lets say you have a page so you can validate the correctness of the page by running the unit test. If you run the unit test which fails and shows a message that the wicket id not bound, so you will avoid an unneccessary server startup, because a server startup takes longer than running a unit test. This reduces the development turnaround. A disadvantage is the difficult testing possibility of AJAX components. However the testing possibilites of Wicket are much more than in other web frameworks.
Avoid interactions with other servlet filters
Try to get as long as possible within the Wicket world. Avoid the usage of other servlet filters. For this you can use theRequestCycle and override the methods onBeginRequest() andonEndRequest(). You can apply the same to the HttpSession. The equivalent in Wicket is theWebSession. Just extend the WebSession and override the newSession()-method from the Application class. There are very few reasons to access the servlet interfaces. An example could be to read an external cookie to authentificate a user. The parts should encapsulated well and minimized. For this example you could put the handling in the Wicket session, because this is an authentification.
Cut small classes and methods
Avoid monolithic classes. Often I have seen that developers put the whole stuff into constructors. These classes are getting very unclear and chaotic, because you use inline implementations over serveral levels. It is recommended to group logical units and extract methods with a correct business naming. This enhances the clarity and the understandability of the business aspect. When a developer navigates to a component, he is not interested in the technical aspect at first, however he just need the business aspect. To retrieve technical information of a component you can navigate to the method implementation. In case of doubt you should consider to extract seperate components. Smaller components increase the chance of reuse and make the testability easier. Listing 17 shows an example of a possible structuring.
github:e78c1a5e85d44002aa2d
The argument “Bad documentation”
Often I have heard that Wicket has a bad documentation. This argument is just particular correct. There are a lot of code samples and snippets which can be used as code templates. Furthermore there is a big community that answers complex questions in shortest time. In Wicket it is very hard to document everything, because nearly everything is extensible and replaceable. If a component is not completely suitable, you will extend or replace it. The work with Wicket is a permanent navigating through the code. For example the validators. How can I find all navigators that exists? Open the interface IValidator (Eclipse Ctrl + Shift + T) and then open the type hierachy (Crtl + T). Now we are seeing all the validators existing in Wicket and our project.
Conclusion
These advices should help you to write better and more maintainable code in Wicket. All described methodologies were already proved in a few Wicket projects. If you follow these advices, your Wicket projects will get future-proof and successful hopefully.
Links:1. http://wicket.apache.org/ (Apache Wicket)2. http://wicketstuff.org/wicket14/ (Wicket Examples)3. http://en.wikipedia.org/wiki/Hollywood_Principle
Thanks to Daniel Bartl for the correction.