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 /**
023 * <code>SOAPFactory</code> is a factory for creating various objects
024 * that exist in the SOAP XML tree.
025 *
026 * <code>SOAPFactory</code> can be
027 * used to create XML fragments that will eventually end up in the
028 * SOAP part. These fragments can be inserted as children of the
029 * <code>SOAPHeaderElement</code> or <code>SOAPBodyElement</code> or
030 * <code>SOAPEnvelope</code>.
031 *
032 * <code>SOAPFactory</code> also has methods to create
033 * <code>javax.xml.soap.Detail</code> objects as well as
034 * <code>java.xml.soap.Name</code> objects.
035 *
036 */
037 public abstract class SOAPFactory {
038
039 public SOAPFactory() {}
040
041 /**
042 * Create a <code>SOAPElement</code> object initialized with the
043 * given <code>Name</code> object.
044 *
045 * @param name a <code>Name</code> object with the XML name for
046 * the new element
047 * @return the new <code>SOAPElement</code> object that was
048 * created
049 * @throws SOAPException if there is an error in creating the
050 * <code>SOAPElement</code> object
051 */
052 public abstract SOAPElement createElement(Name name) throws SOAPException;
053
054 /**
055 * Create a <code>SOAPElement</code> object initialized with the
056 * given local name.
057 *
058 * @param localName a <code>String</code> giving the local name for
059 * the new element
060 * @return the new <code>SOAPElement</code> object that was
061 * created
062 * @throws SOAPException if there is an error in creating the
063 * <code>SOAPElement</code> object
064 */
065 public abstract SOAPElement createElement(String localName) throws SOAPException;
066
067 /**
068 * Create a new <code>SOAPElement</code> object with the given
069 * local name, prefix and uri.
070 *
071 * @param localName a <code>String</code> giving the local name
072 * for the new element
073 * @param prefix the prefix for this <code>SOAPElement</code>
074 * @param uri a <code>String</code> giving the URI of the
075 * namespace to which the new element belongs
076 * @return the new <code>SOAPElement</code> object that was
077 * created
078 * @throws SOAPException if there is an error in creating the
079 * <code>SOAPElement</code> object
080 */
081 public abstract SOAPElement createElement(String localName, String prefix, String uri)
082 throws SOAPException;
083
084 /**
085 * Creates a new <code>Detail</code> object which serves as a container
086 * for <code>DetailEntry</code> objects.
087 * <p>
088 * This factory method creates <code>Detail</code> objects for use in
089 * situations where it is not practical to use the <code>SOAPFault</code>
090 * abstraction.
091 *
092 * @return a <code>Detail</code> object
093 * @throws SOAPException if there is a SOAP error
094 */
095 public abstract Detail createDetail() throws SOAPException;
096
097 /**
098 * Creates a new <code>Name</code> object initialized with the
099 * given local name, namespace prefix, and namespace URI.
100 * <p>
101 * This factory method creates <code>Name</code> objects for use in
102 * situations where it is not practical to use the <code>SOAPEnvelope</code>
103 * abstraction.
104 *
105 * @param localName a <code>String</code> giving the local name
106 * @param prefix a <code>String</code> giving the prefix of the namespace
107 * @param uri a <code>String</code> giving the URI of the namespace
108 * @return a <code>Name</code> object initialized with the given
109 * local name, namespace prefix, and namespace URI
110 * @throws SOAPException if there is a SOAP error
111 */
112 public abstract Name createName(String localName, String prefix, String uri)
113 throws SOAPException;
114
115 /**
116 * Creates a new <code>Name</code> object initialized with the
117 * given local name.
118 * <p>
119 * This factory method creates <code>Name</code> objects for use in
120 * situations where it is not practical to use the <code>SOAPEnvelope</code>
121 * abstraction.
122 *
123 * @param localName a <code>String</code> giving the local name
124 * @return a <code>Name</code> object initialized with the given
125 * local name
126 * @throws SOAPException if there is a SOAP error
127 */
128 public abstract Name createName(String localName) throws SOAPException;
129
130 /**
131 * Creates a new instance of <code>SOAPFactory</code>.
132 *
133 * @return a new instance of a <code>SOAPFactory</code>
134 * @throws SOAPException if there was an error creating the
135 * default <code>SOAPFactory</code>
136 */
137 public static SOAPFactory newInstance() throws SOAPException {
138
139 try {
140 return (SOAPFactory) FactoryFinder.find(SF_PROPERTY, DEFAULT_SF);
141 } catch (Exception exception) {
142 throw new SOAPException("Unable to create SOAP Factory: "
143 + exception.getMessage());
144 }
145 }
146
147 private static final String SF_PROPERTY = "javax.xml.soap.SOAPFactory";
148
149 private static final String DEFAULT_SF =
150 "org.apache.axis.soap.SOAPFactoryImpl";
151 }