Resources

• Products & Solutions
• System Requirements
• Samples
• Install Center
• Third-Party Software Reference
• Documentation
  • What's New in SAS
  • Product Index A-Z
  • SAS Viya
  • SAS 9.4
  • SAS 9.3 and Earlier
• Papers
• Focus Areas

SAS^® AppDev Studio^™ 3.0 Developer's Site

Troubleshooting web.xml Errors

Though not required by the Servlet 2.3 specifications, some application servers and servlet containers validate the Web application's web.xml during startup of the Web application. Errors can cause the Web application to fail to start. Thus, it is good practice to validate the web.xml prior to deployment.

Validation of the web.xml is included as part of webAF's package-war task, and is required to succeed before the WAR file will be created. Validation of the web.xml is also available as a separate task, executed by Build Project Tasks validate-webxml. Note that the success or failure of these tasks is not indicated by the "0 Errors, 0 Warnings" line that appears at the bottom of the Compile output window. Instead, their success or failure is indicated by whether "BUILD SUCCESSFUL" or "BUILD FAILED" appears on a line above it.

Common web.xml errors

If BUILD FAILED appears, the error or warning detected during validation is show above this line. For XML syntax errors, such as an incorrectly spelled or unmatched element tag, the error message will include a line number that should help you locate the error. An error message is also shown if the web.xml fails to meet the requirements of the DTD. In this case, no line number within the web.xml is given, which makes finding the error more of a challenge.

Incorrect element order or misspelled element

The Web Application DTD requires the various elements to appear in a specific order. If they are out of order, an error message like the following is shown:

    Element "parent" does not allow "child" here.

where parent and child are the tag names of the elements involved. If you enter valid XML, but give an incorrect tag name, you will likely see the error message above, plus a line like the following:

    Element type "child" is not declared.

In either case, you will need to search for the offending element in the web.xml and fix its location or name. Consult the Web Application DTD if you are unsure about the proper order.

Missing required element

If a parent element is missing a required child element, you will see an error message like the following:

    Element "parent" requires additional elements.

Unfortunately, the message doesn't identify which child element is missing. If the element is missing due to a spelling error, you should also see the "Element type ... not declared" message, mentioned previously. If you can't tell which child element is missing, consult the Web Application DTD to determine which child elements are required by the indicated parent element.

Missing DOCTYPE Declaration

Finally, if the web.xml is missing a DOCTYPE declaration, an error message like the following is shown:

    Valid documents must have a <!DOCTYPE declaration.
    Element type "web-app" is not declared.
    Additional "Element type not declared" errors.

If the Web application was written for the Servlet 2.2 specifications, add the following declaration to the web.xml, just above the <web-app> element.

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

If the Web application was written for the Servlet 2.3 specifications, or you aren't sure, add the following declaration to the web.xml instead.

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/dtd/web-app_2_3.dtd">

Interpreting the Web Application DTD

To determine which child elements are required and what the element order should be, refer the to Web Application DTD, version 2.3. It can be found in the Servlet 2.3 specifications. A copy of the specifications can be obtained from the Java Community Process under JSR-53: Java Servlet 2.3 and JavaServer Pages 1.2 Specifications.

For the parent element relevant to the problem, try to find a declaration like the following:

    <!ELEMENT parent (child1, child2, ...)>

The required order for child elements is the order shown in the declaration. This declaration indicates all <child1> elements must appear before any <child2> elements within the <parent> element.

The requirements with respect to the quantity of each child element is indicated by the presence, or absence, of a postfix character on the specified tag name. The following table shows the meaning of the postfix characters you might encounter in the Web Application DTD.

Postfix Character	Description
absent	Exactly one is required
+	One is required, but more than one is allowed
?	Zero or one is allowed
*	Zero or more are allowed

For example, you will find the following declaration for the <filter> element.

    <!ELEMENT filter (icon?, filter-name, display-name?, description?,
                      filter-class, init-param*)>

This declares that an <icon> element must come before the <filter-name> element, which must come before a <display-name> element, etc. It also indicates that <filter-name> and <filter-class> elements are required child elements. The <icon>, <display-name>, and <description> elements are optional. Finally, <init-param> elements are also optional, but you can have as many as necessary.

Note that validating the web.xml only ensures that it does not have any XML syntax errors and meets the requirements of the DTD. It does not imply that the web.xml is without errors. For example, an error in a class name would not be detected by validation. This kind of error will make itself apparent only at runtime. Hopefully testing prior to deployment will ensure errors like this are not present.