View Javadoc

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 [email protected]
28   * InputStreamSource}, or a [email protected] 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 [email protected] 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 [email protected] 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 [email protected] 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 [email protected] 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 [email protected] 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 [email protected] 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 }