2362N/A * Copyright (c) 2005, 2006, Oracle and/or its affiliates. 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. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 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 0N/A * @see java.awt.Desktop#isSupported(java.awt.Desktop.Action) 0N/A * Represents an "open" action. 0N/A * @see Desktop#open(java.io.File) 0N/A * Represents an "edit" action. 0N/A * @see Desktop#edit(java.io.File) 0N/A * Represents a "print" action. 0N/A * @see Desktop#print(java.io.File) 0N/A * Represents a "mail" action. 0N/A * @see Desktop#mail() 0N/A * @see Desktop#mail(java.net.URI) 0N/A * Represents a "browse" action. 0N/A * @see Desktop#browse(java.net.URI) 0N/A * Suppresses default constructor for noninstantiability. 0N/A * Returns the <code>Desktop</code> instance of the current 0N/A * browser context. On some platforms the Desktop API may not be 0N/A * supported; use the {@link #isDesktopSupported} method to 0N/A * determine if the current desktop is supported. 0N/A * @return the Desktop instance of the current browser context 0N/A * @throws HeadlessException if {@link 0N/A * GraphicsEnvironment#isHeadless()} returns {@code true} 0N/A * @throws UnsupportedOperationException if this class is not 0N/A * supported on the current platform 0N/A * @see #isDesktopSupported() 0N/A * @see java.awt.GraphicsEnvironment#isHeadless 0N/A "supported on the current platform");
0N/A * Tests whether this class is supported on the current platform. 0N/A * If it's supported, use {@link #getDesktop()} to retrieve an 0N/A * @return <code>true</code> if this class is supported on the 0N/A * current platform; <code>false</code> otherwise 0N/A * @see #getDesktop() 0N/A * Tests whether an action is supported on the current platform. 0N/A * <p>Even when the platform supports an action, a file or URI may 0N/A * not have a registered application for the action. For example, 0N/A * most of the platforms support the {@link Desktop.Action#OPEN} 0N/A * action. But for a specific file, there may not be an 0N/A * application registered to open it. In this case, {@link 0N/A * #isSupported} may return {@code true}, but the corresponding 0N/A * action method will throw an {@link IOException}. 0N/A * @param action the specified {@link Action} 0N/A * @return <code>true</code> if the specified action is supported on 0N/A * the current platform; <code>false</code> otherwise 0N/A * @see Desktop.Action 0N/A * Checks if the file is a valid file and readable. 0N/A * @throws SecurityException If a security manager exists and its 0N/A * {@link SecurityManager#checkRead(java.lang.String)} method 0N/A * denies read access to the file 0N/A * @throws NullPointerException if file is null 0N/A * @throws IllegalArgumentException if file doesn't exist 0N/A * Checks if the action type is supported. 0N/A * @param actionType the action type in question 0N/A * @throws UnsupportedOperationException if the specified action type is not 0N/A * supported on the current platform 0N/A +
" action is not supported on the current platform!");
0N/A * Calls to the security manager's <code>checkPermission</code> method with 0N/A * an <code>AWTPermission("showWindowWithoutWarningBanner")</code> 0N/A "showWindowWithoutWarningBanner"));
0N/A * Launches the associated application to open the file. 0N/A * <p> If the specified file is a directory, the file manager of 0N/A * the current platform is launched to open it. 0N/A * @param file the file to be opened with the associated application 0N/A * @throws NullPointerException if {@code file} is {@code null} 0N/A * @throws IllegalArgumentException if the specified file doesn't 0N/A * @throws UnsupportedOperationException if the current platform 0N/A * does not support the {@link Desktop.Action#OPEN} action 0N/A * @throws IOException if the specified file has no associated 0N/A * application or the associated application fails to be launched 0N/A * @throws SecurityException if a security manager exists and its 0N/A * {@link java.lang.SecurityManager#checkRead(java.lang.String)} 0N/A * method denies read access to the file, or it denies the 0N/A * <code>AWTPermission("showWindowWithoutWarningBanner")</code> 0N/A * permission, or the calling thread is not allowed to create a 0N/A * @see java.awt.AWTPermission 0N/A * Launches the associated editor application and opens a file for 0N/A * @param file the file to be opened for editing 0N/A * @throws NullPointerException if the specified file is {@code null} 0N/A * @throws IllegalArgumentException if the specified file doesn't 0N/A * @throws UnsupportedOperationException if the current platform 0N/A * does not support the {@link Desktop.Action#EDIT} action 0N/A * @throws IOException if the specified file has no associated 0N/A * editor, or the associated application fails to be launched 0N/A * @throws SecurityException if a security manager exists and its 0N/A * {@link java.lang.SecurityManager#checkRead(java.lang.String)} 0N/A * method denies read access to the file, or {@link 0N/A * java.lang.SecurityManager#checkWrite(java.lang.String)} method 0N/A * denies write access to the file, or it denies the 0N/A * <code>AWTPermission("showWindowWithoutWarningBanner")</code> 0N/A * permission, or the calling thread is not allowed to create a 0N/A * @see java.awt.AWTPermission 0N/A * Prints a file with the native desktop printing facility, using 0N/A * the associated application's print command. 0N/A * @param file the file to be printed 0N/A * @throws NullPointerException if the specified file is {@code 0N/A * @throws IllegalArgumentException if the specified file doesn't 0N/A * @throws UnsupportedOperationException if the current platform 0N/A * does not support the {@link Desktop.Action#PRINT} action 0N/A * @throws IOException if the specified file has no associated 0N/A * application that can be used to print it 0N/A * @throws SecurityException if a security manager exists and its 0N/A * {@link java.lang.SecurityManager#checkRead(java.lang.String)} 0N/A * method denies read access to the file, or its {@link 0N/A * java.lang.SecurityManager#checkPrintJobAccess()} method denies 0N/A * the permission to print the file, or the calling thread is not 0N/A * allowed to create a subprocess 0N/A * Launches the default browser to display a {@code URI}. 0N/A * If the default browser is not able to handle the specified 0N/A * {@code URI}, the application registered for handling 0N/A * {@code URIs} of the specified type is invoked. The application 0N/A * is determined from the protocol and path of the {@code URI}, as 0N/A * defined by the {@code URI} class. 0N/A * If the calling thread does not have the necessary permissions, 0N/A * and this is invoked from within an applet, 0N/A * {@code AppletContext.showDocument()} is used. Similarly, if the calling 0N/A * does not have the necessary permissions, and this is invoked from within 0N/A * a Java Web Started application, {@code BasicService.showDocument()} 0N/A * @param uri the URI to be displayed in the user default browser 0N/A * @throws NullPointerException if {@code uri} is {@code null} 0N/A * @throws UnsupportedOperationException if the current platform 0N/A * does not support the {@link Desktop.Action#BROWSE} action 0N/A * @throws IOException if the user default browser is not found, 0N/A * or it fails to be launched, or the default handler application 0N/A * failed to be launched 0N/A * @throws SecurityException if a security manager exists and it 0N/A * <code>AWTPermission("showWindowWithoutWarningBanner")</code> 0N/A * permission, or the calling thread is not allowed to create a 0N/A * subprocess; and not invoked from within an applet or Java Web Started 0N/A * @throws IllegalArgumentException if the necessary permissions 0N/A * are not available and the URI can not be converted to a {@code URL} 0N/A * @see java.awt.AWTPermission 0N/A * @see java.applet.AppletContext 0N/A // Calling thread doesn't have necessary priviledges. 0N/A // Delegate to DesktopBrowse so that it can work in 0N/A * Launches the mail composing window of the user default mail 0N/A * @throws UnsupportedOperationException if the current platform 0N/A * does not support the {@link Desktop.Action#MAIL} action 0N/A * @throws IOException if the user default mail client is not 0N/A * found, or it fails to be launched 0N/A * @throws SecurityException if a security manager exists and it 0N/A * <code>AWTPermission("showWindowWithoutWarningBanner")</code> 0N/A * permission, or the calling thread is not allowed to create a 0N/A * @see java.awt.AWTPermission 0N/A // won't reach here. 0N/A * Launches the mail composing window of the user default mail 0N/A * client, filling the message fields specified by a {@code 0N/A * <p> A <code>mailto:</code> URI can specify message fields 0N/A * including <i>"to"</i>, <i>"cc"</i>, <i>"subject"</i>, 0N/A * <i>"body"</i>, etc. See <a 0N/A * scheme (RFC 2368)</a> for the {@code mailto:} URI specification 0N/A * @param mailtoURI the specified {@code mailto:} URI 0N/A * @throws NullPointerException if the specified URI is {@code 0N/A * @throws IllegalArgumentException if the URI scheme is not 0N/A * <code>"mailto"</code> 0N/A * @throws UnsupportedOperationException if the current platform 0N/A * does not support the {@link Desktop.Action#MAIL} action 0N/A * @throws IOException if the user default mail client is not 0N/A * found or fails to be launched 0N/A * @throws SecurityException if a security manager exists and it 0N/A * <code>AWTPermission("showWindowWithoutWarningBanner")</code> 0N/A * permission, or the calling thread is not allowed to create a 0N/A * @see java.awt.AWTPermission