Using the Desktop API in Java SE 6

Running the DesktopDemo Application

DesktopDemo is a simple Java application that uses the new Desktop API. The application has one main window that exposes the entire API, allowing you to do three things:

1. Launch the default browser with a specific URI.
2. Launch the default email client with a mail recipient.
3. Launch an associated application to open, edit, or print a file.

[img]http://java.sun.com/developer/technicalArticles/J2SE/Desktop/javase6/desktop_api/DesktopDemoUI.gif[/img]

You can run this application by downloading the application source and JAR files, changing your console's active directory to the application project's dist directory, and executing the following command using a JDK 6:

 java -jar DesktopDemo.jar

Determining Desktop API Support

Before launching the browser, email client, or any application, DesktopDemo must determine whether your platform supports the API. First, however, DesktopDemo disables all the graphical text fields and buttons. It enables these graphical components after determining that the platform supports them.

After instantiating the UI, the application's constructor quickly disables the few components of this application as shown in the following code:

 public DesktopDemo() {
        // Initiate all GUI components.
        initComponents();
        // Disable buttons that launch browser and email client. 
        // Disable buttons that open, edit, and print files.
        disableActions();
        ...
    }

    /**
     * Disable all graphical components until we know
     * whether their functionality is supported.
     */
    private void disableActions() {
        txtBrowserURI.setEnabled(false);
        btnLaunchBrowser.setEnabled(false);

        txtMailTo.setEnabled(false);
        btnLaunchEmail.setEnabled(false);

        rbEdit.setEnabled(false);
        rbOpen.setEnabled(false);
        rbPrint.setEnabled(false);

        txtFile.setEnabled(false);
        btnLaunchApplication.setEnabled(false);        
    }

    ...

    public javax.swing.JTextField txtBrowserURI;
    public javax.swing.JButton btnLaunchBrowser;
    public javax.swing.JTextField txtMailTo;
    public javax.swing.JButton btnLaunchEmail;
    public javax.swing.JRadioButton rbEdit;
    public javax.swing.JRadioButton rbOpen;
    public javax.swing.JRadioButton rbPrint;
    public javax.swing.JTextField txtFile;
    public javax.swing.JButton btnLaunchApplication;

Use the Desktop.isDesktopSupported() method to determine whether the Desktop API is available. On the Solaris Operating System and the Linux platform, this API is dependent on Gnome libraries. If those libraries are unavailable, this method will return false. After determining that the API is supported, that is, the isDesktopSupported() returns true, the application can retrieve a Desktop instance using the static method getDesktop().

