1 /*
   2  * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.java.browser.dom;
  27 
  28 public abstract class DOMService
  29 {
  30     /**
  31      * Returns new instance of a DOMService. The implementation
  32      * of the DOMService returns depends on the setting of the
  33      * com.sun.java.browser.dom.DOMServiceProvider property or,
  34      * if the property is not set, a platform specific default.
  35      *
  36      * Throws DOMUnsupportedException if the DOMService is not
  37      * available to the obj.
  38      *
  39      * @param obj Object to leverage the DOMService
  40      */
  41     public static DOMService getService(Object obj)
  42                   throws DOMUnsupportedException
  43     {
  44         try
  45         {
  46             String provider = (String) java.security.AccessController.doPrivileged(
  47                    new sun.security.action.GetPropertyAction("com.sun.java.browser.dom.DOMServiceProvider"));
  48 
  49             Class clazz = DOMService.class.forName("sun.plugin.dom.DOMService");
  50 
  51             return (DOMService) clazz.newInstance();
  52         }
  53         catch (Throwable e)
  54         {
  55             throw new DOMUnsupportedException(e.toString());
  56         }
  57     }
  58 
  59     /**
  60      * An empty constructor is provided. Implementations of this
  61      * abstract class must provide a public no-argument constructor
  62      * in order for the static getService() method to work correctly.
  63      * Application programmers should not be able to directly
  64      * construct implementation subclasses of this abstract subclass.
  65      */
  66     public DOMService()
  67     {
  68     }
  69 
  70     /**
  71      * Causes action.run() to be executed synchronously on the
  72      * DOM action dispatching thread. This call will block until all
  73      * pending DOM actions have been processed and (then)
  74      * action.run() returns. This method should be used when an
  75      * application thread needs to access the browser's DOM.
  76      * It should not be called from the DOMActionDispatchThread.
  77      *
  78      * Note that if the DOMAction.run() method throws an uncaught
  79      * exception (on the DOM action dispatching thread),  it's caught
  80      * and re-thrown, as an DOMAccessException, on the caller's thread.
  81      *
  82      * If the DOMAction.run() method throws any DOM security related
  83      * exception (on the DOM action dispatching thread), it's caught
  84      * and re-thrown, as an DOMSecurityException, on the caller's thread.
  85      *
  86      * @param action DOMAction.
  87      */
  88     public abstract Object invokeAndWait(DOMAction action) throws DOMAccessException;
  89 
  90     /**
  91      * Causes action.run() to be executed asynchronously on the
  92      * DOM action dispatching thread. This method should be used
  93      * when an application thread needs to access the browser's
  94      * DOM. It should not be called from the DOMActionDispatchThread.
  95      *
  96      * Note that if the DOMAction.run() method throws an uncaught
  97      * exception (on the DOM action dispatching thread),  it will not be
  98      * caught and re-thrown on the caller's thread.
  99      *
 100      * @param action DOMAction.
 101      */
 102     public abstract void invokeLater(DOMAction action);
 103 }