src/site/apt/guide.apt

 ~~ Licensed to the Apache Software Foundation (ASF) under one or more
 ~~ contributor license agreements.  See the NOTICE file distributed with
 ~~ this work for additional information regarding copyright ownership.
 ~~ The ASF licenses this file to You under the Apache License, Version 2.0
 ~~ (the "License"); you may not use this file except in compliance with
 ~~ the License.  You may obtain a copy of the License at
 ~~
 ~~      http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing, software
 ~~ distributed under the License is distributed on an "AS IS" BASIS,
 ~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 ~~ See the License for the specific language governing permissions and
 ~~ limitations under the License.

 ------
 Guide to Tobago
 ------

{Guide to Tobago}

  <This guide covers primarily Tobago 1 and 2. Most basic ideas are the same in Tobago 3, but
  documented in the demo application.>

====================

  Tobago is a JavaServer Faces (JSF) framework and component library. It provides a comfortable way to layout screens
  of desktop-like applications with a consistent look & feel. Tobago emphasizes the separation of structure
  and design of screens. Screens are developed independently of the view technology -- no HTML, CSS, or JavaScript.
  Because of strict separation a screen can be displayed with different themes. These themes can be used to render
  screens according to different corporate design without changing the sources of the screens.

  This guide assumes basic knowledge about JSF. For more information about JSF see one of the various books about JSF,
  the {{{http://java.sun.com/javaee/5/docs/tutorial/doc/bnaph.html}Sun Java 5 Tutorial}} or
  the {{{http://java.sun.com/javaee/javaserverfaces/download.html}JSF Specification.}}

{Content}

  \ 

%{toc|fromDepth=0|toDepth=4}

{Environment}

* {Building and Deploying the Tobago Examples}

  Tobago uses Maven as a build management system. The provided examples are normally build with Maven, but it would
  be easy to use an alternative build system. The necessary artifacts can be downloaded {{{./download.html}here}} or
  from the Maven repository.

  We will use the address book demo as an example in this guide. Since the address book example is currently
  not part of the Tobago distribution, you have to check-out the sources from the Apache Subversion repository.
  We will use the latest release tag for this.

+------------------------------------------+
svn co https://svn.apache.org/repos/asf/myfaces/tobago/tags/tobago-1.0.22/example/addressbook/ tobago-addressbook
+------------------------------------------+

  You will need Java 5 and Maven 2.0.9 or later to build the address book example. Use the following command to
  compile the sources and deploy the web application on an embedded Jetty server:

+------------------------------------------+
mvn jetty:run-exploded
+------------------------------------------+

  If you point your browser to {{http://localhost:8080/}} and you will be directed to the login dialog of the address
  book example.\
  \ 

[images/guide-addressbook-login.png] Address Book Login

  You can click on the guest/guest or admin/admin links or fill in the authentication information yourself
  and press the 'Login' button. After displaying a splash screen for a while the application will direct you to
  the address list page.\
  \ 

[images/guide-addressbook-list.png] Address List

  A freshly started instance of the address book example will not contain any addresses in the list. But you can
  add addresses by pressing the 'New' button in the tool bar. The addresses will be stored in an embedded Derby
  database.

* {Building Tobago}

  To use the latest version of Tobago you can use the snapshot artifacts build by our continuous integration server Continuum,
  which are available in the {{{https://repository.apache.org/content/repositories/snapshots/org/apache/myfaces/tobago/}Apache snapshot repository.}}

  Alternatively, you can build Tobago yourself. You will need Java 5 and Maven 2.0.9 or later.

  Check-out Tobago from the Apache Subversion repository

+------------------------------------------+
svn co https://svn.apache.org/repos/asf/myfaces/tobago/trunk/ tobago
+------------------------------------------+

  To build the complete project with all sub-modules you have to enter the following command

+------------------------------------------+
mvn install
+------------------------------------------+

  For more information on building Tobago -- especially the 1.0.x branch -- see {{{./getting-started.html}Getting Started.}}

* {Building your own Tobago Application}

  The Tobago example distribution contains the tobago-example-blank WAR, which can act as starting point for
  your own Tobago application. Since Tobago is based on JSF you need a JSF implementation if the application server
  you are targeting doesn't contain one.

  If you cannot use Java 5 or higher you can use retrotranslated JARs from the Tobago distribution to develop and
  run Tobago applications with Java\ 1.4 (only Tobago 1.0.x).

  A Tobago application is a web application which is packaged as a WAR. For a JSF application the <<<FacesServlet>>> needs
  to be configured in the <<</WEB-INF/web.xml>>>. To serve the internal resources of Tobago directly from the Tobago
  JARs the Tobago <<<ResourceServlet>>> has to configured, too. The configuration of a Tobago application is controlled
  by the <<<WEB-INF/tobago-config.xml>>> file. This can be used to declare the available themes and the default theme.
  Additionally, it can be used to locally add markup -- see the {{Themes}} section for further information.

* {A Minimal Tobago Page}

  You can use JSP or Facelets to write Tobago pages. For Facelets support the extension module tobago-facelets has to
  be added as a dependency. Because the address book example uses JSP as rendering technology we will focus on JSP
  for now.

  Tobago provides two tag libraries --  the core library and the extension library. The corresponding TLDs contain
  documentation for the provided tags which is generated from annotations on the underlying tag classes. The core tag
  library contains basic controls and the extension library convenience tags for pre-assembled tag compositions -- for
  example a composition of a label and an input control.

  A minimal Tobago JSP page looks like this:

+------------------------------------------+
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://myfaces.apache.org/tobago/component" prefix="tc" %>
<%@ taglib uri="http://myfaces.apache.org/tobago/extension" prefix="tx" %>
<f:view>
  <tc:page>
    <f:facet name="layout">
      <tc:gridLayout/>
    </f:facet>
    <tc:out value="Hello World"/>
  </tc:page>
</f:view>
+------------------------------------------+

  A similar page is part of the blank WAR: \
  {{https://svn.apache.org/repos/asf/myfaces/tobago/tags/tobago-1.0.22/example/blank/src/main/webapp/helloWorld.jsp}}

{Creating a Tobago page}

  The address book example needs an address editing page to add new addresses to the address book and to update
  existing ones.

  A simple version of an address editor allows to edit the first and last name of a person and basic address data
  like street, house number and city. Such an editor could look like this:\
  \ 

[images/guide-simple-editor.png] Simple Address Editor

  This page is generated by the following code:

+------------------------------------------+
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://myfaces.apache.org/tobago/component" prefix="tc" %>
<%@ taglib uri="http://myfaces.apache.org/tobago/extension" prefix="tx" %>
<f:view>
  <tc:page width="400">
    <f:facet name="layout">
      <tc:gridLayout rows="fixed;*" margin="10"/>
    </f:facet>
    <tc:box label="Address">
      <f:facet name="layout">
        <tc:gridLayout rows="fixed;fixed;fixed;fixed"/>
      </f:facet>
      <tx:in label="First Name"/>
      <tx:in label="Last Name"/>

      <tc:panel>
        <f:facet name="layout">
          <tc:gridLayout columns="6*;1*"/>
        </f:facet>
        <tx:in label="Street / No"/>
        <tc:in />
      </tc:panel>

      <tx:in label="City"/>
    </tc:box>

    <tc:cell />
  </tc:page>
</f:view>
+------------------------------------------+

  We have a box with the label "Address" containing four rows of input controls for first name, last name, street, 
  house number, and city.

* {Basic Controls}

  HTML offers a decent set of basic controls. These controls form the basis of the Tobago controls including
  single-line input controls, text areas, check boxes, radio buttons, links, buttons, labels, and others.

  The Tobago demo contains an overview page for the basic controls.\
  \ 

[images/guide-basic-controls.png] Basic Controls  

  Live demo of the basic controls: {{http://tobago-vm.apache.org/demo-2-release/faces/content/01-basic/basic.xhtml}}

  The basic controls page also shows two variants of a normal input control: the date input control and the time input
  control.

* {Text Input}

  The single-line text input control comes in two flavors: the <<<\<tc:in\>>>> tag from the core tag library (<<<tc>>>
  is the preferred prefix for the core tag library) and the <<<\<tx:in\>>>> from the extension tag library (<<<tx>>>).

  The extension tag library provides convenient shorthands for boilerplate code. For every input control there
  is for example an extended version, which layouts a label next before the input field. The label is connected
  with the field. If the label is clicked the related field is focused.

  A code fragment from the address book example:

+------------------------------------------+
<tx:in value="#{controller.currentAddress.firstName}"
    label="#{bundle.editorFirstName}" required="true">
  <f:validateLength minimum="2" maximum="20"/>
</tx:in>
+------------------------------------------+

  The <<<value>>> attribute refers the content of the control. If a value binding is used, this content can be written
  back into a bean property.

  The <<<label>>> attribute generates the textual description for the control. The theme decides how the label is
  actually rendered, for example it assigns a default width. This width can be overwritten with the <<<labelWidth>>>
  attribute. If you utilize a value binding to a resource bundle declared by a <<<\<tc:loadBundle\>>>> tag, you
  automatically get localization for the text labels. An underscore in the label transforms the following
  character into an access key. The theme normally underlines the access key to make this circumstance visible to
  the user. The access key can be used to quickly focus the related input control by pressing <<<Alt>>> in combination
  with the access key.

  If the control is marked as <<<required>>> the respective validation takes place. Additionally, the theme tries to
  visualize this fact. Speyside renders a small check mark icon inside the field, which vanishes if the field
  contains any data.

  For more information about the possible attributes of an input tag see the TLD documentation for
  {{{http://myfaces.apache.org/tobago/tobago-core/tlddoc/tc/in.html}<<<\<tc:in\>>>>}} and
  {{{http://myfaces.apache.org/tobago/tobago-core/tlddoc/tx/in.html}<<<\<tx:in\>>>>}}.

* {Sheet}

  The sheet control is used to display tabular data.

  The address book example uses a sheet to give an overview of all stored addresses.\
  \ 

[images/guide-sheet.png] Sheet

  Live demo of a sheet: {{http://tobago-vm.apache.org/demo-2-release/faces/content/02-sheet/sheet.xhtml}}

  A code fragment from the address book example:

+------------------------------------------+
<tc:sheet columns="1*;1*;1*" value="#{controller.currentAddressList}"
    var="address" state="#{controller.selectedAddresses}"
    sortActionListener="#{controller.sheetSorter}" rows="25"
    showRowRange="left" showPageRange="right" showDirectLinks="center">
  <tc:columnEvent event="dblclick" >
    <tc:command action="#{controller.editAddress}"/>
  </tc:columnEvent>
  <tc:column id="firstName" label="#{bundle.listFirstName}" sortable="true"
      rendered="#{controller.renderFirstName}">
    <tc:out value="#{address.firstName}"/>
  </tc:column>
  <tc:column id="lastName" label="#{bundle.listLastName}" sortable="true"
      rendered="#{controller.renderLastName}">
    <tc:out value="#{address.lastName}"/>
  </tc:column>
  <tc:column id="dayOfBirth" label="Birthday" sortable="true"
      rendered="#{controller.renderDayOfBirth}">
    <tc:out value="#{address.dayOfBirth}">
      <f:convertDateTime pattern="#{bundle.editorDatePattern}"/>
    </tc:out>
  </tc:column>
</tc:sheet>
+------------------------------------------+

* {Tab Group}

  The tab group control displays rectangular content in the same area of the screen with the help of tab panels.

  In the address book example the tab group is used to structure the input controls for an address into three groups
  for general, business, and miscellaneous information.\
  \ 

[images/guide-tab-group.png] Tab Group

  Live demo of a tab group: {{http://tobago-vm.apache.org/demo-2-release/faces/content/04-tab/tab.xhtml}}

  A code fragment from the address book example:

+------------------------------------------+
<tc:tabGroup switchType="reloadTab" immediate="true">
  <tc:tab label="#{bundle.editorTabPersonal}">
    <jsp:include page="tab/personal.jsp"/>
  </tc:tab>

  <tc:tab label="#{bundle.editorTabBusiness}" rendered="#{!controller.simple}">
    <jsp:include page="tab/business.jsp"/>
  </tc:tab>

  <tc:tab label="#{bundle.editorTabMisc}" rendered="#{!controller.simple}">
    <jsp:include page="tab/misc.jsp"/>
  </tc:tab>
</tc:tabGroup>
+------------------------------------------+

* {Menu}

  The menu control can be used to render a menu bar at the top of a screen like it is typically used in desktop
  applications. But the location for menus is not limited to this place.\
  \ 
  
[images/guide-menu.png] Menu

  Live demo of a menu: {{http://tobago-vm.apache.org/demo-2-release/faces/content/05-toolBar/toolBar.xhtml}}

  A code fragment from the address book example:

+------------------------------------------+
<tc:menuBar>
  <tc:menu label="#{bundle.menuFile}">
    <tc:menuCommand label="#{bundle.menuFileNew}" action="#{controller.createAddress}" immediate="true"
        image="image/org/tango-project/tango-icon-theme/16x16/actions/contact-new.png"/>
    <tc:menuCommand label="Add Dummy Addresses" action="#{controller.addDummyAddresses}" immediate="true"/>
    <tc:menuSeparator/>
    <tc:menuCommand label="#{bundle.admin}" action="#{admin.admin}"
        image="image/org/tango-project/tango-icon-theme/16x16/categories/preferences-system.png"/>
    <tc:menuSeparator/>
    <tc:menuCommand label="Logout" action="#{controller.logout}"
        image="image/org/tango-project/tango-icon-theme/16x16/actions/system-log-out.png"/>
  </tc:menu>

  <tc:menu label="#{bundle.menuSettings}">
    ...
  </tc:menu>

  <tc:menu label="#{bundle.menuHelp}">
    ...
  </tc:menu>
</tc:menuBar>
+------------------------------------------+

* {Tool Bar}

  The tool bar control is used to render a special rectangular area of buttons. There are two versions of toolbars:
  a standalone version and version that embeds itself in the border of a box. To embed a tool bar it has to be
  attached to a <<<\<tc:box\>>>> via a toolbar facet.

  The address book example uses a tool bar below the menu to provide convenient access to the most common actions
  from the menu.\
  \ 

[images/guide-toolbar.png] Tool Bar

  Live demo of a tool bar: {{http://tobago-vm.apache.org/demo-2-release/faces/content/05-toolBar/toolBar.xhtml}}

  A code fragment from the address book example:

+------------------------------------------+
<tc:toolBar iconSize="big">
  <tc:button label="#{bundle.toolbarAddressList}" action="#{controller.search}" immediate="true"
      image="image/org/tango-project/tango-icon-theme/32x32/mimetypes/x-office-address-book.png"
      disabled="#{facesContext.viewRoot.viewId == '/application/list.jsp'}"/>
  <tc:button label="#{bundle.listNew}" action="#{controller.createAddress}"
      image="image/org/tango-project/tango-icon-theme/32x32/actions/contact-new.png"/>
  <tc:button label="#{bundle.toolbarAbout}"
      image="image/org/tango-project/tango-icon-theme/32x32/apps/help-browser.png">
    <tc:popupReference for=":page:about"/>
  </tc:button>
  <tc:button label="#{bundle.admin}" action="#{admin.admin}"
      image="image/org/tango-project/tango-icon-theme/32x32/categories/preferences-system.png"/>
</tc:toolBar>
+------------------------------------------+

* {Popup}

  Popups are used to render small modal dialogs inside the current screen. The original screen is disabled until
  the popup is released with one of the popup buttons.\
  \ 

[images/guide-popup.png] Tool Bar

  A code fragment from the address book example:

+------------------------------------------+
<tc:popup id="about" width="300" height="220" left="200" top="200">
  <tc:box label="About">
    <f:facet name="layout">
      <tc:gridLayout rows="150px;*;fixed" columns="150px;*"/>
    </f:facet>

    <tc:image width="150" height="150"
        value="image/org/tango-project/tango-icon-theme/address-book-splash-screen.png"/>
    <tc:panel>
      ...
    </tc:panel>

    <tc:cell spanX="2"/>

    <tc:cell spanX="2">
      <tc:panel>
        <f:facet name="layout">
          <tc:gridLayout columns="*;fixed"/>
        </f:facet>
        <tc:cell/>
        <tc:button label="OK">
          <tc:attribute name="popupClose" value="immediate"/>
        </tc:button>
      </tc:panel>
    </tc:cell>
  </tc:box>
</tc:popup>
+------------------------------------------+

* {File Upload}

  The file select control can be used to upload files.\
  \ 

[images/guide-upload.png] File Upload

  A code fragment from the address book example:

+------------------------------------------+
<tc:file value="#{controller.uploadedFile}" required="true">
  <tc:validateFileItem contentType="image/*"/>
</tc:file>
+------------------------------------------+

{Features and Concepts}

* {Layout}

  Tobago organizes the placement of components with the help of layout managers. The main layout manager
  is called grid layout. It divides the available rectangular space into grid cells. The grid is spawned
  by the column and row values of the <<<\<tc:gridLayout\>>>> tag. The syntax of these values is based on
  the {{{http://www.w3.org/TR/html401/types.html#type-multi-length}multi-length notation}} known from HTML.

  To add a layout manager to a container like box, panel or page you have to add a layout facet (i.e. a facet
  with the name 'layout') to the respective container tag.

  A code fragment from the address book example:

+------------------------------------------+
<tc:panel>
  <f:facet name="layout">
    <tc:gridLayout columns="*" rows="fixed;fixed;*"/>
  </f:facet>
  <tx:in label="First Name"/>
  <tx:in label="Last Name"/>
  <tc:cell />
</tc:panel>
+------------------------------------------+

  In this example we place to two input controls with labels into two consecutive rows. Below the two input fields
  we add a spacer element. The layout token '<<<fixed>>>' advises the layout manager to give the input control
  the height, which this kind of control normally possesses in the selected theme.

  The values of the column and row attributes of the <<<\<tc:gridLayout\>>>> tag can contain a semicolon separated
  list of layout tokens. A layout token can be an exact length in pixels like <<<200px>>>, a percentage length like <<<25%>>>,
  a relative length like <<<2*>>>, or a specific length called <<<fixed>>>, which's exact length is determined by the
  theme and make sure the control is usable -- a single-line input control for example needs to be so high that
  characters from the assigned font can be read inside the control.

  Relative lengths are determined last by the layout manager. The available remaining space is distributed among the
  existing relative lengths. Each length receives space proportional to the integer before the '<<<*>>>'. A single
  '<<<*>>>' is a shorthand for '<<<1*>>>'.

  The layout manager handles the <<<rendered>>> attribute of controls, too. If the <<<rendered>>> attribute is
  dynamically defined by a value binding, the page can contain fewer controls in some cases than in others.
  The layout manager can then distribute the newly available space between the remaining relative and percentage
  lengths.

* {Themes}

  A theme defines how the structured view is actually rendered. It provides the look & feel of the controls inside a
  view. It appoints colors, dimensions, spacing, fonts and other graphical properties.

  Tobago includes a small collection of themes called after cities on the island Tobago: Scarborough, Speyside,
  Charlotteville, and Richmond. Scarborough is a basic theme, which tries to focus on features of plain
  HTML, Speyside is the main theme of Tobago, Charlotteville and Richmond are mainly color variations of Speyside.\
  \  

[images/guide-theme-scarborough.png] Scarborough

  Scarborough\
  \ 

[images/guide-theme-speyside.png] Speyside

  Speyside\
  \ 

[images/guide-theme-charlotteville.png] Charlotteville

  Charlotteville\
  \ 

[images/guide-theme-richmond.png] Richmond

  Richmond

* {Markup}

  Since you don't have direct control over design without writing your own theme, Tobago supports the concept of
  markup. You can assign certain logical markup values to a control to fine-tune the rendering. A theme specifies
  the supported markup for every control. The standard theme already provides some helpful markups.\
  \ 

*-----------------------+-------------------------+
| <<<\<tc:out\>>>>      | strong, deleted, number |
*-----------------------+-------------------------+
| <<<\<tc:in\>>>>       | number                  |
*-----------------------+-------------------------+
| <<<\<tc:label\>>>>    | number                  |
*-----------------------+-------------------------+
| <<<\<tc:treeNode\>>>> | strong                  |
*-----------------------+-------------------------+

  Also see the {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-theme/tobago-theme-standard/src/main/resources/META-INF/tobago-config.xml}standard <<<tobago-config.xml>>>}}

  The markup <<<strong>>> is normally emphasized, <<<deleted>>> is rendered struck out, and <<<number>>> is
  right aligned. Multiple markups can be combined as a comma separated list:

+------------------------------------------+
...
<tc:label value="Normal"/>
<tc:out value="999.99"/>

<tc:label value="Number"/>
<tc:out markup="number" value="999.99"/>

<tc:label value="Emphasized"/>
<tc:out markup="strong" value="999.99"/>

<tc:label value="Emphasized Number"/>
<tc:out markup="number,strong" value="999.99"/>
...
+------------------------------------------+

  This code fragment is rendered like this:\
  \ 

[images/guide-markup.png] Markup example

  You can add markup in your own theme or extend the current themes on the fly by adding a <<<\<renderers\>>>> section
  into the <<<tobago-config.xml.>>>

  The address book example adds markup values to the <<<\<tc:progress\>>>> control to be able to colorize the control
  depending on the criticallity of the progress value. On the administration page the progress control is used to
  visualize the memory consumption of the VM.

+------------------------------------------+
<renderers>
  <renderer>
    <name>Progress</name>
    <supported-markup>
      <markup>ok</markup>
      <markup>warn</markup>
      <markup>error</markup>
    </supported-markup>
  </renderer>
</renderers>
+------------------------------------------+

  See the {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-example/tobago-example-addressbook-war/src/main/webapp/WEB-INF/tobago-config.xml}address book <<<tobago-config.xml>>>}} for a complete example.

  The various progress variants look like this:\
  \ 

[images/guide-progress.png] Progress markup


  Markup attributes are rendered into HTML as extra CSS style classes, which can be used to modify the normal
  styling of a control. In the progress example the following CSS is added to the Speyside theme:

+------------------------------------------+
.tobago-progress-value-markup-ok {
  background: green;
}

.tobago-progress-value-markup-warn {
  background: yellow;
}

.tobago-progress-value-markup-error {
  background: red;
}
+------------------------------------------+

  See the address book example 
  {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-example/tobago-example-addressbook-web/src/main/webapp/tobago-resource/html/speyside/standard/style/tobago.css}Speyside <<<tobago.css>>>}}.

  The <<<tobago.css>>> file is collected by the Tobago resource manager and can be used to overwrite and extend the
  default <<<tobago.css>>> file of the theme.

  Tobago 1.0.x and Tobago 1.5.x are using the old name <<<style.css>>>, since Tobago 2.0.0
  <<<tobago.css>>> is used, <<<style.css>>> will also be included for compatibility (in Tobago 2.x).

  The {{{https://svn.apache.org/repos/asf/myfaces/tobago/trunk/tobago-theme/tobago-theme-example/}example theme}} provides
  an example for styling sheet cells and contains more complex examples of markup, which need addtional JavaScript
  to generate more dynamic behaviours like fade-out effects or client-side change detection.

* {Partial Rendering}

  To avoid the reload of complete screens Tobago provides partial rendering, which advises the client to update
  only parts of the screen to optimize the amount of data sent to the client and the time to render necessary updates.
  Some controls like the tab control and the sheet directly support partial rendering. Whereas container
  controls like the generic panel allow to group arbitrary controls to be able to update them exclusively as a group.

* {Virtual Forms}

  The page tag establishes an implicit form for all controls on the screen. The form tag allows to divide these
  controls into smaller groups to be able to manage validation only for these grouped controls.

  A code fragment from the address book example:

+------------------------------------------+
<tc:form>
  <tx:selectOneChoice label="#{bundle.footerLanguage}"
      value="#{controller.language}">
    <f:selectItems value="#{controller.languages}"/>
    <f:facet name="change">
      <tc:command action="#{controller.languageChangedList}"/>
    </f:facet>
  </tx:selectOneChoice>
</tc:form>
+------------------------------------------+

* {Security}

  The extension module tobago-security allows to protect method bindings with the help of annotations. The module
  provides alternative command components with security handling. The available annotations are <<<@RolesAllowed>>>,
  <<<@DenyAll>>>, and <<<@PermitAll>>>.

  A code fragment from the address book example:

+------------------------------------------+
public class AdminController {

  @RolesAllowed("admin")
  public String admin() {
    return OUTCOME_ADMIN;
  }

  ...
}
+------------------------------------------+