1 /*
2 * Copyright 2005-2010 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.ws.mime;
18
19 import java.io.File;
20 import java.util.Iterator;
21 import javax.activation.DataHandler;
22
23 import org.springframework.core.io.InputStreamSource;
24 import org.springframework.ws.WebServiceMessage;
25
26 /**
27 * Represents a Web service message with MIME attachments. Attachments can be added as a file, an {@link
28 * InputStreamSource}, or a {@link DataHandler}.
29 *
30 * @author Arjen Poutsma
31 * @see Attachment
32 * @since 1.0.0
33 */
34 public interface MimeMessage extends WebServiceMessage {
35
36 /**
37 * Indicates whether this message is a XOP package.
38 *
39 * @return <code>true</code> when the constraints specified in <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#identifying_xop_documents">Identifying
40 * XOP Documents</a> are met.
41 * @see <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_packages">XOP Packages</a>
42 */
43 boolean isXopPackage();
44
45 /**
46 * Turns this message into a XOP package.
47 *
48 * @return <code>true</code> when the message is a XOP package
49 * @see <a href="http://www.w3.org/TR/2005/REC-xop10-20050125/#xop_packages">XOP Packages</a>
50 */
51 boolean convertToXopPackage();
52
53 /**
54 * Returns the {@link Attachment} with the specified content Id.
55 *
56 * @return the attachment with the specified content id; or <code>null</code> if it cannot be found
57 * @throws AttachmentException in case of errors
58 */
59 Attachment getAttachment(String contentId) throws AttachmentException;
60
61 /**
62 * Returns an <code>Iterator</code> over all {@link Attachment} objects that are part of this message.
63 *
64 * @return an iterator over all attachments
65 * @throws AttachmentException in case of errors
66 * @see Attachment
67 */
68 Iterator<Attachment> getAttachments() throws AttachmentException;
69
70 /**
71 * Add an attachment to the message, taking the content from a {@link File}.
72 * <p/>
73 * The content type will be determined by the name of the given content file. Do not use this for temporary files
74 * with arbitrary filenames (possibly ending in ".tmp" or the like)!
75 *
76 * @param contentId the content Id of the attachment
77 * @param file the file to take the content from
78 * @return the added attachment
79 * @throws AttachmentException in case of errors
80 */
81 Attachment addAttachment(String contentId, File file) throws AttachmentException;
82
83 /**
84 * Add an attachment to the message, taking the content from an {@link InputStreamSource}.
85 * <p/>
86 * Note that the stream returned by the source needs to be a <em>fresh one on each call</em>, as underlying
87 * implementations can invoke {@link InputStreamSource#getInputStream()} multiple times.
88 *
89 * @param contentId the content Id of the attachment
90 * @param inputStreamSource the resource to take the content from (all of Spring's Resource implementations can be
91 * passed in here)
92 * @param contentType the content type to use for the element
93 * @return the added attachment
94 * @throws AttachmentException in case of errors
95 * @see org.springframework.core.io.Resource
96 */
97 Attachment addAttachment(String contentId, InputStreamSource inputStreamSource, String contentType);
98
99 /**
100 * Add an attachment to the message, taking the content from a {@link DataHandler}.
101 *
102 * @param dataHandler the data handler to take the content from
103 * @return the added attachment
104 * @throws AttachmentException in case of errors
105 */
106 Attachment addAttachment(String contentId, DataHandler dataHandler);
107 }