Save This Page
1 /* Copyright 2004 The Apache Software Foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.apache.xmlbeans;
17
18 import org.w3c.dom.Node;
19 import org.w3c.dom.DOMImplementation;
20
21 import java.io.IOException;
22 import java.io.InputStream;
23 import java.io.Reader;
24 import java.lang.ref.SoftReference;
25
26 import javax.xml.stream.XMLStreamReader;
27
28 import org.apache.xmlbeans.xml.stream.XMLInputStream;
29 import org.apache.xmlbeans.xml.stream.XMLStreamException;
30
31 /**
32 * A hook for the XML Bean Factory mechanism.
33 * Provided for advanced users who wish to provide their own
34 * implementation of the Factory.parse methods. This is used, for example,
35 * to defer reading XML streams until needed.
36 * <p>
37 * To use the hook, call XmlFactoryHook.ThreadContext.setHook(), passing
38 * your own XmlFactoryHook implementation. Then every call to a Factory
39 * method will be delgated to your hook.
40 *
41 * <pre>
42 * MyHook hook = new MyHook();
43 * XmlFactoryHook.ThreadContext.setHook(hook);
44 * // this results in a call to hook.parse(...)
45 * XmlObject.Factory.parse(new File("test.xml"));
46 * </pre>
47 *
48 * If the hook needs to turn around and invoke the built-in parsers, then
49 * it should do so by calling the appropriate method on the passed
50 * SchemaTypeLoader. Since SchemaTypeLoader.parse() methods delegate
51 * to the registered hook, a hook that wishes to actually invoke the
52 * default parser without having itself called back again should
53 * unregister itself before calling loader.parse(), and then re-register
54 * itself again after the call.
55 * <pre>
56 * void parse(SchemaTypeLoader loader, ...)
57 * {
58 * XmlFactoryHook remember = XmlFactoryHook.ThreadContext.getHook();
59 * XmlFactoryHook.ThreadContext.setHook(null);
60 * loader.parse(...); // isn't hooked.
61 * XmlFactoryHook.ThreadContext.setHook(remember);
62 * }
63 * </pre>
64 */
65 public interface XmlFactoryHook
66 {
67 /** Hooks Factory.newInstance calls */
68 public XmlObject newInstance ( SchemaTypeLoader loader, SchemaType type, XmlOptions options );
69 /** Hooks Factory.parse calls */
70 public XmlObject parse ( SchemaTypeLoader loader, String xmlText, SchemaType type, XmlOptions options ) throws XmlException;
71 /** Hooks Factory.parse calls */
72 public XmlObject parse ( SchemaTypeLoader loader, InputStream jiois, SchemaType type, XmlOptions options ) throws XmlException, IOException;
73 /** Hooks Factory.parse calls */
74 public XmlObject parse ( SchemaTypeLoader loader, XMLStreamReader xsr, SchemaType type, XmlOptions options ) throws XmlException;
75 /** Hooks Factory.parse calls */
76 public XmlObject parse ( SchemaTypeLoader loader, Reader jior, SchemaType type, XmlOptions options ) throws XmlException, IOException;
77 /** Hooks Factory.parse calls */
78 public XmlObject parse ( SchemaTypeLoader loader, Node node, SchemaType type, XmlOptions options ) throws XmlException;
79 /** Hooks Factory.parse calls
80 * @deprecated XMLInputStream was deprecated by XMLStreamReader from STaX - jsr173 API.
81 */
82 public XmlObject parse ( SchemaTypeLoader loader, XMLInputStream xis, SchemaType type, XmlOptions options ) throws XmlException, XMLStreamException;
83 /** Hooks Factory.newXmlSaxHandler calls */
84 public XmlSaxHandler newXmlSaxHandler ( SchemaTypeLoader loader, SchemaType type, XmlOptions options );
85 /** Hooks Factory.newDomImplementation calls */
86 public DOMImplementation newDomImplementation ( SchemaTypeLoader loader, XmlOptions options );
87
88 /**
89 * Used to manage the XmlFactoryHook for the current thread.
90 */
91 public final static class ThreadContext
92 {
93 private static ThreadLocal threadHook = new ThreadLocal();
94
95 /**
96 * Returns the current thread's hook, or null if none.
97 */
98 public static XmlFactoryHook getHook()
99 {
100 SoftReference softRef = (SoftReference)threadHook.get();
101 return softRef==null ? null : (XmlFactoryHook)softRef.get();
102 }
103
104 /**
105 * Sets the hook for the current thread.
106 */
107 public static void setHook(XmlFactoryHook hook)
108 {
109 threadHook.set(new SoftReference(hook));
110 }
111
112 // provided to prevent unwanted construction
113 private ThreadContext()
114 {
115 }
116 }
117 }