Use Java EE deployment descriptors to define environment references

This rule flags Context <Environment> elements found in the META-INF/context.xml file that must be transformed into <env-entry> elements in the WEB-INF/web.xml file.

Apache Tomcat allows Context <Environment> elements to be defined in these locations:

• The META-INF/context.xml file
• The application XML configuration file in Tomcat conf directory
• The <Host> element in the conf/server.xml

Since the migration tool might not have access to the Tomcat configuration directory, it only flags the Context <Environment> in the META-INF/context.xml file. Context <Environment> information defined in the other locations can be copied to the META-INF/context.xml file in order for it to be processed by the tool.

If a WEB-INF/web.xml exists in the web project:

Context <Environment> elements will be flagged under any of the following conditions:

• The entry does not have a matching entry in the web.xml file.
• The entry has a different type than the matching entry in the web.xml file.
• The entry has a different value than the matching entry in the web.xml and its override flag set to false.

A quick fix for this rule is available in the source scanner. The quick fix will add a new <env-entry> element in the web.xml file which represents the Context <Environment> element if it does not already exist in the web.xml file. If the entry exists, it will be updated.

If the WEB-INF/web.xml does not exist:

All Context <Environment> elements will be flagged.

The quick fix will create a WEB-INF/web.xml file that includes the appropriate <env-entry> elements if the web project is at Java EE 5 or higher. The quick fix will report an error if the web project is at J2EE 1.4 or lower.

For example, consider a META-INF/context.xml file with the following content:

<Environment description="Trigger because it does not exist" name="newEntry" override="false" type="java.lang.String" value="abc123"/> <Environment description="Trigger because of different value" name="contextEnvString_1" override="false" type="java.lang.String" value="new Value"/> <Environment description="Trigger because of different type" name="contextEnvString_2" override="false" type="java.lang.Integer" value="123"/> <Environment description="will not Trigger because of override set to true." name="contextEnvString_3" override="true" type="java.lang.Integer" value="123"/>

with the following web.xml file in the application:

<env-entry> <description>Trigger because of different value</description> <env-entry-name>contextEnvString_1</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>oldValue</env-entry-value> </env-entry> <env-entry> <description>Trigger because of different type</description> <env-entry-name>contextEnvString_2</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>123</env-entry-value> </env-entry> <env-entry> <description>will not Trigger because of override set to true.</description> <env-entry-name>contextEnvString_3</env-entry-name> <env-entry-type>java.lang.Integer</env-entry-type> <env-entry-value>123456789</env-entry-value> </env-entry>

After the quick fix is applied, the web.xml will be updated to contain:

<env-entry> <description>Trigger because of different value</description> <env-entry-name>contextEnvString_1</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>new Value</env-entry-value> </env-entry> <env-entry> <description>Trigger because of different type</description> <env-entry-name>contextEnvString_2</env-entry-name> <env-entry-type>java.lang.Integer</env-entry-type> <env-entry-value>123</env-entry-value> </env-entry> <env-entry> <description>will not Trigger because of override set to true.</description> <env-entry-name>contextEnvString_3</env-entry-name> <env-entry-type>java.lang.Integer</env-entry-type> <env-entry-value>123456789</env-entry-value> </env-entry> <env-entry> <description>Trigger becasue it does not exist</description> <env-entry-name>newEntry</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>abc123</env-entry-value> </env-entry>