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.Collection;
023    import java.util.Date;
024    import java.util.TimeZone;
025    
026    import org.apache.james.mime4j.dom.address.Address;
027    import org.apache.james.mime4j.dom.address.AddressList;
028    import org.apache.james.mime4j.dom.address.Mailbox;
029    import org.apache.james.mime4j.dom.address.MailboxList;
030    
031    /**
032     * An MIME message (as defined in RFC 2045).
033     */
034    public 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    }