001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package com.sun.tck.wma;
028:
029: /**
030: * An interface representing a multipart message. This is a subinterface of
031: * <code>Message</code> which contains methods to add and get
032: * <code>MessagePart</code>s. The interface also allows to specify the subject
033: * of the message. The basic methods for manipulating the address portion of
034: * the message are inherited from <code>Message</code>. Additionally, this
035: * interface defines methods for adding and removing addresses to/from the
036: * "to", "cc" or "bcc" fields. Furthermore it offers methods to get and set
037: * special header fields of the message. The contents of the MultipartMessage
038: * are assembled during the invocation of the MessageConnection.send() method.
039: * The contents of each MessagePart are copied before the send message returns.
040: * Changes to the MessagePart contents after send must not appear in the
041: * transmitted message.
042: * @since WMA 2.0
043: */
044: public interface MultipartMessage extends Message {
045:
046: /**
047: * Adds an address to the multipart message.
048: * @param type the adress type ("to", "cc" or "bcc") as a
049: * <code>String</code>. Each message can have none or multiple "to",
050: * "cc" and "bcc" addresses. Eash address is added separately. The
051: * method is not case sensitive. The implementation of
052: * <code>MessageConnection.send()</code> makes sure that the "from"
053: * address is set correctly.
054: * @param address the address as a <code>String</code>
055: * @return <code>true</code> if it was possible to add the address, else
056: * <code>false</code>
057: * @throws java.lang.IllegalArgumentException if type is none of "to", "cc",
058: * or "bcc" or if <code>address</code> is not valid.
059: * @see #setAddress(String)
060: */
061: boolean addAddress(java.lang.String type, java.lang.String address);
062:
063: /**
064: * Attaches a <code>MessagePart</code> to the multipart message.
065: * @param part <code>MessagePart</code> to add
066: * @throws java.lang.IllegalArgumentException if the Content-ID of the
067: * <code>MessagePart</code> conflicts with a Content-ID of a
068: * <code>MessagePart</code> already contained in this
069: * <code>MultiPartMessage</code>. The Content-IDs must be unique
070: * within a MultipartMessage.
071: * @throws NullPointerException if the parameter is <code>null</code>
072: * @throws SizeExceededException if it's not possible to attach the
073: * <code>MessagePart</code>.
074: */
075: void addMessagePart(MessagePart part) throws SizeExceededException;
076:
077: /**
078: * Returns the "from" address associated with this message, e.g. address of
079: * the sender. If the message is a newly created message, e.g. not a
080: * received one, then the first "to" address is returned.
081: * Returns <code>null</code> if the "from" or "to" address for the
082: * message, dependent on the case, are not set.
083: * Note: This design allows sending responses to a received message easily
084: * by reusing the same <code>Message</code> object and just replacing the
085: * payload. The address field can normally be kept untouched (unless the
086: * used messaging protocol requires some special handling of the address).
087: * @return the "from" or "to" address of this message, or <code>null</code>
088: * if the address that is expected as a result of this method is not
089: * set
090: * @see #setAddress(String)
091: */
092: java.lang.String getAddress();
093:
094: /**
095: * Gets the addresses of the multipart message of the specified type (e.g.
096: * "to", "cc", "bcc" or "from") as <code>String</code>. The method is not
097: * case sensitive.
098: * @param type the type of address list to return
099: * @return the addresses as a <code>String</code> array or <code>null</code>
100: * if this value is not present.
101: */
102: java.lang.String[] getAddresses(java.lang.String type);
103:
104: /**
105: * Gets the content of the specific header field of the multipart message.
106: * @param headerField the name of the header field as a <code>String</code>
107: * @return the content of the specified header field as a
108: * <code>String</code> or <code>null</code> of the specified header
109: * field is not present.
110: * @throws SecurityException if the access to specified header field is
111: * restricted
112: * @throws IllegalArgumentException if <code>headerField</code> is unknown
113: * @see Appendix D for known headerFields
114: * @see #setHeader
115: */
116: java.lang.String getHeader(java.lang.String headerField);
117:
118: /**
119: * This method returns a <code>MessagePart</code> from the message that
120: * matches the content-id passed as a parameter.
121: * @param contentID the content-id for the <code>MessagePart</code> to be
122: * returned
123: * @return <code>MessagePart</code> that matches the provided content-id or
124: * <code>null</code> if there is no <code>MessagePart</code> in this
125: * message with the provided content-id
126: * @throws NullPointerException if the parameter is <code>null</code>
127: */
128: MessagePart getMessagePart(java.lang.String contentID);
129:
130: /**
131: * Returns an array of all <code>MessagePart</code>s of this message.
132: * @return array of <code>MessagePart</code>s, or <code>null</code> if no
133: * <code>MessagePart</code>s are available
134: */
135: MessagePart[] getMessageParts();
136:
137: /**
138: * Returns the <code>contentId</code> of the start <code>MessagePart</code>.
139: * The start <code>MessagePart</code> is set in
140: * <code>setStartContentId(String)</code>
141: * @return the content-id of the start <code>MessagePart</code> or
142: * <code>null</code> if the start <code>MessagePart</code> is not set.
143: * @see #setStartContentId(String)
144: */
145: java.lang.String getStartContentId();
146:
147: /**
148: * Gets the subject of the multipart message.
149: * @return the message subject as a <code>String</code> or <code>null</code>
150: * if this value is not present.
151: * @see #setSubject
152: */
153: java.lang.String getSubject();
154:
155: /**
156: * Removes an address from the multipart message.
157: * @param type the address type ("to", "cc", "bcc", or "from") as a
158: * <code>String</code>
159: * @param address the address as a <code>String</code>
160: * @return <code>true</code> if it was possible to delete the address, else
161: * <code>false</code>
162: * @throws NullPointerException is type is <code>null</code>
163: * @throws java.lang.IllegalArgumentException if type is none of "to", "cc",
164: * "bcc", or "from"
165: */
166: boolean removeAddress(java.lang.String type,
167: java.lang.String address);
168:
169: /**
170: * Removes all addresses of types "to", "cc", "bcc" from the multipart
171: * message.
172: * @see #setAddress(String)
173: * @see #addAddress(String, String)
174: */
175: void removeAddresses();
176:
177: /**
178: * Removes all addresses of the specified type from the multipart message.
179: * @param type the address type ("to", "cc", "bcc", or "from") as a
180: * <code>String</code>
181: * @throws NullPointerException if type is <code>null</code>
182: * @throws java.lang.IllegalArgumentException if type is none of "to", "cc",
183: * "bcc", or "from"
184: */
185: void removeAddresses(java.lang.String type);
186:
187: /**
188: * Removes a <code>MessagePart</code> from the multipart message.
189: * @param part <code>MessagePart</code> to delete
190: * @return <code>true</code> if it was possible to remove the
191: * <code>MessagePart</code>, else <code>false</code>
192: * @throws NullPointerException if the parameter is <code>null</code>
193: */
194: boolean removeMessagePart(MessagePart part);
195:
196: /**
197: * Removes a <code>MessagePart</code> with the specific
198: * <code>contentID</code> from the multipart message.
199: * @param contentID identifies which <code>MessagePart</code> must be
200: * deleted.
201: * @return <code>true</code> if it was possible to remove the
202: * <code>MessagePart</code>, else <code>false</code>
203: * @throws NullPointerException if the parameter is <code>null</code>
204: */
205: boolean removeMessagePartId(java.lang.String contentID);
206:
207: /**
208: * Removes <code>MessagePart</code>s with the specific content location
209: * from the multipart message. All <code>MessagePart</code>s with the
210: * specified <code>contentLocation</code> are removed.
211: * @param contentLocation content location (file name) of the
212: * <code>MessagePart</code>
213: * @return <code>true</code> if it was possible to remove the
214: * <code>MessagePart</code>, else <code>false</code>
215: * @throws NullPointerException if the parameter is <code>null</code>
216: */
217: boolean removeMessagePartLocation(java.lang.String contentLocation);
218:
219: /**
220: * Sets the "to" address associated with this message. It works the same way
221: * as <code>addAddress("to", addr)</code>. The address may be set to
222: * <code>null</code>.
223: * @param addr address for the message
224: * @see #getAddress()
225: * @see #addAddress(String, String)
226: */
227: void setAddress(java.lang.String addr);
228:
229: /**
230: * Sets the specified header of the multipart message. The header value can
231: * be <code>null</code>.
232: * @param headerField the name of the header field as a <code>String</code>
233: * @param headerValue the value of the header as a <code>String</code>
234: * @throws java.lang.IllegalArgumentException if <code>headerField</code> is
235: * unknown, or if <code>headerValue</code> is not correct (depends on
236: * <code>headerField</code>!)
237: * @throws NullPointerException if <code>headerField</code> is
238: * <code>null</code>
239: * @throws SecurityException if the access to specified header field is
240: * restricted
241: * @see #getHeader(String)
242: * @see Appendix D
243: */
244: void setHeader(java.lang.String headerField,
245: java.lang.String headerValue);
246:
247: /**
248: * Sets the <code>Content-ID</code> of the start <code>MessagePart</code> of
249: * a multipart related message. The <code>Content-ID</code> may be set to
250: * <code>null</code>. The <code>StartContentId</code> is set for the
251: * MessagePart that is used to reference the other MessageParts of the
252: * MultipartMessage for presentation or processing purposes.
253: * @param contentId as a <code>String</code>
254: * @throws java.lang.IllegalArgumentException if <code>contentId</code> is
255: * none of the added <code>MessagePart</code> objects matches the
256: * <code>contentId</code>
257: * @see #getStartContentId()
258: */
259: void setStartContentId(java.lang.String contentId);
260:
261: /**
262: * Sets the Subject of the multipart message. This value can be
263: * <code>null</code>.
264: * @param subject the message subject as a <code>String</code>
265: * @see #getSubject()
266: */
267: void setSubject(java.lang.String subject);
268: }
|