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    }