javax.xml.soap.MessageFactory Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package javax.xml.soap;
import java.io.IOException;
import java.io.InputStream;
/**
* A factory for creating SOAPMessage objects.
*
* A JAXM client performs the following steps to create a message.
*
* - Creates a
MessageFactory object from a ProviderConnection
* object (con in the following line of code). The String passed to the
* createMessageFactory method is the name of of a messaging profile, which must be the
* URL for the schema. MessageFactory mf = con.createMessageFactory(schemaURL);
*
* - Calls the method
createMessage on the MessageFactory object. All
* messages produced by this MessageFactory object will have the header information
* appropriate for the messaging profile that was specified when the MessageFactory
* object was created. SOAPMessage m = mf.createMessage();
It is also
* possible to create a MessageFactory object using the method
* newInstance, as shown in the following line of code. MessageFactory mf =
* MessageFactory.newInstance();
A standalone client (a client that is not running in a
* container) can use the newInstance method to create a MessageFactory
* object.
*
* All MessageFactory objects, regardless of how they are created, will produce
* SOAPMessage objects that have the following elements by default:
*
* - A
SOAPPart object
*
* - A
SOAPEnvelope object
*
* - A
SOAPBody object
*
* - A
SOAPHeader object
If a MessageFactory object was
* created using a ProviderConnection object, which means that it was initialized with
* a specified profile, it will produce messages that also come prepopulated with additional entries
* in the SOAPHeader object and the SOAPBody object. The content of a new
* SOAPMessage object depends on which of the two MessageFactory methods
* is used to create it.
*
* createMessage() -- message has no content
This is the method clients
* would normally use to create a request message.createMessage(MimeHeaders, java.io.InputStream) -- message has content from the
* InputStream object and headers from the MimeHeaders object
This
* method can be used internally by a service implementation to create a message that is a response
* to a request.
*/
public abstract class MessageFactory {
/** Create a new MessageFactory. */
public MessageFactory() {
}
/**
* Creates a new MessageFactory object that is an instance of the default
* implementation.
*
* @return a new MessageFactory object
* @throws SOAPException if there was an error in creating the default implementation of the
* MessageFactory
*/
public static MessageFactory newInstance() throws SOAPException {
try {
MessageFactory factory = (MessageFactory)FactoryFinder.find(MessageFactory.class, null);
if (factory == null) {
factory = newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
}
return factory;
} catch (Exception exception) {
throw new SOAPException("Unable to create MessageFactory: " + exception.getMessage());
}
}
/**
* Creates a new SOAPMessage object with the default SOAPPart,
* SOAPEnvelope, SOAPBody, and SOAPHeader objects.
* Profile-specific message factories can choose to prepopulate the SOAPMessage
* object with profile-specific headers.
*
* Content can be added to this message's SOAPPart object, and the message can
* be sent "as is" when a message containing only a SOAP part is sufficient. Otherwise, the
* SOAPMessage object needs to create one or more AttachmentPart
* objects and add them to itself. Any content that is not in XML format must be in an
* AttachmentPart object.
*
* @return a new SOAPMessage object
* @throws SOAPException if a SOAP error occurs java.lang.UnsupportedOperationException - if the
* protocol of this MessageFactory instance is DYNAMIC_SOAP_PROTOCOL
*/
public abstract SOAPMessage createMessage() throws SOAPException;
/**
* Internalizes the contents of the given InputStream object into a new
* SOAPMessage object and returns the SOAPMessage object.
*
* @param mimeheaders the transport-specific headers passed to the message in a
* transport-independent fashion for creation of the message
* @param inputstream the InputStream object that contains the data for a message
* @return a new SOAPMessage object containing the data from the given
* InputStream object
* @throws IOException if there is a problem in reading data from the input stream
* @throws SOAPException if the message is invalid
*/
public abstract SOAPMessage createMessage(MimeHeaders mimeheaders,
InputStream inputstream)
throws IOException, SOAPException;
public static MessageFactory newInstance(String soapVersion)
throws SOAPException {
return SAAJMetaFactory.getInstance().newMessageFactory(soapVersion);
}
}