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: 117: private Desktop() 118: { 119: /* nothing to be done */ 120: } 121: 122: /** 123: * Returns an istance 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: */ 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: */ 158: private 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 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: */ 263: public void print(File file) 264: throws IOException 265: { 266: peer.print(file); 267: } 268: }