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
020package org.apache.james.mime4j.dom;
021
022import java.util.Iterator;
023import java.util.List;
024
025import org.apache.james.mime4j.stream.Field;
026
027/**
028 * A header of an MIME entity (as defined in RFC 2045).
029 */
030public 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}