Chapter 5. Best Practices

Chapter 5. Best Practices
Prev		Next

This chapter discusses Best Practices for designing and building Click + applications. +

5.1. Security

For application security it is highly recommended that you use the + declarative JEE Servlet path role based security model. While Click pages + provide an onSecurityCheck() method for rolling your own + programatic security model, the declarative JEE model provides numerous + advantages. +

These advantages include: +

Its an industry standard pattern making development and maintenance + easier. +
Application servers generally provide numerous ways of integration + with an organisations security infrastructure, including LDAP directories + and relational databases. +
Servlet security model support users bookmarking pages. When users + go to access these pages later, the container will automatically authenticate + them before allowing them to access the resource. +
Using this security model you can keep your Page code free of + security concerns. This makes you code more reusable, or at least easier + to write. +

If your application has very fine grained or complex security requirements + you may need to combine both the JEE declarative security model and a + programmatic security model to meet your needs. In these cases its + recommended you use declarative security for course grained access and + programmatic security for finner grained access control. +

5.1.1. Declarative Security

The declarative JEE Servlet security model requires users to be + authenticated and in the right roles before they can access secure resources. + Relative to many of the JEE specifications the Servlet security model is + surprisingly simple. +

+ For example to secure admin pages, you add a security + constraint in your web.xml file. This requires users + to be in the admin role before they can access to any + resources under the admin directory: +

