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     * <P><CODE>SOAPElementFactory</CODE> is a factory for XML
024     * fragments that will eventually end up in the SOAP part. These
025     * fragments can be inserted as children of the <CODE>
026     * SOAPHeader</CODE> or <CODE>SOAPBody</CODE> or <CODE>
027     * SOAPEnvelope</CODE>.</P>
028     *
029     * <P>Elements created using this factory do not have the
030     * properties of an element that lives inside a SOAP header
031     * document. These elements are copied into the XML document tree
032     * when they are inserted.</P>
033     * @deprecated - Use javax.xml.soap.SOAPFactory for creating SOAPElements.
034     * @see SOAPFactory SOAPFactory
035     */
036    public class SOAPElementFactory {
037    
038        /**
039         * Create a new <code>SOAPElementFactory from a <code>SOAPFactory</code>.
040         *
041         * @param soapfactory  the <code>SOAPFactory</code> to use
042         */
043        private SOAPElementFactory(SOAPFactory soapfactory) {
044            sf = soapfactory;
045        }
046    
047        /**
048         * Create a <CODE>SOAPElement</CODE> object initialized with
049         * the given <CODE>Name</CODE> object.
050         * @param   name a <CODE>Name</CODE> object with
051         *     the XML name for the new element
052         * @return the new <CODE>SOAPElement</CODE> object that was
053         *     created
054         * @throws  SOAPException if there is an error in
055         *     creating the <CODE>SOAPElement</CODE> object
056         * @deprecated Use javax.xml.soap.SOAPFactory.createElement(javax.xml.soap.Name) instead
057         * @see SOAPFactory#createElement(javax.xml.soap.Name) SOAPFactory.createElement(javax.xml.soap.Name)
058         */
059        public SOAPElement create(Name name) throws SOAPException {
060            return sf.createElement(name);
061        }
062    
063        /**
064         * Create a <CODE>SOAPElement</CODE> object initialized with
065         * the given local name.
066         * @param   localName a <CODE>String</CODE> giving
067         *     the local name for the new element
068         * @return the new <CODE>SOAPElement</CODE> object that was
069         *     created
070         * @throws  SOAPException if there is an error in
071         *     creating the <CODE>SOAPElement</CODE> object
072         * @deprecated Use javax.xml.soap.SOAPFactory.createElement(String localName) instead
073         * @see SOAPFactory#createElement(java.lang.String) SOAPFactory.createElement(java.lang.String)
074         */
075        public SOAPElement create(String localName) throws SOAPException {
076            return sf.createElement(localName);
077        }
078    
079        /**
080         * Create a new <CODE>SOAPElement</CODE> object with the
081         * given local name, prefix and uri.
082         * @param   localName a <CODE>String</CODE> giving
083         *     the local name for the new element
084         * @param   prefix the prefix for this <CODE>
085         *     SOAPElement</CODE>
086         * @param   uri a <CODE>String</CODE> giving the
087         *     URI of the namespace to which the new element
088         *     belongs
089         * @return the new <CODE>SOAPElement</CODE> object that was
090         *     created
091         * @throws  SOAPException if there is an error in
092         *     creating the <CODE>SOAPElement</CODE> object
093         * @deprecated Use javax.xml.soap.SOAPFactory.createElement(String localName, String prefix, String uri) instead
094         * @see SOAPFactory#createElement(java.lang.String, java.lang.String, java.lang.String) SOAPFactory.createElement(java.lang.String, java.lang.String, java.lang.String)
095         */
096        public SOAPElement create(String localName, String prefix, String uri)
097                throws SOAPException {
098            return sf.createElement(localName, prefix, uri);
099        }
100    
101        /**
102         * Creates a new instance of <CODE>SOAPElementFactory</CODE>.
103         *
104         * @return a new instance of a <CODE>
105         *     SOAPElementFactory</CODE>
106         * @throws  SOAPException if there was an error creating
107         *     the default <CODE>SOAPElementFactory
108         */
109        public static SOAPElementFactory newInstance() throws SOAPException {
110    
111            try {
112                return new SOAPElementFactory(SOAPFactory.newInstance());
113            } catch (Exception exception) {
114                throw new SOAPException("Unable to create SOAP Element Factory: "
115                                        + exception.getMessage());
116            }
117        }
118    
119        private SOAPFactory sf;
120    }