1 /*
2 * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.soap;
27
28
29 import java.io.IOException;
30 import java.io.InputStream;
31
32 /**
33 * A factory for creating {@code SOAPMessage} objects.
34 * <P>
35 * A SAAJ client can create a {@code MessageFactory} object
36 * using the method {@code newInstance}, as shown in the following
37 * lines of code.
38 * <pre>{@code
39 * MessageFactory mf = MessageFactory.newInstance();
40 * MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
41 * }</pre>
42 * <P>
43 * All {@code MessageFactory} objects, regardless of how they are
44 * created, will produce {@code SOAPMessage} objects that
45 * have the following elements by default:
46 * <UL>
47 * <LI>A {@code SOAPPart} object
48 * <LI>A {@code SOAPEnvelope} object
49 * <LI>A {@code SOAPBody} object
50 * <LI>A {@code SOAPHeader} object
51 * </UL>
52 * In some cases, specialized MessageFactory objects may be obtained that produce messages
53 * prepopulated with additional entries in the {@code SOAPHeader} object and the
54 * {@code SOAPBody} object.
55 * The content of a new {@code SOAPMessage} object depends on which of the two
56 * {@code MessageFactory} methods is used to create it.
57 * <UL>
58 * <LI>{@code createMessage()} <BR>
59 * This is the method clients would normally use to create a request message.
60 * <LI>{@code createMessage(MimeHeaders, java.io.InputStream)} -- message has
61 * content from the {@code InputStream} object and headers from the
62 * {@code MimeHeaders} object <BR>
63 * This method can be used internally by a service implementation to
64 * create a message that is a response to a request.
65 * </UL>
66 *
67 * @since 1.6
68 */
69 public abstract class MessageFactory {
70
71 private static final String DEFAULT_MESSAGE_FACTORY
72 = "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl";
73
74 /**
75 * Creates a new {@code MessageFactory} object that is an instance
76 * of the default implementation (SOAP 1.1).
77 *
78 * This method uses the lookup procedure specified in {@link javax.xml.soap} to locate and load the
79 * {@link javax.xml.soap.MessageFactory} class.
80 *
81 * @return a new instance of a {@code MessageFactory}
82 *
83 * @exception SOAPException if there was an error in creating the
84 * default implementation of the
85 * {@code MessageFactory}.
86 * @see SAAJMetaFactory
87 */
88
89 public static MessageFactory newInstance() throws SOAPException {
90
91
92 try {
93 MessageFactory factory = (MessageFactory) FactoryFinder.find(
94 MessageFactory.class,
95 DEFAULT_MESSAGE_FACTORY,
96 false);
97
98 if (factory != null) {
99 return factory;
100 }
101 return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
102
103 } catch (Exception ex) {
104 throw new SOAPException(
105 "Unable to create message factory for SOAP: "
106 +ex.getMessage());
107 }
108
109 }
110
111 /**
112 * Creates a new {@code MessageFactory} object that is an instance
113 * of the specified implementation. May be a dynamic message factory,
114 * a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic
115 * message factory creates messages based on the MIME headers specified
116 * as arguments to the {@code createMessage} method.
117 *
118 * This method uses the SAAJMetaFactory to locate the implementation class
119 * and create the MessageFactory instance.
120 *
121 * @return a new instance of a {@code MessageFactory}
122 *
123 * @param protocol a string constant representing the class of the
124 * specified message factory implementation. May be
125 * either {@code DYNAMIC_SOAP_PROTOCOL},
126 * {@code DEFAULT_SOAP_PROTOCOL} (which is the same
127 * as) {@code SOAP_1_1_PROTOCOL}, or
128 * {@code SOAP_1_2_PROTOCOL}.
129 *
130 * @exception SOAPException if there was an error in creating the
131 * specified implementation of {@code MessageFactory}.
132 * @see SAAJMetaFactory
133 * @since 1.6, SAAJ 1.3
134 */
135 public static MessageFactory newInstance(String protocol) throws SOAPException {
136 return SAAJMetaFactory.getInstance().newMessageFactory(protocol);
137 }
138
139 /**
140 * Creates a new {@code SOAPMessage} object with the default
141 * {@code SOAPPart}, {@code SOAPEnvelope}, {@code SOAPBody},
142 * and {@code SOAPHeader} objects. Profile-specific message factories
143 * can choose to prepopulate the {@code SOAPMessage} object with
144 * profile-specific headers.
145 * <P>
146 * Content can be added to this message's {@code SOAPPart} object, and
147 * the message can be sent "as is" when a message containing only a SOAP part
148 * is sufficient. Otherwise, the {@code SOAPMessage} object needs
149 * to create one or more {@code AttachmentPart} objects and
150 * add them to itself. Any content that is not in XML format must be
151 * in an {@code AttachmentPart} object.
152 *
153 * @return a new {@code SOAPMessage} object
154 * @exception SOAPException if a SOAP error occurs
155 * @exception UnsupportedOperationException if the protocol of this
156 * {@code MessageFactory} instance is {@code DYNAMIC_SOAP_PROTOCOL}
157 */
158 public abstract SOAPMessage createMessage()
159 throws SOAPException;
160
161 /**
162 * Internalizes the contents of the given {@code InputStream} object into a
163 * new {@code SOAPMessage} object and returns the {@code SOAPMessage}
164 * object.
165 *
166 * @param in the {@code InputStream} object that contains the data
167 * for a message
168 * @param headers the transport-specific headers passed to the
169 * message in a transport-independent fashion for creation of the
170 * message
171 * @return a new {@code SOAPMessage} object containing the data from
172 * the given {@code InputStream} object
173 *
174 * @exception IOException if there is a problem in reading data from
175 * the input stream
176 *
177 * @exception SOAPException may be thrown if the message is invalid
178 *
179 * @exception IllegalArgumentException if the {@code MessageFactory}
180 * requires one or more MIME headers to be present in the
181 * {@code headers} parameter and they are missing.
182 * {@code MessageFactory} implementations for
183 * {@code SOAP_1_1_PROTOCOL} or
184 * {@code SOAP_1_2_PROTOCOL} must not throw
185 * {@code IllegalArgumentException} for this reason.
186 */
187 public abstract SOAPMessage createMessage(MimeHeaders headers,
188 InputStream in)
189 throws IOException, SOAPException;
190 }