public WebXml(Document theDocument) 
{
    
    // Constructors ------------------------------------------------------------
        this.document = theDocument;
        this.rootElement = theDocument.getDocumentElement();
}

Constructor.

Parameters:

theDocument - The DOM document representing the parsed deployment descriptor

 public final  void addContextParam(Element theContextParam) 
{
        checkElement(theContextParam, WebXmlTag.CONTEXT_PARAM);
        String paramName = 
            getNestedText(theContextParam, WebXmlTag.PARAM_NAME);
        if (paramName == null)
        {
            throw new IllegalArgumentException(
                "Not a valid context-param name element");
        }
        String paramValue = 
            getNestedText(theContextParam, WebXmlTag.PARAM_VALUE);
        if (paramValue == null)
        {
            throw new IllegalArgumentException(
                "Not a valid context-param value element");
        }
        if (hasContextParam(paramName))
        {
            throw new IllegalStateException("Context param '" + paramName
                + "' already defined");
        }
        addElement(WebXmlTag.CONTEXT_PARAM, theContextParam);
}

Adds a new context-param element to the descriptor.

 public final  void addElement(WebXmlTag theTag,
    Element theElement) 
{
        checkElement(theElement, theTag);
        if (!theTag.isMultipleAllowed() && getElements(theTag).hasNext())
        {
            throw new IllegalStateException("The tag '" + theTag
                + "' may not occur more than once in the descriptor");
        }
        Node importedNode = this.document.importNode(theElement, true);
        Node refNode = getInsertionPointFor(theTag);
        this.rootElement.insertBefore(importedNode, refNode);
}

Adds an element of the specified tag to the descriptor.

 public final  void addFilter(Element theFilter) 
{
        checkElement(theFilter, WebXmlTag.FILTER);
        String filterName = getNestedText(theFilter, WebXmlTag.FILTER_NAME);
        if (filterName == null)
        {
            throw new IllegalArgumentException("Not a valid filter element");
        }
        if (hasFilter(filterName))
        {
            throw new IllegalStateException("Filter '" + filterName
                + "' already defined");
        }
        addElement(WebXmlTag.FILTER, theFilter);
}

Adds a new servlet filter to the descriptor.

 public final  void addFilter(String theFilterName,
    String theFilterClass) 
{
        if (theFilterName == null)
        {
            throw new NullPointerException();
        }
        if (hasFilter(theFilterName))
        {
            throw new IllegalStateException("Filter '" + theFilterName
                + "' already defined");
        }
        Element filterElement =
            this.document.createElement(WebXmlTag.FILTER.getTagName());
        filterElement.appendChild(
            createNestedText(WebXmlTag.FILTER_NAME, theFilterName));
        filterElement.appendChild(
            createNestedText(WebXmlTag.FILTER_CLASS, theFilterClass));
        addElement(WebXmlTag.FILTER, filterElement);
}

Adds a new servlet filter to the descriptor.

 public final  void addFilterInitParam(String theFilterName,
    String theParamName,
    String theParamValue) 
{
        Element filterElement = getFilter(theFilterName);
        if (filterElement == null)
        {
            throw new IllegalStateException("Filter '" + theFilterName
                + "' not defined");
        }
        addInitParam(filterElement, theParamName, theParamValue);
}

Adds an initialization parameter to the specified filter.

 public final  void addFilterMapping(String theFilterName,
    String theUrlPattern) 
{
        if (!hasFilter(theFilterName))
        {
            throw new IllegalStateException("Filter '" + theFilterName
                + "' not defined");
        }
        Element filterMappingElement =
            this.document.createElement(WebXmlTag.FILTER_MAPPING.getTagName());
        filterMappingElement.appendChild(
            createNestedText(WebXmlTag.FILTER_NAME, theFilterName));
        filterMappingElement.appendChild(
            createNestedText(WebXmlTag.URL_PATTERN,  theUrlPattern));
        addElement(WebXmlTag.FILTER_MAPPING, filterMappingElement);
}

