001    /****************************************************************
002     * Licensed to the Apache Software Foundation (ASF) under one   *
003     * or more contributor license agreements.  See the NOTICE file *
004     * distributed with this work for additional information        *
005     * regarding copyright ownership.  The ASF licenses this file   *
006     * to you under the Apache License, Version 2.0 (the            *
007     * "License"); you may not use this file except in compliance   *
008     * with the License.  You may obtain a copy of the License at   *
009     *                                                              *
010     *   http://www.apache.org/licenses/LICENSE-2.0                 *
011     *                                                              *
012     * Unless required by applicable law or agreed to in writing,   *
013     * software distributed under the License is distributed on an  *
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
015     * KIND, either express or implied.  See the License for the    *
016     * specific language governing permissions and limitations      *
017     * under the License.                                           *
018     ****************************************************************/
019    
020    package org.apache.james.mime4j.dom;
021    
022    import java.util.Iterator;
023    import java.util.List;
024    
025    import org.apache.james.mime4j.stream.Field;
026    
027    /**
028     * A header of an MIME entity (as defined in RFC 2045).
029     */
030    public interface Header extends Iterable<Field> {
031    
032        /**
033         * Adds a field to the end of the list of fields.
034         *
035         * @param field the field to add.
036         */
037        void addField(Field field);
038    
039        /**
040         * Gets the fields of this header. The returned list will not be
041         * modifiable.
042         *
043         * @return the list of <code>Field</code> objects.
044         */
045        List<Field> getFields();
046    
047        /**
048         * Gets a <code>Field</code> given a field name. If there are multiple
049         * such fields defined in this header the first one will be returned.
050         *
051         * @param name the field name (e.g. From, Subject).
052         * @return the field or <code>null</code> if none found.
053         */
054        Field getField(String name);
055    
056        /**
057         * Gets all <code>Field</code>s having the specified field name.
058         *
059         * @param name the field name (e.g. From, Subject).
060         * @return the list of fields.
061         */
062        List<Field> getFields(final String name);
063    
064        /**
065         * Returns an iterator over the list of fields of this header.
066         *
067         * @return an iterator.
068         */
069        Iterator<Field> iterator();
070    
071        /**
072         * Removes all <code>Field</code>s having the specified field name.
073         *
074         * @param name
075         *            the field name (e.g. From, Subject).
076         * @return number of fields removed.
077         */
078        int removeFields(String name);
079    
080        /**
081         * Sets or replaces a field. This method is useful for header fields such as
082         * Subject or Message-ID that should not occur more than once in a message.
083         *
084         * If this <code>Header</code> does not already contain a header field of
085         * the same name as the given field then it is added to the end of the list
086         * of fields (same behavior as {@link #addField(Field)}). Otherwise the
087         * first occurrence of a field with the same name is replaced by the given
088         * field and all further occurrences are removed.
089         *
090         * @param field the field to set.
091         */
092        void setField(Field field);
093    
094    }