Adding a helloworld headless command (Buckminster)

Here is a description of how to build a sample new command called 'helloworld' and then how to add some simple functionality.

As a prerequisite, we need a plugin project — use the new plugin project wizard. Most likely you wish to deselect the option 'This plugin will make contributions to the UI'.

Declare the command using the command extension point

First, the plugin must be dependent on the org.eclipse.buckminster.cmdline plugin in order to see the extension point. Use the plugin manifest editor to add this dependency.

Now you can select the Extensions tab, and add an extension to the extension point org.eclipse.buckminster.cmdline.commands. This extension point can describe multiple commands; right click and select 'New > command'. To the right you will see the possible things you can set for the command. If you wish, you may change the class name, but it is not necessary - here we will use 'HWCommand'. Set the 'name' attribute to 'helloworld'. The others can be left to the default.

Implement the command

Click on the 'class*' attribute name - this will open New Java Class dialog. Note that the super class is set to org.eclipse.buckminster.cmdline.AbstractCommand. You don't need any method stubs (you may uncheck those boxes). Now click Finish and you will end up with a new class somewhat like this:

import org.eclipse.buckminster.cmdline.AbstractCommand;
import org.eclipse.core.runtime.IProgressMonitor;

public class HWCommand extends AbstractCommand
{

}

At this point you're almost done - add a run method:

@Override
protected int run(IProgressMonitor monitor) throws Exception
{
    System.out.println("Hello world");
    return 0;
}

That's it! Now let's run it.

Run the command

Normally, the finished plugin will be installed into a Buckminster product, or be part of an Eclipse IDE installation together with the Buckminster plugins. This will make it easy to start the command using the command line (e.g. 'buckminster helloworld').

Create a launch configuration to use this. Use 'Run/Run...' to open the launch configurations dialog. You want to create an 'Eclipse application'. The name isn't important. However, in 'Program to run', it must select the product org.eclipse.buckminster.product. Also, on the tab 'Arguments', you must add the command as a 'Program argument', i.e. 'helloworld'.

Running this configuration should print 'Hello world' in a Console view.

Adding an alias

Open the plugin manifest and activate the command extension point for helloworld. Right click on it and add an alias - for example 'hw'. Now you can interchangeably use either 'helloworld' or 'hw' to run your command.

Adding help text

Change the program arguments in your launch configuration to read::

hw -?

Running the command now will just declare:

Help missing for HWPlugin.helloworld

The framework has recognized the -? option but can't find the help text. Add a file called HWCommand.help alongside your java file prints out:

'Hello world'
usage: helloworld
       [{ -? | --help }]
 -?
--help
  Show this help text

Running the command again should now print the help text.

Adding option handling

We now want the command to recognize the option --goodbye <text>.

First we need to add a descriptor:

static private final OptionDescriptor GOODBYE_DESCRIPTOR = new OptionDescriptor(null, "goodbye", OptionValueType.REQUIRED);

The 'null' in this particular descriptor says that there are no equivalent single letter option flag. We also describe that this option requires a value.

We also add a variable to hold the value we (might) receive, and a default value:

private String m_goodbye = "Goodbye!";

Now we need to override a method so the framework can get our descriptor(s):

    @SuppressWarnings("unchecked")
    @Override
    protected void getOptionDescriptors(List appendHere) throws Exception
    {
        appendHere.add(GOODBYE_DESCRIPTOR);
    }

We also need to override a method so the framework can tell us about received options:

    @Override
    protected void handleOption(Option option) throws Exception
    {
        if (option.is(GOODBYE_DESCRIPTOR))
            m_goodbye = option.getValue();
    }

Finally, let's add a print out of the value:

import org.eclipse.buckminster.headless.AbstractCommand;
import org.eclipse.buckminster.headless.parser.Option;
import org.eclipse.buckminster.headless.parser.OptionDescriptor;
import org.eclipse.buckminster.headless.parser.OptionValueType;

public class HWCommand extends AbstractCommand
{
    static private final OptionDescriptor GOODBYE_DESCRIPTOR = new OptionDescriptor(null, "goodbye", ptionValueType.REQUIRED);

    private String m_goodbye = "Goodbye!";

    @SuppressWarnings("unchecked")
    @Override
    protected void getOptionDescriptors(List appendHere) throws Exception
    {
        appendHere.add(GOODBYE_DESCRIPTOR);
    }

    @Override
    protected int run() throws Exception
    {
        System.out.println("Hello world");
        System.out.println(m_goodbye);
        return 0;
    }

    @Override
    protected void handleOption(Option option) throws Exception
    {
        if (option.is(GOODBYE_DESCRIPTOR))
            m_goodbye = option.getValue();
    }
}

To test, edit the program arguments of the launch configuration to read something like this:

hw --goodbye "Don't go!"

Adding parameter handling

It is worth noting that in addition to options you can also access command line parameters. To do this override the 'handleUnparsed' method. For example:

    @Override
    protected void handleUnparsed(String[] unparsed) throws Exception {
       if (unparsed.length != 1){
         throw new UsageException("Need to include a parameter.");
      }
    }

Obtaining the source

The source for this demo can be found in CVS. If you have Buckminster installed, then open and run this CQUERY: http://www.eclipse.org/buckminster/samples/queries/hwcommand.cquery. You can also use the following CVS checkout:

cvs -D :pserver:anonymous@dev.eclipse.org:/cvsroot/technology checkout org.eclipse.buckminster/org.eclipse.buckminster/demo/org.demo.hwcommand