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.Collection;
023import java.util.Date;
024import java.util.TimeZone;
025
026import org.apache.james.mime4j.dom.address.Address;
027import org.apache.james.mime4j.dom.address.AddressList;
028import org.apache.james.mime4j.dom.address.Mailbox;
029import org.apache.james.mime4j.dom.address.MailboxList;
030
031/**
032 * An MIME message (as defined in RFC 2045).
033 */
034public interface Message extends Entity, Body {
035
036    /**
037     * Returns the value of the <i>Message-ID</i> header field of this message
038     * or <code>null</code> if it is not present.
039     *
040     * @return the identifier of this message.
041     */
042    String getMessageId();
043
044    /**
045     * Creates and sets a new <i>Message-ID</i> header field for this message.
046     * A <code>Header</code> is created if this message does not already have
047     * one.
048     *
049     * @param hostname
050     *            host name to be included in the identifier or
051     *            <code>null</code> if no host name should be included.
052     */
053    void createMessageId(String hostname);
054
055    /**
056     * Returns the (decoded) value of the <i>Subject</i> header field of this
057     * message or <code>null</code> if it is not present.
058     *
059     * @return the subject of this message.
060     */
061    String getSubject();
062
063    /**
064     * Sets the <i>Subject</i> header field for this message. The specified
065     * string may contain non-ASCII characters, in which case it gets encoded as
066     * an 'encoded-word' automatically. A <code>Header</code> is created if
067     * this message does not already have one.
068     *
069     * @param subject
070     *            subject to set or <code>null</code> to remove the subject
071     *            header field.
072     */
073    void setSubject(String subject);
074
075    /**
076     * Returns the value of the <i>Date</i> header field of this message as
077     * <code>Date</code> object or <code>null</code> if it is not present.
078     *
079     * @return the date of this message.
080     */
081    Date getDate();
082
083    /**
084     * Sets the <i>Date</i> header field for this message. This method uses the
085     * default <code>TimeZone</code> of this host to encode the specified
086     * <code>Date</code> object into a string.
087     *
088     * @param date
089     *            date to set or <code>null</code> to remove the date header
090     *            field.
091     */
092    void setDate(Date date);
093
094    /**
095     * Sets the <i>Date</i> header field for this message. The specified
096     * <code>TimeZone</code> is used to encode the specified <code>Date</code>
097     * object into a string.
098     *
099     * @param date
100     *            date to set or <code>null</code> to remove the date header
101     *            field.
102     * @param zone
103     *            a time zone.
104     */
105    void setDate(Date date, TimeZone zone);
106
107    /**
108     * Returns the value of the <i>Sender</i> header field of this message as
109     * <code>Mailbox</code> object or <code>null</code> if it is not
110     * present.
111     *
112     * @return the sender of this message.
113     */
114    Mailbox getSender();
115
116    /**
117     * Sets the <i>Sender</i> header field of this message to the specified
118     * mailbox address.
119     *
120     * @param sender
121     *            address to set or <code>null</code> to remove the header
122     *            field.
123     */
124    void setSender(Mailbox sender);
125
126    /**
127     * Returns the value of the <i>From</i> header field of this message as
128     * <code>MailboxList</code> object or <code>null</code> if it is not
129     * present.
130     *
131     * @return value of the from field of this message.
132     */
133    MailboxList getFrom();
134
135    /**
136     * Sets the <i>From</i> header field of this message to the specified
137     * mailbox address.
138     *
139     * @param from
140     *            address to set or <code>null</code> to remove the header
141     *            field.
142     */
143    void setFrom(Mailbox from);
144
145    /**
146     * Sets the <i>From</i> header field of this message to the specified
147     * mailbox addresses.
148     *
149     * @param from
150     *            addresses to set or <code>null</code> or no arguments to
151     *            remove the header field.
152     */
153    void setFrom(Mailbox... from);
154
155    /**
156     * Sets the <i>From</i> header field of this message to the specified
157     * mailbox addresses.
158     *
159     * @param from
160     *            addresses to set or <code>null</code> or an empty collection
161     *            to remove the header field.
162     */
163    void setFrom(Collection<Mailbox> from);
164
165    /**
166     * Returns the value of the <i>To</i> header field of this message as
167     * <code>AddressList</code> object or <code>null</code> if it is not
168     * present.
169     *
170     * @return value of the to field of this message.
171     */
172    AddressList getTo();
173
174    /**
175     * Sets the <i>To</i> header field of this message to the specified
176     * address.
177     *
178     * @param to
179     *            address to set or <code>null</code> to remove the header
180     *            field.
181     */
182    void setTo(Address to);
183
184    /**
185     * Sets the <i>To</i> header field of this message to the specified
186     * addresses.
187     *
188     * @param to
189     *            addresses to set or <code>null</code> or no arguments to
190     *            remove the header field.
191     */
192    void setTo(Address... to);
193
194    /**
195     * Sets the <i>To</i> header field of this message to the specified
196     * addresses.
197     *
198     * @param to
199     *            addresses to set or <code>null</code> or an empty collection
200     *            to remove the header field.
201     */
202    void setTo(Collection<? extends Address> to);
203
204    /**
205     * Returns the value of the <i>Cc</i> header field of this message as
206     * <code>AddressList</code> object or <code>null</code> if it is not
207     * present.
208     *
209     * @return value of the cc field of this message.
210     */
211    AddressList getCc();
212
213    /**
214     * Sets the <i>Cc</i> header field of this message to the specified
215     * address.
216     *
217     * @param cc
218     *            address to set or <code>null</code> to remove the header
219     *            field.
220     */
221    void setCc(Address cc);
222
223    /**
224     * Sets the <i>Cc</i> header field of this message to the specified
225     * addresses.
226     *
227     * @param cc
228     *            addresses to set or <code>null</code> or no arguments to
229     *            remove the header field.
230     */
231    void setCc(Address... cc);
232
233    /**
234     * Sets the <i>Cc</i> header field of this message to the specified
235     * addresses.
236     *
237     * @param cc
238     *            addresses to set or <code>null</code> or an empty collection
239     *            to remove the header field.
240     */
241    void setCc(Collection<? extends Address> cc);
242
243    /**
244     * Returns the value of the <i>Bcc</i> header field of this message as
245     * <code>AddressList</code> object or <code>null</code> if it is not
246     * present.
247     *
248     * @return value of the bcc field of this message.
249     */
250    AddressList getBcc();
251
252    /**
253     * Sets the <i>Bcc</i> header field of this message to the specified
254     * address.
255     *
256     * @param bcc
257     *            address to set or <code>null</code> to remove the header
258     *            field.
259     */
260    void setBcc(Address bcc);
261
262    /**
263     * Sets the <i>Bcc</i> header field of this message to the specified
264     * addresses.
265     *
266     * @param bcc
267     *            addresses to set or <code>null</code> or no arguments to
268     *            remove the header field.
269     */
270    void setBcc(Address... bcc);
271
272    /**
273     * Sets the <i>Bcc</i> header field of this message to the specified
274     * addresses.
275     *
276     * @param bcc
277     *            addresses to set or <code>null</code> or an empty collection
278     *            to remove the header field.
279     */
280    void setBcc(Collection<? extends Address> bcc);
281
282    /**
283     * Returns the value of the <i>Reply-To</i> header field of this message as
284     * <code>AddressList</code> object or <code>null</code> if it is not
285     * present.
286     *
287     * @return value of the reply to field of this message.
288     */
289    AddressList getReplyTo();
290
291    /**
292     * Sets the <i>Reply-To</i> header field of this message to the specified
293     * address.
294     *
295     * @param replyTo
296     *            address to set or <code>null</code> to remove the header
297     *            field.
298     */
299    void setReplyTo(Address replyTo);
300
301    /**
302     * Sets the <i>Reply-To</i> header field of this message to the specified
303     * addresses.
304     *
305     * @param replyTo
306     *            addresses to set or <code>null</code> or no arguments to
307     *            remove the header field.
308     */
309    void setReplyTo(Address... replyTo);
310
311    /**
312     * Sets the <i>Reply-To</i> header field of this message to the specified
313     * addresses.
314     *
315     * @param replyTo
316     *            addresses to set or <code>null</code> or an empty collection
317     *            to remove the header field.
318     */
319    void setReplyTo(Collection<? extends Address> replyTo);
320
321}