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 }