Adds a filter mapping to the descriptor.

 public final  void addJspFile(String theServletName,
    String theJspFile) 
{
        if (theServletName == null)
        {
            throw new NullPointerException();
        }
        if (hasFilter(theServletName))
        {
            throw new IllegalStateException("Servlet '" + theServletName
                + "' already defined");
        }
        Element servletElement =
            this.document.createElement(WebXmlTag.SERVLET.getTagName());
        servletElement.appendChild(
            createNestedText(WebXmlTag.SERVLET_NAME, theServletName));
        servletElement.appendChild(
            createNestedText(WebXmlTag.JSP_FILE, theJspFile));
        addElement(WebXmlTag.SERVLET, servletElement);
}

Adds a mapped JSP file to the descriptor.

 public final  void addSecurityConstraint(String theWebResourceName,
    String theUrlPattern,
    List theRoles) 
{
        if ((theWebResourceName == null) || (theUrlPattern == null)
         || (theRoles == null))
        {
            throw new NullPointerException();
        }
        if (hasSecurityConstraint(theUrlPattern))
        {
            throw new IllegalStateException("Security constraint for URL "
                + "pattern " + theUrlPattern + " already defined");
        }
        Element securityConstraintElement =
            this.document.createElement(
                WebXmlTag.SECURITY_CONSTRAINT.getTagName());
        Element webResourceCollectionElement =
            this.document.createElement(
                WebXmlTag.WEB_RESOURCE_COLLECTION.getTagName());
        webResourceCollectionElement.appendChild(
            createNestedText(WebXmlTag.WEB_RESOURCE_NAME, theWebResourceName));
        webResourceCollectionElement.appendChild(
            createNestedText(WebXmlTag.URL_PATTERN, theUrlPattern));
        securityConstraintElement.appendChild(webResourceCollectionElement);
        Element authConstraintElement =
            this.document.createElement(WebXmlTag.AUTH_CONSTRAINT.getTagName());
        for (Iterator i = theRoles.iterator(); i.hasNext();)
        {
            authConstraintElement.appendChild(
                createNestedText(WebXmlTag.ROLE_NAME, (String) i.next()));
        }
        securityConstraintElement.appendChild(authConstraintElement);
        addElement(WebXmlTag.SECURITY_CONSTRAINT, securityConstraintElement);
}

Creates and adds a security-constraint to the descriptor.

 public final  void addSecurityRole(String theRoleName) 
{
        if (theRoleName == null)
        {
            throw new NullPointerException();
        }
        if (hasSecurityRole(theRoleName))
        {
            throw new IllegalStateException("Security role '" + theRoleName
                + "' already defined");
        }
        Element securityRoleElement =
            this.document.createElement(WebXmlTag.SECURITY_ROLE.getTagName());
        securityRoleElement.appendChild(
            createNestedText(WebXmlTag.ROLE_NAME, theRoleName));
        addElement(WebXmlTag.SECURITY_ROLE, securityRoleElement);
}

Adds a new security role to the descriptor.

 public final  void addServlet(Element theServlet) 
{
        checkElement(theServlet, WebXmlTag.SERVLET);
        String servletName = getNestedText(theServlet, WebXmlTag.SERVLET_NAME);
        if (servletName == null)
        {
            throw new IllegalArgumentException("Not a valid servlet element");
        }
        if (hasServlet(servletName))
        {
            throw new IllegalStateException("Servlet '" + servletName
                + "' already defined");
        }
        addElement(WebXmlTag.SERVLET, theServlet);
}

Adds a new servlet to the descriptor.

 public final  void addServlet(String theServletName,
    String theServletClass) 
{
        if (theServletName == null)
        {
            throw new NullPointerException();
        }
        if (hasServlet(theServletName))
        {
            throw new IllegalStateException("Servlet '" + theServletName
                + "' already defined");
        }
        Element servletElement =
            this.document.createElement(WebXmlTag.SERVLET.getTagName());
        servletElement.appendChild(
            createNestedText(WebXmlTag.SERVLET_NAME, theServletName));
        servletElement.appendChild(
            createNestedText(WebXmlTag.SERVLET_CLASS, theServletClass));
        addElement(WebXmlTag.SERVLET, servletElement);
}

