Desktop.java revision 0
2362N/A * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 2362N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * The {@code Desktop} class allows a Java application to launch 0N/A * associated applications registered on the native desktop to handle 0N/A * a {@link java.net.URI} or a file. 0N/A * <p> Supported operations include: 0N/A * <li>launching the user-default browser to show a specified 0N/A * <li>launching the user-default mail client with an optional 0N/A * {@code mailto} URI;</li> 0N/A * <li>launching a registered application to open, edit or print a 0N/A * specified file.</li> 0N/A * <p> This class provides methods corresponding to these 0N/A * operations. The methods look for the associated application 0N/A * registered on the current platform, and launch it to handle a URI 0N/A * or file. If there is no associated application or the associated 0N/A * application fails to be launched, an exception is thrown. 0N/A * <p> An application is registered to a URI or file type; for 0N/A * example, the {@code "sxi"} file extension is typically registered 0N/A * to StarOffice. The mechanism of registering, accessing, and 0N/A * launching the associated application is platform-dependent. 0N/A * <p> Each operation is an action type represented by the {@link 0N/A * Desktop.Action} class. 0N/A * <p> Note: when some action is invoked and the associated 0N/A * application is executed, it will be executed on the same system as 0N/A * the one on which the Java application was launched. 0N/A * @author Armin Chen 0N/A * @author George Zhang 0N/A * Represents an action type. Each platform supports a different 0N/A * set of actions. You may use the {@link Desktop#isSupported} 0N/A * method to determine if the given action is supported by the * @see java.awt.Desktop#isSupported(java.awt.Desktop.Action) * Represents an "open" action. * @see Desktop#open(java.io.File) * Represents an "edit" action. * @see Desktop#edit(java.io.File) * Represents a "print" action. * @see Desktop#print(java.io.File) * Represents a "mail" action. * @see Desktop#mail(java.net.URI) * Represents a "browse" action. * @see Desktop#browse(java.net.URI) * Suppresses default constructor for noninstantiability. * Returns the <code>Desktop</code> instance of the current * browser context. On some platforms the Desktop API may not be * supported; use the {@link #isDesktopSupported} method to * determine if the current desktop is supported. * @return the Desktop instance of the current browser context * @throws HeadlessException if {@link * GraphicsEnvironment#isHeadless()} returns {@code true} * @throws UnsupportedOperationException if this class is not * supported on the current platform * @see #isDesktopSupported() * @see java.awt.GraphicsEnvironment#isHeadless "supported on the current platform");
* Tests whether this class is supported on the current platform. * If it's supported, use {@link #getDesktop()} to retrieve an * @return <code>true</code> if this class is supported on the * current platform; <code>false</code> otherwise * Tests whether an action is supported on the current platform. * <p>Even when the platform supports an action, a file or URI may * not have a registered application for the action. For example, * most of the platforms support the {@link Desktop.Action#OPEN} * action. But for a specific file, there may not be an * application registered to open it. In this case, {@link * #isSupported} may return {@code true}, but the corresponding * action method will throw an {@link IOException}. * @param action the specified {@link Action} * @return <code>true</code> if the specified action is supported on * the current platform; <code>false</code> otherwise * Checks if the file is a valid file and readable. * @throws SecurityException If a security manager exists and its * {@link SecurityManager#checkRead(java.lang.String)} method * denies read access to the file * @throws NullPointerException if file is null * @throws IllegalArgumentException if file doesn't exist * Checks if the action type is supported. * @param actionType the action type in question * @throws UnsupportedOperationException if the specified action type is not * supported on the current platform +
" action is not supported on the current platform!");
* Calls to the security manager's <code>checkPermission</code> method with * an <code>AWTPermission("showWindowWithoutWarningBanner")</code> "showWindowWithoutWarningBanner"));
* Launches the associated application to open the file. * <p> If the specified file is a directory, the file manager of * the current platform is launched to open it. * @param file the file to be opened with the associated application * @throws NullPointerException if {@code file} is {@code null} * @throws IllegalArgumentException if the specified file doesn't * @throws UnsupportedOperationException if the current platform * does not support the {@link Desktop.Action#OPEN} action * @throws IOException if the specified file has no associated * application or the associated application fails to be launched * @throws SecurityException if a security manager exists and its * {@link java.lang.SecurityManager#checkRead(java.lang.String)} * method denies read access to the file, or it denies the * <code>AWTPermission("showWindowWithoutWarningBanner")</code> * permission, or the calling thread is not allowed to create a * @see java.awt.AWTPermission * Launches the associated editor application and opens a file for * @param file the file to be opened for editing * @throws NullPointerException if the specified file is {@code null} * @throws IllegalArgumentException if the specified file doesn't * @throws UnsupportedOperationException if the current platform * does not support the {@link Desktop.Action#EDIT} action * @throws IOException if the specified file has no associated * editor, or the associated application fails to be launched * @throws SecurityException if a security manager exists and its * {@link java.lang.SecurityManager#checkRead(java.lang.String)} * method denies read access to the file, or {@link * java.lang.SecurityManager#checkWrite(java.lang.String)} method * denies write access to the file, or it denies the * <code>AWTPermission("showWindowWithoutWarningBanner")</code> * permission, or the calling thread is not allowed to create a * @see java.awt.AWTPermission * Prints a file with the native desktop printing facility, using * the associated application's print command. * @param file the file to be printed * @throws NullPointerException if the specified file is {@code * @throws IllegalArgumentException if the specified file doesn't * @throws UnsupportedOperationException if the current platform * does not support the {@link Desktop.Action#PRINT} action * @throws IOException if the specified file has no associated * application that can be used to print it * @throws SecurityException if a security manager exists and its * {@link java.lang.SecurityManager#checkRead(java.lang.String)} * method denies read access to the file, or its {@link * java.lang.SecurityManager#checkPrintJobAccess()} method denies * the permission to print the file, or the calling thread is not * allowed to create a subprocess * Launches the default browser to display a {@code URI}. * If the default browser is not able to handle the specified * {@code URI}, the application registered for handling * {@code URIs} of the specified type is invoked. The application * is determined from the protocol and path of the {@code URI}, as * defined by the {@code URI} class. * If the calling thread does not have the necessary permissions, * and this is invoked from within an applet, * {@code AppletContext.showDocument()} is used. Similarly, if the calling * does not have the necessary permissions, and this is invoked from within * a Java Web Started application, {@code BasicService.showDocument()} * @param uri the URI to be displayed in the user default browser * @throws NullPointerException if {@code uri} is {@code null} * @throws UnsupportedOperationException if the current platform * does not support the {@link Desktop.Action#BROWSE} action * @throws IOException if the user default browser is not found, * or it fails to be launched, or the default handler application * @throws SecurityException if a security manager exists and it * <code>AWTPermission("showWindowWithoutWarningBanner")</code> * permission, or the calling thread is not allowed to create a * subprocess; and not invoked from within an applet or Java Web Started * @throws IllegalArgumentException if the necessary permissions * are not available and the URI can not be converted to a {@code URL} * @see java.awt.AWTPermission * @see java.applet.AppletContext // Calling thread doesn't have necessary priviledges. // Delegate to DesktopBrowse so that it can work in * Launches the mail composing window of the user default mail * @throws UnsupportedOperationException if the current platform * does not support the {@link Desktop.Action#MAIL} action * @throws IOException if the user default mail client is not * found, or it fails to be launched * @throws SecurityException if a security manager exists and it * <code>AWTPermission("showWindowWithoutWarningBanner")</code> * permission, or the calling thread is not allowed to create a * @see java.awt.AWTPermission * Launches the mail composing window of the user default mail * client, filling the message fields specified by a {@code * <p> A <code>mailto:</code> URI can specify message fields * including <i>"to"</i>, <i>"cc"</i>, <i>"subject"</i>, * <i>"body"</i>, etc. See <a * scheme (RFC 2368)</a> for the {@code mailto:} URI specification * @param mailtoURI the specified {@code mailto:} URI * @throws NullPointerException if the specified URI is {@code * @throws IllegalArgumentException if the URI scheme is not * @throws UnsupportedOperationException if the current platform * does not support the {@link Desktop.Action#MAIL} action * @throws IOException if the user default mail client is not * found or fails to be launched * @throws SecurityException if a security manager exists and it * <code>AWTPermission("showWindowWithoutWarningBanner")</code> * permission, or the calling thread is not allowed to create a * @see java.awt.AWTPermission