Deployment Descriptors and Annotations

A deployment descriptor is an XML file that describes how a Java EE application or module should be deployed. Each deployment descriptor XML file has a corresponding Document Type Definition (DTD) file or schema (XSD) file, which defines the elements, data, and attributes that the deployment descriptor file can contain. The deployment descriptor directs a deployment tool to deploy a module or application with specific container options, and also describes specific configuration requirements that you must resolve.

Because the information in a deployment descriptor is declarative, it can be changed without requiring modifications to source code. At run time, GlassFish Server reads the information in the deployment descriptor and deploys the application or module as directed.

The following types of deployment descriptors are associated with GlassFish Server:

• Java EE Standard Descriptors. Java EE standard deployment descriptors are described in the Java EE 6 specification. You can find the specification at http://developers.sun.com/downloads/. Information about the XML schemas that define Java EE standard deployment descriptors is available at http://java.sun.com/xml/ns/javaee/.

• GlassFish Server Descriptors. GlassFish Server provides optional deployment descriptors for configuring features that are specific to GlassFish Server. For example, when you assemble an EJB module, you annotate or create two GlassFish Server deployment descriptor files with these names: ejb-jar.xml and sun-ejb-jar.xml. For complete descriptions of these files and their elements, see Appendix B, GlassFish^TM Server Deployment Descriptor Files and Appendix C, Elements of the GlassFish^TM Server Deployment Descriptors.

  Unless otherwise stated, settings in the GlassFish Server deployment descriptors override corresponding settings in the Java EE standard descriptors and in the GlassFish Server configuration. For more information about the domain configuration file, see Oracle GlassFish Server 3.0.1 Domain File Format Reference.

An annotation, also called metadata, enables a declarative style of programming. You can specify information within a class file by using annotations. When the application or module is deployed, the information can either be used or overridden by the deployment descriptor. GlassFish Server supports annotation according to the following specifications:

• JSR 250 Common Annotation Specification (http://www.jcp.org/en/jsr/detail?id=250)

• JSR 181 Annotation for Web Services Specification (http://www.jcp.org/en/jsr/detail?id=181)

• EJB 3.1 Specification (http://www.jcp.org/en/jsr/detail?id=318)

The following annotation and deployment descriptor combinations are supported:

• Java EE applications or modules can be packaged with full Java EE 6 compliant standard and runtime deployment descriptors. If the standard deployment descriptors have specified the metadata-complete attribute, annotations in the module are ignored.

• Java EE applications or modules can be fully annotated with metadata defined by the listed specifications. Annotation eliminates the need for Java EE standard deployment descriptors. In most cases, the GlassFish Server deployment descriptors are also not needed.

• Java EE applications or modules can be partially annotated with some deployment information in standard deployment descriptors. In case of conflicts, deployment descriptor values supersede the annotated metadata, and a warning message is logged.