Platinum Partner
netbeans

Getting Started with Spring RCP

Let's familiarize ourselves with the Spring RCP. New life seems to have been blowing into this project: after almost two years of hiatus, the 1.0.0 release came out a few months ago. Let's leave aside the question about its direction and so on and, instead, let's look purely at the technology itself to see exactly what it offers. In that light, I've made available a simple plugin for NetBeans IDE that provides samples and templates to get things started. Below, I walk through a basic scenario using the plugin. However, even those who are not NetBeans users could learn a lot about Spring RCP by reading the steps in this tutorial and the explanations that accompany them.

Table of Contents

Getting Started


  1. Install the Spring RCP Tooling plugin into NetBeans IDE 6.1.

  2. In the New Project wizard (Ctrl-Shift-N), you will find a new project template:

     

  3. Complete the wizard and you have a project structure as follows:

    A brief overview of the files that you see above (be aware that if you move "richclient-application-context.xml" or "messages.properties" to any other place, or if you rename either of them, you need to update the Spring Rich Client panel in the application's Project Properties dialog box):

    File Explanation
    SimpleApp.java
    Provides the application's "main" method and launches the application
    via the Spring RCP "ApplicationLauncher" class. That class loads the
    application context XML file and the startup context XML file, where application-level concerns such as the splash screen, initialization sequences, and views are defined.
    SimpleLifecycleAdvisor.java Provides lifecycle management for the application. This class is
    registered in the application context XML file. It provides methods such
    as "onWindowOpened" and "onCommandsCreated", so that you have
    entry points to customize what happens when the application starts. (For example, you can adjust the application's size in the "onPreWindowOpen" method.)
    richclient-application-context.xml Provides the application context XML file, which configures the Spring RCP
    components and services.
    richclient-startup-context.xml Provides the startup context XML file, which defines the splash screen, but could define anything that you want to have happen specifically at startup.
    images.properties Provides the image resource. It is registered in the application context
    XML file.
    splash-screen.jpg Provides the splash screen image that is used in the startup context XML
    file.
    commands-context.xml Provides the application's commands, organized within menu bars and toolbars, and the items within them. This file is declared in the application context XML file.
    messages.properties Provides the display texts in a centralized location. For example, texts for titles and descriptions are found here.


    Note: The template also put most of the Spring RCP JARs on your application's classpath. Look in the Libraries node to see which ones are there. Potentially, more JARs could be included in the plugin as the complexity of the provided tooling increases.

     

  4. Run the application. You should see this:

Creating a View

Now we will create a new window in our application.

  1. Right-click the project node and choose New | Spring View, as shown here:

  2.  

  3. In the New Spring View dialog, type "CustomerView" and set the existing package as your package name:

     

  4. Click Finish. You now have a new class that extends the Spring RCP AbstractView class:
    package simple;

    import javax.swing.JComponent;
    import javax.swing.JPanel;
    import org.springframework.richclient.application.support.AbstractView;

    public class CustomerView extends AbstractView {

    @Override
    protected JComponent createControl() {
    JPanel panel = new JPanel();
    return panel;
    }

    }

    Open the richclient-application-context.xml file. At the end of the file, notice that your view has been automatically registered for you as follows:

    <bean id="CustomerView" class="org.springframework.richclient.application.support.DefaultViewDescriptor">
    <property name="viewClass" value="simple.CustomerView"></property>
    </bean>

    Finally, open ui/messages.properties and notice the new entry for the menu item that will open the view:

    CustomerView.label=&CustomerView

     

  5. Run the application and go to Window | Show View, from where you can open the new Customer View:

     

  6. Let's make our new view open by default whenever the application starts. In other words, our Customer View will be the application's initial view. To do that, open the richclient-application-context.xml file and find the bean that has "lifecycleAdvisor" as its "id" attribute. Add this property to that bean's list of properties:
    <property name="startingPageId" value="CustomerView" />

    Notice that the "name" attribute can be completed automatically if you call up code completion (which is Ctrl-Space, by default):

    Therefore, the whole bean definition is now as follows:

    <bean id="lifecycleAdvisor" class="simple.SimpleLifecycleAdvisor">
    <property name="startingPageId" value="CustomerView" />
    <property name="windowCommandBarDefinitions" value="ui/commands-context.xml" />
    <property name="windowCommandManagerBeanName" value="windowCommandManager" />
    <property name="menubarBeanName" value="menuBar" />
    <property name="toolbarBeanName" value="toolBar" />
    </bean>

     

  7. Run the application again and notice that the Customer View now appears when the application starts.

Adding Customer Data

Next, we'll use our new Spring View to display customer data to our users. Nothing in this section is specific to Spring RCP. Nothing more than its seamless integration with standard Swing development is demonstrated below, together with the related benefit of being able to use the associated development tools provided by NetBeans IDE. We'll use one of the databases bundled with the IDE, but we could be using any database at all.

     

  1. Right-click the project node and choose New | JPanel Form. Name the panel "CustomerPanel" and choose "simple" in the package drop-down so that your panel will be created in the same package as where the other classes are found. Click Finish.
  2.  

  3. Open "CustomerView.java". Change the line that instantiates the JPanel so that your new CustomerPanel is created instead:
    public class CustomerView extends AbstractView {

    @Override
    protected JComponent createControl() {
    JPanel panel = new CustomerPanel();
    return panel;
    }

    }

    Now, whenever you run the application, the CustomerPanel will define the initial view.

     

  4. Open the Services window (Ctrl-5). In the Services window, expand the Databases node, right-click the jdbc:derby node, and choose Connect. The IDE now connects to its bundled Derby database. Expand the jdbc:derby node, expand the Tables node, and notice that there is a table called "CUSTOMER". That's the table we'll show in our application.

     

  5. Open the CustomerPanel in Design mode. Next, drag and drop a table from the Palette onto the CustomerPanel's Design view. Finally, drag and drop the CUSTOMER node onto the table. You should now see this:

    Note: Make sure that you click the two arrow buttons on the top right of the screenshot above. Doing that will result in the JTable resizing automatically at runtime, to fit snugly into the size of the JPanel.

  6.  

  7. The related JAR files should automatically be added to your project. If they're not and you see a lot of error messages in the generated code, right-click the Libraries node, choose Add Library, and then add "Beans Binding" and "TopLink Essentials", as well as "derbyclient.jar" from your JDK's db/lib folder.

     

  8. Back in the Projects window, you should see that JPA-related artifacts have been added to your project:

     

  9. Run the application and you will see your initial view populated with data from your database:

Adding Docking Views

At the moment, we only have one view (i.e., one window). One of the central reasons for desktop developers choosing to use an RCP is the need for a windowing system. As soon as a desktop application starts becoming non-trivial, you need to be able to deal with multiple windows. More than simply showing multiple windows, you also need to provide functionality for maximizing and minimizing them, for opening and closing them, for docking and undocking them. Not much fun to code all of that. Let's see how Spring RCP can help us with this basic requirement.

  1. First, we need to add a new view, so that we have two windows. Use the Spring View template, as described earlier in this tutorial, and add a new view with whatever name you like, in the same package as before (or anywhere else). As before, the view is registered for you in the richclient-application-context.xml file, as well as in the messages.properties file.

     

  2. When you run the application, you'll have two menu items under Window | Show View. On selection, the second view replaces the first view, and vice versa. That's not docking, that's replacing. So let's now change that so that both are displayed at the same time, i.e., so that both windows dock within the Spring RCP.

     

  3. Begin by adding this bean to the richclient-application-context.xml file:
    <bean id="applicationPageFactory" depends-on="serviceLocator"   
    class="org.springframework.richclient.application.docking.vldocking.VLDockingApplicationPageFactory">
    </bean>

     

  4. Run the application. When you open both views, you should see the following:

  5.  

  6. Next, find the beans that declare the two views and change the class that they use in the richclient-application-context.xml to the following:
    org.springframework.richclient.application.docking.vldocking.VLDockingViewDescriptor

    So now the bean for the Customer View should be as follows, while the same should be true for the other view you created:
    <bean id="CustomerView" class="org.springframework.richclient.application.docking.vldocking.VLDockingViewDescriptor">
    <property name="viewClass" value="simple.CustomerView" />
    </bean>
  7.  

  8. Let's now look more carefully at how our views are defined. Find the CustomerView bean, place the cursor at the start of the property element's "name" attribute's value, and call up code completion (Ctrl-Space). You should now see the list of possible values displayed:

    Go ahead and take a whole bunch of those names, specifically, the ones shown below, setting them all to "true":

    <bean id="CustomerView" class="org.springframework.richclient.application.docking.vldocking.VLDockingViewDescriptor">
    <property name="viewClass" value="simple.CustomerView" />
    <property name="autoHideEnabled" value="true" />
    <property name="closeEnabled" value="true" />
    <property name="floatEnabled" value="true" />
    <property name="maximizeEnabled" value="true"/>
    </bean>

    You can do the same for the other view, depending on which of the properties above you would like to make available to that particular window. The names of the above properties are self explanatory, except for "autoHideEnabled", which will add minimize functionality to your view.
  9.  

  10. Run the application again and notice some small new buttons in the top right of the view:

    If you right-click inside the title bar, you see the same options, this time as menu items together with the keystroke that can invoke them:

  11.  

     

  12. Try out a few of those new features in your application. For example, click the "Detach" button and then you're able to move the whole view out of the application (handy if your user has multiple monitors, for example), as shown below:

  13. Note: To be able to drag a detached window, your cursor needs to become a hand, which is what happens when you move the mouse over the dotted line at the top of the window's title bar.

     

  14. Finally, drag the title bar of a view to a position where it could conceivably be dropped and then you will see a shadow where it will appear when you release the view:

  15.  

  16. Once you have more windows, you can move them around and you can even end up with tabs, if you drag the window to the correct position, as shown below:

    Note: One thing I haven't been able to figure out is how to save window positions at shutdown. In other words, at startup the user would like to have the window positions be restored to where they were when the application last closed. I don't know how this is handled in Spring RCP. I believe it should be done automatically, which doesn't seem to be the case since the application reverts to its default state when I rerun it.

Enabling Actions

Let's now look at the menubar. Several menu items are available by default. Where do they come from? Our simple application contains no Java classes that have anything to do with menu items. So, what's going on here?

Menus and toolbars are all declared in the "command-context.xml" file. That file and its contents, in turn, are declared in the "richclient-application-context.xml" file, which is the application context XML file that is loaded at startup.

     

  1. Open the "richclient-application-context.xml" file and take note of the declaration of the command-context.xml file, as follows, in line 3:
    <bean id="lifecycleAdvisor" class="simple.SimpleLifecycleAdvisor">
    <property name="startingPageId" value="CustomerView" />
    <property name="windowCommandBarDefinitions" value="ui/commands-context.xml" />
    <property name="windowCommandManagerBeanName" value="windowCommandManager" />
    <property name="menubarBeanName" value="menuBar" />
    <property name="toolbarBeanName" value="toolBar" />
    </bean>

    Note: The menubar and the toolbar are also declared above and are then further spelled out in the "command-context.xml" file.

     

  2. Notice the third line above and then open that file, i.e., the commands-context.xml file. Let's start by looking at the Help menu:

    So, the "Help Contents" item is disabled, while the "About" item is enabled. Why?

     

  3. Look at the "menuBar" bean in commands-context.xml, where you'll find that one of its members is "helpMenu". Hold down the Ctrl key and move your mouse over the "helpMenu" text and you will see a hyperlink:

    Click it and you will jump to the "helpMenu" bean, which is defined as follows:

    <bean id="helpMenu" 
    class="org.springframework.richclient.command.CommandGroupFactoryBean">
    <property name="members">
    <list>
    <value>helpContentsCommand</value>
    <value>separator</value>
    <ref bean="aboutCommand" />
    </list>
    </property>
    </bean>

    <bean id="aboutCommand"
    class="org.springframework.richclient.command.support.AboutCommand" />

     

  4. Now you can see why the "Help Contents" item is disabled, while the "About" item is enabled. In the first case, only a value has been declared, while in the second case there is a reference to a bean, for which a class has been defined that handles the invocation of the menu item. Let's do the same for the "Help Contents" item, starting by creating a new bean for the "Help Contents" item:
    <bean id="helpContentsCommand" class="org.springframework.richclient.command.support.HelpContentsCommand">
    <property name="helpSetPath" value="help/simple-hs.xml" />
    </bean>

    Note: We refer above to "help/simple-hs.xml". That's the JavaHelp helpset file that is the entrypoint to our helpset. You could create that by hand, as well as all the files that are needed to set up a JavaHelp helpset. Instead of that, save yourself some time and trouble by going back to the New Project wizard (Ctrl-Shift-N) and in the "Samples" category you will find some Spring Rich Client samples. Complete the wizard for one of them and then copy its "help" package into the "Resource Packages" node of your own application. Hurray you now have the start of your own helpset.

     

  5. Finally, we need to hook the bean up to our help menu, replacing the value with a reference to the bean, as shown below, in the same way as is done by default for the About item:
    <bean id="helpMenu" 
    class="org.springframework.richclient.command.CommandGroupFactoryBean">
    <property name="members">
    <list>
    <ref bean="helpContentsCommand"/>
    <value>separator</value>
    <ref bean="aboutCommand" />
    </list>
    </property>
    </bean>

     

  6. Run the application and now the "Help Contents" item is enabled. When you click the item, the JavaHelp from the sample appears.

Adding Context Sensitivity

As your application increases in size, fewer actions remain relevant to all views. Not every menu item should be available to every window, for example. This aspect of large applications is referred to as "context sensitivity" or "selection management". Depending on the current context, certain features should be available while other features are hidden or greyed out or disabled.

So, in this section, we will set things up so that the "New" command is only available if the current view is the Customer view. If the current view is not the Customer view, the "New" menu item and toolbar button (first button in the toolbar in the two following screenshots) will be disabled:

Otherwise, both will be enabled. Below you see the "New" toolbar button enabled because the current view is the Customer view:

To achieve the above result, one simply needs to modify the CustomerView class, as follows:

public class CustomerView extends AbstractView {

/**
* Handler for the "New" action.
*/
private ActionCommandExecutor newContactExecutor = new NewExecutor();

@Override
protected JComponent createControl() {
JPanel panel = new CustomerPanel();
return panel;
}

/**
* Register the local command executor to be
* associated with named commands. This is called by
* Spring RCP prior
* to making the view visible.
*/
@Override
protected void registerLocalCommandExecutors(PageComponentContext context) {
context.register("newCommand", newContactExecutor);
}

/**
* Private inner class to create a new customer.
*/
private class NewExecutor implements ActionCommandExecutor {
@Override
public void execute() {
JOptionPane.showMessageDialog(null, "new customer...");
}
}

}

Notice lines 20-23 in the code above:

@Override  
protected void registerLocalCommandExecutors(PageComponentContext context) {
context.register("newCommand", newContactExecutor);
}

Reference is made here to "newCommand". Where's that defined? As always, all commands in Spring RCP are defined in "command-context.xml" file. There, note that the "windowCommandManager" bean declares "newCommand", among other commands, under "sharedCommandIds". In each view, a different target executor could be defined for the same command. In the code above, an "ActionCommandExecutor" is defined in the CustomerView, which produces a JOptionPane with a message as a placeholder for real code. In the OtherView, there could be a different way of handling the "newCommand". In other words, though the "newCommand" is globally visible, it is implemented differently per view.

In addition to commands that are defined in "command-context.xml", there are several that are predefined, which you can simply declare in your code:

As a result, for the view above, the commands declared above will be available and implemented as defined in the second argument to "GlobalCommandIds" (all of which are handled by "newContactExecutor", though that's not very likely in real life). Potentially, you could have all or some of these displayed as toolbar buttons in the toolbar, assuming you declare the related tags in the "command-context.xml" file. They would be enabled if the view in which they're declared is active:

...while being disabled in the context of other views:

 

 

Changing the Look & Feel

Since the end result is a standard Swing application, we should be able to change the look and feel. Open the "richclient-application-context.xml" and find the bean that is defined as follows, thanks to the NetBeans project template that created the source structure used in this tutorial:

<bean id="lookAndFeelConfigurer"
class="org.springframework.richclient.application.config.JGoodiesLooksConfigurer">
<property name="popupDropShadowEnabled" value="false" />
<property name="theme">
<bean class="com.jgoodies.looks.plastic.theme.ExperienceBlue" />
</property>
</bean>

Let's change the look and feel to Metal:

<bean id="lookAndFeelConfigurer"
class="javax.swing.plaf.metal.MetalLookAndFeel">
</bean>

Now run it again, with this result:

If you remove the bean altogether, you can set the look and feel via the VM option:

-Dswing.defaultlaf=net.sourceforge.napkinlaf.NapkinLookAndFeel

The result, assuming the Napkin look and feel is on your classpath, is then as follows:

 

Conclusion

There are several other topics that could be discussed in the context of Spring RCP. However, the topics discussed so far should serve as a pretty good basis and give you an understanding of what Spring RCP can do for you and how various pieces fit together. At this point, you certainly should have enough information to build some pretty solid applications on top of Spring RCP.

It is tempting to attempt to compare Spring RCP with similar offerings in the desktop framework domain. It is also tempting to make value judgements. However, that's not the purpose of this article and will be broached at another point in time.

(And now continue with part 2 of this series!)

 

{{ tag }}, {{tag}},

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}
{{ parent.authors[0].realName || parent.author}}

{{ parent.authors[0].tagline || parent.tagline }}

{{ parent.views }} ViewsClicks
Tweet

{{parent.nComments}}