<security-constraint>
+   <web-resource-collection>
+      <web-resource-name>admin</web-resource-name>
+      <url-pattern>/admin/*</url-pattern>
+   </web-resource-collection>
+   <auth-constraint>
+      <role-name>admin</role-name>
+   </auth-constraint>
+</security-constraint>

The application user roles are defined in the web.xml + file as security-role elements: +

<security-role>
+   <role-name>admin</role-name>
+</security-role>

The Servlet security model supports three different authentication method:

+ BASIC - only recommended for internal + applications where security is not important. This is the easiest + authentication method, which simply displays a dialog box to users + requiring them to authenticate before accessing secure resources. + The BASIC method is relatively unsecure as the username and password + are posted to the server as a Base64 encoded string. +
+ DIGEST - recommended for internal applications + with a moderate level of security. As with BASIC authentication, + this method simply displays a dialog box to users requiring them to + authenticate before accessing secure resources. Not all application + servers support DIGEST authentication, with only more recent + versions of Apache Tomcat supporting this method. +
+ FORM - recommended applications for where + you need a customised login page. For applications requiring a high + level of security it is recommended that you use the FORM method + over HTTPS. +

The authentication method is specified in the <login-method> element. + For example to use the BASIC authentication method you would specify: +

<login-config>
+   <auth-method>BASIC</auth-method>
+   <realm-name>Admin Realm</realm-name>
+</login-config>

To use the FORM method you also need to specify the path to the login + page and the login error page: +

<login-config>
+   <auth-method>FORM</auth-method>
+   <realm-name>Secure Realm</realm-name>
+   <form-login-config>
+      <form-login-page>/login.htm</form-login-page>
+      <form-error-page>/login.htm?auth-error=true</form-error-page>
+   </form-login-config>
+</login-config>

In your Click login.htm page you need to include a + special j_security_check form which includes the input + fields j_username and j_password. + For example: +

#if ($request.getParameter("auth-error"))
+<div style="margin-bottom:1em;margin-top:1em;color:red;">
+  Invalid User Name or Password, please try again.<br/>
+  Please ensure Caps Lock is off.
+</div>
+#end
+
+<form method="POST" action="j_security_check" name="form">
+<table border="0" style="margin-left:0.25em;">
+ <tr>
+   <td><label>User Name</label><font color="red">*</font></td>
+   <td><input type="text" name="j_username" maxlength="20" style="width:150px;"/></td>
+   <td>&nbsp;</td>
+  </tr>
+  <tr>
+   <td><label>User Password</label><font color="red">*</font></td>
+   <td><input type="password" name="j_password" maxlength="20" style="width:150px;"/></td>
+   <td><input type="image" src="$context/images/login.png" title="Click to Login"/></td>
+  </tr>
+</table>
+</form>
+
+<script type="text/javascript">
+  document.form.j_username.focus();
+</script>

When using FORM based authentication do NOT + put application logic in a Click Login Page class, as the role of this page + is to simply render the login form. If you attempt to put navigation logic + in your Login Page class, the JEE Container may simply ignore it or throw + errors. +

Putting this all together below is a web.xml + snippet which features security constraints for pages under the admin + path and the user path. This configuration uses the FORM method for + authentication, and will also redirect unauthorized (403) requests to the + /not-authorized.htm page. +

<web-app>
+
+    ..
+
+    <error-page>
+        <error-code>403</error-code>
+        <location>/not-authorized.htm</location>
+    </error-page>
+
+    <security-constraint>
+        <web-resource-collection>
+            <web-resource-name>admin</web-resource-name>
+            <url-pattern>/admin/*</url-pattern>
+        </web-resource-collection>
+        <auth-constraint>
+            <role-name>admin</role-name>
+        </auth-constraint>
+    </security-constraint>
+
+    <security-constraint>
+        <web-resource-collection>
+            <web-resource-name>user</web-resource-name>
+            <url-pattern>/user/*</url-pattern>
+        </web-resource-collection>
+        <auth-constraint>
+            <role-name>admin</role-name>
+            <role-name>user</role-name>
+        </auth-constraint>
+    </security-constraint>
+
+    <login-config>
+        <auth-method>FORM</auth-method>
+        <realm-name>Secure Zone</realm-name>
+        <form-login-config>
+            <form-login-page>/login.htm</form-login-page>
+            <form-error-page>/login.htm?auth-error=true</form-error-page>
+        </form-login-config>
+    </login-config>
+
+    <security-role>
+        <role-name>admin</role-name>
+    </security-role>
+
+    <security-role>
+        <role-name>user</role-name>
+    </security-role>
+
+</web-app>

5.1.2. Alternative Security solutions

There are also alternative security solutions that provide extra + features not available in JEE, such as RememberMe functionality, better + resource mapping and Post Logon Page support. + (Post Logon Page support allows one to specify a default + URL where the user will be forwarded after successful login. This feature + allows one to embed a login form in all non-secure pages and after successful + authentication the user will be forwarded to their home page.) +

Below are some of the alternative security solutions available: +

5.1.3. Resources

For more information on using security see the resources below:

+ + Form Based Authentication + by Louis E. Mauget +
+ Servlet Specification + by Sun Microsystems +
+ + Basic authentication scheme + +
+ + Digest authentication scheme + +
+ Https URI scheme +

5.2. Packages and Classes
Prev	Chapter 5. Best Practices	Next

5.2. Packages and Classes

An excellent way to design your project package structure is the + classify packages initially by technology. So in a Click application all + of our pages would be contained under a page package. + This also works very well with the Page automapping feature. +

+ All the projects domain entity classes would be contained under a + entity package, and service classes would be contained + under a service directory. Note alternative names for the + entity package include domain or model. We also typically + have a util package for any stray classes which don't quite + fit into the other packages. +

In Java, package names are singular by convention, so we have a util + package rather than a utils package. +

An example project structure for a MyCorp web application is illustrated + below: +

Figure 5.1. Example project structure

In this example application we use declarative role and path based security. + All the pages in the admin package and directory require the + "admin" role to be access, while all the pages in the + user package and directory require the "user" + role to be accessed. +

5.2.1. Page Classes

A best practice when developing application Page classes is to + place common methods in a base page class. This is typically used for + providing access methods to application services and logger objects. +

For example the BasePage below provides access to Spring configured + service objects and a Log4J logger object: +

public class BasePage extends Page implements ApplicationContextAware {
+
+    /** The Spring application context. */
+    protected ApplicationContext applicationContext;
+
+    /** The page Logger instance. */
+    protected Logger logger;
+
+    /**
+     * Return the Spring configured Customer service.
+     *
+     * @return the Spring configured Customer service
+     */
+    public CustomerService getCustomerService() {
+        return (CustomerService) getBean("customerService");
+    }
+
+    /**
+     * Return the Spring configured User service.
+     *
+     * @return the Spring configured User service
+     */
+    public UserService getUserService() {
+        return (UserService) getBean("userService");
+    }
+
+    /**
+     * Return the page Logger instance.
+     *
+     * @return the page Logger instance
+     */
+    public Logger getLogger() {
+        if (logger == null) {
+            logger = Logger.getLogger(getClass());
+        }
+        return logger;
+    }
+
+    /**
+     * @see ApplicationContextAware#setApplicationContext(ApplicationContext)
+     */
+    public void setApplicationContext(ApplicationContext applicationContext)  {
+        this.applicationContext = applicationContext;
+    }
+
+    /**
+     * Return the configured Spring Bean for the given name.
+     *
+     * @param beanName the configured name of the Java Bean
+     * @return the configured Spring Bean for the given name
+     */
+    public Object getBean(String beanName) {
+        return applicationContext.getBean(beanName);
+    }
+
+}

