Component
Type Classes implementing the following interfaces
Servlets javax.servlet.Servlet Filters javax.servlet.Filter Listeners javax.servlet.ServletContextListener javax.servlet.ServletContextAttributeListener javax.servlet.ServletRequestListener javax.servlet.ServletRequestAttributeListener javax.servlet.http.HttpSessionListener javax.servlet.http.HttpSessionAttributeListener
defines whether the web descriptor is complete, or whether the class files of the jar file should be examined for annotations that specify deployment information. If “metadata-complete” is set to "true", the deployment tool must ignore any Servlet annotations present in the class files of the application. If the full attribute is not specified or is set to "false", the deployment tool must examine the class files of the application for annotations, as previously specified.
Following are the annotations that are required by a Java EE technology compliant web container.
SRV.14.5.1 @DeclaresRoles
This annotation is used to define the security roles that comprise the security model of the application. This annotation is specified on a class, and it typically would be used to define roles that could be tested (i.e., by calling isUserInRole) from within the methods of the annotated class. It could also be used to declare application roles that are not implicitly declared as the result of their use in a
@DeclaresRoles annotation on the class implementing the javax.serv- let.Servlet interface or a subclass thereof.
Following is an example of how this annotation would be used.
@DeclaresRoles("BusinessAdmin") public class CalculatorServlet { //...
}
Declaring @DeclaresRoles ("BusinessAdmin") is equivalent to defining the following in the web.xml.
<web-app>
<security-role>
<role-name>BusinessAdmin</role-name> </security-role>
</web-app>
This annotation is not used to relink application roles to other roles. When such linking is necessary, it is accomplished by defining an appropriate security- role-ref in the associated deployment descriptor.
When a call is made to isUserInRole from the annotated class, the caller identity associated with the invocation of the class is tested for membership in the
Final Version
role-ref has been defined for the argument role-name the caller is tested for
membership in the role mapped to the role-name.
For further details on the @DeclaresRoles annotation refer to the Common
Annotations for the JavaTM PlatformTM specifcation (JSR 250) section 2.10.
SRV.14.5.2 @EJB Annotation
EnterpriseJavaBeansTM 3.0 (EJB) components may referenced from a web
component using the @EJB annotation. The @EJB annotation provides the equivalent functionality of declaring the ejb-ref or ejb-local-ref elements in the deployment descriptor. Fields that have a corresponding @EJB annotation are injected with the a reference to the corresponding EJB component.
An example:
@EJB private ShoppingCart myCart;
In the case above a reference to the EJB component “myCart” is injected as the value of the private field “myCart” prior to the classs declaring the injection being made available.
The behavior the @EJB annotation is further detailed in section 15.5 of the EJB 3.0 specification (JSR220).
SRV.14.5.3 @EJBs Annotation
The @EJBs annotation allows more than one @EJB annotations to be declared on a single resource.
An example:
@EJBs({@EJB(Calculator), @EJB(ShoppingCart)}) public class ShoppingCartServlet {
//... }
The example above the EJB components ShoppingCart and Calculator
are made available to ShoppingCartServlet. The ShoppingCartServlet
must still look up the references using JNDI but the EJBs do not need to declared in the web.xml file.
The @EJBs annotation is discussed in further detailed in section 15.5 of the EJB 3.0 specification (JSR220).
SRV.14.5.4 @Resource Annotation
The @Resource annotation is used to declare a reference to a resource such as a data source, Java Messaging Service (JMS) destination, or environment entry. This annotation is equivalent to declaring a resource-ref, message-destination- ref or env-ref, or resource-env-ref element in the deployment descriptor.
The @Resource annotation is specified on a class, method or field. The container is responsible injecting references to resources declared by the
@Resource annotation and mapping it to the proper JNDI resources. See the Java EE Specification Chapter 5 for further details.
An example of a @Resource annotation follows:
@Resource private javax.sql.DataSource catalogDS; public getProductsByCategory() {
// get a connection and execute the query Connection conn = catalogDS.getConnection(); ..
}
In the example code above, a servlet, filter, or listener declares a field cata- logDS of type javax.sql.DataSource for which the reference to the data
source is injected by the container prior to the component being made available to the application. The data source JNDI mapping is inferred from the field name “catalogDS” and type (javax.sql.DataSource). Moreover, the catalogDS
resource no longer needs to be defined in the deployment descriptor. The semantics of the @Resource annotation are further detailed in the
Common Annotations for the JavaTM PlatformTM specifcation (JSR 250) Section 2.3 and Java EE Specification specification 5.2.3.
SRV.14.5.5 @PersistenceContext Annotation
This annotation specifies the container managed entity manager for referenced persistence units.
Final Version
EntityManager em;
The behavior the @PersistenceContext annotation is further detailed in
section 8.4.1 of the Java Persistence document which is part of the EJB 3.0 specification (JSR220) and in section 15.11 of the EJB 3.0 specification.
SRV.14.5.6 @PersistenceContexts Annotation
The PersistenceContexts annotation allows more than one @PersistenceContext to be declared on a resource. The behavior the @PersistenceContext
annotation is further detailed in section 8.4.1 of the Java Persistence document which is part of the EJB 3.0 specification (JSR220) and in section 15.11 of the EJB 3.0 specification.
SRV.14.5.7 @PersistenceUnit Annotation
The @PersistenceUnit annotation provides Enterprise Java Beans components
declared in a servlet a reference to a entity manager factory. The entity manager factory is bound to a separate persistence.xml configuration file as described in section 5.10 of the EJB 3.0 specification (JSR220).
An example:
@PersistenceUnit
EntityManagerFactory emf;
The behavior the @PersistenceUnit annotation is further detailed in section 8.4.2 of the Java Persistence document which is part of the EJB 3.0 specification (JSR220) and in section 15.10 of the EJB 3.0 specification.
SRV.14.5.8 @PersistenceUnits Annotation
This annotation allows for more than one @PersistentUnit annotations to be
declared on a resource. The behavior the @PersistenceUnits annotation is further detailed in section 8.4.2 of the Java Persistence document which is part of the EJB 3.0 specification (JSR220) and in section 15.10 of the EJB 3.0 specification..
SRV.14.5.9 @PostConstruct Annotation
The @PostConstruct annotation is declared on a method that does not take
any arguments, and must not throw any checked expections. The return value must be void. The method MUST be called after the resources injections have been completed and before any lifecycle methods on the component are called.
An example:
@PostConstruct
public void postConstruct() { ...
}
The example above shows a method using the @PostConstruct annotation.
The @PostConstruct annnotation MUST be supported by all classes that
support dependency injection and called even if the class does not request any reources to be injected. If the method throws an unchecked exception the class MUST not be put into service and no method on that instance can be called.
Refer to the Java EE specification section 2.5 and the Common Annotations for the JavaTM PlatformTM specifcation section 2.5 for more details.
SRV.14.5.10 @PreDestroy Annotation
The @PreDestroy annotation is declared on a method of a container managed component. The method is called prior to component being reomvoed by the container.
An example:
@PreDestroy
public void cleanup() {
// clean up any open resources
... }
The method annotated with @PreDestroy must return void and must not throw a checked exception. The method may be public, protected, package private
Final Version
Refer to the JSR 250 section 2.6 for more details.
SRV.14.5.11 @Resources Annotation
The @Resources annotation acts as a container for multiple @Resource
annotations because the Java MetaData specification does not allow for multiple annotations with the same name on the same annotation target.
An example:
@Resources ({
@Resource(name=”myDB” type=javax.sql.DataSource),
@Resource(name=”myMQ” type=javax.jms.ConnectionFactory) })
public class CalculatorServlet { //...
}
In the example above a JMS connection factory and a data source are made available to the CalculatorServlet by means of an @Resources annotation.
The semantics of the @Resources annotation are further detailed in the Common Annotations for the JavaTM PlatformTM specifcation (JSR 250) section 2.4.
SRV.14.5.12 @RunAs Annotation
The @RunAs annotation is equivalent to the run-as element in the deployment descriptor. The @RunAs annotation may only be defined in classes implementing the
javax.servlet.Servlet interface or a subclass thereof.
An example:
@RunAs(“Admin”)
public class CalculatorServlet {
@EJB private ShoppingCart myCart;
public void doGet(HttpServletRequest, req, HttpServletResponse res) {
//....
//....
} }
//.... }
The @RunAs(“Admin”) statement would be equivalent to defining the following in the web.xml.
<servlet>
<servlet-name>CalculatorServlet</servlet-name> <run-as>Admin</run-as>
</servlet>
The example above shows how a servlet uses the @RunAs annotation to propagate the security identity “Admin” to an EJB component when the
myCart.getTotal() method is called. For further details on propagating identities see SRV.14.3.1.
For further details on the @RunAs annotation refer to the Common Annotations for the JavaTM PlatformTM specifcation (JSR 250) section 2.6.
SRV.14.5.13 @WebServiceRef Annotation
The @WebServiceRef annotation provides a reference to a web service in a web component in same way as a resource-ref element would in the deployment
descriptor. An example:
@WebServiceRef private MyService service;
In this example a reference to the web service “MyService” will be injected to the class declaring the annotation.
This annotation and behavior are further detailed in the JAX-WS Specification (JSR 224) section 7.
SRV.14.5.14 @WebServiceRefs Annotation
C H A P T E R
SRV.15
javax.servlet
This chapter describes the javax.servlet package. The chapter includes content that is generated automatically from javadoc embedded in the actual Java classes and interfaces. This allows the creation of a single, authoritative, specification docu- ment.