Java > Open Source Codes > org > apache > cactus > integration > ant > deployment > webapp > WebXml


1 /*
2  * ========================================================================
3  *
4  * Copyright 2003-2004 The Apache Software Foundation.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  *
18  * ========================================================================
19  */
20 package org.apache.cactus.integration.ant.deployment.webapp;
21
22 import java.util.ArrayList ;
23 import java.util.Iterator ;
24 import java.util.List ;
25
26 import org.w3c.dom.Document ;
27 import org.w3c.dom.DocumentType ;
28 import org.w3c.dom.Element ;
29 import org.w3c.dom.Node ;
30 import org.w3c.dom.NodeList ;
31
32 /**
33  * Encapsulates the DOM representation of a web deployment descriptor
34  * <code>web.xml</code> to provide convenience methods for easy access and
35  * manipulation.
36  *
37  * @since Cactus 1.5
38  * @version $Id: WebXml.java,v 1.1 2004/05/31 20:05:23 vmassol Exp $
39  */
40 public class WebXml
41 {
42     
43     // Private Constants -------------------------------------------------------
44
45     /**
46      * Specifies the order in which the top-level elements must appear in the
47      * descriptor, according to the DTD.
48      */
49     private static final WebXmlTag[] ELEMENT_ORDER = {
50         WebXmlTag.ICON,
51         WebXmlTag.DISPLAY_NAME,
52         WebXmlTag.DESCRIPTION,
53         WebXmlTag.DISTRIBUTABLE,
54         WebXmlTag.FILTER,
55         WebXmlTag.FILTER_MAPPING,
56         WebXmlTag.LISTENER,
57         WebXmlTag.SERVLET,
58         WebXmlTag.SERVLET_MAPPING,
59         WebXmlTag.SESSION_CONFIG,
60         WebXmlTag.MIME_MAPPING,
61         WebXmlTag.WELCOME_FILE_LIST,
62         WebXmlTag.ERROR_PAGE,
63         WebXmlTag.TAGLIB,
64         WebXmlTag.RESOURCE_ENV_REF,
65         WebXmlTag.RESOURCE_REF,
66         WebXmlTag.SECURITY_CONSTRAINT,
67         WebXmlTag.LOGIN_CONFIG,
68         WebXmlTag.SECURITY_ROLE,
69         WebXmlTag.ENV_ENTRY,
70         WebXmlTag.EJB_REF,
71         WebXmlTag.EJB_LOCAL_REF,
72     };
73     
74     // Instance Variables ------------------------------------------------------
75
76     /**
77      * The DOM representation of the deployment descriptor.
78      */
79     private final Document document;
80     
81     /**
82      * The root element of the descriptor.
83      */
84     private final Element rootElement;
85     
86     // Constructors ------------------------------------------------------------
87
88     /**
89      * Constructor.
90      *
91      * @param theDocument The DOM document representing the parsed deployment
92      * descriptor
93      */
94     public WebXml(Document theDocument)
95     {
96         this.document = theDocument;
97         this.rootElement = theDocument.getDocumentElement();
98     }
99     
100     // Public Methods ----------------------------------------------------------
101
102     /**
103      * Returns the DOM document representing the deployment descriptor. The
104      * document will contain any modifications made through this instance.
105      *
106      * @return The document representing the deploy descriptor
107      */
108     public final Document getDocument()
109     {
110         return this.document;
111     }
112     
113     /**
114      * Returns the servlet API version.
115      *
116      * @return The version
117      */
118     public final WebXmlVersion getVersion()
119     {
120         DocumentType docType = this.document.getDoctype();
121         if (docType != null)
122         {
123             return WebXmlVersion.valueOf(docType);
124         }
125         return null;
126     }
127
128     /**
129      * Adds a new servlet filter to the descriptor.
130      *
131      * @param theFilterName The name of the filter to add
132      * @param theFilterClass The name of the class implementing the filter
133      */
134     public final void addFilter(String theFilterName, String theFilterClass)
135     {
136         if (theFilterName == null)
137         {
138             throw new NullPointerException ();
139         }
140         if (hasFilter(theFilterName))
141         {
142             throw new IllegalStateException ("Filter '" + theFilterName
143                 + "' already defined");
144         }
145         Element filterElement =
146             this.document.createElement(WebXmlTag.FILTER.getTagName());
147         filterElement.appendChild(
148             createNestedText(WebXmlTag.FILTER_NAME, theFilterName));
149         filterElement.appendChild(
150             createNestedText(WebXmlTag.FILTER_CLASS, theFilterClass));
151         addElement(WebXmlTag.FILTER, filterElement);
152     }
153
154     /**
155      * Adds a new context-param element to the descriptor.
156      *
157      * @param theContextParam The element representing the context-param
158      * definition
159      */
160     public final void addContextParam(Element theContextParam)
161     {
162         checkElement(theContextParam, WebXmlTag.CONTEXT_PARAM);
163
164         String paramName =
165             getNestedText(theContextParam, WebXmlTag.PARAM_NAME);
166         if (paramName == null)
167         {
168             throw new IllegalArgumentException (
169                 "Not a valid context-param name element");
170         }
171
172         String paramValue =
173             getNestedText(theContextParam, WebXmlTag.PARAM_VALUE);
174         if (paramValue == null)
175         {
176             throw new IllegalArgumentException (
177                 "Not a valid context-param value element");
178         }
179
180         if (hasContextParam(paramName))
181         {
182             throw new IllegalStateException ("Context param '" + paramName
183                 + "' already defined");
184         }
185         addElement(WebXmlTag.CONTEXT_PARAM, theContextParam);
186     }
187     
188     /**
189      * Adds a new servlet filter to the descriptor.
190      *
191      * @param theFilter The element representing the filter definition
192      */
193     public final void addFilter(Element theFilter)
194     {
195         checkElement(theFilter, WebXmlTag.FILTER);
196         String filterName = getNestedText(theFilter, WebXmlTag.FILTER_NAME);
197         if (filterName == null)
198         {
199             throw new IllegalArgumentException ("Not a valid filter element");
200         }
201         if (hasFilter(filterName))
202         {
203             throw new IllegalStateException ("Filter '" + filterName
204                 + "' already defined");
205         }
206         addElement(WebXmlTag.FILTER, theFilter);
207     }
208     
209     /**
210      * Adds an initialization parameter to the specified filter.
211      *
212      * @param theFilterName The name of the filter
213      * @param theParamName The name of the parameter
214      * @param theParamValue The parameter value
215      */
216     public final void addFilterInitParam(String theFilterName,
217         String theParamName, String theParamValue)
218     {
219         Element filterElement = getFilter(theFilterName);
220         if (filterElement == null)
221         {
222             throw new IllegalStateException ("Filter '" + theFilterName
223                 + "' not defined");
224         }
225         addInitParam(filterElement, theParamName, theParamValue);
226     }
227     
228     /**
229      * Adds a filter mapping to the descriptor.
230      *
231      * @param theFilterName The name of the filter
232      * @param theUrlPattern The URL pattern the filter should be mapped to
233      */
234     public final void addFilterMapping(String theFilterName,
235         String theUrlPattern)
236     {
237         if (!hasFilter(theFilterName))
238         {
239             throw new IllegalStateException ("Filter '" + theFilterName
240                 + "' not defined");
241         }
242         Element filterMappingElement =
243             this.document.createElement(WebXmlTag.FILTER_MAPPING.getTagName());
244         filterMappingElement.appendChild(
245             createNestedText(WebXmlTag.FILTER_NAME, theFilterName));
246         filterMappingElement.appendChild(
247             createNestedText(WebXmlTag.URL_PATTERN, theUrlPattern));
248         addElement(WebXmlTag.FILTER_MAPPING, filterMappingElement);
249     }
250     
251     /**
252      * Returns the element that contains the definition of a specific servlet
253      * filter, or <code>null</code> if a filter of the specified name is not
254      * defined in the descriptor.
255      *
256      * @param theFilterName The name of the servlet filter
257      * @return The DOM element representing the filter definition
258      */
259     public final Element getFilter(String theFilterName)
260     {
261         if (theFilterName == null)
262         {
263             throw new NullPointerException ();
264         }
265         Iterator filterElements = getElements(WebXmlTag.FILTER);
266         while (filterElements.hasNext())
267         {
268             Element filterElement = (Element ) filterElements.next();
269             if (theFilterName.equals(getNestedText(
270                 filterElement, WebXmlTag.FILTER_NAME)))
271             {
272                 return filterElement;
273             }
274         }
275         return null;
276     }
277
278     /**
279      * Returns the element that contains the definition of a specific context
280      * param, or <code>null</code> if a context param of the specified name
281      * is not defined in the descriptor.
282      *
283      * @param theParamName The context param name
284      * @return The DOM element representing the context param definition
285      */
286     public final Element getContextParam(String theParamName)
287     {
288         if (theParamName == null)
289         {
290             throw new NullPointerException ();
291         }
292         Iterator contextParamElements = getElements(WebXmlTag.CONTEXT_PARAM);
293         while (contextParamElements.hasNext())
294         {
295             Element contextParamElement = (Element ) contextParamElements.next();
296             if (theParamName.equals(getNestedText(
297                     contextParamElement, WebXmlTag.PARAM_NAME)))
298             {
299                 return contextParamElement;
300             }
301         }
302         return null;
303     }
304
305     /**
306      * @param theContextParam the context param element from which to extract
307      * the name
308      * @return the name of the passed context param element
309      */
310     public final String getContextParamName(Element theContextParam)
311     {
312         return getNestedText(theContextParam, WebXmlTag.PARAM_NAME);
313     }
314     
315     /**
316      * Returns a list of names of filters that are mapped to the specified
317      * class.
318      *
319      * @param theClassName The fully qualified name of the filter class
320      * @return An iterator over the names of the filters mapped to the class
321      */
322     public final Iterator getFilterNamesForClass(String theClassName)
323     {
324         if (theClassName == null)
325         {
326             throw new NullPointerException ();
327         }
328         Iterator filterElements = getElements(WebXmlTag.FILTER);
329         List filterNames = new ArrayList ();
330         while (filterElements.hasNext())
331         {
332             Element filterElement = (Element ) filterElements.next();
333             if (theClassName.equals(getNestedText(
334                 filterElement, WebXmlTag.FILTER_CLASS)))
335             {
336                 filterNames.add(getNestedText(
337                     filterElement, WebXmlTag.FILTER_NAME));
338             }
339         }
340         return filterNames.iterator();
341     }
342     
343     /**
344      * Returns the value of an initialization parameter of the specified filter.
345      *
346      * @param theFilterName The name of the servlet filter
347      * @param theParamName The name of the initialization parameter
348      * @return The parameter value
349      */
350     public final String getFilterInitParam(String theFilterName,
351         String theParamName)
352     {
353         return getInitParam(getFilter(theFilterName), theParamName);
354     }
355     
356     /**
357      * Returns the names of the initialization parameters of the specified
358      * servlet filter.
359      *
360      * @param theFilterName The name of the servlet filter of which the
361      * parameter names should be retrieved
362      * @return An iterator over the ordered list of parameter names
363      */
364     public final Iterator getFilterInitParamNames(String theFilterName)
365     {
366         return getInitParamNames(getFilter(theFilterName));
367     }
368     
369     /**
370      * Returns the URL-patterns that the specified filter is mapped to in an
371      * ordered list. If there are no mappings for the specified filter, an
372      * iterator over an empty list is returned.
373      *
374      * @param theFilterName The name of the servlet filter of which the
375      * mappings should be retrieved
376      * @return An iterator over the ordered list of URL-patterns
377      */
378     public final Iterator getFilterMappings(String theFilterName)
379     {
380         if (theFilterName == null)
381         {
382             throw new NullPointerException ();
383         }
384         List filterMappings = new ArrayList ();
385         Iterator filterMappingElements = getElements(WebXmlTag.FILTER_MAPPING);
386         while (filterMappingElements.hasNext())
387         {
388             Element filterMappingElement = (Element )
389                 filterMappingElements.next();
390             if (theFilterName.equals(getNestedText(
391                 filterMappingElement, WebXmlTag.FILTER_NAME)))
392             {
393                 String urlPattern = getNestedText(
394                     filterMappingElement, WebXmlTag.URL_PATTERN);
395                 if (urlPattern != null)
396                 {
397                     filterMappings.add(urlPattern);
398                 }
399             }
400         }
401         return filterMappings.iterator();
402     }
403     
404     /**
405      * Returns the names of all filters defined in the deployment descriptor.
406      * The names are returned as an iterator over an ordered list.
407      *
408      * @return The filter names
409      */
410     public final Iterator getFilterNames()
411     {
412         List filterNames = new ArrayList ();
413         Iterator filterElements = getElements(WebXmlTag.FILTER);
414         while (filterElements.hasNext())
415         {
416             Element filterElement = (Element ) filterElements.next();
417             String filterName =
418                 getNestedText(filterElement, WebXmlTag.FILTER_NAME);
419             if (filterName != null)
420             {
421                 filterNames.add(filterName);
422             }
423         }
424         return filterNames.iterator();
425     }
426
427     /**
428      * Returns whether a context param by the specified name is defined in the
429      * deployment descriptor.
430      *
431      * @param theParamName The name of the context param
432      * @return <code>true</code> if the context param is defined,
433      * <code>false</code> otherwise
434      */
435     public final boolean hasContextParam(String theParamName)
436     {
437         return (getContextParam(theParamName) != null);
438     }
439     
440     /**
441      * Returns whether a servlet filter by the specified name is defined in the
442      * deployment descriptor.
443      *
444      * @param theFilterName The name of the filter
445      * @return <code>true</code> if the filter is defined, <code>false</code>
446      * otherwise
447      */
448     public final boolean hasFilter(String theFilterName)
449     {
450         return (getFilter(theFilterName) != null);
451     }
452     
453     /**
454      * Adds a mapped JSP file to the descriptor.
455      *
456      * @param theServletName The name of the servlet to add
457      * @param theJspFile The path to the JSP file relative to the root of the
458      * web application
459      */
460     public final void addJspFile(String theServletName, String theJspFile)
461     {
462         if (theServletName == null)
463         {
464             throw new NullPointerException ();
465         }
466         if (hasFilter(theServletName))
467         {
468             throw new IllegalStateException ("Servlet '" + theServletName
469                 + "' already defined");
470         }
471         Element servletElement =
472             this.document.createElement(WebXmlTag.SERVLET.getTagName());
473         servletElement.appendChild(
474             createNestedText(WebXmlTag.SERVLET_NAME, theServletName));
475         servletElement.appendChild(
476             createNestedText(WebXmlTag.JSP_FILE, theJspFile));
477         addElement(WebXmlTag.SERVLET, servletElement);
478     }
479     
480     /**
481      * Adds a new servlet to the descriptor.
482      *
483      * @param theServletName The name of the servlet to add
484      * @param theServletClass The name of the class implementing the servlet
485      */
486     public final void addServlet(String theServletName, String theServletClass)
487     {
488         if (theServletName == null)
489         {
490             throw new NullPointerException ();
491         }
492         if (hasServlet(theServletName))
493         {
494             throw new IllegalStateException ("Servlet '" + theServletName
495                 + "' already defined");
496         }
497         Element servletElement =
498             this.document.createElement(WebXmlTag.SERVLET.getTagName());
499         servletElement.appendChild(
500             createNestedText(WebXmlTag.SERVLET_NAME, theServletName));
501         servletElement.appendChild(
502             createNestedText(WebXmlTag.SERVLET_CLASS, theServletClass));
503         addElement(WebXmlTag.SERVLET, servletElement);
504     }
505     
506     /**
507      * Adds a new servlet to the descriptor.
508      *
509      * @param theServlet The element representing the servlet definition
510      */
511     public final void addServlet(Element theServlet)
512     {
513         checkElement(theServlet, WebXmlTag.SERVLET);
514         String servletName = getNestedText(theServlet, WebXmlTag.SERVLET_NAME);
515         if (servletName == null)
516         {
517             throw new IllegalArgumentException ("Not a valid servlet element");
518         }
519         if (hasServlet(servletName))
520         {
521             throw new IllegalStateException ("Servlet '" + servletName
522                 + "' already defined");
523         }
524         addElement(WebXmlTag.SERVLET, theServlet);
525     }
526     
527     /**
528      * Adds an initialization parameter to the specified servlet.
529      *
530      * @param theServletName The name of the filter
531      * @param theParamName The name of the parameter
532      * @param theParamValue The parameter value
533      */
534     public final void addServletInitParam(String theServletName,
535         String theParamName, String theParamValue)
536     {
537         Element servletElement = getServlet(theServletName);
538         if (servletElement == null)
539         {
540             throw new IllegalStateException ("Servlet '" + theServletName
541                 + "' not defined");
542         }
543         addInitParam(servletElement, theParamName, theParamValue);
544     }
545     
546     /**
547      * Adds a servlet mapping to the descriptor.
548      *
549      * @param theServletName The name of the servlet
550      * @param theUrlPattern The URL pattern the servlet should be mapped to
551      */
552     public final void addServletMapping(String theServletName,
553         String theUrlPattern)
554     {
555         if (!hasServlet(theServletName))
556         {
557             throw new IllegalStateException ("Servlet '" + theServletName
558                 + "' not defined");
559         }
560         Element servletMappingElement =
561             this.document.createElement(WebXmlTag.SERVLET_MAPPING.getTagName());
562         servletMappingElement.appendChild(
563             createNestedText(WebXmlTag.SERVLET_NAME, theServletName));
564         servletMappingElement.appendChild(
565             createNestedText(WebXmlTag.URL_PATTERN, theUrlPattern));
566         addElement(WebXmlTag.SERVLET_MAPPING, servletMappingElement);
567     }
568     
569     /**
570      * Returns the element that contains the definition of a specific servlet,
571      * or <code>null</code> if a servlet of the specified name is not defined
572      * in the descriptor.
573      *
574      * @param theServletName The name of the servlet
575      * @return The DOM element representing the servlet definition
576      */
577     public final Element getServlet(String theServletName)
578     {
579         if (theServletName == null)
580         {
581             throw new NullPointerException ();
582         }
583         Iterator servletElements = getElements(WebXmlTag.SERVLET);
584         while (servletElements.hasNext())
585         {
586             Element servletElement = (Element ) servletElements.next();
587             if (theServletName.equals(getNestedText(
588                 servletElement, WebXmlTag.SERVLET_NAME)))
589             {
590                 return servletElement;
591             }
592         }
593         return null;
594     }
595     
596     /**
597      * Returns the value of an initialization parameter of the specified
598      * servlet.
599      *
600      * @param theServletName The name of the servlet
601      * @param theParamName The name of the initialization parameter
602      * @return The parameter value
603      */
604     public final String getServletInitParam(String theServletName,
605         String theParamName)
606     {
607         return getInitParam(getServlet(theServletName), theParamName);
608     }
609     
610     /**
611      * Returns the names of the initialization parameters of the specified
612      * servlet.
613      *
614      * @param theServletName The name of the servlet of which the parameter
615      * names should be retrieved
616      * @return An iterator over the ordered list of parameter names
617      */
618     public final Iterator getServletInitParamNames(String theServletName)
619     {
620         return getInitParamNames(getServlet(theServletName));
621     }
622     
623     /**
624      * Returns the URL-patterns that the specified servlet is mapped to in an
625      * ordered list. If there are no mappings for the specified servlet, an
626      * iterator over an empty list is returned.
627      *
628      * @param theServletName The name of the servlet of which the mappings
629      * should be retrieved
630      * @return An iterator over the ordered list of URL-patterns
631      */
632     public final Iterator getServletMappings(String theServletName)
633     {
634         if (theServletName == null)
635         {
636             throw new NullPointerException ();
637         }
638         List servletMappings = new ArrayList ();
639         Iterator servletMappingElements =
640             getElements(WebXmlTag.SERVLET_MAPPING);
641         while (servletMappingElements.hasNext())
642         {
643             Element servletMappingElement = (Element )
644                 servletMappingElements.next();
645             if (theServletName.equals(getNestedText(
646                 servletMappingElement, WebXmlTag.SERVLET_NAME)))
647             {
648                 String urlPattern = getNestedText(
649                     servletMappingElement, WebXmlTag.URL_PATTERN);
650                 if (urlPattern != null)
651                 {
652                     servletMappings.add(urlPattern);
653                 }
654             }
655         }
656         return servletMappings.iterator();
657     }
658     
659     /**
660      * Returns the names of all servlets defined in the deployment descriptor.
661      * The names are returned as an iterator over an ordered list.
662      *
663      * @return The servlet names
664      */
665     public final Iterator getServletNames()
666     {
667         List servletNames = new ArrayList ();
668         Iterator servletElements = getElements(WebXmlTag.SERVLET);
669         while (servletElements.hasNext())
670         {
671             Element servletElement = (Element ) servletElements.next();
672             String servletName =
673                 getNestedText(servletElement, WebXmlTag.SERVLET_NAME);
674             if (servletName != null)
675             {
676                 servletNames.add(servletName);
677             }
678         }
679         return servletNames.iterator();
680     }
681     
682     /**
683      * Returns a list of names of servlets that are mapped to the specified
684      * class.
685      *
686      * @param theClassName The fully qualified name of the servlet class
687      * @return An iterator over the names of the servlets mapped to the class
688      */
689     public final Iterator getServletNamesForClass(String theClassName)
690     {
691         if (theClassName == null)
692         {
693             throw new NullPointerException ();
694         }
695         Iterator servletElements = getElements(WebXmlTag.SERVLET);
696         List servletNames = new ArrayList ();
697         while (servletElements.hasNext())
698         {
699             Element servletElement = (Element ) servletElements.next();
700             if (theClassName.equals(getNestedText(
701                 servletElement, WebXmlTag.SERVLET_CLASS)))
702             {
703                 servletNames.add(getNestedText(
704                     servletElement, WebXmlTag.SERVLET_NAME));
705             }
706         }
707         return servletNames.iterator();
708     }
709     
710     /**
711      * Returns a list of names of servlets that are mapped to the specified
712      * JSP file.
713      *
714      * @param theJspFile The path to the JSP file, relative to the root of the
715      * web-application
716      * @return An iterator over the names of the servlets mapped to the JSP file
717      */
718     public final Iterator getServletNamesForJspFile(String theJspFile)
719     {
720         if (theJspFile == null)
721         {
722             throw new NullPointerException ();
723         }
724         Iterator servletElements = getElements(WebXmlTag.SERVLET);
725         List servletNames = new ArrayList ();
726         while (servletElements.hasNext())
727         {
728             Element servletElement = (Element ) servletElements.next();
729             if (theJspFile.equals(getNestedText(
730                 servletElement, WebXmlTag.JSP_FILE)))
731             {
732                 servletNames.add(getNestedText(
733                     servletElement, WebXmlTag.SERVLET_NAME));
734             }
735         }
736         return servletNames.iterator();
737     }
738     
739     /**
740      * Returns whether a servlet by the specified name is defined in the
741      * deployment descriptor.
742      *
743      * @param theServletName The name of the servlet
744      * @return <code>true</code> if the servlet is defined, <code>false</code>
745      * otherwise
746      */
747     public final boolean hasServlet(String theServletName)
748     {
749         return (getServlet(theServletName) != null);
750     }
751     
752     /**
753      * Creates and adds a security-constraint to the descriptor.
754      *
755      * @param theWebResourceName The name of the web resource collection to
756      * protect
757      * @param theUrlPattern The URL pattern to apply the constraint to
758      * @param theRoles The list of authorized roles
759      */
760     public final void addSecurityConstraint(String theWebResourceName,
761         String theUrlPattern, List theRoles)
762     {
763         if ((theWebResourceName == null) || (theUrlPattern == null)
764          || (theRoles == null))
765         {
766             throw new NullPointerException ();
767         }
768         if (hasSecurityConstraint(theUrlPattern))
769         {
770             throw new IllegalStateException ("Security constraint for URL "
771                 + "pattern " + theUrlPattern + " already defined");
772         }
773         Element securityConstraintElement =
774             this.document.createElement(
775                 WebXmlTag.SECURITY_CONSTRAINT.getTagName());
776         Element webResourceCollectionElement =
777             this.document.createElement(
778                 WebXmlTag.WEB_RESOURCE_COLLECTION.getTagName());
779         webResourceCollectionElement.appendChild(
780             createNestedText(WebXmlTag.WEB_RESOURCE_NAME, theWebResourceName));
781         webResourceCollectionElement.appendChild(
782             createNestedText(WebXmlTag.URL_PATTERN, theUrlPattern));
783         securityConstraintElement.appendChild(webResourceCollectionElement);
784         Element authConstraintElement =
785             this.document.createElement(WebXmlTag.AUTH_CONSTRAINT.getTagName());
786         for (Iterator i = theRoles.iterator(); i.hasNext();)
787         {
788             authConstraintElement.appendChild(
789                 createNestedText(WebXmlTag.ROLE_NAME, (String ) i.next()));
790         }
791         securityConstraintElement.appendChild(authConstraintElement);
792         addElement(WebXmlTag.SECURITY_CONSTRAINT, securityConstraintElement);
793     }
794
795     /**
796      * Returns the element that contains the security constraint defined for the
797      * specified URL pattern.
798      *
799      * @param theUrlPattern The URL pattern
800      * @return The DOM element representing the security constraint
801      */
802     public final Element getSecurityConstraint(String theUrlPattern)
803     {
804         if (theUrlPattern == null)
805         {
806             throw new NullPointerException ();
807         }
808         Iterator securityConstraintElements =
809             getElements(WebXmlTag.SECURITY_CONSTRAINT);
810         while (securityConstraintElements.hasNext())
811         {
812             Element securityConstraintElement = (Element )
813                 securityConstraintElements.next();
814             Iterator webResourceCollectionElements =
815                 getNestedElements(securityConstraintElement,
816                     WebXmlTag.WEB_RESOURCE_COLLECTION);
817             if (webResourceCollectionElements.hasNext())
818             {
819                 Element webResourceCollectionElement = (Element )
820                     webResourceCollectionElements.next();
821                 if (theUrlPattern.equals(getNestedText(
822                     webResourceCollectionElement, WebXmlTag.URL_PATTERN)))
823                 {
824                     return securityConstraintElement;
825                 }
826             }
827         }
828         return null;
829     }
830     
831     /**
832      * Returns whether a security constraint has been mapped to the specified
833      * URL pattern.
834      *
835      * @param theUrlPattern The URL patterm
836      * @return <code>true</code> if a security constraint is defined,
837      * <code>false</code> otherwise
838      */
839     public final boolean hasSecurityConstraint(String theUrlPattern)
840     {
841         return (getSecurityConstraint(theUrlPattern) != null);
842     }
843     
844     /**
845      * Returns whether the descriptor has a login configuration.
846      *
847      * @return <code>true</code> if a login config is defined,
848      * <code>false</code> otherwise
849      */
850     public final boolean hasLoginConfig()
851     {
852         return (getLoginConfig() != null);
853     }
854
855     /**
856      * Returns whether the descriptor has a login configuration.
857      *
858      * @return <code>true</code> if a login config is defined,
859      * <code>false</code> otherwise
860      */
861     public final Element getLoginConfig()
862     {
863         Iterator loginConfigElements = getElements(WebXmlTag.LOGIN_CONFIG);
864         if (loginConfigElements.hasNext())
865         {
866             return (Element ) loginConfigElements.next();
867         }
868         return null;
869     }
870
871     /**
872      * Returns the authorization method defined by the login configuration.
873      *
874      * @return The authorization method
875      */
876     public final String getLoginConfigAuthMethod()
877     {
878         return getNestedText(getLoginConfig(), WebXmlTag.AUTH_METHOD);
879     }
880
881     /**
882      * Sets the login configuration.
883      *
884      * @param theAuthMethod The authentication method (for example, BASIC)
885      * @param theRealmName The name of the realm
886      */
887     public final void setLoginConfig(String theAuthMethod, String theRealmName)
888     {
889         if ((theRealmName == null) || (theAuthMethod == null))
890         {
891             throw new NullPointerException ();
892         }
893         Element loginConfigElement =
894             document.createElement(WebXmlTag.LOGIN_CONFIG.getTagName());
895         loginConfigElement.appendChild(
896             createNestedText(WebXmlTag.AUTH_METHOD, theAuthMethod));
897         loginConfigElement.appendChild(
898             createNestedText(WebXmlTag.REALM_NAME, theRealmName));
899         replaceElement(WebXmlTag.LOGIN_CONFIG, loginConfigElement);
900     }
901
902     /**
903      * Adds a new security role to the descriptor.
904      *
905      * @param theRoleName The name of the role to add
906      */
907     public final void addSecurityRole(String theRoleName)
908     {
909         if (theRoleName == null)
910         {
911             throw new NullPointerException ();
912         }
913         if (hasSecurityRole(theRoleName))
914         {
915             throw new IllegalStateException ("Security role '" + theRoleName
916                 + "' already defined");
917         }
918         Element securityRoleElement =
919             this.document.createElement(WebXmlTag.SECURITY_ROLE.getTagName());
920         securityRoleElement.appendChild(
921             createNestedText(WebXmlTag.ROLE_NAME, theRoleName));
922         addElement(WebXmlTag.SECURITY_ROLE, securityRoleElement);
923     }
924     
925     /**
926      * Returns the element that contains the specified security role, or
927      * <code>null</code> if the role is not defined in the descriptor.
928      *
929      * @param theRoleName The name of the role
930      * @return The DOM element representing the security role
931      */
932     public final Element getSecurityRole(String theRoleName)
933     {
934         if (theRoleName == null)
935         {
936             throw new NullPointerException ();
937         }
938         Iterator securityRoleElements = getElements(WebXmlTag.SECURITY_ROLE);
939         while (securityRoleElements.hasNext())
940         {
941             Element securityRoleElement = (Element ) securityRoleElements.next();
942             if (theRoleName.equals(getNestedText(
943                 securityRoleElement, WebXmlTag.ROLE_NAME)))
944             {
945                 return securityRoleElement;
946             }
947         }
948         return null;
949     }
950     
951     /**
952      * Returns a list of the security role names defined in the deployment
953      * descriptor
954      *
955      * @return An iterator over the list of security role names, or an empty
956      * iterator if no security roles are defined in the descriptor
957      */
958     public final Iterator getSecurityRoleNames()
959     {
960         List securityRoleNames = new ArrayList ();
961         Iterator securityRoleElements = getElements(WebXmlTag.SECURITY_ROLE);
962         while (securityRoleElements.hasNext())
963         {
964             Element securityRoleElement = (Element ) securityRoleElements.next();
965             String securityRoleName =
966                 getNestedText(securityRoleElement, WebXmlTag.ROLE_NAME);
967             if (securityRoleName != null)
968             {
969                 securityRoleNames.add(securityRoleName);
970             }
971         }
972         return securityRoleNames.iterator();
973     }
974     
975     /**
976      * Returns whether a specific security role has been defined.
977      *
978      * @param theRoleName The name of the role
979      * @return <code>true</code> if the security role is defined,
980      * <code>false</code> otherwise
981      */
982     public final boolean hasSecurityRole(String theRoleName)
983     {
984         return (getSecurityRole(theRoleName) != null);
985     }
986     
987     /**
988      * Returns an iterator over the elements that match the specified tag.
989      *
990      * @param theTag The descriptor tag of which the elements should be
991      * returned
992      * @return An iterator over the elements matching the tag, in the order
993      * they occur in the descriptor
994      */
995     public final Iterator getElements(WebXmlTag theTag)
996     {
997         List elements = new ArrayList ();
998         NodeList nodeList =
999             this.rootElement.getElementsByTagName(theTag.getTagName());
1000        for (int i = 0; i < nodeList.getLength(); i++)
1001        {
1002            elements.add(nodeList.item(i));
1003        }
1004        return elements.iterator();
1005    }
1006    
1007    /**
1008     * Adds an element of the specified tag to the descriptor.
1009     *
1010     * @param theTag The descriptor tag
1011     * @param theElement The element to add
1012     */
1013    public final void addElement(WebXmlTag theTag, Element theElement)
1014    {
1015        checkElement(theElement, theTag);
1016        if (!theTag.isMultipleAllowed() && getElements(theTag).hasNext())
1017        {
1018            throw new IllegalStateException ("The tag '" + theTag
1019                + "' may not occur more than once in the descriptor");
1020        }
1021        Node importedNode = this.document.importNode(theElement, true);
1022        Node refNode = getInsertionPointFor(theTag);
1023        this.rootElement.insertBefore(importedNode, refNode);
1024    }
1025    
1026    /**
1027     * Replaces all elements of the specified tag with the provided element.
1028     *
1029     * @param theTag The descriptor tag
1030     * @param theElement The element to replace the current elements with
1031     */
1032    public final void replaceElement(WebXmlTag theTag, Element theElement)
1033    {
1034        Iterator elements = getElements(theTag);
1035        while (elements.hasNext())
1036        {
1037            Element element = (Element ) elements.next();
1038            element.getParentNode().removeChild(element);
1039        }
1040        addElement(theTag, theElement);
1041    }
1042    
1043    // Private Methods ---------------------------------------------------------
1044
1045    /**
1046     * Adds an initialization parameter to the specified filter or servlet.
1047     *
1048     * @param theElement The filter or servlet element to which the
1049     * initialization parameter should be added
1050     * @param theParamName The name of the parameter
1051     * @param theParamValue The parameter value
1052     */
1053    private void addInitParam(Element theElement, String theParamName,
1054        String theParamValue)
1055    {
1056        Element initParamElement =
1057            this.document.createElement(WebXmlTag.INIT_PARAM.getTagName());
1058        initParamElement.appendChild(
1059            createNestedText(WebXmlTag.PARAM_NAME, theParamName));
1060        initParamElement.appendChild(
1061            createNestedText(WebXmlTag.PARAM_VALUE, theParamValue));
1062        Iterator loadOnStartupElements = getNestedElements(theElement,
1063            WebXmlTag.LOAD_ON_STARTUP);
1064        if (loadOnStartupElements.hasNext())
1065        {
1066            theElement.insertBefore(initParamElement,
1067                (Element ) loadOnStartupElements.next());
1068        }
1069        else
1070        {
1071            theElement.appendChild(initParamElement);
1072        }
1073    }
1074    
1075    /**
1076     * Checks an element whether its name matches the specified name.
1077     *
1078     * @param theElement The element to check
1079     * @param theExpectedTag The expected tag name
1080     * @throws IllegalArgumentException If the element name doesn't match
1081     */
1082    private void checkElement(Element theElement, WebXmlTag theExpectedTag)
1083        throws IllegalArgumentException
1084    {
1085        if (!theExpectedTag.getTagName().equals(theElement.getNodeName()))
1086        {
1087            throw new IllegalArgumentException ("Not a '" + theExpectedTag
1088                + "' element");
1089        }
1090    }
1091    
1092    /**
1093     * Returns an iterator over the child elements of the specified element that
1094     * match the specified tag.
1095     *
1096     * @param theParent The element of which the nested elements should be
1097     * retrieved
1098     * @param theTag The descriptor tag of which the elements should be
1099     * returned
1100     * @return An iterator over the elements matching the tag, in the order
1101     * they occur in the descriptor
1102     */
1103    private Iterator getNestedElements(Element theParent,
1104        WebXmlTag theTag)
1105    {
1106        List elements = new ArrayList ();
1107        NodeList nodeList = theParent.getElementsByTagName(theTag.getTagName());
1108        for (int i = 0; i < nodeList.getLength(); i++)
1109        {
1110            elements.add(nodeList.item(i));
1111        }
1112        return elements.iterator();
1113    }
1114
1115    /**
1116     * Creates an element that contains nested text.
1117     *
1118     * @param theTag The tag to create an instance of
1119     * @param theText The text that should be nested in the element
1120     * @return The created DOM element
1121     */
1122    private Element createNestedText(WebXmlTag theTag, String theText)
1123    {
1124        Element element = this.document.createElement(theTag.getTagName());
1125        element.appendChild(this.document.createTextNode(theText));
1126        return element;
1127    }
1128    
1129    /**
1130     * Returns the value of an initialization parameter of the specified filter
1131     * or servlet.
1132     *
1133     * @param theElement The filter or servlet element that contains the
1134     * initialization parameters
1135     * @param theParamName The name of the initialization parameter
1136     * @return The parameter value
1137     */
1138    private String getInitParam(Element theElement, String theParamName)
1139    {
1140        if (theElement != null)
1141        {
1142            NodeList initParamElements =
1143                theElement.getElementsByTagName(
1144                    WebXmlTag.INIT_PARAM.getTagName());
1145            for (int i = 0; i < initParamElements.getLength(); i++)
1146            {
1147                Element initParamElement = (Element ) initParamElements.item(i);
1148                String paramName = getNestedText(
1149                    initParamElement, WebXmlTag.PARAM_NAME);
1150                if (theParamName.equals(paramName))
1151                {
1152                    return getNestedText(
1153                        initParamElement, WebXmlTag.PARAM_VALUE);
1154                }
1155            }
1156        }
1157        return null;
1158    }
1159    
1160    /**
1161     * Returns the names of the initialization parameters of the specified
1162     * filter or servlet.
1163     *
1164     * @param theElement The filter or servlet element that contains the
1165     * initialization parameters
1166     * @return An iterator over the ordered list of parameter names
1167     */
1168    private Iterator getInitParamNames(Element theElement)
1169    {
1170        List initParamNames = new ArrayList ();
1171        if (theElement != null)
1172        {
1173            NodeList initParamElements =
1174                theElement.getElementsByTagName(
1175                    WebXmlTag.INIT_PARAM.getTagName());
1176            for (int i = 0; i < initParamElements.getLength(); i++)
1177            {
1178                Element initParamElement = (Element ) initParamElements.item(i);
1179                String paramName = getNestedText(
1180                    initParamElement, WebXmlTag.PARAM_NAME);
1181                if (paramName != null)
1182                {
1183                    initParamNames.add(paramName);
1184                }
1185            }
1186        }
1187        return initParamNames.iterator();
1188    }
1189    
1190    /**
1191     * Returns the node before which the specified tag should be inserted, or
1192     * <code>null</code> if the node should be inserted at the end of the
1193     * descriptor.
1194     *
1195     * @param theTag The tag that should be inserted
1196     * @return The node before which the tag can be inserted
1197     */
1198    private Node getInsertionPointFor(WebXmlTag theTag)
1199    {
1200        for (int i = 0; i < ELEMENT_ORDER.length; i++)
1201        {
1202            if (ELEMENT_ORDER[i] == theTag)
1203            {
1204                for (int j = i + 1; j < ELEMENT_ORDER.length; j++)
1205                {
1206                    NodeList elements =
1207                        this.rootElement.getElementsByTagName(
1208                            ELEMENT_ORDER[j].getTagName());
1209                    if (elements.getLength() > 0)
1210                    {
1211                        Node result = elements.item(0);
1212                        Node previous = result.getPreviousSibling();
1213                        while ((previous != null)
1214                            && ((previous.getNodeType() == Node.COMMENT_NODE)
1215                             || (previous.getNodeType() == Node.TEXT_NODE)))
1216                        {
1217                            result = previous;
1218                            previous = result.getPreviousSibling();
1219                        }
1220                        return result;
1221                    }
1222                }
1223                break;
1224            }
1225        }
1226        return null;
1227    }
1228    
1229    /**
1230     * Returns the text nested inside a child element of the specified element.
1231     *
1232     * @param theElement The element of which the nested text should be
1233     * returned
1234     * @param theTag The descriptor tag in which the text is nested
1235     * @return The text nested in the element
1236     */
1237    private String getNestedText(Element theElement,
1238        WebXmlTag theTag)
1239    {
1240        NodeList nestedElements =
1241            theElement.getElementsByTagName(theTag.getTagName());
1242        if (nestedElements.getLength() > 0)
1243        {
1244            Node nestedText = nestedElements.item(0).getFirstChild();
1245            if (nestedText != null)
1246            {
1247                return nestedText.getNodeValue();
1248            }
1249        }
1250        return null;
1251    }
1252    
1253}
1254

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags