1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package javax.xml.parsers;
18
19 import org.apache.mirae.j2me.xml.SAXParserFactoryImpl;
20 import org.xml.sax.SAXException;
21 import org.xml.sax.SAXNotRecognizedException;
22 import org.xml.sax.SAXNotSupportedException;
23
24 /***
25 * Defines a factory API that enables applications to configure and
26 * obtain a SAX based parser to parse XML documents.<p>
27 * An implementation of the <code>SAXParserFactory</code> class is
28 * <em>NOT</em> guaranteed to be thread safe. It is up to the user application
29 * to make sure about the use of the <code>SAXParserFactory</code> from
30 * more than one thread. Alternatively the application can have one instance
31 * of the <code>SAXParserFactory</code> per thread.
32 * An application can use the same instance of the factory to obtain one or
33 * more instances of the <code>SAXParser</code> provided the instance
34 * of the factory isn't being used in more than one thread at a time.
35 * <p>
36 *
37 * The static <code>newInstance</code> method returns a new concrete
38 * implementation of this class.
39 *
40 * @author Ias (iasandcb@tmax.co.kr)
41 */
42
43 public abstract class SAXParserFactory {
44 private boolean validating = false;
45 private boolean namespaceAware= false;
46
47 protected SAXParserFactory () {
48
49 }
50
51 /***
52 * Obtain a new instance of a <code>SAXParserFactory</code>. This
53 * static method creates a new factory instance
54 * This method uses the following ordered lookup procedure to determine
55 * the <code>SAXParserFactory</code> implementation class to
56 * load:
57 * <ul>
58 * <li>
59 * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
60 * property.
61 * </li>
62 * <li>
63 * Use the properties file "lib/jaxp.properties" in the JRE directory.
64 * This configuration file is in standard <code>java.util.Properties
65 * </code> format and contains the fully qualified name of the
66 * implementation class with the key being the system property defined
67 * above.
68 * </li>
69 * <li>
70 * Use the Services API (as detailed in the JAR specification), if
71 * available, to determine the classname. The Services API will look
72 * for a classname in the file
73 * <code>META-INF/services/javax.xml.parsers.SAXParserFactory</code>
74 * in jars available to the runtime.
75 * </li>
76 * <li>
77 * Platform default <code>SAXParserFactory</code> instance.
78 * </li>
79 * </ul>
80 *
81 * Once an application has obtained a reference to a
82 * <code>SAXParserFactory</code> it can use the factory to
83 * configure and obtain parser instances.
84 *
85 * @return A new instance of a SAXParserFactory.
86 *
87 * @exception FactoryConfigurationError if the implementation is
88 * not available or cannot be instantiated.
89 */
90
91 public static SAXParserFactory newInstance()
92 throws FactoryConfigurationError
93 {
94 return new SAXParserFactoryImpl();
95 }
96
97 /***
98 * Creates a new instance of a SAXParser using the currently
99 * configured factory parameters.
100 *
101 * @return A new instance of a SAXParser.
102 *
103 * @exception ParserConfigurationException if a parser cannot
104 * be created which satisfies the requested configuration.
105 */
106
107 public abstract SAXParser newSAXParser()
108 throws ParserConfigurationException, SAXException;
109
110
111 /***
112 * Specifies that the parser produced by this code will
113 * provide support for XML namespaces. By default the value of this is set
114 * to <code>false</code>.
115 *
116 * @param awareness true if the parser produced by this code will
117 * provide support for XML namespaces; false otherwise.
118 */
119
120 public void setNamespaceAware(boolean awareness)
121 {
122 this.namespaceAware = awareness;
123 }
124
125 /***
126 * Specifies that the parser produced by this code will
127 * validate documents as they are parsed. By default the value of this is
128 * set to <code>false</code>.
129 *
130 * @param validating true if the parser produced by this code will
131 * validate documents as they are parsed; false otherwise.
132 */
133
134 public void setValidating(boolean validating)
135 {
136 this.validating = validating;
137 }
138
139 /***
140 * Indicates whether or not the factory is configured to produce
141 * parsers which are namespace aware.
142 *
143 * @return true if the factory is configured to produce
144 * parsers which are namespace aware; false otherwise.
145 */
146
147 public boolean isNamespaceAware() {
148 return namespaceAware;
149 }
150
151 /***
152 * Indicates whether or not the factory is configured to produce
153 * parsers which validate the XML content during parse.
154 *
155 * @return true if the factory is configured to produce parsers which validate
156 * the XML content during parse; false otherwise.
157 */
158
159 public boolean isValidating() {
160 return validating;
161 }
162
163 /***
164 *
165 * Sets the particular feature in the underlying implementation of
166 * org.xml.sax.XMLReader.
167 * A list of the core features and properties can be found at
168 * <a href="http://www.megginson.com/SAX/Java/features.html"> http://www.megginson.com/SAX/Java/features.html </a>
169 *
170 * @param name The name of the feature to be set.
171 * @param value The value of the feature to be set.
172 * @exception SAXNotRecognizedException When the underlying XMLReader does
173 * not recognize the property name.
174 *
175 * @exception SAXNotSupportedException When the underlying XMLReader
176 * recognizes the property name but doesn't support the
177 * property.
178 *
179 * @see org.xml.sax.XMLReader#setFeature
180 */
181 public abstract void setFeature(String name, boolean value)
182 throws ParserConfigurationException, SAXNotRecognizedException,
183 SAXNotSupportedException;
184
185 /***
186 *
187 * Returns the particular property requested for in the underlying
188 * implementation of org.xml.sax.XMLReader.
189 *
190 * @param name The name of the property to be retrieved.
191 * @return Value of the requested property.
192 *
193 * @exception SAXNotRecognizedException When the underlying XMLReader does
194 * not recognize the property name.
195 *
196 * @exception SAXNotSupportedException When the underlying XMLReader
197 * recognizes the property name but doesn't support the
198 * property.
199 *
200 * @see org.xml.sax.XMLReader#getProperty
201 */
202 public abstract boolean getFeature(String name)
203 throws ParserConfigurationException, SAXNotRecognizedException,
204 SAXNotSupportedException;
205 }