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   * <code>SOAPFactory</code> is a factory for creating various objects
20   * that exist in the SOAP XML tree.
21   *
22   * <code>SOAPFactory</code> can be
23   * used to create XML fragments that will eventually end up in the
24   * SOAP part. These fragments can be inserted as children of the
25   * <code>SOAPHeaderElement</code> or <code>SOAPBodyElement</code> or
26   * <code>SOAPEnvelope</code>.
27   *
28   * <code>SOAPFactory</code> also has methods to create
29   * <code>javax.xml.soap.Detail</code> objects as well as
30   * <code>java.xml.soap.Name</code> objects.
31   *
32   */
33  public abstract class SOAPFactory {
34  
35      public SOAPFactory() {}
36  
37      /**
38       * Create a <code>SOAPElement</code> object initialized with the
39       * given <code>Name</code> object.
40       *
41       * @param name a <code>Name</code> object with the XML name for
42       *        the new element
43       * @return  the new <code>SOAPElement</code> object that was
44       *    created
45       * @throws SOAPException if there is an error in creating the
46       *       <code>SOAPElement</code> object
47       */
48      public abstract SOAPElement createElement(Name name) throws SOAPException;
49  
50      /**
51       * Create a <code>SOAPElement</code> object initialized with the
52       * given local name.
53       *
54       * @param localName a <code>String</code> giving the local name for
55       *       the new element
56       * @return the new <code>SOAPElement</code> object that was
57       *    created
58       * @throws SOAPException if there is an error in creating the
59       *       <code>SOAPElement</code> object
60       */
61      public abstract SOAPElement createElement(String localName) throws SOAPException;
62  
63      /**
64       * Create a new <code>SOAPElement</code> object with the given
65       * local name, prefix and uri.
66       *
67       * @param localName a <code>String</code> giving the local name
68       *            for the new element
69       * @param prefix the prefix for this <code>SOAPElement</code>
70       * @param uri a <code>String</code> giving the URI of the
71       *      namespace to which the new element belongs
72       * @return the new <code>SOAPElement</code> object that was
73       *    created
74       * @throws SOAPException if there is an error in creating the
75       *      <code>SOAPElement</code> object
76       */
77      public abstract SOAPElement createElement(String localName, String prefix, String uri)
78          throws SOAPException;
79  
80      /**
81       * Creates a new <code>Detail</code> object which serves as a container
82       * for <code>DetailEntry</code> objects.
83       * <p>
84       * This factory method creates <code>Detail</code> objects for use in
85       * situations where it is not practical to use the <code>SOAPFault</code>
86       * abstraction.
87       *
88       * @return a <code>Detail</code> object
89       * @throws SOAPException if there is a SOAP error
90       */
91      public abstract Detail createDetail() throws SOAPException;
92  
93      /**
94       * Creates a new <code>Name</code> object initialized with the
95       * given local name, namespace prefix, and namespace URI.
96       * <p>
97       * This factory method creates <code>Name</code> objects for use in
98       * situations where it is not practical to use the <code>SOAPEnvelope</code>
99       * 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 }