Adds a new servlet to the descriptor.

 public final  void addServletInitParam(String theServletName,
    String theParamName,
    String theParamValue) 
{
        Element servletElement = getServlet(theServletName);
        if (servletElement == null)
        {
            throw new IllegalStateException("Servlet '" + theServletName
                + "' not defined");
        }
        addInitParam(servletElement, theParamName, theParamValue);
}

Adds an initialization parameter to the specified servlet.

 public final  void addServletMapping(String theServletName,
    String theUrlPattern) 
{
        if (!hasServlet(theServletName))
        {
            throw new IllegalStateException("Servlet '" + theServletName
                + "' not defined");
        }
        Element servletMappingElement =
            this.document.createElement(WebXmlTag.SERVLET_MAPPING.getTagName());
        servletMappingElement.appendChild(
            createNestedText(WebXmlTag.SERVLET_NAME, theServletName));
        servletMappingElement.appendChild(
            createNestedText(WebXmlTag.URL_PATTERN, theUrlPattern));
        addElement(WebXmlTag.SERVLET_MAPPING, servletMappingElement);
}

Adds a servlet mapping to the descriptor.

 public final  void addServletRunAsRoleName(String theServletName,
    String theRoleName) 
{
        Element servlet = getServlet(theServletName);
        Element runAsElement =
            this.document.createElement(WebXmlTag.RUN_AS.getTagName());
        runAsElement.appendChild(createNestedText(WebXmlTag.ROLE_NAME, 
                                                  theRoleName));
        servlet.appendChild(runAsElement);
}

Adds a run-as declaration to the specified servlet.

 public final Element getContextParam(String theParamName) 
{
        if (theParamName == null)
        {
            throw new NullPointerException();
        }
        Iterator contextParamElements = getElements(WebXmlTag.CONTEXT_PARAM);
        while (contextParamElements.hasNext())
        {
            Element contextParamElement = (Element) contextParamElements.next();
            if (theParamName.equals(getNestedText(
                    contextParamElement, WebXmlTag.PARAM_NAME)))
            {
                return contextParamElement;
            }
        }
        return null;
}

Returns the element that contains the definition of a specific context param, or null if a context param of the specified name is not defined in the descriptor.

 public final String getContextParamName(Element theContextParam) 
{
        return getNestedText(theContextParam, WebXmlTag.PARAM_NAME);
}

 public final Document getDocument() 
{
        return this.document;
}

Returns the DOM document representing the deployment descriptor. The document will contain any modifications made through this instance.

 public final Iterator getElements(WebXmlTag theTag) 
{
        List elements = new ArrayList();
        NodeList nodeList =
            this.rootElement.getElementsByTagName(theTag.getTagName()); 
        for (int i = 0; i <  nodeList.getLength(); i++)
        {
            elements.add(nodeList.item(i));
        }
        return elements.iterator();
}

Returns an iterator over the elements that match the specified tag.

 public final Element getFilter(String theFilterName) 
{
        if (theFilterName == null)
        {
            throw new NullPointerException();
        }
        Iterator filterElements = getElements(WebXmlTag.FILTER);
        while (filterElements.hasNext())
        {
            Element filterElement = (Element) filterElements.next();
            if (theFilterName.equals(getNestedText(
                filterElement, WebXmlTag.FILTER_NAME)))
            {
                return filterElement;
            }
        }
        return null;
}

Returns the element that contains the definition of a specific servlet filter, or null if a filter of the specified name is not defined in the descriptor.

 public final String getFilterInitParam(String theFilterName,
    String theParamName) 
{
        return getInitParam(getFilter(theFilterName), theParamName);
}

