MagicBeans Tutorial

MagicBeans is a framework to support the use of plugin components in Java applications. Here we will show how to write and run a simple application that uses the MagicBeans framework.

Components

Components that work with the MagicBeans framework are simply Jar files containing Java classes (and possibly other things such as graphics). You can create a component that works with MagicBeans using only the standard javac and jar utilities.

Once you have written a few components you can run the application (starting with just one component) and very easily add in the others over time, so that you can provide extra functionality.

Logging Example

Writing the Code

Here is a simple class that pops up a dialog box requesting a string repeatedly. You can compile this class and put it into a Jar file to form a very basic component.

package logex;

import javax.swing.JOptionPane;

public class BoxPop {

    public static void main( String[] p_args ) {

        new BoxPop().go();
    }

    private void go() {

        String x_input = "";

        while( x_input != null ) {
            x_input = JOptionPane.showInputDialog("Please input a value");
        }
    }
}

We can use the plugin framework to optionally add in functionality to record the values that are entered, by adding another component. To do this we need to define an interface through which the two components can communicate. This is done using a standard Java interface.

package logex;

public interface Log {

    public void record( String p_str );
}

The BoxPop class is then altered to use this interface

package logex;

import javax.swing.JOptionPane;

public class BoxPop {

    private Log o_log;

    public static void main( String[] p_args ) {

        new BoxPop().go();
    }

    private void go() {

        String x_input = "";

        while( x_input != null ) {

            x_input = JOptionPane.showInputDialog("Please input a value");
            if ( o_log != null ) { o_log.record( x_input ); }
        }
    }
}

Here, if a Log is available (i.e. if the field o_log is not null) the value is passed to the Log to be recorded. In order for this to work, we need a way for the BoxPop to acquire a reference to a Log. This is done by registering as an observer with the plugin platform. The platform will then pass a reference to a Log when and if one becomes available.

import javax.swing.JOptionPane;

public class BoxPop {

    private Log o_log;

    public BoxPop() {
    
        com.chatley.magicbeans.PluginManager.getInstance().addObserver( this );
    }

    public static void main( String[] p_args ) {

        new BoxPop().go();
    }

    public void pluginAdded( Log p_log ) { o_log = p_log; }

    ....
}

Here we have added a constructor to BoxPop in which the object adds itself as an observer by calling the MagicBeans platform.

We have also added a method pluginAdded() taking a Log as a parameter, which will be called back by the platform when a Log is plugged in.

To complete this example we need a class that implements the Log interface.

public class SimpleLogger implements Log {

    public void record( String p_str ) {

        System.out.println( "[" + new java.util.Date() + "] - " + p_str );
    }
}

Creating the Components

We can compile these three classes (BoxPop, Log and SimpleLogger) using javac. To compile BoxPop, you will need to have the MagicBeans jar file in your classpath. You should then have three corresponding class files. From the we create two components, using the jar utility. Note that we put Log.class into both components.

jar cvf boxpop.jar BoxPop.class Log.class
jar cvf logger.jar SimpleLogger.class Log.class

Running the Appliction

To run an application with MagicBeans requires a simple configuration file to be written. Create a file called loggerdemo.mb with the following content:

frameworkjar   = magicbeans-beta1.jar
targetjar      = boxpop.jar
targetclass    = BoxPop

The default way of adding plugins to a MagicBeans application is to put them in a directory called plugins. Create this directory, but leave it empty for now. Now start MagicBeans, giving the configuration file as a parameter, using the following command

java -cp magicbeans-beta1.jar com.chatley.magicbeans.PluginManager loggerdemo.mb

The dialog box should pop up, requesting input. Type something in the box and press OK. At the moment you should see no effect, except that the same dialog reappears.

Now copy logger.jar into the plugins directory. After a few seconds the system will reconfigure. Now, when you type a value in the box and press OK, the data should be recorded in the console window.