12.5.1 Purpose and scope of the functionality for controlling the annotation references

This subsection describes the purpose and scope of the functionality for controlling the annotation references.

Organization of this subsection
(1) Purpose of the functionality for controlling the annotation references
(2) Scope

(1) Purpose of the functionality for controlling the annotation references

The functionality for controlling the annotation references is used to specify whether to reference (parsing) annotations in J2EE applications. To determine the presence of annotations in a module, the application must be parsed. However, if all the applications are parsed, unnecessary overhead occurs for the applications not using annotations. Also, for the applications that reference resources and other applications, a class file reference error might occur during annotation parsing and the deployment might fail.

If you use the functionality for controlling the annotation references, you can control the parsing of annotations when an annotation is not used.

You can use the functionality for controlling the annotation references in Servlet 2.5 or later. The functionality for controlling the annotation references cannot be used in EJB 3.0 and later.

The operations in Servlet 2.5 or later are as follows:

In Servlet 2.5 or later
With Java EE 5 and later applications, annotations can be used with the standard specifications. The metadata-complete attribute, an attribute for controlling annotation references, is added in the DD of Servlet 2.5 and later. By using the metadata-complete attribute, you can control the annotation references for each module.
However, in the case of applications where the DD is omitted, the functionality for controlling the annotation references cannot be used because the annotations are necessarily referenced for reading the module definition information.
The functionality for controlling the annotation references for each module conforms to the standard specifications for Java EE 5 or later.
Reference note
With Application Server, apart from the <display-name> element, only the definitions related to the interceptors and application exceptions can be defined in the DD of EJB 3.0. With EJB 3.1, you can define the <module-name> element in addition to this, but all the other module definition information for EJB 3.0 or EJB 3.1 must be defined with annotations. Therefore, the functionality for controlling the annotation references cannot be used in EJB 3.0.
Note
If you change the functionality for controlling the annotation references from disable to enable after importing a J2EE application containing the annotation-coded EJB 2.1 or Servlet 2.4 modules, the following events occur:
  • The annotation information is output to the property file
  • When @Resource or @Resources is used, the property file cannot be set up and the J2EE application fails to start

(2) Scope

The scope of the functionality for controlling the annotation references differs according to the module type that includes the annotation.

The following table describes the scope of the functionality for controlling the annotation references.

Table 12-10 Scope of the functionality for controlling the annotation references

Module versionPresence of DD and specified contentsScope of reference control
J2EE serversModules
EJB1.1, 2.0DD exists (metadata-complete attribute does not exist)----
2.1#1DD exists (metadata-complete attribute does not exist)Y#2--
3.0 or laterNo DDNY
DD exists (metadata-complete attribute exists)OmittedNY
SpecifiedNY#3
Servlet2.2, 2.3
2.4#1
2.5 or later
DD exists (metadata-complete attribute does not exist)----
DD exists (metadata-complete attribute does not exist)Y#2--
No DDNY
DD exists (metadata-complete attribute exists)OmittedNY
SpecifiedNY
Legend:
Y: Enabled
N: Cannot be used
--: Not applicable

#1: The use of annotations with EJB 2.1 and Servlet 2.4 is the functionality for compatibility with the earlier versions. For details, see 5.4 Using annotations with EJB 2.1 and Servlet 2.4 in the uCosminexus Application Server Maintenance and Migration Guide.

#2: If enabled, the J2EE application containing the EJB 2.1 or Servlet 2.4 modules with the annotations coded cannot be used.

#3: You cannot specify true as the value. If true is specified, the importing and redeploying of applications in the J2EE server fails.


Specify the module settings in the metadata-complete attribute of the DD. Specify the J2EE server settings in the ejbserver.deploy.applications.metadata_complete property. The following table describes whether the annotations are referenced when the settings for the modules and J2EE servers are combined.

Table 12-11 Combining the settings for the J2EE servers and modules

Module versionSettings for modulesSettings for J2EE servers
Property is not specifiedejbserver.deploy.applications.metadata_complete property
falsetrue
EJB 3.0 or laterNo DDYYY
DD exists (metadata-complete attribute exists)OmittedYYY
falseYYY
true--#--#--#
Servlet 2.5 or laterNo DDYYY
DD exists (metadata-complete attribute exists)OmittedYYY
falseYYY
trueNNN
Legend:
Y: Referenced
N: Not referenced
--: Not applicable

#: The application containing EJB 3.0 with true specified in the metadata-complete attribute of the DD cannot be imported and redeployed.