KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > soap > MessageFactory


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