Using the Desktop API in Java SE 6 (Mustang)
With the default graphical user interface (GUI) look and feel, printing, and performance, the Java platform has come a long way in its effort to minimize the difference between the performance and integration of native applications and Java applications. Version 6 of the Java Platform, Standard Edition (Java SE), code-named Mustang, continues to narrow the gap with new system tray functionality, better print support for JTable, and now the Desktop API (java.awt.Desktop API). This article describes the new Desktop API, which allows Java applications to interact with the default applications associated with specific file types on the host platform. In order to describe the API more effectively, the article also features a simple application called DesktopDemo.
Desktop Overview
This new functionality is provided by the java.awt.Desktop class. The API is adopted from the JDesktop Integration Components (JDIC) project. The goal of that project is to make "Java technology-based applications first-class citizens" of the desktop, enabling seamless integration. Specifically, the new Desktop API allows your Java applications to do the following:
- Launch the host system's default browser with a specific Uniform Resource Identifier (URI)
- Launch the host system's default email client
- Launch applications to open, edit, or print files associatedwith those applications
The Desktop API uses your host operating system's file associations to launch applications associated with specific file types. For example, if OpenDocument text (.odt) file extensions are associated with the OpenOffice Writer application, your Java application could launch OpenOffice Writer to open, edit, or even print files with that association. Depending on your host system, different applications may be associated with each different action.
Running the DesktopDemo Application
DesktopDemo is a simple Java application that uses Mustang's Desktop API. The application has one main window that exposes the entire API, allowing you to do three things:
- Launch the default browser with a specific URI.
- Launch the default email client with a mail recipient.
- Launch an associated application to open, edit, or print a file.
Figure 1 shows the user interface (UI).
 | | Figure 1: DesktopDemo UI | |
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 Mustang JDK:
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
Before invoking any of these actions, an application should determine whether the Desktop instance supports them. This is different from determining whether a Desktop instance is available. The Desktop.isDesktopSupported() method tells you whether an instance can be created. Once a Desktop object is acquired, you can query the object to find out which specific actions are supported. If the Desktop object does not support specific actions, or if the Desktop API itself is unsupported, DesktopDemo simply keeps the affected graphical components disabled. As Figure 2 indicates, the components cannot be used to invoke Desktop features in the disabled state.
 | | Figure 2: Graphical components are disabled when the desktop is unsupported. | |
Using a new Desktop instance, the following code checks each Desktop.Action for support and enables the appropriate graphical components:
public DesktopDemo() {
...
// Before more Desktop API is used, first check
// whether the API is supported by this particular
// VM on this particular host.
if (Desktop.isDesktopSupported()) {
desktop = Desktop.getDesktop();
// Now enable buttons for actions that are supported.
enableSupportedActions();
}
...
}
/**
* Enable actions that are supported on this host.
* The actions are the following: open browser,
* open email client, and open, edit, and print
* files using their associated application.
*/
private void enableSupportedActions() {
if (desktop.isSupported(Desktop.Action.BROWSE)) {
txtBrowserURI.setEnabled(true);
btnLaunchBrowser.setEnabled(true);
}
if (desktop.isSupported(Desktop.Action.MAIL)) {
txtMailTo.setEnabled(true);
btnLaunchEmail.setEnabled(true);
}
if (desktop.isSupported(Desktop.Action.OPEN)) {
rbOpen.setEnabled(true);
}
if (desktop.isSupported(Desktop.Action.EDIT)) {
rbEdit.setEnabled(true);
}
if (desktop.isSupported(Desktop.Action.PRINT)) {
rbPrint.setEnabled(true);
}
if (rbEdit.isEnabled() || rbOpen.isEnabled() || rbPrint.isEnabled()) {
txtFile.setEnabled(true);
btnLaunchApplication.setEnabled(true);
}
}
|
Once the application determines the supported actions, it enables the appropriate graphical components. If all components are enabled, the UI should look like Figure 3.
| | Figure 3: Components are enabled when the Desktop API is supported. | |
Opening the Browser
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.
 | | Figure 4: Launch the default browser with a specific URI. | |
 | | Figure 5: The default browser launches using the Desktop API. | |
Sending Email
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 (see Figure 6).
 | | Figure 6: Launch the default email client with an email 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!
|
Figure 7 shows the result.
 mailto parameters." border="0" height="415" width="538"> | | Figure 7: The Desktop API launches the default email client with multiple mailto parameters. | |
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.
Opening, Editing, and Printing a File
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.
 | | Figure 8: Launch the associated application for a specific file type. | |
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 Mustang, and those associations can be created or changed only with platform-dependent tools at this time.
Summary
Desktop integration is an important Mustang theme. One way that Mustang 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
The following information may help you learn more about Mustang's integration features as well as related topics:
No comments:
Post a Comment