JaxoDraw – Plugins

JaxoDraw plugins

In version 2.0 a plugin architecture was added to JaxoDraw. Plugins are software components that may optionally be added to the program at runtime, ie without the need of changing or re-compiling the main program. This makes it easy to use optional features, in particuar export to uncommon formats or import of other custom file formats, while keeping the size of the main program at a minimum. In fact, the original main purpose of the plugin architecture was to draw some functionality out of the JaxoDraw core.

This document gives some instructions on how to use plugins, and a short tutorial on how to write your own!

Installing and using plugins

Please check the JaxoDraw Plugins home page for an overview of currently available plugins and installation instructions.

Writing plugins

To write your own custom export plugin you should extend the JaxoExportPlugin class and implement all required abstract methods.

The classes that are to be loaded as plugins have to be listed as <manifestSection>s in the plugin jar's manifest MANIFEST.MF. If several classes are to be loaded from one plugin jar (e.g. export and import plugins, or several export formats), then each class has to be listed in separate <manifestSection>s. The name of each <manifestSection> has to be of the form JaxoDraw<...>Plugin.java and the entry must use the tag name <plugin>.

The following is a template that you can use for an export plugin:

package net.sf.jaxodraw.plugin;

        import javax.swing.JComponent;

        import net.sf.jaxodraw.io.JaxoPreview;

        public class TestExportJaxoPlugin extends JaxoExportPlugin {
        public void commitConfiguration() {
        // Apply the changes made in the configuration panel.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public JComponent getConfigurationPanel() {
        // Returns a panel that allows to configure optional parameters of this
        // export format. May return null if there is nothing to configure.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        protected void exportTo(String fileName) throws JaxoPluginExecutionException {
        // Export a JaxoGraph to the given nonempty file name.
        // The graph is obtained from the getGraph() method.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public void preview(JaxoPreview p, boolean sameWindow) {
        // Show a preview of the export.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public String getWarningForGraph() {
        // Returns a warning for the graph, eg if some objects cannot be exported.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public String getFormatName() {
        // The name of the export format.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public String getFileExtension() {
        // The file extension to be used for generated files.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public String getFileExtensionDescription() {
        // Description to be used for plugin file extensions.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public String pluginId() {
        // This must return the class name of the plugin:
        return TestJaxoPlugin.class.getName();
        }

        public String getShortName() {
        // Return a short name for this plugin.  This is used to construct names
        // of output files, eg to get a "jaxodraw-pdf-plugin.properties" file,
        // the short name should just be "pdf".
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public String description() {
        // A short description  of what this plugin does.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public String version() {
        // Return the version number of this plugin.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public boolean makeAvailableAtRuntime() {
        // Checks some eventual runtime requirements for the plugin,
        // eg if some required runtime dependencies are present.
        throw new UnsupportedOperationException("Not supported yet.");
        }

        public void updateLanguage() {
        // update any components after a language change.
        throw new UnsupportedOperationException("Not supported yet.");
        }
        }

Import plugins look very similar except that you should extend JaxoImportPlugin, and the important method to implement is:

protected JaxoGraph importGraph(InputStream inputStream)
        throws JaxoPluginExecutionException {
        // return a graph read from an InputStream
        throw new UnsupportedOperationException("Not supported yet.");
        }

Internationalization

If you want to internationalize your plugin (so it shows messages in the same languages as JaxoDraw), you have to register a JaxoDictionary for your plugin. This is done by calling the registerDictionary(Class) method of the abstract super-class AbstractJaxoPlugin, in the constructor of your plugin:

    public TestJaxoPlugin() {
          registerDictionary(TestJaxoPlugin.class);
          }

The dictionary is then accessed with the getLang() method

String i18n = getLang().translate("TestJaxoPlugin.myKey");

You should put your translations into language.properties files in a directory resources/properties/ relative to your main code. Voila!

Logging

You may use the same logging system as the main JaxoDraw program by calling the getLog() method, eg:

getLog().debug("Plugin registered!");

Properties

Your plugin can store its own set of properties that will be initialized automatically by JaxoDraw when the plugin is loaded. You can load, set and store properties with the commands

String propertyValue = getProperty("property.key");
          setProperty("property.key", "property.value");
          storeProperties();

Note that you need to set properties before you can store them. The properties are stored in a file jaxodraw-shortname-plugin.properties (where shortname is the String returned by the getShortName() method) in the JaxoDraw plugins directory (~/.jaxodraw/$VERSION/plugins/).

Have a look at the pdf plugin for a realistic example where a custom pdf viewer may be stored in a property.

Compilation and packaging

To compile the plugin you have to add a JaxoDraw jar to your classpath, and don't forget to bundle up any resource files (language properties) in your jar.

You may check the source code of the available plugins for some realistic examples.