Desktop desktop = null;
    // Before more Desktop API is used, first check 
    // whether the API is supported by this particular 
    // virtual machine (VM) on this particular host.
    if (Desktop.isDesktopSupported()) {
        desktop = Desktop.getDesktop();
        ...

If your application doesn't check for API support using isDesktopSupported() before calling getDesktop(), it must be prepared to catch an UnsupportedOperationException, which is thrown when your application requests a Desktop instance on a platform that does not support these features. Additionally, if your application runs in an environment without a keyboard, mouse, or monitor (a "headless" environment), the getDesktop() method will throw a java.awt.HeadlessException.

Once retrieved, the Desktop instance allows your application to browse, mail, open, edit, or even print a file or URI, but only if the retrieved Desktop instance supports these activities. Each of these activities is called an action, and each is represented as a Desktop.Action enumeration instance:

* BROWSE. Represents a browse action performed by the host's default browser
* MAIL. Represents a mail action performed by the host's default email client
* OPEN. Represents an open action performed by an application associated with opening a specific file type
* EDIT. Represents an edit action performed by an application associated with editing a specific file type
* PRINT. Represents a print action performed by an application associated with printing a specific file type


[b]Opening the Browser[/b]

Calling the following instance method will open your host's default browser:

public void browse(URI uri) throws IOException

Because DesktopDemo's UI components are enabled only if the associated Desktop.Action is supported, this simple demo application doesn't need to check support again before actually calling the browse() method. However, checking action support before each invocation may be more robust in real-world applications:

if (desktop.isSupported(Desktop.Action.BROWSE)) {
        // launch browser
        ...
    }

DesktopDemo adds a java.awt.event.ActionListener to each button. When enabled, the Launch Browser button invokes the following method through its ActionListener:

 private void onLaunchBrowser(java.awt.event.ActionEvent evt) {
        URI uri = null;
        try {
            uri = new URI(txtBrowserURI.getText());
            desktop.browse(uri);
        }
        catch(IOException ioe) {
            ioe.printStackTrace();
        }
        catch(URISyntaxException use) {
            use.printStackTrace();

        }
        ...
    }

The browse() method can throw a variety of exceptions, including a NullPointerException if the URI is null, an UnsupportedOperationException if the BROWSE action is unsupported, an IOException if the default browser or application can't be found or launched, and a SecurityException if a security manager denies the invocation.

If all goes well, however, the listener retrieves the text from the associated text field in Figure 4, creates a URI, and invokes the browse() method. The code above launches the default browser on your system and instructs the browser to load the URI, as Figure 5 shows.

[b]Sending Email[/b]

Applications can launch the host's default email client, if that action is supported, by calling this Desktop instance method:

public void mail(URI uri) throws IOException

DesktopDemo has an ActionListener for the Launch Mail button. In this case, the listener invokes the following method:

   private void onLaunchMail(java.awt.event.ActionEvent evt) {
        String mailTo = txtMailTo.getText();
        URI uriMailTo = null;
        try {
            if (mailTo.length() > 0) {
                uriMailTo = new URI("mailto", mailTo, null);
                desktop.mail(uriMailTo);
            } else {
                desktop.mail();
            }
        }
        catch(IOException ioe) {
            ioe.printStackTrace();
        }
        catch(URISyntaxException use) {
            use.printStackTrace();
        }
        ...
    }

The onLaunchMail() method retrieves the email recipient from the associated text field, creates the URI with a mailto scheme argument if a recipient exists, and then invokes the mail() method. The mail() method is overloaded, so you can call it with or without a URI that represents its mailto recipient.

You can use more than just a single email recipient when creating this URI. The mailto scheme supports CC, BCC, SUBJECT, and BODY fields as well. For example, the following text could be used to create a mailto URI:

  mailto:duke@sun.com?SUBJECT=Happy New Year!&BODY=Happy New Year, Duke!

[img]http://java.sun.com/developer/technicalArticles/J2SE/Desktop/javase6/desktop_api/DesktopEmailClient.gif[/img]

You can, of course, invoke mail() without an argument. In this case, your email client will launch a new email window without specifying a recipient, subject, or body message.

[b]Opening, Editing, and Printing a File[/b]

Java applications can open, edit, and print files from their associated application using a Desktop object's open(), edit(), and print() methods, respectively (see Figure 8). Again, DesktopDemo allows these actions only if the Desktop instance supports them, so in this application scenario, it is not necessary to check for support again.

Each of DesktopDemo's radio buttons has its own ActionListener as well. In this case, each sets an instance variable so that it represents the most recently selected button's associated Desktop.Action:

Desktop.Action action;

 private void onPrintAction(java.awt.event.ActionEvent evt) {
        action = Desktop.Action.PRINT;
    }                              

    private void onEditAction(java.awt.event.ActionEvent evt) {
        action = Desktop.Action.EDIT;
    }                             

    private void onOpenAction(java.awt.event.ActionEvent evt) {
        action = Desktop.Action.OPEN;
    }

When you press the Launch Default Application button, it invokes its own listener, which calls the following method:

  private void onLaunchDefaultApplication(java.awt.event.ActionEvent evt) {
        String fileName = txtFile.getText();
        File file = new File(fileName);

        try {
            switch(action) {
                case OPEN:
                    desktop.open(file);
                    break;
                case EDIT:
                    desktop.edit(file);
                    break;
                case PRINT:
                    desktop.print(file);
                    break;
            }
        }
        catch (IOException ioe) {
            ioe.printStackTrace();
        }
        ...
    }

This method determines which Desktop.Action is selected and invokes the appropriate Desktop instance method, either open(), edit(), or print(). Each method requires a File argument, which will be used to perform the requested action.

Interestingly, different applications may be registered for these different actions even on the same file type. For example, the Firefox browser may be launched for the OPEN action, Emacs for the EDIT action, and yet a different application for the PRINT action. Your host desktop's associations are used to determine what application should be invoked. The ability to manipulate desktop file associations is not possible with the existing Desktop API in JDK 6, and those associations can be created or changed only with platform-dependent tools at this time.

Summary
-----------------
Desktop integration is an important theme. One way that Java SE 6 technology supports this theme is through the java.awt.Desktop API. This API allows Java applications to launch the host's default browser and email client. Additionally, Java applications can launch applications associated with specific file types to open, edit, and print files. Although Java applications cannot manipulate, create, or change file associations, the Desktop API does allow Java applications to launch the default associated applications. This article provides a sample application that demonstrates the API, which you can download from this site.

Note: Any API additions or other enhancements to the Java SE platform specification are subject to review and approval by the JSR 270 Expert Group.
For More Information