View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package javax.xml.soap;
17  
18  /**
19   * <P><CODE>SOAPElementFactory</CODE> is a factory for XML
20   * fragments that will eventually end up in the SOAP part. These
21   * fragments can be inserted as children of the <CODE>
22   * SOAPHeader</CODE> or <CODE>SOAPBody</CODE> or <CODE>
23   * SOAPEnvelope</CODE>.</P>
24   *
25   * <P>Elements created using this factory do not have the
26   * properties of an element that lives inside a SOAP header
27   * document. These elements are copied into the XML document tree
28   * when they are inserted.</P>
29   * @deprecated - Use javax.xml.soap.SOAPFactory for creating SOAPElements.
30   * @see SOAPFactory SOAPFactory
31   */
32  public class SOAPElementFactory {
33  
34      /**
35       * Create a new <code>SOAPElementFactory from a <code>SOAPFactory</code>.
36       *
37       * @param soapfactory  the <code>SOAPFactory</code> to use
38       */
39      private SOAPElementFactory(SOAPFactory soapfactory) {
40          sf = soapfactory;
41      }
42  
43      /**
44       * Create a <CODE>SOAPElement</CODE> object initialized with
45       * the given <CODE>Name</CODE> object.
46       * @param   name a <CODE>Name</CODE> object with
47       *     the XML name for the new element
48       * @return the new <CODE>SOAPElement</CODE> object that was
49       *     created
50       * @throws  SOAPException if there is an error in
51       *     creating the <CODE>SOAPElement</CODE> object
52       * @deprecated Use javax.xml.soap.SOAPFactory.createElement(javax.xml.soap.Name) instead
53       * @see SOAPFactory#createElement(javax.xml.soap.Name) SOAPFactory.createElement(javax.xml.soap.Name)
54       */
55      public SOAPElement create(Name name) throws SOAPException {
56          return sf.createElement(name);
57      }
58  
59      /**
60       * Create a <CODE>SOAPElement</CODE> object initialized with
61       * the given local name.
62       * @param   localName a <CODE>String</CODE> giving
63       *     the local name for the new element
64       * @return the new <CODE>SOAPElement</CODE> object that was
65       *     created
66       * @throws  SOAPException if there is an error in
67       *     creating the <CODE>SOAPElement</CODE> object
68       * @deprecated Use javax.xml.soap.SOAPFactory.createElement(String localName) instead
69       * @see SOAPFactory#createElement(java.lang.String) SOAPFactory.createElement(java.lang.String)
70       */
71      public SOAPElement create(String localName) throws SOAPException {
72          return sf.createElement(localName);
73      }
74  
75      /**
76       * Create a new <CODE>SOAPElement</CODE> object with the
77       * given local name, prefix and uri.
78       * @param   localName a <CODE>String</CODE> giving
79       *     the local name for the new element
80       * @param   prefix the prefix for this <CODE>
81       *     SOAPElement</CODE>
82       * @param   uri a <CODE>String</CODE> giving the
83       *     URI of the namespace to which the new element
84       *     belongs
85       * @return the new <CODE>SOAPElement</CODE> object that was
86       *     created
87       * @throws  SOAPException if there is an error in
88       *     creating the <CODE>SOAPElement</CODE> object
89       * @deprecated Use javax.xml.soap.SOAPFactory.createElement(String localName, String prefix, String uri) instead
90       * @see SOAPFactory#createElement(java.lang.String, java.lang.String, java.lang.String) SOAPFactory.createElement(java.lang.String, java.lang.String, java.lang.String)
91       */
92      public SOAPElement create(String localName, String prefix, String uri)
93              throws SOAPException {
94          return sf.createElement(localName, prefix, uri);
95      }
96  
97      /**
98       * Creates a new instance of <CODE>SOAPElementFactory</CODE>.
99       *
100      * @return a new instance of a <CODE>
101      *     SOAPElementFactory</CODE>
102      * @throws  SOAPException if there was an error creating
103      *     the default <CODE>SOAPElementFactory
104      */
105     public static SOAPElementFactory newInstance() throws SOAPException {
106 
107         try {
108             return new SOAPElementFactory(SOAPFactory.newInstance());
109         } catch (Exception exception) {
110             throw new SOAPException("Unable to create SOAP Element Factory: "
111                                     + exception.getMessage());
112         }
113     }
114 
115     private SOAPFactory sf;
116 }