A Guide to Java EE Web-Related Annotations

1. Overview

Java EE annotations make developers’ life easier by allowing them to specify how application components should behave in a container. These are modern alternatives for XML descriptors and basically make it possible to avoid boilerplate code.

In this article, we’ll focus on annotations introduced with Servlet API 3.1 in Java EE 7. We will examine their purpose and look at their usage.

2. Web Annotations

Servlet API 3.1 introduced a new set of annotation types that can be used in Servlet classes:

• @WebServlet
• @WebInitParam
• @WebFilter
• @WebListener
• @ServletSecurity
• @HttpConstraint
• @HttpMethodConstraint
• @MultipartConfig

We’ll examine them in detail in next sections.

3. @WebServlet

Simply put, this annotation allows us to declare Java classes as servlets:

@WebServlet("/account")
public class AccountServlet extends javax.servlet.http.HttpServlet {
    
    public void doGet(HttpServletRequest request, HttpServletResponse response) 
      throws IOException {
        // ...
    }
 
    public void doPost(HttpServletRequest request, HttpServletResponse response) 
      throws IOException {
        // ...
    }
}

3.1. Using Attributes of @WebServlet Annotation

@WebServlet has a set of attributes that allow us to customize the servlet:

• name
• description
• urlPatterns
• initParams

We can use these as shown in the example below:

@WebServlet(
  name = "BankAccountServlet", 
  description = "Represents a Bank Account and it's transactions", 
  urlPatterns = {"/account", "/bankAccount" }, 
  initParams = { @WebInitParam(name = "type", value = "savings")})
public class AccountServlet extends javax.servlet.http.HttpServlet {

    String accountType = null;

    public void init(ServletConfig config) throws ServletException {
        // ...
    }

    public void doGet(HttpServletRequest request, HttpServletResponse response) 
      throws IOException {
        // ... 
    }

    public void doPost(HttpServletRequest request, HttpServletResponse response) 
      throws IOException {
        // ...  
    }
}

The name attribute overrides the default servlet name which is the fully qualified class name by default. If we want to provide a description of what the servlet does, we can use the description attribute.

The urlPatterns attribute is used to specify the URL(s) at which the servlet is available (multiple values can be provided to this attribute as shown in the code example).

4. @WebInitParam

This annotation is used with the initParams attribute of the @WebServlet annotation and the servlet’s initialization parameters.

In this example, we set a servlet initialization parameter type, to the value of ‘savings’:

@WebServlet(
  name = "BankAccountServlet", 
  description = "Represents a Bank Account and it's transactions", 
  urlPatterns = {"/account", "/bankAccount" }, 
  initParams = { @WebInitParam(name = "type", value = "savings")})
public class AccountServlet extends javax.servlet.http.HttpServlet {

    String accountType = null;

    public void init(ServletConfig config) throws ServletException {
        accountType = config.getInitParameter("type");
    }

    public void doPost(HttpServletRequest request, HttpServletResponse response) 
      throws IOException {
        // ...
    }
}

5. @WebFilter

If we want to alter the request and response of a servlet without touching its internal logic, we can use the WebFilter annotation. We can associate filters with a servlet or with a group of servlets and static content by specifying an URL pattern.

In the example below we are using the @WebFilter annotation to redirect any unauthorized access to the login page:

@WebFilter(
  urlPatterns = "/account/*",
  filterName = "LoggingFilter",
  description = "Filter all account transaction URLs")
public class LogInFilter implements javax.servlet.Filter {
    
    public void init(FilterConfig filterConfig) throws ServletException {
    }

    public void doFilter(
        ServletRequest request, ServletResponse response, FilterChain chain) 
          throws IOException, ServletException {
        HttpServletRequest req = (HttpServletRequest) request;
        HttpServletResponse res = (HttpServletResponse) response;

        res.sendRedirect(req.getContextPath() + "/login.jsp");
        chain.doFilter(request, response);
    }

    public void destroy() {
    }

}

6. @WebListener

Should we want knowledge or control over how and when a servlet and its requests are initialized or changed, we can use the @WebListener annotation.

To write a web listener we need to extend one or more of the following interfaces:

• ServletContextListener  – for notifications about the ServletContext lifecycle
• ServletContextAttributeListener – for notifications when a ServletContext attribute is changed
• ServletRequestListener – for notifications whenever a request for a resource is made
• ServletRequestAttributeListener – for notifications when an attribute is added, removed or changed in a ServletRequest
• HttpSessionListener – for notifications when a new session is created and destroyed
• HttpSessionAttributeListener – for notifications when a new attribute is being added to or removed from a session

