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}