Returns the value of an initialization parameter of the specified filter.

 public final Iterator getFilterInitParamNames(String theFilterName) 
{
        return getInitParamNames(getFilter(theFilterName));
}

Returns the names of the initialization parameters of the specified servlet filter.

 public final Iterator getFilterMappings(String theFilterName) 
{
        if (theFilterName == null)
        {
            throw new NullPointerException();
        }
        List filterMappings = new ArrayList();
        Iterator filterMappingElements = getElements(WebXmlTag.FILTER_MAPPING);
        while (filterMappingElements.hasNext())
        {
            Element filterMappingElement = (Element)
                filterMappingElements.next();
            if (theFilterName.equals(getNestedText(
                filterMappingElement, WebXmlTag.FILTER_NAME)))
            {
                String urlPattern = getNestedText(
                    filterMappingElement, WebXmlTag.URL_PATTERN);
                if (urlPattern != null)
                {
                    filterMappings.add(urlPattern);
                }
            }
        }
        return filterMappings.iterator();
}

Returns the URL-patterns that the specified filter is mapped to in an ordered list. If there are no mappings for the specified filter, an iterator over an empty list is returned.

 public final Iterator getFilterNames() 
{
        List filterNames = new ArrayList();
        Iterator filterElements = getElements(WebXmlTag.FILTER);
        while (filterElements.hasNext())
        {
            Element filterElement = (Element) filterElements.next();
            String filterName =
                getNestedText(filterElement, WebXmlTag.FILTER_NAME);
            if (filterName != null)
            {
                filterNames.add(filterName);
            }
        }
        return filterNames.iterator();
}

Returns the names of all filters defined in the deployment descriptor. The names are returned as an iterator over an ordered list.

 public final Iterator getFilterNamesForClass(String theClassName) 
{
        if (theClassName == null)
        {
            throw new NullPointerException();
        }
        Iterator filterElements = getElements(WebXmlTag.FILTER);
        List filterNames = new ArrayList();
        while (filterElements.hasNext())
        {
            Element filterElement = (Element) filterElements.next();
            if (theClassName.equals(getNestedText(
                filterElement, WebXmlTag.FILTER_CLASS)))
            {
                filterNames.add(getNestedText(
                    filterElement, WebXmlTag.FILTER_NAME));
            }
        }
        return filterNames.iterator();
}

Returns a list of names of filters that are mapped to the specified class.

 public final Element getLoginConfig() 
{
        Iterator loginConfigElements = getElements(WebXmlTag.LOGIN_CONFIG);
        if (loginConfigElements.hasNext())
        {
            return (Element) loginConfigElements.next();
        }
        return null;
}

Returns whether the descriptor has a login configuration.

 public final String getLoginConfigAuthMethod() 
{
        return getNestedText(getLoginConfig(), WebXmlTag.AUTH_METHOD);
}

Returns the authorization method defined by the login configuration.

 public final Element getSecurityConstraint(String theUrlPattern) 
{
        if (theUrlPattern == null)
        {
            throw new NullPointerException();
        }
        Iterator securityConstraintElements =
            getElements(WebXmlTag.SECURITY_CONSTRAINT);
        while (securityConstraintElements.hasNext())
        {
            Element securityConstraintElement = (Element)
                securityConstraintElements.next();
            Iterator webResourceCollectionElements = 
                getNestedElements(securityConstraintElement,
                    WebXmlTag.WEB_RESOURCE_COLLECTION);
            if (webResourceCollectionElements.hasNext())
            {
                Element webResourceCollectionElement = (Element)
                    webResourceCollectionElements.next();
                if (theUrlPattern.equals(getNestedText(
                    webResourceCollectionElement, WebXmlTag.URL_PATTERN)))
                {
                    return securityConstraintElement;
                }
            }
        }
        return null;
}

