12.6.2 Overwriting the annotations using the DD

You can overwrite the information defined in the annotation with the DD. The annotations defined in the modules of Servlet 2.5 or later and EJB 3.0 or later can be overwritten by the DD.

The methods of overwriting the annotations are as follows:

Method of overwriting by editing the DD
In this method, you directly edit the DD.
Method of overwriting by using the server management commands to change the attributes
In this method, you use the cjsetappprop command or cjsetresprop command to change the attributes for the application after the application is imported into the J2EE server. However, the annotations that can be overwritten with this method have some conditions. For details, see 12.6.3 Referencing and updating the definitions with the server management commands.
Reference note
You can specify the following definitions in the DD of EJB 3.0 or later that is imported into Application Server:
  • <display-name> element
  • <interceptor-binding> element, and the elements beneath this element (interceptor-related definition)
  • <application-exception> element, and the elements beneath this element (application exception-related definition)
Note
In the name attribute of the @WebServlet annotation, you cannot specify the same value as another @WebServlet annotation. Also, in the filtername attribute of the @WebFilter annotation, you cannot specify the same value as another @WebFilter annotation. If you specify the same value as another annotation, the following messages are output during overwriting in the DD and the relevant annotation is ignored.
AnnotationAttributeMessage
@WebServletname attributeKDJE42397-W
@WebFilterfiltername attributeKDJE42398-W

The overwriting method differs depending on whether the target DD elements and child elements can appear multiple times.

When the DD elements appear 0 times (do not appear) or only once
The annotation information is overwritten with the DD information.
When the DD elements appear 0 or more times or 1 or more times
The overwriting rules differ with the presence or absence of elements (key) associating the DD and annotations and the occurrence count of the child elements in the DD elements.

This subsection describes the rules for overwriting the annotations using the DD by separating them into the following 4 patterns.

Table 12-16 Pattern of rules for overwriting the annotations using the DD

PatternOccurrence count of the DD elements corresponding to the annotationsPresence of keysOccurrence count of the DD child elementsReference location
Pattern 10 times or onceWhen the key does not exist--(1)
Pattern 20 or more times or 1 or more timesWhen the key does not exist--(2)
Pattern 3When the key exists0 times or once(3)
Pattern 40 or more times or 1 or more times(4)
Legend:
--: There is no difference based on the presence or absence of the key

For the mapping between the annotation and DD elements, presence or absence of keys for each element, and the key elements, see the standard specifications.

The description of each pattern is as follows:

Organization of this subsection
(1) Pattern 1 (when the element appears 0 times or once)
(2) Pattern 2 (when the key does not exist in an element that appears 0 or more times or 1 or more times)
(3) Pattern 3 (when the child element appears 0 times or once in the element that appears 0 or more times or 1 or more times)
(4) Pattern 4 (when the child element appears 0 or more times or 1 or more times in an element that appears 0 or more times or 1 or more times)

(1) Pattern 1 (when the element appears 0 times or once)

If the occurrence count of an element is 0 times or once, whether to overwrite the definition is determined by whether the element corresponding to the annotation is defined in the DD. The key value does not make a difference.

When the element corresponding to the annotation is defined in the DD
The annotation definition is overwritten by the DD definition.
When the element corresponding to the annotation is not defined in the DD
The annotation definition becomes valid.

The following figure shows an example of an element with occurrence count of 0 times or once. In this example, the key exists.

Figure 12-3 Example of an element that appears 0 times or once

[Figure]

(2) Pattern 2 (when the key does not exist in an element that appears 0 or more times or 1 or more times)

The definitions of both the DD and annotations are valid.

The following figure shows an example when the key does not exist. In addition to the security role defined in @DeclareRoles, a new security role is defined in the DD.

Figure 12-4 Example when the key does not exist

[Figure]

In this example, three security roles, 'admin', 'adminadmin', and 'adminadminadmin', are defined in the annotation. In addition to these, 'admin2' defined in the DD is added and applied in the merged DD. Note that 'adminadmin' is a security role defined in both, annotation and the DD. The application is operated assuming the merged DD is defined.

Note that when this pattern is applicable, the annotation definition cannot be changed using the server management commands. Even if the information corresponding to the annotation is deleted or changed in the property file and the cjsetappprop command is executed, the information defined in the annotation is output to the property file obtained by using the cjgetappprop command thereafter.

(3) Pattern 3 (when the child element appears 0 times or once in the element that appears 0 or more times or 1 or more times)

When the child element within a DD element appears 0 times or once, the overwriting method differs on the basis of the key value.

If the key value matches in the DD and annotation
The DD element overwrites the annotation definition.
If the key value does not match in the DD and annotation
The annotation is not overwritten. Both the DD and annotation definitions become valid.

Figure 12-5 Example when the child element appears 0 times or once

[Figure]

In this example, the value of the environment entry 'res1' is changed from 'TEST' defined in the annotation to 'RUNNING' defined in the DD. The application is operated assuming that the merged DD is defined.

(4) Pattern 4 (when the child element appears 0 or more times or 1 or more times in an element that appears 0 or more times or 1 or more times)

When the child element within a DD element appears 0 or more times or 1 or more times, the overwriting method differs on the basis of the key value.

If the key value matches in the DD and annotation
The DD element is added to the annotation definition.
If the key value does not match in the DD and annotation
The annotation is not overwritten. Both the DD and annotation definitions become valid.

Figure 12-6 Example when the child element appears 0 or more times or 1 or more times

[Figure]

In this example, the element 'injection-target' defined in the DD is added to the annotation definition. The application is operated assuming that the merged DD is defined.