001 /*
002 * Copyright 2001-2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package javax.xml.soap;
017
018 /**
019 * <code>SOAPFactory</code> is a factory for creating various objects
020 * that exist in the SOAP XML tree.
021 *
022 * <code>SOAPFactory</code> can be
023 * used to create XML fragments that will eventually end up in the
024 * SOAP part. These fragments can be inserted as children of the
025 * <code>SOAPHeaderElement</code> or <code>SOAPBodyElement</code> or
026 * <code>SOAPEnvelope</code>.
027 *
028 * <code>SOAPFactory</code> also has methods to create
029 * <code>javax.xml.soap.Detail</code> objects as well as
030 * <code>java.xml.soap.Name</code> objects.
031 *
032 */
033 public abstract class SOAPFactory {
034
035 public SOAPFactory() {}
036
037 /**
038 * Create a <code>SOAPElement</code> object initialized with the
039 * given <code>Name</code> object.
040 *
041 * @param name a <code>Name</code> object with the XML name for
042 * the new element
043 * @return the new <code>SOAPElement</code> object that was
044 * created
045 * @throws SOAPException if there is an error in creating the
046 * <code>SOAPElement</code> object
047 */
048 public abstract SOAPElement createElement(Name name) throws SOAPException;
049
050 /**
051 * Create a <code>SOAPElement</code> object initialized with the
052 * given local name.
053 *
054 * @param localName a <code>String</code> giving the local name for
055 * the new element
056 * @return the new <code>SOAPElement</code> object that was
057 * created
058 * @throws SOAPException if there is an error in creating the
059 * <code>SOAPElement</code> object
060 */
061 public abstract SOAPElement createElement(String localName) throws SOAPException;
062
063 /**
064 * Create a new <code>SOAPElement</code> object with the given
065 * local name, prefix and uri.
066 *
067 * @param localName a <code>String</code> giving the local name
068 * for the new element
069 * @param prefix the prefix for this <code>SOAPElement</code>
070 * @param uri a <code>String</code> giving the URI of the
071 * namespace to which the new element belongs
072 * @return the new <code>SOAPElement</code> object that was
073 * created
074 * @throws SOAPException if there is an error in creating the
075 * <code>SOAPElement</code> object
076 */
077 public abstract SOAPElement createElement(String localName, String prefix, String uri)
078 throws SOAPException;
079
080 /**
081 * Creates a new <code>Detail</code> object which serves as a container
082 * for <code>DetailEntry</code> objects.
083 * <p>
084 * This factory method creates <code>Detail</code> objects for use in
085 * situations where it is not practical to use the <code>SOAPFault</code>
086 * abstraction.
087 *
088 * @return a <code>Detail</code> object
089 * @throws SOAPException if there is a SOAP error
090 */
091 public abstract Detail createDetail() throws SOAPException;
092
093 /**
094 * Creates a new <code>Name</code> object initialized with the
095 * given local name, namespace prefix, and namespace URI.
096 * <p>
097 * This factory method creates <code>Name</code> objects for use in
098 * situations where it is not practical to use the <code>SOAPEnvelope</code>
099 * abstraction.
100 *
101 * @param localName a <code>String</code> giving the local name
102 * @param prefix a <code>String</code> giving the prefix of the namespace
103 * @param uri a <code>String</code> giving the URI of the namespace
104 * @return a <code>Name</code> object initialized with the given
105 * local name, namespace prefix, and namespace URI
106 * @throws SOAPException if there is a SOAP error
107 */
108 public abstract Name createName(String localName, String prefix, String uri)
109 throws SOAPException;
110
111 /**
112 * Creates a new <code>Name</code> object initialized with the
113 * given local name.
114 * <p>
115 * This factory method creates <code>Name</code> objects for use in
116 * situations where it is not practical to use the <code>SOAPEnvelope</code>
117 * abstraction.
118 *
119 * @param localName a <code>String</code> giving the local name
120 * @return a <code>Name</code> object initialized with the given
121 * local name
122 * @throws SOAPException if there is a SOAP error
123 */
124 public abstract Name createName(String localName) throws SOAPException;
125
126 /**
127 * Creates a new instance of <code>SOAPFactory</code>.
128 *
129 * @return a new instance of a <code>SOAPFactory</code>
130 * @throws SOAPException if there was an error creating the
131 * default <code>SOAPFactory</code>
132 */
133 public static SOAPFactory newInstance() throws SOAPException {
134
135 try {
136 return (SOAPFactory) FactoryFinder.find(SF_PROPERTY, DEFAULT_SF);
137 } catch (Exception exception) {
138 throw new SOAPException("Unable to create SOAP Factory: "
139 + exception.getMessage());
140 }
141 }
142
143 private static final String SF_PROPERTY = "javax.xml.soap.SOAPFactory";
144
145 private static final String DEFAULT_SF =
146 "org.apache.axis.soap.SOAPFactoryImpl";
147 }