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 javax.xml.soap;
021
022 import java.io.IOException;
023 import java.io.InputStream;
024
025 /**
026 * <P>A factory for creating <CODE>SOAPMessage</CODE> objects.</P>
027 *
028 * <P>A JAXM client performs the following steps to create a
029 * message.</P>
030 *
031 * <UL>
032 * <LI>
033 * Creates a <CODE>MessageFactory</CODE> object from a <CODE>
034 * ProviderConnection</CODE> object (<CODE>con</CODE> in the
035 * following line of code). The <CODE>String</CODE> passed to
036 * the <CODE>createMessageFactory</CODE> method is the name of
037 * of a messaging profile, which must be the URL for the
038 * schema.
039 * <PRE>
040 * MessageFactory mf = con.createMessageFactory(schemaURL);
041 * </PRE>
042 * </LI>
043 *
044 * <LI>
045 * Calls the method <CODE>createMessage</CODE> on the <CODE>
046 * MessageFactory</CODE> object. All messages produced by this
047 * <CODE>MessageFactory</CODE> object will have the header
048 * information appropriate for the messaging profile that was
049 * specified when the <CODE>MessageFactory</CODE> object was
050 * created.
051 * <PRE>
052 * SOAPMessage m = mf.createMessage();
053 * </PRE>
054 * </LI>
055 * </UL>
056 * It is also possible to create a <CODE>MessageFactory</CODE>
057 * object using the method <CODE>newInstance</CODE>, as shown in
058 * the following line of code.
059 * <PRE>
060 * MessageFactory mf = MessageFactory.newInstance();
061 * </PRE>
062 * A standalone client (a client that is not running in a
063 * container) can use the <CODE>newInstance</CODE> method to
064 * create a <CODE>MessageFactory</CODE> object.
065 *
066 * <P>All <CODE>MessageFactory</CODE> objects, regardless of how
067 * they are created, will produce <CODE>SOAPMessage</CODE> objects
068 * that have the following elements by default:</P>
069 *
070 * <UL>
071 * <LI>A <CODE>SOAPPart</CODE> object</LI>
072 *
073 * <LI>A <CODE>SOAPEnvelope</CODE> object</LI>
074 *
075 * <LI>A <CODE>SOAPBody</CODE> object</LI>
076 *
077 * <LI>A <CODE>SOAPHeader</CODE> object</LI>
078 * </UL>
079 * If a <CODE>MessageFactory</CODE> object was created using a
080 * <CODE>ProviderConnection</CODE> object, which means that it was
081 * initialized with a specified profile, it will produce messages
082 * that also come prepopulated with additional entries in the
083 * <CODE>SOAPHeader</CODE> object and the <CODE>SOAPBody</CODE>
084 * object. The content of a new <CODE>SOAPMessage</CODE> object
085 * depends on which of the two <CODE>MessageFactory</CODE> methods
086 * is used to create it.
087 *
088 * <UL>
089 * <LI><CODE>createMessage()</CODE> -- message has no
090 * content<BR>
091 * This is the method clients would normally use to create a
092 * request message.</LI>
093 *
094 * <LI><CODE>createMessage(MimeHeaders,
095 * java.io.InputStream)</CODE> -- message has content from the
096 * <CODE>InputStream</CODE> object and headers from the <CODE>
097 * MimeHeaders</CODE> object<BR>
098 * This method can be used internally by a service
099 * implementation to create a message that is a response to a
100 * request.</LI>
101 * </UL>
102 */
103 public abstract class MessageFactory {
104
105 // fixme: this should be protected as the class is abstract.
106 /** Create a new MessageFactory. */
107 public MessageFactory() {}
108
109 /**
110 * Creates a new <CODE>MessageFactory</CODE> object that is
111 * an instance of the default implementation.
112 * @return a new <CODE>MessageFactory</CODE> object
113 * @throws SOAPException if there was an error in
114 * creating the default implementation of the <CODE>
115 * MessageFactory</CODE>
116 */
117 public static MessageFactory newInstance() throws SOAPException {
118
119 try {
120 return (MessageFactory) FactoryFinder.find(MESSAGE_FACTORY_PROPERTY,
121 DEFAULT_MESSAGE_FACTORY);
122 } catch (Exception exception) {
123 throw new SOAPException(
124 "Unable to create message factory for SOAP: "
125 + exception.getMessage());
126 }
127 }
128
129 /**
130 * Creates a new <CODE>SOAPMessage</CODE> object with the
131 * default <CODE>SOAPPart</CODE>, <CODE>SOAPEnvelope</CODE>,
132 * <CODE>SOAPBody</CODE>, and <CODE>SOAPHeader</CODE> objects.
133 * Profile-specific message factories can choose to
134 * prepopulate the <CODE>SOAPMessage</CODE> object with
135 * profile-specific headers.
136 *
137 * <P>Content can be added to this message's <CODE>
138 * SOAPPart</CODE> object, and the message can be sent "as is"
139 * when a message containing only a SOAP part is sufficient.
140 * Otherwise, the <CODE>SOAPMessage</CODE> object needs to
141 * create one or more <CODE>AttachmentPart</CODE> objects and
142 * add them to itself. Any content that is not in XML format
143 * must be in an <CODE>AttachmentPart</CODE> object.</P>
144 * @return a new <CODE>SOAPMessage</CODE> object
145 * @throws SOAPException if a SOAP error occurs
146 */
147 public abstract SOAPMessage createMessage() throws SOAPException;
148
149 /**
150 * Internalizes the contents of the given <CODE>
151 * InputStream</CODE> object into a new <CODE>SOAPMessage</CODE>
152 * object and returns the <CODE>SOAPMessage</CODE> object.
153 * @param mimeheaders the transport-specific headers
154 * passed to the message in a transport-independent fashion
155 * for creation of the message
156 * @param inputstream the <CODE>InputStream</CODE> object
157 * that contains the data for a message
158 * @return a new <CODE>SOAPMessage</CODE> object containing the
159 * data from the given <CODE>InputStream</CODE> object
160 * @throws IOException if there is a
161 * problem in reading data from the input stream
162 * @throws SOAPException if the message is invalid
163 */
164 public abstract SOAPMessage createMessage(
165 MimeHeaders mimeheaders, InputStream inputstream)
166 throws IOException, SOAPException;
167
168 private static final String DEFAULT_MESSAGE_FACTORY =
169 "org.apache.axis.soap.MessageFactoryImpl";
170
171 private static final String MESSAGE_FACTORY_PROPERTY =
172 "javax.xml.soap.MessageFactory";
173 }