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    
040    package java.awt;
041    
042    import java.awt.peer.DesktopPeer;
043    import java.io.File;
044    import java.io.IOException;
045    import 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     */
099    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    }