Returns the element that contains the security constraint defined for the specified URL pattern.

 public final Element getSecurityRole(String theRoleName) 
{
        if (theRoleName == null)
        {
            throw new NullPointerException();
        }
        Iterator securityRoleElements = getElements(WebXmlTag.SECURITY_ROLE);
        while (securityRoleElements.hasNext())
        {
            Element securityRoleElement = (Element) securityRoleElements.next();
            if (theRoleName.equals(getNestedText(
                securityRoleElement, WebXmlTag.ROLE_NAME)))
            {
                return securityRoleElement;
            }
        }
        return null;
}

Returns the element that contains the specified security role, or null if the role is not defined in the descriptor.

 public final Iterator getSecurityRoleNames() 
{
        List securityRoleNames = new ArrayList();
        Iterator securityRoleElements = getElements(WebXmlTag.SECURITY_ROLE);
        while (securityRoleElements.hasNext())
        {
            Element securityRoleElement = (Element) securityRoleElements.next();
            String securityRoleName =
                getNestedText(securityRoleElement, WebXmlTag.ROLE_NAME);
            if (securityRoleName != null)
            {
                securityRoleNames.add(securityRoleName);
            }
        }
        return securityRoleNames.iterator();
}

Returns a list of the security role names defined in the deployment descriptor

 public final Element getServlet(String theServletName) 
{
        if (theServletName == null)
        {
            throw new NullPointerException();
        }
        Iterator servletElements = getElements(WebXmlTag.SERVLET);
        while (servletElements.hasNext())
        {
            Element servletElement = (Element) servletElements.next();
            if (theServletName.equals(getNestedText(
                servletElement, WebXmlTag.SERVLET_NAME)))
            {
                return servletElement;
            }
        }
        return null;
}

Returns the element that contains the definition of a specific servlet, or null if a servlet of the specified name is not defined in the descriptor.

 public final String getServletInitParam(String theServletName,
    String theParamName) 
{
        return getInitParam(getServlet(theServletName), theParamName);
}

Returns the value of an initialization parameter of the specified servlet.

 public final Iterator getServletInitParamNames(String theServletName) 
{
        return getInitParamNames(getServlet(theServletName));
}

Returns the names of the initialization parameters of the specified servlet.

 public final Iterator getServletMappings(String theServletName) 
{
        if (theServletName == null)
        {
            throw new NullPointerException();
        }
        List servletMappings = new ArrayList();
        Iterator servletMappingElements =
            getElements(WebXmlTag.SERVLET_MAPPING);
        while (servletMappingElements.hasNext())
        {
            Element servletMappingElement = (Element)
                servletMappingElements.next();
            if (theServletName.equals(getNestedText(
                servletMappingElement, WebXmlTag.SERVLET_NAME)))
            {
                String urlPattern = getNestedText(
                    servletMappingElement, WebXmlTag.URL_PATTERN);
                if (urlPattern != null)
                {
                    servletMappings.add(urlPattern);
                }
            }
        }
        return servletMappings.iterator();
}

Returns the URL-patterns that the specified servlet is mapped to in an ordered list. If there are no mappings for the specified servlet, an iterator over an empty list is returned.

 public final Iterator getServletNames() 
{
        List servletNames = new ArrayList();
        Iterator servletElements = getElements(WebXmlTag.SERVLET);
        while (servletElements.hasNext())
        {
            Element servletElement = (Element) servletElements.next();
            String servletName =
                getNestedText(servletElement, WebXmlTag.SERVLET_NAME);
            if (servletName != null)
            {
                servletNames.add(servletName);
            }
        }
        return servletNames.iterator();
}

Returns the names of all servlets defined in the deployment descriptor. The names are returned as an iterator over an ordered list.

 public final Iterator getServletNamesForClass(String theClassName) 
{
        if (theClassName == null)
        {
            throw new NullPointerException();
        }
        Iterator servletElements = getElements(WebXmlTag.SERVLET);
        List servletNames = new ArrayList();
        while (servletElements.hasNext())
        {
            Element servletElement = (Element) servletElements.next();
            if (theClassName.equals(getNestedText(
                servletElement, WebXmlTag.SERVLET_CLASS)))
            {
                servletNames.add(getNestedText(
                    servletElement, WebXmlTag.SERVLET_NAME));
            }
        }
        return servletNames.iterator();
}

