1 /* Desktop.java -- enable desktop integration between java programs and system 2 programs. 3 Copyright (C) 2006 Free Software Foundation, Inc. 4 5 This file is part of GNU Classpath. 6 7 GNU Classpath is free software; you can redistribute it and/or modify 8 it under the terms of the GNU General Public License as published by 9 the Free Software Foundation; either version 2, or (at your option) 10 any later version. 11 12 GNU Classpath is distributed in the hope that it will be useful, but 13 WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with GNU Classpath; see the file COPYING. If not, write to the 19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 20 02110-1301 USA. 21 22 Linking this library statically or dynamically with other modules is 23 making a combined work based on this library. Thus, the terms and 24 conditions of the GNU General Public License cover the whole 25 combination. 26 27 As a special exception, the copyright holders of this library give you 28 permission to link this library with independent modules to produce an 29 executable, regardless of the license terms of these independent 30 modules, and to copy and distribute the resulting executable under 31 terms of your choice, provided that you also meet, for each linked 32 independent module, the terms and conditions of the license of that 33 module. An independent module is a module which is not derived from 34 or based on this library. If you modify this library, you may extend 35 this exception to your version of the library, but you are not 36 obligated to do so. If you do not wish to do so, delete this 37 exception statement from your version. */ 38 39 40 package java.awt; 41 42 import java.awt.peer.DesktopPeer; 43 import java.io.File; 44 import java.io.IOException; 45 import java.net.URI; 46 47 /** 48 * This class enables Java application to access system commands to perform 49 * desktop oriented operations, like writing and sending emails, or surfing 50 * webpages with the system browser or editing/printing files with a default 51 * editor. Methods are provided to handle these common operations, plus an 52 * <code>open</code> command selects a default registered application for the 53 * specified file type. For example, opening an odf file results in launching 54 * OpenOffice. If an operation is not supported, or the application fails to 55 * launch, an exception is generated. 56 * 57 * <strong>Implementation note: </strong>As this class is used to manage Desktop 58 * integration, we provide some extension to configure the behaviour of this 59 * class depending on the type of dektop that is detected.<br /> 60 * 61 * First of all, we support 5 system properties that can be used to define 62 * the application to launch in any given case. These properties are:<br /> 63 * <br /> 64 * <code>gnu.java.awt.peer.Desktop.html.command</code><br /> 65 * <code>gnu.java.awt.peer.Desktop.mail.command</code><br /> 66 * <code>gnu.java.awt.peer.Desktop.edit.command</code><br /> 67 * <code>gnu.java.awt.peer.Desktop.print.command</code><br /> 68 * <code>gnu.java.awt.peer.Desktop.open.command</code><br /> 69 * <br /> 70 * <br /> 71 * These can be specified from the command line and have priority on every 72 * other setting.<br /> 73 * <br /> 74 * The second method supported is defining a Java preference.<br /> 75 * The main preference node is a <strong>user node</strong> relative to the 76 * class <code>gnu.java.awt.peer.ClasspathDesktopPeer</code>. This node 77 * contains a child for each supported operation. The key for each type is 78 * always <code>command</code>: 79 * <br /><br /> 80 * <code>gnu.java.awt.peer.Desktop.html.command</code><br /> 81 * <code>gnu.java.awt.peer.Desktop.mail.command</code><br /> 82 * <code>gnu.java.awt.peer.Desktop.edit.command</code><br /> 83 * <code>gnu.java.awt.peer.Desktop.print.command</code><br /> 84 * <code>gnu.java.awt.peer.Desktop.open.command</code><br /> 85 * <br /> 86 * <br /> 87 * The access to these keys is done with the Preference API or, if outside 88 * of the java scope, is done in a backend dependent way. For example, 89 * with the GConf backend, you can access these properties 90 * with (may not be accurate on your system): 91 * <br /><br /> 92 * <code> 93 * gconftool-2 -g /apps/classpath/gnu/java/awt/peer/Desktop/html/command 94 * </code> 95 * 96 * @author Mario Torre <neugens@limasoftware.net> 97 * @since 1.6 98 */ 99 public class Desktop 100 { 101 /** 102 * Represents an action type supported by a platform. 103 * 104 * To determine if a given action is supported by the platform, 105 * use the <code>Desktop.isSupported(java.awt.Desktop.Action)</code> 106 * method. 107 * 108 * @author Mario Torre <neugens@limasoftware.net> 109 */ 110 public enum Action 111 { 112 BROWSE, EDIT, MAIL, OPEN, PRINT 113 } 114 115 private DesktopPeer peer; 116 Desktop()117 private Desktop() 118 { 119 /* nothing to be done */ 120 } 121 122 /** 123 * Returns an instance of the Desktop Class. 124 * 125 * If this implementation does not support Desktop, an 126 * UnsupportedOperationException will be thrown. 127 * Also, an HeadlessException will be generated if 128 * GraphicsEnvironment.isHeadless() returns true. 129 * 130 * @throws UnsupportedOperationException 131 * @throws HeadlessException 132 */ getDesktop()133 public static Desktop getDesktop() throws UnsupportedOperationException, 134 HeadlessException 135 { 136 if (GraphicsEnvironment.isHeadless()) 137 throw new HeadlessException(); 138 139 if (!Desktop.isDesktopSupported()) 140 throw new UnsupportedOperationException(); 141 142 Desktop desktop = new Desktop(); 143 desktop.peer = Toolkit.getDefaultToolkit().createDesktopPeer(desktop); 144 145 return desktop; 146 } 147 148 /** 149 * Check if this implementation supports Desktop. 150 * If true, use getDesktop to get an instance of this class. 151 * 152 * This implementation will return false when GraphicsEnvironment.isHeadless 153 * returns true. 154 * 155 * @return true if this class is supported on the current platform; 156 * false otherwise 157 */ isDesktopSupported()158 public static boolean isDesktopSupported() 159 { 160 if (GraphicsEnvironment.isHeadless()) 161 return false; 162 163 return true; 164 } 165 166 /** 167 * Check if the given Action is supported by this implementation. 168 * 169 * @param action 170 * @return 171 */ isSupported(Desktop.Action action)172 public boolean isSupported(Desktop.Action action) 173 { 174 return peer.isSupported(action); 175 } 176 177 /** 178 * Launches the Desktop default browser to open the given <code>uri</code>. 179 * 180 * If a security manager exists and denies 181 * AWTPermission("showWindowWithoutWarningBanner"),a SecurityException will 182 * be generated. 183 * 184 * @param uri 185 * @throws IOException 186 */ browse(URI uri)187 public void browse(URI uri) 188 throws IOException 189 { 190 peer.browse(uri); 191 } 192 193 /** 194 * Launch the edit command to edit this file. 195 * File should already exist before the editing starts. 196 * 197 * If a security manager exists and 198 * SecurityManager.checkRead(java.lang.String) method denies read access to 199 * the file, or SecurityManager.checkPrintJobAccess() method denies the 200 * permission to print the file, a SecurityException will be generated. 201 * 202 * @param file 203 * @throws IOException 204 */ edit(File file)205 public void edit(File file) 206 throws IOException 207 { 208 peer.edit(file); 209 } 210 211 /** 212 * Launches the Desktop default mailer. 213 * 214 * If a security manager exists and denies 215 * AWTPermission("showWindowWithoutWarningBanner"), a SecurityException will 216 * be generated. 217 * 218 * @throws IOException 219 */ mail()220 public void mail() 221 throws IOException 222 { 223 peer.mail(); 224 } 225 226 /** 227 * Launches the Desktop default mailer, with the given mailtoURI 228 * as agrument. The <code>mailtoURI</code> must conform to the 229 * {@link http://www.ietf.org/rfc/rfc2368.txt The mailto URL scheme (RFC 2368)} 230 * 231 * If a security manager exists and denies 232 * AWTPermission("showWindowWithoutWarningBanner"), a SecurityException will 233 * be generated. 234 * 235 * @param mailtoURI 236 * @throws IOException 237 */ mail(URI mailtoURI)238 public void mail(URI mailtoURI) 239 throws IOException 240 { 241 peer.mail(mailtoURI); 242 } 243 244 /** 245 * Launches the Desktop default application to open the given File. 246 * If <code>file</code> is a directory, a file manager is launched. 247 * 248 * @param file 249 * @throws IOException 250 */ open(File file)251 public void open(File file) 252 throws IOException 253 { 254 peer.open(file); 255 } 256 257 /** 258 * Launch the print program to print this file. 259 * 260 * @param file 261 * @throws IOException 262 */ print(File file)263 public void print(File file) 264 throws IOException 265 { 266 peer.print(file); 267 } 268 } 269