Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 2005, 2006, 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 java.awt;
   27   
   28   import java.io.File;
   29   import java.io.IOException;
   30   import java.net.URISyntaxException;
   31   import java.net.URI;
   32   import java.net.URL;
   33   import java.net.MalformedURLException;
   34   import java.awt.AWTPermission;
   35   import java.awt.GraphicsEnvironment;
   36   import java.awt.HeadlessException;
   37   import java.awt.peer.DesktopPeer;
   38   import sun.awt.SunToolkit;
   39   import sun.awt.HeadlessToolkit;
   40   import java.io.FilePermission;
   41   import sun.security.util.SecurityConstants;
   42   
   43   /**
   44    * The {@code Desktop} class allows a Java application to launch
   45    * associated applications registered on the native desktop to handle
   46    * a {@link java.net.URI} or a file.
   47    *
   48    * <p> Supported operations include:
   49    * <ul>
   50    *   <li>launching the user-default browser to show a specified
   51    *       URI;</li>
   52    *   <li>launching the user-default mail client with an optional
   53    *       {@code mailto} URI;</li>
   54    *   <li>launching a registered application to open, edit or print a
   55    *       specified file.</li>
   56    * </ul>
   57    *
   58    * <p> This class provides methods corresponding to these
   59    * operations. The methods look for the associated application
   60    * registered on the current platform, and launch it to handle a URI
   61    * or file. If there is no associated application or the associated
   62    * application fails to be launched, an exception is thrown.
   63    *
   64    * <p> An application is registered to a URI or file type; for
   65    * example, the {@code "sxi"} file extension is typically registered
   66    * to StarOffice.  The mechanism of registering, accessing, and
   67    * launching the associated application is platform-dependent.
   68    *
   69    * <p> Each operation is an action type represented by the {@link
   70    * Desktop.Action} class.
   71    *
   72    * <p> Note: when some action is invoked and the associated
   73    * application is executed, it will be executed on the same system as
   74    * the one on which the Java application was launched.
   75    *
   76    * @since 1.6
   77    * @author Armin Chen
   78    * @author George Zhang
   79    */
   80   public class Desktop {
   81   
   82       /**
   83        * Represents an action type.  Each platform supports a different
   84        * set of actions.  You may use the {@link Desktop#isSupported}
   85        * method to determine if the given action is supported by the
   86        * current platform.
   87        * @see java.awt.Desktop#isSupported(java.awt.Desktop.Action)
   88        * @since 1.6
   89        */
   90       public static enum Action {
   91           /**
   92            * Represents an "open" action.
   93            * @see Desktop#open(java.io.File)
   94            */
   95           OPEN,
   96           /**
   97            * Represents an "edit" action.
   98            * @see Desktop#edit(java.io.File)
   99            */
  100           EDIT,
  101           /**
  102            * Represents a "print" action.
  103            * @see Desktop#print(java.io.File)
  104            */
  105           PRINT,
  106           /**
  107            * Represents a "mail" action.
  108            * @see Desktop#mail()
  109            * @see Desktop#mail(java.net.URI)
  110            */
  111           MAIL,
  112           /**
  113            * Represents a "browse" action.
  114            * @see Desktop#browse(java.net.URI)
  115            */
  116           BROWSE
  117       };
  118   
  119       private DesktopPeer peer;
  120   
  121       /**
  122        * Suppresses default constructor for noninstantiability.
  123        */
  124       private Desktop() {
  125           peer = Toolkit.getDefaultToolkit().createDesktopPeer(this);
  126       }
  127   
  128       /**
  129        * Returns the <code>Desktop</code> instance of the current
  130        * browser context.  On some platforms the Desktop API may not be
  131        * supported; use the {@link #isDesktopSupported} method to
  132        * determine if the current desktop is supported.
  133        * @return the Desktop instance of the current browser context
  134        * @throws HeadlessException if {@link
  135        * GraphicsEnvironment#isHeadless()} returns {@code true}
  136        * @throws UnsupportedOperationException if this class is not
  137        * supported on the current platform
  138        * @see #isDesktopSupported()
  139        * @see java.awt.GraphicsEnvironment#isHeadless
  140        */
  141       public static synchronized Desktop getDesktop(){
  142           if (GraphicsEnvironment.isHeadless()) throw new HeadlessException();
  143           if (!Desktop.isDesktopSupported()) {
  144               throw new UnsupportedOperationException("Desktop API is not " +
  145                                                       "supported on the current platform");
  146           }
  147   
  148           sun.awt.AppContext context = sun.awt.AppContext.getAppContext();
  149           Desktop desktop = (Desktop)context.get(Desktop.class);
  150   
  151           if (desktop == null) {
  152               desktop = new Desktop();
  153               context.put(Desktop.class, desktop);
  154           }
  155   
  156           return desktop;
  157       }
  158   
  159       /**
  160        * Tests whether this class is supported on the current platform.
  161        * If it's supported, use {@link #getDesktop()} to retrieve an
  162        * instance.
  163        *
  164        * @return <code>true</code> if this class is supported on the
  165        *         current platform; <code>false</code> otherwise
  166        * @see #getDesktop()
  167        */
  168       public static boolean isDesktopSupported(){
  169           Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
  170           if (defaultToolkit instanceof SunToolkit) {
  171               return ((SunToolkit)defaultToolkit).isDesktopSupported();
  172           }
  173           return false;
  174       }
  175   
  176       /**
  177        * Tests whether an action is supported on the current platform.
  178        *
  179        * <p>Even when the platform supports an action, a file or URI may
  180        * not have a registered application for the action.  For example,
  181        * most of the platforms support the {@link Desktop.Action#OPEN}
  182        * action.  But for a specific file, there may not be an
  183        * application registered to open it.  In this case, {@link
  184        * #isSupported} may return {@code true}, but the corresponding
  185        * action method will throw an {@link IOException}.
  186        *
  187        * @param action the specified {@link Action}
  188        * @return <code>true</code> if the specified action is supported on
  189        *         the current platform; <code>false</code> otherwise
  190        * @see Desktop.Action
  191        */
  192       public boolean isSupported(Action action) {
  193           return peer.isSupported(action);
  194       }
  195   
  196       /**
  197        * Checks if the file is a valid file and readable.
  198        *
  199        * @throws SecurityException If a security manager exists and its
  200        *         {@link SecurityManager#checkRead(java.lang.String)} method
  201        *         denies read access to the file
  202        * @throws NullPointerException if file is null
  203        * @throws IllegalArgumentException if file doesn't exist
  204        */
  205       private static void checkFileValidation(File file){
  206           if (file == null) throw new NullPointerException("File must not be null");
  207   
  208           if (!file.exists()) {
  209               throw new IllegalArgumentException("The file: "
  210                                                  + file.getPath() + " doesn't exist.");
  211           }
  212   
  213           file.canRead();
  214       }
  215   
  216       /**
  217        * Checks if the action type is supported.
  218        *
  219        * @param actionType the action type in question
  220        * @throws UnsupportedOperationException if the specified action type is not
  221        *         supported on the current platform
  222        */
  223       private void checkActionSupport(Action actionType){
  224           if (!isSupported(actionType)) {
  225               throw new UnsupportedOperationException("The " + actionType.name()
  226                                                       + " action is not supported on the current platform!");
  227           }
  228       }
  229   
  230   
  231       /**
  232        *  Calls to the security manager's <code>checkPermission</code> method with
  233        *  an <code>AWTPermission("showWindowWithoutWarningBanner")</code>
  234        *  permission.
  235        */
  236       private void checkAWTPermission(){
  237           SecurityManager sm = System.getSecurityManager();
  238           if (sm != null) {
  239               sm.checkPermission(new AWTPermission(
  240                                      "showWindowWithoutWarningBanner"));
  241           }
  242       }
  243   
  244       /**
  245        * Launches the associated application to open the file.
  246        *
  247        * <p> If the specified file is a directory, the file manager of
  248        * the current platform is launched to open it.
  249        *
  250        * @param file the file to be opened with the associated application
  251        * @throws NullPointerException if {@code file} is {@code null}
  252        * @throws IllegalArgumentException if the specified file doesn't
  253        * exist
  254        * @throws UnsupportedOperationException if the current platform
  255        * does not support the {@link Desktop.Action#OPEN} action
  256        * @throws IOException if the specified file has no associated
  257        * application or the associated application fails to be launched
  258        * @throws SecurityException if a security manager exists and its
  259        * {@link java.lang.SecurityManager#checkRead(java.lang.String)}
  260        * method denies read access to the file, or it denies the
  261        * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
  262        * permission, or the calling thread is not allowed to create a
  263        * subprocess
  264        * @see java.awt.AWTPermission
  265        */
  266       public void open(File file) throws IOException {
  267           checkAWTPermission();
  268           checkExec();
  269           checkActionSupport(Action.OPEN);
  270           checkFileValidation(file);
  271   
  272           peer.open(file);
  273       }
  274   
  275       /**
  276        * Launches the associated editor application and opens a file for
  277        * editing.
  278        *
  279        * @param file the file to be opened for editing
  280        * @throws NullPointerException if the specified file is {@code null}
  281        * @throws IllegalArgumentException if the specified file doesn't
  282        * exist
  283        * @throws UnsupportedOperationException if the current platform
  284        * does not support the {@link Desktop.Action#EDIT} action
  285        * @throws IOException if the specified file has no associated
  286        * editor, or the associated application fails to be launched
  287        * @throws SecurityException if a security manager exists and its
  288        * {@link java.lang.SecurityManager#checkRead(java.lang.String)}
  289        * method denies read access to the file, or {@link
  290        * java.lang.SecurityManager#checkWrite(java.lang.String)} method
  291        * denies write access to the file, or it denies the
  292        * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
  293        * permission, or the calling thread is not allowed to create a
  294        * subprocess
  295        * @see java.awt.AWTPermission
  296        */
  297       public void edit(File file) throws IOException {
  298           checkAWTPermission();
  299           checkExec();
  300           checkActionSupport(Action.EDIT);
  301           file.canWrite();
  302           checkFileValidation(file);
  303   
  304           peer.edit(file);
  305       }
  306   
  307       /**
  308        * Prints a file with the native desktop printing facility, using
  309        * the associated application's print command.
  310        *
  311        * @param file the file to be printed
  312        * @throws NullPointerException if the specified file is {@code
  313        * null}
  314        * @throws IllegalArgumentException if the specified file doesn't
  315        * exist
  316        * @throws UnsupportedOperationException if the current platform
  317        *         does not support the {@link Desktop.Action#PRINT} action
  318        * @throws IOException if the specified file has no associated
  319        * application that can be used to print it
  320        * @throws SecurityException if a security manager exists and its
  321        * {@link java.lang.SecurityManager#checkRead(java.lang.String)}
  322        * method denies read access to the file, or its {@link
  323        * java.lang.SecurityManager#checkPrintJobAccess()} method denies
  324        * the permission to print the file, or the calling thread is not
  325        * allowed to create a subprocess
  326        */
  327       public void print(File file) throws IOException {
  328           checkExec();
  329           SecurityManager sm = System.getSecurityManager();
  330           if (sm != null) {
  331               sm.checkPrintJobAccess();
  332           }
  333           checkActionSupport(Action.PRINT);
  334           checkFileValidation(file);
  335   
  336           peer.print(file);
  337       }
  338   
  339       /**
  340        * Launches the default browser to display a {@code URI}.
  341        * If the default browser is not able to handle the specified
  342        * {@code URI}, the application registered for handling
  343        * {@code URIs} of the specified type is invoked. The application
  344        * is determined from the protocol and path of the {@code URI}, as
  345        * defined by the {@code URI} class.
  346        * <p>
  347        * If the calling thread does not have the necessary permissions,
  348        * and this is invoked from within an applet,
  349        * {@code AppletContext.showDocument()} is used. Similarly, if the calling
  350        * does not have the necessary permissions, and this is invoked from within
  351        * a Java Web Started application, {@code BasicService.showDocument()}
  352        * is used.
  353        *
  354        * @param uri the URI to be displayed in the user default browser
  355        * @throws NullPointerException if {@code uri} is {@code null}
  356        * @throws UnsupportedOperationException if the current platform
  357        * does not support the {@link Desktop.Action#BROWSE} action
  358        * @throws IOException if the user default browser is not found,
  359        * or it fails to be launched, or the default handler application
  360        * failed to be launched
  361        * @throws SecurityException if a security manager exists and it
  362        * denies the
  363        * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
  364        * permission, or the calling thread is not allowed to create a
  365        * subprocess; and not invoked from within an applet or Java Web Started
  366        * application
  367        * @throws IllegalArgumentException if the necessary permissions
  368        * are not available and the URI can not be converted to a {@code URL}
  369        * @see java.net.URI
  370        * @see java.awt.AWTPermission
  371        * @see java.applet.AppletContext
  372        */
  373       public void browse(URI uri) throws IOException {
  374           SecurityException securityException = null;
  375           try {
  376               checkAWTPermission();
  377               checkExec();
  378           } catch (SecurityException e) {
  379               securityException = e;
  380           }
  381           checkActionSupport(Action.BROWSE);
  382           if (uri == null) {
  383               throw new NullPointerException();
  384           }
  385           if (securityException == null) {
  386               peer.browse(uri);
  387               return;
  388           }
  389   
  390           // Calling thread doesn't have necessary priviledges.
  391           // Delegate to DesktopBrowse so that it can work in
  392           // applet/webstart.
  393           URL url = null;
  394           try {
  395               url = uri.toURL();
  396           } catch (MalformedURLException e) {
  397               throw new IllegalArgumentException("Unable to convert URI to URL", e);
  398           }
  399           sun.awt.DesktopBrowse db = sun.awt.DesktopBrowse.getInstance();
  400           if (db == null) {
  401               // Not in webstart/applet, throw the exception.
  402               throw securityException;
  403           }
  404           db.browse(url);
  405       }
  406   
  407       /**
  408        * Launches the mail composing window of the user default mail
  409        * client.
  410        *
  411        * @throws UnsupportedOperationException if the current platform
  412        * does not support the {@link Desktop.Action#MAIL} action
  413        * @throws IOException if the user default mail client is not
  414        * found, or it fails to be launched
  415        * @throws SecurityException if a security manager exists and it
  416        * denies the
  417        * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
  418        * permission, or the calling thread is not allowed to create a
  419        * subprocess
  420        * @see java.awt.AWTPermission
  421        */
  422       public void mail() throws IOException {
  423           checkAWTPermission();
  424           checkExec();
  425           checkActionSupport(Action.MAIL);
  426           URI mailtoURI = null;
  427           try{
  428               mailtoURI = new URI("mailto:?");
  429               peer.mail(mailtoURI);
  430           } catch (URISyntaxException e){
  431               // won't reach here.
  432           }
  433       }
  434   
  435       /**
  436        * Launches the mail composing window of the user default mail
  437        * client, filling the message fields specified by a {@code
  438        * mailto:} URI.
  439        *
  440        * <p> A <code>mailto:</code> URI can specify message fields
  441        * including <i>"to"</i>, <i>"cc"</i>, <i>"subject"</i>,
  442        * <i>"body"</i>, etc.  See <a
  443        * href="http://www.ietf.org/rfc/rfc2368.txt">The mailto URL
  444        * scheme (RFC 2368)</a> for the {@code mailto:} URI specification
  445        * details.
  446        *
  447        * @param mailtoURI the specified {@code mailto:} URI
  448        * @throws NullPointerException if the specified URI is {@code
  449        * null}
  450        * @throws IllegalArgumentException if the URI scheme is not
  451        *         <code>"mailto"</code>
  452        * @throws UnsupportedOperationException if the current platform
  453        * does not support the {@link Desktop.Action#MAIL} action
  454        * @throws IOException if the user default mail client is not
  455        * found or fails to be launched
  456        * @throws SecurityException if a security manager exists and it
  457        * denies the
  458        * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
  459        * permission, or the calling thread is not allowed to create a
  460        * subprocess
  461        * @see java.net.URI
  462        * @see java.awt.AWTPermission
  463        */
  464       public  void mail(URI mailtoURI) throws IOException {
  465           checkAWTPermission();
  466           checkExec();
  467           checkActionSupport(Action.MAIL);
  468           if (mailtoURI == null) throw new NullPointerException();
  469   
  470           if (!"mailto".equalsIgnoreCase(mailtoURI.getScheme())) {
  471               throw new IllegalArgumentException("URI scheme is not \"mailto\"");
  472           }
  473   
  474           peer.mail(mailtoURI);
  475       }
  476   
  477       private void checkExec() throws SecurityException {
  478           SecurityManager sm = System.getSecurityManager();
  479           if (sm != null) {
  480               sm.checkPermission(new FilePermission("<<ALL FILES>>",
  481                                                     SecurityConstants.FILE_EXECUTE_ACTION));
  482           }
  483       }
  484   }

Home » openjdk-7 » java » awt » [javadoc | source]