Applications typically use a border template and have a + BorderPage which extends BasePage + and defines the template. For example: +

public class BorderPage extends BasePage {
+
+    /** The root Menu item. */
+    public Menu rootMenu = new Menu();
+
+    /**
+     * @see Page#getTemplate()
+     */
+    public String getTemplate() {
+        return "/border-template.htm";
+    }
+}

Most application pages subclass BorderPage, except + AJAX pages which have no need for a HTML border template and typically extend + BasePage. The BorderPage class + should not include common logic, other than that required for rendering the + border template. Common page logic should be defined in the + BasePage class. +

To prevent these base Page classes being auto mapped, and becoming + directly acessible web pages, ensure that there are no page templates which + could match their class name. For example the BorderPage + class above will not be auto mapped to border-template.htm. +

5.3. Page Auto Mapping
Prev	Chapter 5. Best Practices	Next

You should use the Click page automapping configuration feature. + See the Page Automapping + topic for details. +

Automapping will save you from having to manually configure URL path to + Page class mappings in your click.xml file. If you follow + this convention it is very easy to maintain and refactor applications. +

You can also quickly determine what the corresponding Page class is for a + page HTML template and visa versa, and if you use the ClickIDE Eclipse plugin + you can switch between a page's class and template by pressing Ctrl+Alt+S. +

An example click.xml automapping configuration is + provided below (automapping is enabled by default): +

To see how the page templates are mapped to Page classes set the application + mode to + debug and at startup the mappings will be listed out. An + example Click startup listing is provided below: +

5.4. Navigation
Prev	Chapter 5. Best Practices	Next

5.5. Templating
Prev	Chapter 5. Best Practices	Next

5.6. Menus
Prev	Chapter 5. Best Practices	Next

5.7. Logging
Prev	Chapter 5. Best Practices	Next

< h2 class="title" style="clear: both">5.7. Logging

+ For application logging you should use one of the well established + logging libraries such as Java Util Logging (JUL) or Log4J. +

+ The library you use will largely depend upon the application server you are targeting. + For Apache Tomcat or RedHat JBoss the + Log4j library is a good + choice. While for the IBM WebSphere or Oracle WebLogic application servers Java Util + Logging is better choice as this library is better supported. +

+ If you have to target multiple application servers you should consider using the + SLF4J library which uses compile time bindings + to an underlying logging implementation. +

+ As a general principle you should + probably avoid Commons Logging + because of the class loading issues associated with it. If you are using + Commons Logging please make sure you have the latest version. +

+ It is a best place to define a logger method in a common base page, for example: +

public class BasePage extends Page {
+
+    protected Logger logger;
+
+    public Logger getLogger() {
+        if (logger == null) {
+            logger = Logger.getLogger(getClass());
+        }
+        return logger;
+    }
+}

Using this pattern all your application bases should extend + BasePage so they can use the + getLogger() method. +

public class CustomerListPage extends BasePage {
+
+    public void onGet() {
+        try {
+            ..
+        } catch (Exception e) {
+            getLogger().error(e);
+        }
+    }
+}

If you have some very heavy debug statement you should possibly use an + isDebugEnabled switch so it is not invoked if debug is + not required. +

public class CustomerListPage extends BasePage {
+
+    public void onGet() {
+        if (getLogger().isDebugEnabled()) {
+            String msg = ..
+
+            getLogger().debug(msg);
+        }
+
+        ..
+    }
+}

+ Please note the Click logging facility is not designed for application use, + and is for Click internal use only. When Click is running in + production mode it will not produce any logging output. + By default Click logs to the console using + ConsoleLogService. +

+ If you need to configure Click to log to an alternative destination please configure a LogService such as + JdkLogService, + Log4JLogService or + Slf4jLogService. +

