Package bluej.extensions

Provides access for extensions to the BlueJ application via a proxy object, and to the classes and objects which BlueJ is manipulating via a number of wrapper classes.

See:
Description

Interface Summary

PreferenceGenerator

Extensions which wish to add preference items to BlueJ's Tools/Preferences/Extensions panel should register an instance of PreferenceGenerator with the BlueJ proxy object.

Class Summary

BArray	A wrapper for an array object in BlueJ.
BClass	A wrapper for a class.
BConstructor	A wrapper for a constructor of a BlueJ class.
BField	A wrapper for a field of a BlueJ class.
BlueJ	A proxy object which provides services to BlueJ extensions.
BMethod	A wrapper for a method of a BlueJ class.
BObject	A wrapper for an object on the BlueJ object bench.
BPackage	A wrapper for a single package of a BlueJ project.
BProject	A wrapper for a BlueJ project.
Extension	Defines the interface between BlueJ and an extension.
MenuGenerator	Extensions which wish to add a menu item to BlueJ's menus should register an instance of MenuGenerator with the BlueJ proxy object.

Exception Summary

ClassNotFoundException	This exception will be thrown when a reference to a class is no longer valid.
CompilationNotStartedException	This exception will be thrown when a compile request cannot be started.
ExtensionException	Base class for the different Exception event generated by BlueJ for extensions.
ExtensionUnloadedException	This exception will be thrown when an Extension that has been unloaded from BlueJ still tries to access methods of the BlueJ class.
InvocationArgumentException	This exception will be thrown when the parameters passed to an invocation do not match the list of arguments of the invocation.
InvocationErrorException	This exception will be thrown when an exception occurs during a method or constructor invocation.
MissingJavaFileException	This exception will be thrown when a new class is created and not java source file is provided.
PackageAlreadyExistsException	This exception is thrown when there is a request to create a new Package but the package already exists in BlueJ.
PackageNotFoundException	This exception will be thrown when a reference to a package is no longer valid.
ProjectNotOpenException	This exception will be thrown when a reference to a project is no longer valid.

Package bluej.extensions Description

Provides access for extensions to the BlueJ application via a proxy object, and to the classes and objects which BlueJ is manipulating via a number of wrapper classes.

An extension can add a menu item to the BlueJ Tools, Class and/or Object menus, and a preference panel to the Tools/Preferences/Extensions panel. The BlueJ proxy object generates events when the user performs significant actions within BlueJ, and provides access to its projects, packages, classes and objects via a set of wrapper classes which behave in a similar way to the java.lang.reflect classes.

The editor sub-package provides access from an extension to the BlueJ editor, which can be used either to interact with the user's use of the editor, or to modify the text being edited.

A simple extension

The following example implements an extension which logs the name of every BlueJ project opened by the user to System.out. Once it is installed you should see an entry in the "Installed Extensions" panel of the BlueJ help menu.

How to build and install it

• Compile it, including lib/bluejext.jar from your BlueJ installation in the compiler classpath
• Create a Jar file containing the classes of your extension, and add a Main-Class attribute to the Manifest of the Jar file. Note that this does not mean that the extension needs to have a main() method.
• Install it by copying the Jar file either into the lib/extensions directory of your BlueJ installation, or into an extensions directory in your BlueJ user configuration directory (<USER_HOME>/.bluej/extensions or <USER_HOME>\bluej\extensions), or into an extensions directory in the single BlueJ project you wish the extension to be active for.
• Run it. The extension should start when you next run BlueJ, or when you open the BlueJ project into which you installed the extension.

Note to Mac users: To navigate to the lib/extensions directory of your BlueJ installation, right-click (or control-click) on the BlueJ application icon, the select "Show Package Contents"and then extensions. The Mac equivalent of <USER_HOME>\bluej\extensions is ~/Library/Preferences/org.bluej/extensions.

Sample extension code

import bluej.extensions.*;
import bluej.extensions.event.*;

import java.net.URL;

/*
 * This is the starting point of a BlueJ Extension
 */
public class SimpleExtension extends Extension implements PackageListener {
    /*
     * When this method is called, the extension may start its work.
     */
    public void startup (BlueJ bluej) {
        // Listen for BlueJ events at the "package" level
        bluej.addPackageListener(this);
    }

    /*
     * A package has been opened. Print the name of the project it is part of.
     * System.out is redirected to the BlueJ debug log file.
     * The location of this file is given in the Help/About BlueJ dialog box.
     */
    public void packageOpened ( PackageEvent ev ) {
        try {
            System.out.println ("Project " + ev.getPackage().getProject().getName() + " opened.");
        } catch (ExtensionException e) {
            System.out.println("Project closed by BlueJ");
        }
    }  
  
    /*
     * A package is closing.
     */
    public void packageClosing ( PackageEvent ev ) {
    }  
    
    /*
     * This method must decide if this Extension is compatible with the 
     * current release of the BlueJ Extensions API
     */
    public boolean isCompatible () { 
        return true; 
    }

    /*
     * Returns the version number of this extension
     */
    public String  getVersion () { 
        return ("2004.09");  
    }

    /*
     * Returns the user-visible name of this extension
     */
    public String  getName () { 
        return ("Simple Extension");  
    }

    public void terminate() {
        System.out.println ("Simple extension terminates");
    }
    
    public String getDescription () {
        return ("A simple extension");
    }

    /*
     * Returns a URL where you can find info on this extension.
     * The real problem is making sure that the link will still be alive in three years...
     */
    public URL getURL () {
        try {
            return new URL("http://www.bluej.org/doc/writingextensions.html");
        } catch ( Exception eee ) {
            // The link is either dead or otherwise unreachable
            System.out.println ("Simple extension: getURL: Exception="+eee.getMessage());
            return null;
        }
    }
}