Difference between revisions of "Adding a helloworld headless command (Buckminster)"

Revision as of 06:43, 19 December 2006

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 the extension point org.eclipse.buckminster.cmdline.command. 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, 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 cmdline file, adding a request for help:

# helloworld.cmdline - for testing the helloworld command
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):

@Override
    protected OptionDescriptor[] getOptionDescriptors() throws Exception
    {
        return new OptionDescriptor[] { GOODBYE_DESCRIPTOR };
    }

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

@Override
    protected void handleOption(Option option, boolean defaults) 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!";

    @Override
    protected OptionDescriptor[] getOptionDescriptors() throws Exception
    {
        return new OptionDescriptor[] { 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, boolean defaults) throws Exception
    {
        if (option.is(GOODBYE_DESCRIPTOR))
            m_goodbye = option.getValue();
    }
}

To test, edit the cmdline file to read something like this:

# helloworld.cmdline - for testing the helloworld command
hw
--goodbye
Don't go!