ohair@286: /*
mkos@384: * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved.
ohair@286: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
ohair@286: *
ohair@286: * This code is free software; you can redistribute it and/or modify it
ohair@286: * under the terms of the GNU General Public License version 2 only, as
ohair@286: * published by the Free Software Foundation. Oracle designates this
ohair@286: * particular file as subject to the "Classpath" exception as provided
ohair@286: * by Oracle in the LICENSE file that accompanied this code.
ohair@286: *
ohair@286: * This code is distributed in the hope that it will be useful, but WITHOUT
ohair@286: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
ohair@286: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
ohair@286: * version 2 for more details (a copy is included in the LICENSE file that
ohair@286: * accompanied this code).
ohair@286: *
ohair@286: * You should have received a copy of the GNU General Public License version
ohair@286: * 2 along with this work; if not, write to the Free Software Foundation,
ohair@286: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
ohair@286: *
ohair@286: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
ohair@286: * or visit www.oracle.com if you need additional information or have any
ohair@286: * questions.
ohair@286: */
ohair@286:
ohair@286: package javax.xml.soap;
ohair@286:
ohair@286:
ohair@286: import java.io.IOException;
ohair@286: import java.io.InputStream;
ohair@286:
ohair@286: /**
ohair@286: * A factory for creating SOAPMessage
objects.
ohair@286: *
ohair@286: * A SAAJ client can create a MessageFactory
object
ohair@286: * using the method newInstance
, as shown in the following
ohair@286: * lines of code.
ohair@286: *
ohair@286: * MessageFactory mf = MessageFactory.newInstance(); ohair@286: * MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL); ohair@286: *ohair@286: *
ohair@286: * All MessageFactory
objects, regardless of how they are
ohair@286: * created, will produce SOAPMessage
objects that
ohair@286: * have the following elements by default:
ohair@286: *
SOAPPart
object
ohair@286: * SOAPEnvelope
object
ohair@286: * SOAPBody
object
ohair@286: * SOAPHeader
object
ohair@286: * SOAPHeader
object and the
ohair@286: * SOAPBody
object.
ohair@286: * The content of a new SOAPMessage
object depends on which of the two
ohair@286: * MessageFactory
methods is used to create it.
ohair@286: * createMessage()
createMessage(MimeHeaders, java.io.InputStream)
-- message has
ohair@286: * content from the InputStream
object and headers from the
ohair@286: * MimeHeaders
object MessageFactory
object that is an instance
ohair@286: * of the default implementation (SOAP 1.1),
ohair@286: *
ohair@286: * This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load:
ohair@286: * MessageFactory
ohair@286: *
ohair@286: * @exception SOAPException if there was an error in creating the
ohair@286: * default implementation of the
ohair@286: * MessageFactory
.
ohair@286: * @see SAAJMetaFactory
ohair@286: */
ohair@286:
mkos@384: public static MessageFactory newInstance() throws SOAPException {
mkos@384:
mkos@384:
ohair@286: try {
mkos@384: MessageFactory factory = (MessageFactory) FactoryFinder.find(
mkos@384: MESSAGE_FACTORY_PROPERTY,
mkos@384: DEFAULT_MESSAGE_FACTORY,
mkos@384: false);
ohair@286:
mkos@384: if (factory != null) {
ohair@286: return factory;
mkos@384: }
ohair@286: return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
mkos@384:
ohair@286: } catch (Exception ex) {
ohair@286: throw new SOAPException(
ohair@286: "Unable to create message factory for SOAP: "
ohair@286: +ex.getMessage());
ohair@286: }
ohair@286:
ohair@286: }
ohair@286:
ohair@286: /**
ohair@286: * Creates a new MessageFactory
object that is an instance
ohair@286: * of the specified implementation. May be a dynamic message factory,
ohair@286: * a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic
ohair@286: * message factory creates messages based on the MIME headers specified
ohair@286: * as arguments to the createMessage
method.
ohair@286: *
ohair@286: * This method uses the SAAJMetaFactory to locate the implementation class
ohair@286: * and create the MessageFactory instance.
ohair@286: *
ohair@286: * @return a new instance of a MessageFactory
ohair@286: *
ohair@286: * @param protocol a string constant representing the class of the
ohair@286: * specified message factory implementation. May be
ohair@286: * either DYNAMIC_SOAP_PROTOCOL
,
ohair@286: * DEFAULT_SOAP_PROTOCOL
(which is the same
ohair@286: * as) SOAP_1_1_PROTOCOL
, or
ohair@286: * SOAP_1_2_PROTOCOL
.
ohair@286: *
ohair@286: * @exception SOAPException if there was an error in creating the
ohair@286: * specified implementation of MessageFactory
.
ohair@286: * @see SAAJMetaFactory
ohair@286: * @since SAAJ 1.3
ohair@286: */
ohair@286: public static MessageFactory newInstance(String protocol) throws SOAPException {
ohair@286: return SAAJMetaFactory.getInstance().newMessageFactory(protocol);
ohair@286: }
ohair@286:
ohair@286: /**
ohair@286: * Creates a new SOAPMessage
object with the default
ohair@286: * SOAPPart
, SOAPEnvelope
, SOAPBody
,
ohair@286: * and SOAPHeader
objects. Profile-specific message factories
ohair@286: * can choose to prepopulate the SOAPMessage
object with
ohair@286: * profile-specific headers.
ohair@286: *
ohair@286: * Content can be added to this message's SOAPPart
object, and
ohair@286: * the message can be sent "as is" when a message containing only a SOAP part
ohair@286: * is sufficient. Otherwise, the SOAPMessage
object needs
ohair@286: * to create one or more AttachmentPart
objects and
ohair@286: * add them to itself. Any content that is not in XML format must be
ohair@286: * in an AttachmentPart
object.
ohair@286: *
ohair@286: * @return a new SOAPMessage
object
ohair@286: * @exception SOAPException if a SOAP error occurs
ohair@286: * @exception UnsupportedOperationException if the protocol of this
ohair@286: * MessageFactory
instance is DYNAMIC_SOAP_PROTOCOL
ohair@286: */
ohair@286: public abstract SOAPMessage createMessage()
ohair@286: throws SOAPException;
ohair@286:
ohair@286: /**
ohair@286: * Internalizes the contents of the given InputStream
object into a
ohair@286: * new SOAPMessage
object and returns the SOAPMessage
ohair@286: * object.
ohair@286: *
ohair@286: * @param in the InputStream
object that contains the data
ohair@286: * for a message
ohair@286: * @param headers the transport-specific headers passed to the
ohair@286: * message in a transport-independent fashion for creation of the
ohair@286: * message
ohair@286: * @return a new SOAPMessage
object containing the data from
ohair@286: * the given InputStream
object
ohair@286: *
ohair@286: * @exception IOException if there is a problem in reading data from
ohair@286: * the input stream
ohair@286: *
ohair@286: * @exception SOAPException may be thrown if the message is invalid
ohair@286: *
ohair@286: * @exception IllegalArgumentException if the MessageFactory
ohair@286: * requires one or more MIME headers to be present in the
ohair@286: * headers
parameter and they are missing.
ohair@286: * MessageFactory
implementations for
ohair@286: * SOAP_1_1_PROTOCOL
or
ohair@286: * SOAP_1_2_PROTOCOL
must not throw
ohair@286: * IllegalArgumentException
for this reason.
ohair@286: */
ohair@286: public abstract SOAPMessage createMessage(MimeHeaders headers,
ohair@286: InputStream in)
ohair@286: throws IOException, SOAPException;
ohair@286: }