001/* Desktop.java -- enable desktop integration between java programs and system
002 programs.
003 Copyright (C) 2006 Free Software Foundation, Inc.
004
005 This file is part of GNU Classpath.
006
007 GNU Classpath is free software; you can redistribute it and/or modify
008 it under the terms of the GNU General Public License as published by
009 the Free Software Foundation; either version 2, or (at your option)
010 any later version.
011
012 GNU Classpath is distributed in the hope that it will be useful, but
013 WITHOUT ANY WARRANTY; without even the implied warranty of
014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015 General Public License for more details.
016
017 You should have received a copy of the GNU General Public License
018 along with GNU Classpath; see the file COPYING.  If not, write to the
019 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020 02110-1301 USA.
021
022 Linking this library statically or dynamically with other modules is
023 making a combined work based on this library.  Thus, the terms and
024 conditions of the GNU General Public License cover the whole
025 combination.
026
027 As a special exception, the copyright holders of this library give you
028 permission to link this library with independent modules to produce an
029 executable, regardless of the license terms of these independent
030 modules, and to copy and distribute the resulting executable under
031 terms of your choice, provided that you also meet, for each linked
032 independent module, the terms and conditions of the license of that
033 module.  An independent module is a module which is not derived from
034 or based on this library.  If you modify this library, you may extend
035 this exception to your version of the library, but you are not
036 obligated to do so.  If you do not wish to do so, delete this
037 exception statement from your version. */
038
039
040package java.awt;
041
042import java.awt.peer.DesktopPeer;
043import java.io.File;
044import java.io.IOException;
045import java.net.URI;
046
047/**
048 * This class enables Java application to access system commands to perform
049 * desktop oriented operations, like writing and sending emails, or surfing
050 * webpages with the system browser or editing/printing files with a default
051 * editor. Methods are provided to handle these common operations, plus an
052 * <code>open</code> command selects a default registered application for the
053 * specified file type. For example, opening an odf file results in launching
054 * OpenOffice. If an operation is not supported, or the application fails to
055 * launch, an exception is generated.
056 * 
057 * <strong>Implementation note: </strong>As this class is used to manage Desktop
058 * integration, we provide some extension to configure the behaviour of this
059 * class depending on the type of dektop that is detected.<br />
060 * 
061 * First of all, we support 5 system properties that can be used to define
062 * the application to launch in any given case. These properties are:<br />
063 * <br />
064 * <code>gnu.java.awt.peer.Desktop.html.command</code><br />
065 * <code>gnu.java.awt.peer.Desktop.mail.command</code><br />
066 * <code>gnu.java.awt.peer.Desktop.edit.command</code><br />
067 * <code>gnu.java.awt.peer.Desktop.print.command</code><br />
068 * <code>gnu.java.awt.peer.Desktop.open.command</code><br />
069 * <br />
070 * <br />
071 * These can be specified from the command line and have priority on every
072 * other setting.<br />
073 * <br />
074 * The second method supported is defining a Java preference.<br />
075 * The main preference node is a <strong>user node</strong> relative to the
076 * class <code>gnu.java.awt.peer.ClasspathDesktopPeer</code>. This node
077 * contains a child for each supported operation. The key for each type is
078 * always <code>command</code>:
079 * <br /><br />
080 * <code>gnu.java.awt.peer.Desktop.html.command</code><br />
081 * <code>gnu.java.awt.peer.Desktop.mail.command</code><br />
082 * <code>gnu.java.awt.peer.Desktop.edit.command</code><br />
083 * <code>gnu.java.awt.peer.Desktop.print.command</code><br />
084 * <code>gnu.java.awt.peer.Desktop.open.command</code><br />
085 * <br />
086 * <br />
087 * The access to these keys is done with the Preference API or, if outside
088 * of the java scope, is done in a backend dependent way. For example,
089 * with the GConf backend, you can access these properties
090 * with (may not be accurate on your system):
091 * <br /><br />
092 * <code>
093 * gconftool-2 -g /apps/classpath/gnu/java/awt/peer/Desktop/html/command
094 * </code> 
095 * 
096 * @author Mario Torre <neugens@limasoftware.net>
097 * @since 1.6
098 */
099public 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 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   */
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  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   */
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}