lib/classpath/external/w3c_dom/org/w3c/dom/bootstrap/DOMImplementationRegistry.java

   1 /*
   2  * Copyright (c) 2004 World Wide Web Consortium,
   3  *
   4  * (Massachusetts Institute of Technology, European Research Consortium for
   5  * Informatics and Mathematics, Keio University). All Rights Reserved. This
   6  * work is distributed under the W3C(r) Software License [1] in the hope that
   7  * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
   8  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   9  *
  10  * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
  11  */
  12
  13
  14 package org.w3c.dom.bootstrap;
  15
  16 import java.util.StringTokenizer;
  17 import java.util.Vector;
  18 import org.w3c.dom.DOMImplementationSource;
  19 import org.w3c.dom.DOMImplementationList;
  20 import org.w3c.dom.DOMImplementation;
  21 import java.io.InputStream;
  22 import java.io.BufferedReader;
  23 import java.io.InputStreamReader;
  24 import java.security.AccessController;
  25 import java.security.PrivilegedAction;
  26
  27 /**
  28  * A factory that enables applications to obtain instances of
  29  * <code>DOMImplementation</code>.
  30  *
  31  * <p>
  32  * Example:
  33  * </p>
  34  *
  35  * <pre class='example'>
  36  *  // get an instance of the DOMImplementation registry
  37  *  DOMImplementationRegistry registry =
  38  *       DOMImplementationRegistry.newInstance();
  39  *  // get a DOM implementation the Level 3 XML module
  40  *  DOMImplementation domImpl =
  41  *       registry.getDOMImplementation("XML 3.0");
  42  * </pre>
  43  *
  44  * <p>
  45  * This provides an application with an implementation-independent starting
  46  * point. DOM implementations may modify this class to meet new security
  47  * standards or to provide *additional* fallbacks for the list of
  48  * DOMImplementationSources.
  49  * </p>
  50  *
  51  * @see DOMImplementation
  52  * @see DOMImplementationSource
  53  * @since DOM Level 3
  54  */
  55 public final class DOMImplementationRegistry {
  56     /**
  57      * The system property to specify the
  58      * DOMImplementationSource class names.
  59      */
  60     public static final String PROPERTY =
  61         "org.w3c.dom.DOMImplementationSourceList";
  62
  63     /**
  64      * Default columns per line.
  65      */
  66     private static final int DEFAULT_LINE_LENGTH = 80;
  67
  68     /**
  69      * The list of DOMImplementationSources.
  70      */
  71     private Vector sources;
  72
  73     /**
  74      * Private constructor.
  75      * @param srcs Vector List of DOMImplementationSources
  76      */
  77     private DOMImplementationRegistry(final Vector srcs) {
  78         sources = srcs;
  79     }
  80
  81     /**
  82      * Obtain a new instance of a <code>DOMImplementationRegistry</code>.
  83      *
  84
  85      * The <code>DOMImplementationRegistry</code> is initialized by the
  86      * application or the implementation, depending on the context, by
  87      * first checking the value of the Java system property
  88      * <code>org.w3c.dom.DOMImplementationSourceList</code> and
  89      * the the service provider whose contents are at
  90      * "<code>META_INF/services/org.w3c.dom.DOMImplementationSourceList</code>"
  91      * The value of this property is a white-space separated list of
  92      * names of availables classes implementing the
  93      * <code>DOMImplementationSource</code> interface. Each class listed
  94      * in the class name list is instantiated and any exceptions
  95      * encountered are thrown to the application.
  96      *
  97      * @return an initialized instance of DOMImplementationRegistry
  98      * @throws ClassNotFoundException
  99      *     If any specified class can not be found
 100      * @throws InstantiationException
 101      *     If any specified class is an interface or abstract class
 102      * @throws IllegalAccessException
 103      *     If the default constructor of a specified class is not accessible
 104      * @throws ClassCastException
 105      *     If any specified class does not implement
 106      * <code>DOMImplementationSource</code>
 107      */
 108     public static DOMImplementationRegistry newInstance()
 109         throws
 110         ClassNotFoundException,
 111         InstantiationException,
 112         IllegalAccessException,
 113         ClassCastException {
 114         Vector sources = new Vector();
 115
 116         ClassLoader classLoader = getClassLoader();
 117         // fetch system property:
 118         String p = getSystemProperty(PROPERTY);
 119
 120         //
 121         // if property is not specified then use contents of
 122         // META_INF/org.w3c.dom.DOMImplementationSourceList from classpath
 123         if (p == null) {
 124             p = getServiceValue(classLoader);
 125         }
 126         if (p == null) {
 127             //
 128             // DOM Implementations can modify here to add *additional* fallback
 129             // mechanisms to access a list of default DOMImplementationSources.
 130             p = "gnu.xml.dom.ImplementationSource";
 131         }
 132         if (p != null) {
 133             StringTokenizer st = new StringTokenizer(p);
 134             while (st.hasMoreTokens()) {
 135                 String sourceName = st.nextToken();
 136                 // Use context class loader, falling back to Class.forName
 137                 // if and only if this fails...
 138                 Class sourceClass = null;
 139                 if (classLoader != null) {
 140                     sourceClass = classLoader.loadClass(sourceName);
 141                 } else {
 142                     sourceClass = Class.forName(sourceName);
 143                 }
 144                 DOMImplementationSource source =
 145                     (DOMImplementationSource) sourceClass.newInstance();
 146                 sources.addElement(source);
 147             }
 148         }
 149         return new DOMImplementationRegistry(sources);
 150     }
 151
 152     /**
 153      * Return the first implementation that has the desired
 154      * features, or <code>null</code> if none is found.
 155      *
 156      * @param features
 157      *            A string that specifies which features are required. This is
 158      *            a space separated list in which each feature is specified by
 159      *            its name optionally followed by a space and a version number.
 160      *            This is something like: "XML 1.0 Traversal +Events 2.0"
 161      * @return An implementation that has the desired features,
 162      *         or <code>null</code> if none found.
 163      */
 164     public DOMImplementation getDOMImplementation(final String features) {
 165         int size = sources.size();
 166         String name = null;
 167         for (int i = 0; i < size; i++) {
 168             DOMImplementationSource source =
 169                 (DOMImplementationSource) sources.elementAt(i);
 170             DOMImplementation impl = source.getDOMImplementation(features);
 171             if (impl != null) {
 172                 return impl;
 173             }
 174         }
 175         return null;
 176     }
 177
 178     /**
 179      * Return a list of implementations that support the
 180      * desired features.
 181      *
 182      * @param features
 183      *            A string that specifies which features are required. This is
 184      *            a space separated list in which each feature is specified by
 185      *            its name optionally followed by a space and a version number.
 186      *            This is something like: "XML 1.0 Traversal +Events 2.0"
 187      * @return A list of DOMImplementations that support the desired features.
 188      */
 189     public DOMImplementationList getDOMImplementationList(final String features) {
 190         final Vector implementations = new Vector();
 191         int size = sources.size();
 192         for (int i = 0; i < size; i++) {
 193             DOMImplementationSource source =
 194                 (DOMImplementationSource) sources.elementAt(i);
 195             DOMImplementationList impls =
 196                 source.getDOMImplementationList(features);
 197             for (int j = 0; j < impls.getLength(); j++) {
 198                 DOMImplementation impl = impls.item(j);
 199                 implementations.addElement(impl);
 200             }
 201         }
 202         return new DOMImplementationList() {
 203                 public DOMImplementation item(final int index) {
 204                     if (index >= 0 && index < implementations.size()) {
 205                         try {
 206                             return (DOMImplementation)
 207                                 implementations.elementAt(index);
 208                         } catch (ArrayIndexOutOfBoundsException e) {
 209                             return null;
 210                         }
 211                     }
 212                     return null;
 213                 }
 214
 215                 public int getLength() {
 216                     return implementations.size();
 217                 }
 218             };
 219     }
 220
 221     /**
 222      * Register an implementation.
 223      *
 224      * @param s The source to be registered, may not be <code>null</code>
 225      */
 226     public void addSource(final DOMImplementationSource s) {
 227         if (s == null) {
 228             throw new NullPointerException();
 229         }
 230         if (!sources.contains(s)) {
 231             sources.addElement(s);
 232         }
 233     }
 234
 235     /**
 236      *
 237      * Gets a class loader.
 238      *
 239      * @return A class loader, possibly <code>null</code>
 240      */
 241     private static ClassLoader getClassLoader() {
 242         try {
 243             ClassLoader contextClassLoader = getContextClassLoader();
 244
 245             if (contextClassLoader != null) {
 246                 return contextClassLoader;
 247             }
 248         } catch (Exception e) {
 249             // Assume that the DOM application is in a JRE 1.1, use the
 250             // current ClassLoader
 251             return DOMImplementationRegistry.class.getClassLoader();
 252         }
 253         return DOMImplementationRegistry.class.getClassLoader();
 254     }
 255
 256     /**
 257      * This method attempts to return the first line of the resource
 258      * META_INF/services/org.w3c.dom.DOMImplementationSourceList
 259      * from the provided ClassLoader.
 260      *
 261      * @param classLoader classLoader, may not be <code>null</code>.
 262      * @return first line of resource, or <code>null</code>
 263      */
 264     private static String getServiceValue(final ClassLoader classLoader) {
 265         String serviceId = "META-INF/services/" + PROPERTY;
 266         // try to find services in CLASSPATH
 267         try {
 268             InputStream is = getResourceAsStream(classLoader, serviceId);
 269
 270             if (is != null) {
 271                 BufferedReader rd;
 272                 try {
 273                     rd =
 274                         new BufferedReader(new InputStreamReader(is, "UTF-8"),
 275                                            DEFAULT_LINE_LENGTH);
 276                 } catch (java.io.UnsupportedEncodingException e) {
 277                     rd =
 278                         new BufferedReader(new InputStreamReader(is),
 279                                            DEFAULT_LINE_LENGTH);
 280                 }
 281                 String serviceValue = rd.readLine();
 282                 rd.close();
 283                 if (serviceValue != null && serviceValue.length() > 0) {
 284                     return serviceValue;
 285                 }
 286             }
 287         } catch (Exception ex) {
 288             return null;
 289         }
 290         return null;
 291     }
 292
 293     /**
 294      * A simple JRE (Java Runtime Environment) 1.1 test
 295      *
 296      * @return <code>true</code> if JRE 1.1
 297      */
 298     private static boolean isJRE11() {
 299         try {
 300             Class c = Class.forName("java.security.AccessController");
 301             // java.security.AccessController existed since 1.2 so, if no
 302             // exception was thrown, the DOM application is running in a JRE
 303             // 1.2 or higher
 304             return false;
 305         } catch (Exception ex) {
 306             // ignore
 307         }
 308         return true;
 309     }
 310
 311     /**
 312      * This method returns the ContextClassLoader or <code>null</code> if
 313      * running in a JRE 1.1
 314      *
 315      * @return The Context Classloader
 316      */
 317     private static ClassLoader getContextClassLoader() {
 318         return isJRE11()
 319             ? null
 320             : (ClassLoader)
 321               AccessController.doPrivileged(new PrivilegedAction() {
 322                     public Object run() {
 323                         ClassLoader classLoader = null;
 324                         try {
 325                             classLoader =
 326                                 Thread.currentThread().getContextClassLoader();
 327                         } catch (SecurityException ex) {
 328                         }
 329                         return classLoader;
 330                     }
 331                 });
 332     }
 333
 334     /**
 335      * This method returns the system property indicated by the specified name
 336      * after checking access control privileges. For a JRE 1.1, this check is
 337      * not done.
 338      *
 339      * @param name the name of the system property
 340      * @return the system property
 341      */
 342     private static String getSystemProperty(final String name) {
 343         return isJRE11()
 344             ? (String) System.getProperty(name)
 345             : (String) AccessController.doPrivileged(new PrivilegedAction() {
 346                     public Object run() {
 347                         return System.getProperty(name);
 348                     }
 349                 });
 350     }
 351
 352     /**
 353      * This method returns an Inputstream for the reading resource
 354      * META_INF/services/org.w3c.dom.DOMImplementationSourceList after checking
 355      * access control privileges. For a JRE 1.1, this check is not done.
 356      *
 357      * @param classLoader classLoader
 358      * @param name the resource
 359      * @return an Inputstream for the resource specified
 360      */
 361     private static InputStream getResourceAsStream(final ClassLoader classLoader,
 362                                                    final String name) {
 363         if (isJRE11()) {
 364             InputStream ris;
 365             if (classLoader == null) {
 366                 ris = ClassLoader.getSystemResourceAsStream(name);
 367             } else {
 368                 ris = classLoader.getResourceAsStream(name);
 369             }
 370             return ris;
 371         } else {
 372             return (InputStream)
 373                 AccessController.doPrivileged(new PrivilegedAction() {
 374                         public Object run() {
 375                             InputStream ris;
 376                             if (classLoader == null) {
 377                                 ris =
 378                                     ClassLoader.getSystemResourceAsStream(name);
 379                             } else {
 380                                 ris = classLoader.getResourceAsStream(name);
 381                             }
 382                             return ris;
 383                         }
 384                     });
 385         }
 386     }
 387 }