Returns a list of names of servlets that are mapped to the specified class.

 public final Iterator getServletNamesForJspFile(String theJspFile) 
{
        if (theJspFile == null)
        {
            throw new NullPointerException();
        }
        Iterator servletElements = getElements(WebXmlTag.SERVLET);
        List servletNames = new ArrayList();
        while (servletElements.hasNext())
        {
            Element servletElement = (Element) servletElements.next();
            if (theJspFile.equals(getNestedText(
                servletElement, WebXmlTag.JSP_FILE)))
            {
                servletNames.add(getNestedText(
                    servletElement, WebXmlTag.SERVLET_NAME));
            }
        }
        return servletNames.iterator();
}

Returns a list of names of servlets that are mapped to the specified JSP file.

 public final String getServletRunAsRoleName(String theServletName) 
{
        if (theServletName == null)
        {
            throw new NullPointerException();
        }
        String roleName = null;
        Element servlet = getServlet(theServletName);
        NodeList nodeList = 
            servlet.getElementsByTagName(WebXmlTag.RUN_AS.getTagName());
        if (nodeList != null)
        {
            Element e = (Element) nodeList.item(0);
            if (e != null)
            {
                roleName = getNestedText(e, WebXmlTag.ROLE_NAME);
            }
        }
        return roleName;
}

Returns the role name that the servlet is running as.

 public final WebXmlVersion getVersion() 
{
        DocumentType docType = this.document.getDoctype();
        if (docType != null)
        {
            return WebXmlVersion.valueOf(docType);
        }
        return null;
}

Returns the servlet API version.

 public final boolean hasContextParam(String theParamName) 
{
        return (getContextParam(theParamName) != null);
}

Returns whether a context param by the specified name is defined in the deployment descriptor.

 public final boolean hasFilter(String theFilterName) 
{
        return (getFilter(theFilterName) != null);
}

Returns whether a servlet filter by the specified name is defined in the deployment descriptor.

 public final boolean hasLoginConfig() 
{
        return (getLoginConfig() != null);
}

Returns whether the descriptor has a login configuration.

 public final boolean hasSecurityConstraint(String theUrlPattern) 
{
        return (getSecurityConstraint(theUrlPattern) != null);
}

Returns whether a security constraint has been mapped to the specified URL pattern.

 public final boolean hasSecurityRole(String theRoleName) 
{
        return (getSecurityRole(theRoleName) != null);
}

Returns whether a specific security role has been defined.

 public final boolean hasServlet(String theServletName) 
{
        return (getServlet(theServletName) != null);
}

Returns whether a servlet by the specified name is defined in the deployment descriptor.

 public final  void replaceElement(WebXmlTag theTag,
    Element theElement) 
{
        Iterator elements = getElements(theTag);
        while (elements.hasNext())
        {
            Element element = (Element) elements.next();
            element.getParentNode().removeChild(element);
        }
        addElement(theTag, theElement);
}

Replaces all elements of the specified tag with the provided element.

 public final  void setLoginConfig(String theAuthMethod,
    String theRealmName) 
{
        if ((theRealmName == null) || (theAuthMethod == null))
        {
            throw new NullPointerException();
        }
        Element loginConfigElement =
            document.createElement(WebXmlTag.LOGIN_CONFIG.getTagName());
        loginConfigElement.appendChild(
            createNestedText(WebXmlTag.AUTH_METHOD, theAuthMethod));
        loginConfigElement.appendChild(
            createNestedText(WebXmlTag.REALM_NAME, theRealmName));
        replaceElement(WebXmlTag.LOGIN_CONFIG, loginConfigElement);
}

Sets the login configuration.