Below is an example of how we can use a ServletContextListener to configured a web application:

@WebListener
public class BankAppServletContextListener 
  implements ServletContextListener {

    public void contextInitialized(ServletContextEvent sce) { 
        sce.getServletContext().setAttribute("ATTR_DEFAULT_LANGUAGE", "english"); 
    } 
    
    public void contextDestroyed(ServletContextEvent sce) { 
        // ... 
    } 
}

7. @ServletSecurity

When we want to specify the security model for our servlet, including roles, access control and authentication requirements we use the annotation @ServletSecurity.

In this example we will restrict access to our AccountServlet using the @ServletSecurity annotation:

@WebServlet(
  name = "BankAccountServlet", 
  description = "Represents a Bank Account and it's transactions", 
  urlPatterns = {"/account", "/bankAccount" }, 
  initParams = { @WebInitParam(name = "type", value = "savings")})
@ServletSecurity(
  value = @HttpConstraint(rolesAllowed = {"Member"}),
  httpMethodConstraints = {@HttpMethodConstraint(value = "POST", rolesAllowed = {"Admin"})})
public class AccountServlet extends javax.servlet.http.HttpServlet {

    String accountType = null;

    public void init(ServletConfig config) throws ServletException {
        // ...
    }

    public void doGet(HttpServletRequest request, HttpServletResponse response) 
      throws IOException {
       // ...
    }

    public void doPost(HttpServletRequest request, HttpServletResponse response) 
      throws IOException {        
        double accountBalance = 1000d;

        String paramDepositAmt = request.getParameter("dep");
        double depositAmt = Double.parseDouble(paramDepositAmt);
        accountBalance = accountBalance + depositAmt;

        PrintWriter writer = response.getWriter();
        writer.println("<html> Balance of " + accountType + " account is: " + accountBalance 
        + "</html>");
        writer.flush();
    }
}

In this case, when invoking the AccountServlet, the browser pops up a login screen for the user to enter a valid username and password.

We can use @HttpConstraint and  @HttpMethodConstraint annotations to specify values for the attributes value and httpMethodConstraints, of @ServletSecurity annotation.

@HttpConstraint  annotation applies to all HTTP methods. In other words, it specifies the default security constraint.

@HttpConstraint has three attributes:

• value
• rolesAllowed
• transportGuarantee

Out of these attributes, the most commonly used attribute is rolesAllowed. In the example code snippet above, users who belong to the role Member are allowed to invoke all HTTP methods.

@HttpMethodConstraint  annotation allows us to specify the security constraints of a particular HTTP method.

@HttpMethodConstraint has the following attributes:

• value
• emptyRoleSemantic
• rolesAllowed
• transportGuarantee

In the example code snippet above, it shows how the doPost method is restricted only for users who belong to the Admin role, allowing the deposit function to be done only by an Admin user.

8. @MultipartConfig

This annotation is used when we need to annotate a servlet to handle multipart/form-data requests (typically used for a File Upload servlet).

This will expose the getParts() and getPart(name) methods of the HttpServletRequest can be used to access all parts as well as an individual part.

The uploaded file can be written to the disk by calling the write(fileName) of the Part object.

Now we will look at an example servlet UploadCustomerDocumentsServlet that demonstrates its usage:

@WebServlet(urlPatterns = { "/uploadCustDocs" })
@MultipartConfig(
  fileSizeThreshold = 1024 * 1024 * 20,
  maxFileSize = 1024 * 1024 * 20,
  maxRequestSize = 1024 * 1024 * 25,
  location = "./custDocs")
public class UploadCustomerDocumentsServlet extends HttpServlet {

    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
      throws ServletException, IOException {
        for (Part part : request.getParts()) {
            part.write("myFile");
        }
    }

}

@MultipartConfig  has four attributes:

• fileSizeThreshold – This is the size threshold when saving the uploaded file temporarily. If the uploaded file’s size is greater than this threshold, it will be stored on the disk. Otherwise, the file is stored in memory (size in bytes)
• maxFileSize  – This is the maximum size of the uploaded file (size in bytes)
• maxRequestSize – This is the highest size of the request, including both uploaded files and other form data (size in bytes)
• location – The is the directory where uploaded files are stored

9. Conclusion

In this article, we looked at some Java EE annotations introduced with the Servlet API 3.1 and their purpose and their usage.

Source code related to this article can be found over on GitHub.