Home » xml-commons-external-1.4.01-src » javax » xml » soap » [javadoc | source]

    1   /*
    2    * Copyright 2005-2006 Sun Microsystems, Inc.  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.  Sun designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
   22    * CA 95054 USA or visit www.sun.com if you need additional information or
   23    * have any questions.
   24    */
   25   /*
   26    * $Id: MessageFactory.java,v 1.11 2006/03/30 00:59:38 ofung Exp $
   27    * $Revision: 1.11 $
   28    * $Date: 2006/03/30 00:59:38 $
   29    */
   30   
   31   
   32   package javax.xml.soap;
   33   
   34   
   35   import java.io.IOException;
   36   import java.io.InputStream;
   37   
   38   /**
   39    * A factory for creating <code>SOAPMessage</code> objects.
   40    * <P>
   41    * A SAAJ client can create a <code>MessageFactory</code> object
   42    * using the method <code>newInstance</code>, as shown in the following
   43    * lines of code.
   44    * <PRE>
   45    *       MessageFactory mf = MessageFactory.newInstance();
   46    *       MessageFactory mf12 = MessageFactory.newInstance(SOAPConstants.SOAP_1_2_PROTOCOL);
   47    * </PRE>
   48    * <P>
   49    * All <code>MessageFactory</code> objects, regardless of how they are
   50    * created, will produce <code>SOAPMessage</code> objects that
   51    * have the following elements by default:
   52    * <UL>
   53    *  <LI>A <code>SOAPPart</code> object
   54    *  <LI>A <code>SOAPEnvelope</code> object
   55    *  <LI>A <code>SOAPBody</code> object
   56    *  <LI>A <code>SOAPHeader</code> object
   57    * </UL>
   58    * In some cases, specialized MessageFactory objects may be obtained that produce messages
   59    * prepopulated with additional entries in the <code>SOAPHeader</code> object and the
   60    * <code>SOAPBody</code> object.
   61    * The content of a new <code>SOAPMessage</code> object depends on which of the two
   62    * <code>MessageFactory</code> methods is used to create it.
   63    * <UL>
   64    *  <LI><code>createMessage()</code> <BR>
   65    *      This is the method clients would normally use to create a request message.
   66    *  <LI><code>createMessage(MimeHeaders, java.io.InputStream)</code> -- message has
   67    *       content from the <code>InputStream</code> object and headers from the
   68    *       <code>MimeHeaders</code> object <BR>
   69    *        This method can be used internally by a service implementation to
   70    *        create a message that is a response to a request.
   71    * </UL>
   72    */
   73   public abstract class MessageFactory {
   74   
   75       static private final String DEFAULT_MESSAGE_FACTORY
   76           = "com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl";
   77   
   78       static private final String MESSAGE_FACTORY_PROPERTY
   79           = "javax.xml.soap.MessageFactory";
   80   
   81       /**
   82        * Creates a new <code>MessageFactory</code> object that is an instance
   83        * of the default implementation (SOAP 1.1),
   84        *
   85        * This method uses the following ordered lookup procedure to determine the MessageFactory implementation class to load:
   86        * <UL>
   87        *  <LI> Use the javax.xml.soap.MessageFactory system property.
   88        *  <LI> Use the properties file "lib/jaxm.properties" in the JRE directory. This configuration file is in standard
   89        * java.util.Properties format and contains the fully qualified name of the implementation class with the key being the
   90        * system property defined above.
   91        *  <LI> Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API
   92        * will look for a classname in the file META-INF/services/javax.xml.soap.MessageFactory in jars available to the runtime.
   93        *  <LI> Use the SAAJMetaFactory instance to locate the MessageFactory implementation class.
   94        * </UL>
   95   
   96        *
   97        * @return a new instance of a <code>MessageFactory</code>
   98        *
   99        * @exception SOAPException if there was an error in creating the
  100        *            default implementation of the
  101        *            <code>MessageFactory</code>.
  102        * @see SAAJMetaFactory
  103        */
  104   
  105       public static MessageFactory newInstance()
  106           throws SOAPException {
  107           try {
  108               MessageFactory factory = (MessageFactory)
  109                   FactoryFinder.find(MESSAGE_FACTORY_PROPERTY);
  110   
  111               if (factory != null)
  112                   return factory;
  113   
  114               return newInstance(SOAPConstants.SOAP_1_1_PROTOCOL);
  115           } catch (Exception ex) {
  116               throw new SOAPException(
  117                       "Unable to create message factory for SOAP: "
  118                                       +ex.getMessage());
  119           }
  120   
  121       }
  122   
  123       /**
  124        * Creates a new <code>MessageFactory</code> object that is an instance
  125        * of the specified implementation.  May be a dynamic message factory,
  126        * a SOAP 1.1 message factory, or a SOAP 1.2 message factory. A dynamic
  127        * message factory creates messages based on the MIME headers specified
  128        * as arguments to the <code>createMessage</code> method.
  129        *
  130        * This method uses the SAAJMetaFactory to locate the implementation class
  131        * and create the MessageFactory instance.
  132        *
  133        * @return a new instance of a <code>MessageFactory</code>
  134        *
  135        * @param protocol  a string constant representing the class of the
  136        *                   specified message factory implementation. May be
  137        *                   either <code>DYNAMIC_SOAP_PROTOCOL</code>,
  138        *                   <code>DEFAULT_SOAP_PROTOCOL</code> (which is the same
  139        *                   as) <code>SOAP_1_1_PROTOCOL</code>, or
  140        *                   <code>SOAP_1_2_PROTOCOL</code>.
  141        *
  142        * @exception SOAPException if there was an error in creating the
  143        *            specified implementation of  <code>MessageFactory</code>.
  144        * @see SAAJMetaFactory
  145        * @since SAAJ 1.3
  146        */
  147       public static MessageFactory newInstance(String protocol) throws SOAPException {
  148           return SAAJMetaFactory.getInstance().newMessageFactory(protocol);
  149       }
  150   
  151       /**
  152        * Creates a new <code>SOAPMessage</code> object with the default
  153        * <code>SOAPPart</code>, <code>SOAPEnvelope</code>, <code>SOAPBody</code>,
  154        * and <code>SOAPHeader</code> objects. Profile-specific message factories
  155        * can choose to prepopulate the <code>SOAPMessage</code> object with
  156        * profile-specific headers.
  157        * <P>
  158        * Content can be added to this message's <code>SOAPPart</code> object, and
  159        * the message can be sent "as is" when a message containing only a SOAP part
  160        * is sufficient. Otherwise, the <code>SOAPMessage</code> object needs
  161        * to create one or more <code>AttachmentPart</code> objects and
  162        * add them to itself. Any content that is not in XML format must be
  163        * in an <code>AttachmentPart</code> object.
  164        *
  165        * @return a new <code>SOAPMessage</code> object
  166        * @exception SOAPException if a SOAP error occurs
  167        * @exception UnsupportedOperationException if the protocol of this
  168        *      <code>MessageFactory</code> instance is <code>DYNAMIC_SOAP_PROTOCOL</code>
  169        */
  170       public abstract SOAPMessage createMessage()
  171           throws SOAPException;
  172   
  173       /**
  174        * Internalizes the contents of the given <code>InputStream</code> object into a
  175        * new <code>SOAPMessage</code> object and returns the <code>SOAPMessage</code>
  176        * object.
  177        *
  178        * @param in the <code>InputStream</code> object that contains the data
  179        *           for a message
  180        * @param headers the transport-specific headers passed to the
  181        *        message in a transport-independent fashion for creation of the
  182        *        message
  183        * @return a new <code>SOAPMessage</code> object containing the data from
  184        *         the given <code>InputStream</code> object
  185        *
  186        * @exception IOException if there is a problem in reading data from
  187        *            the input stream
  188        *
  189        * @exception SOAPException may be thrown if the message is invalid
  190        *
  191        * @exception IllegalArgumentException if the <code>MessageFactory</code>
  192        *      requires one or more MIME headers to be present in the
  193        *      <code>headers</code> parameter and they are missing.
  194        *      <code>MessageFactory</code> implementations for
  195        *      <code>SOAP_1_1_PROTOCOL</code> or
  196        *      <code>SOAP_1_2_PROTOCOL</code> must not throw
  197        *      <code>IllegalArgumentException</code> for this reason.
  198        */
  199       public abstract SOAPMessage createMessage(MimeHeaders headers,
  200                                                 InputStream in)
  201           throws IOException, SOAPException;
  202   }

Home » xml-commons-external-1.4.01-src » javax » xml » soap » [javadoc | source]