Appendix D

Web Annotations

Servlet 3.0 added a set of annotation types to the API. These annotation types belong in the javax.servlet.annotation package and are used to annotate web objects such as servlets, filters, and listeners. This Appendix lists the annotation types.

HandlesTypes

This annotation type is used to declare the class types that a ServletContainerInitializer can handle. It has one attribute, value, that is used to declare the class types. For example, the following ServletContainerInitializer is annotated with @HandleTypes that declares that the initializer can handle UsefulServlet.

@HandlesTypes({UsefulServlet.class})
public class MyInitializer implements ServletContainerInitializer {
    ...
}

HttpConstraint

The HttpConstraint annotation type represents the security constraints applied to all HTTP protocol methods for which a corresponding HttpMethodConstraint element is not present. This annotation type must reside within the ServletSecurity annotation.

The attributes of HttpConstraint are given in Table D.1.

Table D.1: HttpConstraint attributes

For example, the following HttpConstraint annotation declares that the annotated servlet can only be accessed by users that are part of the manager role. Since no HttpMethodConstraint annotation is present, the constraint applies to all HTTP methods.

@ServletSecurity(@HttpConstraint(rolesAllowed = "manager"))

HttpMethodConstraint

This annotation type represents a security constraint on a specific HTTP method. The HttpMethodConstraint annotation can only appear within the ServletSecurity annotation.

The attributes for HttpMethodConstraint are given in Table D.2.

Table D.2: HttpMethodConstraint attributes

For example, the following ServletSecurity annotation employs both the value and httpMethodConstraints attributes. The HttpConstraint annotation defines roles that can access the annotated servlet and the HttpMethodConstraint annotation, which is written without the rolesAllowed attribute, overrides the constraint for the Get method. As such, the servlet can be accessed via Get by any user. On the other hand, access via all other HTTP methods can only be granted to users in the manager role.

@ServletSecurity(value = @HttpConstraint(rolesAllowed = "manager"),
    httpMethodConstraints = {@HttpMethodConstraint("GET")}
)

However, if the emptyRoleSemantic attribute of the HttpMethodConstraint annotation type is assigned EmptyRoleSemantic.DENY, then the method is restricted for all users. For example, the servlet annotated with the following ServletSecurity annotation prevents access via the Get method but allows access to all users in the member role via other HTTP methods.

@ServletSecurity(value = @HttpConstraint(rolesAllowed = "member"),
httpMethodConstraints = {@HttpMethodConstraint(value = "GET", 
    emptyRoleSemantic = EmptyRoleSemantic.DENY)}
)

MultipartConfig

The MultipartConfig annotation type is used to annotate a servlet to indicate that instances of the servlet is capable of handling the multipart/form-data MIME type, which is commonly used when uploading files.

Table D.3 lists the attributes of MultipartConfig.

Table D.3: MultipartConfig attributes

For example, the following MultipartConfig annotation specifies that the maximum file size that can be uploaded is a million bytes.

@MultipartConfig(maxFileSize = 1000000)

ServletSecurity

The ServletSecurity annotation type is used to annotate a servlet class to apply security constraints on the servlet. The attributes that can appear in the ServletSecurity annotation are given in Table D.4.

Table D.4: ServletSecurity attributes

For example, the following ServletSecurity annotation contains an HttpConstraint annotation that dictates that the annotated servlet can only be accessed by those in the manager role.

@ServletSecurity(value = @HttpConstraint(rolesAllowed = "manager"))

WebFilter

The WebFilter annotation type is used to annotate a filter. Table D.5 shows attributes that may appear in the WebFilter annotation. All attributes are optional.

Table D.5: WebFilter attributes

WebInitParam

This annotation type is used to pass initialization parameters to a servlet or a filter. The attributes that may appear in a WebInitParam annotation are given in Table D.6. The asterisk to the right of the attribute name indicates that the attribute is required.

Table D.6: WebInitParam attributes

WebListener

This annotation type is used to annotate a listener. Its only attribute, value, is optional and contains the description of the listener.

WebServlet

This annotation type is used to annotate a servlet. Its attributes are listed in Table D.7. All attributes are optional.

Table D.7: WebServlet attributes