Source for java.awt.Desktop

   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: }