5.8. Error Handling
Prev	Chapter 5. Best Practices	Next

5.9. Performance
Prev	Chapter 5. Best Practices

5.9. Performance

Yahoo published a list of + best practices + for improving web application performance. +

Click Framework provides a + PerformanceFilter + which caters for some of these rules. However not all rules can be easily automated. +

This section outlines how to apply some important rules which are not + covered by the PerformanceFilter namely, + Minimize HTTP Requests (by combining files) + and Minify JavaScript and CSS. +

The Rule, Minimize HTTP Requests, + also mentions CSS Sprites, + a method for combining multiple images into a single master image. CSS Sprites + can boost performance when your application has many images, however it is + harder to create and maintain. Note that CSS Sprites is not covered here. +

It is worth pointing out that its not necessary to optimize + every page in your application. Instead concentrate on popular pages, for + example a web site's Home Page would be a good + candidate. +

There are a couple of tools that are useful in applying the rules + "Minimize HTTP Requests" and "Minify JavaScript and CSS": +

+ YUICompressor + - minifies and compresses JavaScript and CSS files so less bytes have to + be transferred across the wire. +
+ Ant Task for YUICompressor + - an Ant task that uses YUICompressor to compress JavaScript and CSS files. +
+ JSMin + - similar to YUICompressor but only minifies (remove whitespace and newlines) + JavaScript files and does no compression at all. An advantage of JSMin + over YUICompressor is that its faster and can be used at runtime to minify + JavaScript, while YUICompressor is most often used at build time. +

Below are some articles outlining how to use YUICompressor and Ant to + concatenate and compress JavaScript and CSS files: +

+ Article + explaining how to use Ant and YUICompressor for compression. +
+ Article + outlining how to use a special YUICompressor Ant Task for compression. +

Using one of the approaches above you can concatenate and compress all + JavaScript and CSS for your Pages into two separate files, for example + home-page.css + and home-page.js. Note that the two files must include + all the JavaScript and CSS that is generated by the Page and its Controls. + Then you can instruct Click to only include the two + compressed files, home-page.css and home-page.js. +

Click makes use of the utility class + PageImports + to include the CSS and JavaScript. PageImports exposes the method + setInitialized(boolean), + which controls when PageImports are fully initialized. Once PageImports have + been initialized, no other CSS and JavaScript will be included. +

Knowing this one can override + Page.getPageImports(), + and import the necessary JavaScript and CSS files and then set PageImports to + initialized, forcing PageImports to skip other CSS and + JavaScript files. +

Here is an example:

public class HomePage extends Page {
+
+    private Form form = new Form("form");
+
+    public void onInit() {
+        form.add(new EmailField("email");
+        addControl(form);
+    }
+
+    public PageImports getPageImports () {
+        PageImports pageImports = super.getPageImports();
+
+        // Add the Page Css to the PageImports
+        pageImports.add(new CssImport("/assets/css/home-page.css"));
+
+        // Add the Page JS to the PageImports
+        pageImports.add(new JsImport("/assets/js/home-page.js"));
+
+        // Set pageImports to initialized so that no other Css and JavaScript
+        // files will be included.
+        pageImports.setInitialized(true);
+        
+        return pageImports;
+    }
+}

Using the following border-template.htm: +

<html>
+  <head>
+    <title>Click Examples</title>
+    ${headElements}
+  </head>
+  <body>
+
+  ...
+
+  ${jsElements}
+  </body>
+</html>

the rendered HTML will include one CSS and one JavaScript import:

<html>
+  <head>
+    <title>Click Examples</title>
+    <link type="text/css" rel="stylesheet"
+          href="/click-examples/assets/css/home-page.css" title="Style"/>
+  </head>
+  <body>
+
+  ...
+
+  <script type="text/javascript" src="/click-examples/assets/js/home-page.js"></script>
+  </body>
+</html>

A live demo is available + here +

Prev	Up
5.8. Error Handling	Home

\ No newline at end of file Propchange: incubator/click/trunk/tools/eclipse/org.apache.click.eclipse/documentation/user-guide/ch05s09.html ------------------------------------------------------------------------------ svn:mime-type = text/plain

Prev		Next
4.3. Auto Deployed Files	Home	5.2. Packages and Classes