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   }