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    }