[API Review] RT-27887: introduce a node to embed Swing into JavaFX

[Anton V. Tarasov]

Hi All,

Please, review a request to add a new SwingNode class:

http://javafx-jira.kenai.com/browse/RT-27887

/**
  * This class is used to embed a Swing content into a JavaFX application.
  * The content to be displayed is specified with the {@link 
#setContent} method
  * that accepts an instance of Swing {@code JComponent}. The hierarchy 
of components
  * contained in the {@code JComponent} instance should not contain any 
heavyweight
  * components, otherwise {@code SwingNode} may fail to paint it. The 
content gets
  * repainted automatically. All the input and focus events are 
forwarded to the
  * {@code JComponent} instance transparently to the developer.
  * <p>
  * Here is a typical pattern which demonstrates how {@code SwingNode} 
can be used:
  * <pre>
  *     public class SwingFx extends Application {
  *
  *         private SwingNode swingNode;
  *
  * &#064;Override
  *         public void start(Stage stage) {
  *             swingNode = new SwingNode();
  *
  *             createAndSetSwingContent();
  *
  *             StackPane pane = new StackPane();
  *             pane.getChildren().add(swingNode);
  *
  *             stage.setScene(new Scene(pane, 100, 50));
  *             stage.show();
  *         }
  *
  *         private void createAndSetSwingContent() {
  *             SwingUtilities.invokeLater(new Runnable() {
  * &#064;Override
  *                 public void run() {
  *                     swingNode.setContent(new JButton("Click me!"));
  *                 }
  *             });
  *         }
  *     }
  * </pre>
  */
public class SwingNode extends Node {
    /**
      * Constructs a new instance of {@code SwingNode}.
      */
     public SwingNode();

     /**
      * Attaches a {@code JComponent} instance to display in this {@code 
SwingNode}.
      * The method can be called either on the event dispatch thread or 
the JavaFX
      * application thread.
      *
      * @param content a component to display in this {@code SwingNode}
      *
      * @see java.awt.EventQueue#isDispatchThread()
      * @see javafx.application.Platform#isFxApplicationThread()
      */
     public void setContent(final JComponent content);

     /**
      * Returns the {@code JComponent} instance attached to this {@code 
SwingNode}.
      *
      * @return the {@code JComponent} instance attached to this {@code 
SwingNode}
      */
     public JComponent getContent();
}

Additional question is about disposing. When SwingNode is removed from a 
Scene its underlying
resources (on the AWT toolkit side) should be released. An option is to 
add a "dispose" method to
the node and leave it to a user's discretion when to call it. However, 
having this managed
automatically would be preferable. For that, a node should be able to be 
notified when it is no
longer a part of a rendering process. This is an issue and it is tracked 
separately as RT-129.

Thanks,
Anton.