View Javadoc
1   /*
2    * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.xml.soap;
27  
28  import java.util.Iterator;
29  import java.util.Vector;
30  
31  /**
32   * A container for <code>MimeHeader</code> objects, which represent
33   * the MIME headers present in a MIME part of a message.
34   *
35   * <p>This class is used primarily when an application wants to
36   * retrieve specific attachments based on certain MIME headers and
37   * values. This class will most likely be used by implementations of
38   * <code>AttachmentPart</code> and other MIME dependent parts of the SAAJ
39   * API.
40   * @see SOAPMessage#getAttachments
41   * @see AttachmentPart
42   */
43  public class MimeHeaders {
44      private Vector headers;
45  
46     /**
47      * Constructs a default <code>MimeHeaders</code> object initialized with
48      * an empty <code>Vector</code> object.
49      */
50      public MimeHeaders() {
51          headers = new Vector();
52      }
53  
54      /**
55       * Returns all of the values for the specified header as an array of
56       * <code>String</code> objects.
57       *
58       * @param   name the name of the header for which values will be returned
59       * @return a <code>String</code> array with all of the values for the
60       *         specified header
61       * @see #setHeader
62       */
63      public String[] getHeader(String name) {
64          Vector values = new Vector();
65  
66          for(int i = 0; i < headers.size(); i++) {
67              MimeHeader hdr = (MimeHeader) headers.elementAt(i);
68              if (hdr.getName().equalsIgnoreCase(name)
69                  && hdr.getValue() != null)
70                  values.addElement(hdr.getValue());
71          }
72  
73          if (values.size() == 0)
74              return null;
75  
76          String r[] = new String[values.size()];
77          values.copyInto(r);
78          return r;
79      }
80  
81      /**
82       * Replaces the current value of the first header entry whose name matches
83       * the given name with the given value, adding a new header if no existing header
84       * name matches. This method also removes all matching headers after the first one.
85       * <P>
86       * Note that RFC822 headers can contain only US-ASCII characters.
87       *
88       * @param   name a <code>String</code> with the name of the header for
89       *          which to search
90       * @param   value a <code>String</code> with the value that will replace the
91       *          current value of the specified header
92       *
93       * @exception IllegalArgumentException if there was a problem in the
94       * mime header name or the value being set
95       * @see #getHeader
96       */
97      public void setHeader(String name, String value)
98      {
99          boolean found = false;
100 
101         if ((name == null) || name.equals(""))
102             throw new IllegalArgumentException("Illegal MimeHeader name");
103 
104         for(int i = 0; i < headers.size(); i++) {
105             MimeHeader hdr = (MimeHeader) headers.elementAt(i);
106             if (hdr.getName().equalsIgnoreCase(name)) {
107                 if (!found) {
108                     headers.setElementAt(new MimeHeader(hdr.getName(),
109                                                         value), i);
110                     found = true;
111                 }
112                 else
113                     headers.removeElementAt(i--);
114             }
115         }
116 
117         if (!found)
118             addHeader(name, value);
119     }
120 
121     /**
122      * Adds a <code>MimeHeader</code> object with the specified name and value
123      * to this <code>MimeHeaders</code> object's list of headers.
124      * <P>
125      * Note that RFC822 headers can contain only US-ASCII characters.
126      *
127      * @param   name a <code>String</code> with the name of the header to
128      *          be added
129      * @param   value a <code>String</code> with the value of the header to
130      *          be added
131      *
132      * @exception IllegalArgumentException if there was a problem in the
133      * mime header name or value being added
134      */
135     public void addHeader(String name, String value)
136     {
137         if ((name == null) || name.equals(""))
138             throw new IllegalArgumentException("Illegal MimeHeader name");
139 
140         int pos = headers.size();
141 
142         for(int i = pos - 1 ; i >= 0; i--) {
143             MimeHeader hdr = (MimeHeader) headers.elementAt(i);
144             if (hdr.getName().equalsIgnoreCase(name)) {
145                 headers.insertElementAt(new MimeHeader(name, value),
146                                         i+1);
147                 return;
148             }
149         }
150         headers.addElement(new MimeHeader(name, value));
151     }
152 
153     /**
154      * Remove all <code>MimeHeader</code> objects whose name matches the
155      * given name.
156      *
157      * @param   name a <code>String</code> with the name of the header for
158      *          which to search
159      */
160     public void removeHeader(String name) {
161         for(int i = 0; i < headers.size(); i++) {
162             MimeHeader hdr = (MimeHeader) headers.elementAt(i);
163             if (hdr.getName().equalsIgnoreCase(name))
164                 headers.removeElementAt(i--);
165         }
166     }
167 
168     /**
169      * Removes all the header entries from this <code>MimeHeaders</code> object.
170      */
171     public void removeAllHeaders() {
172         headers.removeAllElements();
173     }
174 
175 
176     /**
177      * Returns all the <code>MimeHeader</code>s in this <code>MimeHeaders</code> object.
178      *
179      * @return  an <code>Iterator</code> object over this <code>MimeHeaders</code>
180      *          object's list of <code>MimeHeader</code> objects
181      */
182     public Iterator getAllHeaders() {
183         return headers.iterator();
184     }
185 
186     class MatchingIterator implements Iterator {
187         private boolean match;
188         private Iterator iterator;
189         private String[] names;
190         private Object nextHeader;
191 
192         MatchingIterator(String[] names, boolean match) {
193             this.match = match;
194             this.names = names;
195             this.iterator = headers.iterator();
196         }
197 
198         private Object nextMatch() {
199         next:
200             while (iterator.hasNext()) {
201                 MimeHeader hdr = (MimeHeader) iterator.next();
202 
203                 if (names == null)
204                     return match ? null : hdr;
205 
206                 for(int i = 0; i < names.length; i++)
207                     if (hdr.getName().equalsIgnoreCase(names[i]))
208                         if (match)
209                             return hdr;
210                         else
211                             continue next;
212                 if (!match)
213                     return hdr;
214             }
215             return null;
216         }
217 
218 
219         public boolean hasNext() {
220             if (nextHeader == null)
221                 nextHeader = nextMatch();
222             return nextHeader != null;
223         }
224 
225         public Object next() {
226             // hasNext should've prefetched the header for us,
227             // return it.
228             if (nextHeader != null) {
229                 Object ret = nextHeader;
230                 nextHeader = null;
231                 return ret;
232             }
233             if (hasNext())
234                 return nextHeader;
235             return null;
236         }
237 
238         public void remove() {
239             iterator.remove();
240         }
241     }
242 
243 
244     /**
245      * Returns all the <code>MimeHeader</code> objects whose name matches
246      * a name in the given array of names.
247      *
248      * @param names an array of <code>String</code> objects with the names
249      *         for which to search
250      * @return  an <code>Iterator</code> object over the <code>MimeHeader</code>
251      *          objects whose name matches one of the names in the given list
252      */
253     public Iterator getMatchingHeaders(String[] names) {
254         return new MatchingIterator(names, true);
255     }
256 
257     /**
258      * Returns all of the <code>MimeHeader</code> objects whose name does not
259      * match a name in the given array of names.
260      *
261      * @param names an array of <code>String</code> objects with the names
262      *         for which to search
263      * @return  an <code>Iterator</code> object over the <code>MimeHeader</code>
264      *          objects whose name does not match one of the names in the given list
265      */
266     public Iterator getNonMatchingHeaders(String[] names) {
267         return new MatchingIterator(names, false);
268     }
269 }