# JPF Code Generator - 0.4

## Table of Contents

1. Introduction
2. Examples / Tutorials
3. Download and Bugtracker
4. Dependencies
5. Version information
6. Release announcements
7. Contact & License

## Introduction

This is a handy little tool that generates classes for accessing the attributes and extensions of JPF plug-ins from plugin.xml files. This has the advantage of providing a strongly typed access to the plug-in and simplyfies working with plug-ins.

Run it using...

    jar -jar jpfCodeGenerator-x.x.jar <comma separated plug-in locations> <overwrite:true|false>

...and pass it a comma separated list of plug-in locations (folders in which to search for plugin.xml) and a boolean whether generated files from previous runs should be overwritten.

The plugin.xml needs to contain the class attribute:

    <plugin id="pluginID" version="0.1.0" class="com.example.MyPlugin">

or have an attribute with id "helperClassName" set:

    <attributes>
       <attribute id="jpfcodegen">
          <attribute id="helperClassName" value="com.example.MyPluginHelper"/>
       </attribute>
    </attributes>

so that the script knows which class to generate.

The script will generate two files (in a src-folder in the same folder as the plugin.xml):

    com.example.MyPlugin

and

    com.example.generated._MyPlugin

_MyPlugin contains all the essential method for accessing the attributes and extensions of the plug-in but will be regenerated when you re-run the code generator. All customizations should thus be put into MyPlugin (which extends _MyPlugin), which by default is not recreated. To recreate MyPlugin also, pass true as a second parameter to the script.

If you choose to use the attribute helperClassName version, then a separate class is generated that is independent of the plugin-class (you don't even need one at all).

## Examples / Tutorials

The source distribution of the code generator comes with the following examples / tutorials:

- Basic Tutorial for the JPF CodeGenerator

## Downloads

The latest version of the code generator can be downloaded from the JPF Code Generator project homepage where you also find the bug-tracker of the project.

- Version 0.4 - Download Page
  - JPFCodeGenerator-0.4.jar - Binary jar for running the code generator.
  - JPFCodeGenerator-0.4-rt.jar - Runtime Jar, needed for running applications that use code generated by the code generator.
  - JPFCodeGenerator-0.4-src.jar - Source Distribution including examples and documentation.
- Version 0.3 - Download Page
  - JPFCodeGenerator-0.3.jar - Binary jar for running the code generator.
  - JPFCodeGenerator-0.3-rt.jar - Runtime Jar, needed for running applications that use code generated by the code generator.
  - JPFCodeGenerator-0.3-src.jar - Source Distribution including examples and documentation.

## Configuration

There are a couple of attributes that can be used to configure the code generation behavior of the JPF code generator. Each attribute needs to be defined in the `<attributes>`-element of the plugin.xml as a sub-`attribute` of an `attribute` with id `jpfcodegen`

Possible attributes include

- `helperClassName` - If defined will cause the code generator to not create a plug-in class with helper methods to access the attributes and extensions of the plug-in, but rather an independent helper class. If not defined the code generator will use the name of the plugin class attribute.
- `targetDir` - If defined will alter the output directory into which the code generator will write the resulting java files. If the attribute is not given the default directory is `src/`

An example of how to tell the code generator to create a standalone helper class with class name `com.example.MyPluginHelper` in the `src` two levels up from the location of the plugin.xml:

    <attributes>
       <attribute id="jpfcodegen">
          <attribute id="helperClassName" value="com.example.MyPluginHelper"/>
          <attribute id="targetDir" value="../../src/"/>
       </attribute>
    </attributes>

## Dependencies

To run the code generator jar you need (from the lib directory):

- Velocity-dep-1.5.jar - Apache Velocity Template Engine is used to create the classes.
- jpf.jar - JPF engine is used to read the plugin.xml
- jpf-boot.jar - The boot library is used to collect plugin-locations.

To run the code that gets generated you need:

- jpf.jar - You need this anyway to use JPF ;-)
- JPFCodeGenerator-x.x-rt.jar - Contains some helper classes needed by the generated classes.
- commons-logging.jar - This is both needed by JPF and the classes generated by the code generator.

## Version / Todo

Todo:

- Advanced examples.
- Support extension multiplicity.
- Support inheritance of extension points.
- Support extension plugin attributes (normal and nested).
- Support for documentation nodes
- Support for all extension parameter types (plugin-ID, extension-point-ID, extension-ID are missing).
- Improve support for naming choices. At the moment if you define extension-attributes using type "fixed", the values you use must be valid Java identifiers.
- Add JUnit tests.

0.4 - 2007-07-19

- Bug in generator template that caused a wrong classname to be generated.
- Can now create classes in a user-defined target directory.
- Bug fixes for parameter that are not set in an extension.
- Documentation improvement for Helper Classes.
- Added support for parameters of type resource.

0.3 - 2007-07-11

- Date/time extension parameters are now supported.
- Basic Tutorial added to documentation.
- Nested extension parameters are now possible.

0.2 - 2007-07-05

- Added option to generate HelperClass instead of putting the code into the Plugin class
- Added ant build.xml to generate rt.jar and run the Code Generator
- Added support for type "fixed" attributes using enums. See limitations.
- Multiplicity support for parameter attributes (so far only String (and Class), Number, Fixed, Boolean parameters are supported).

0.1 - 2007-07-03

- Initial release posted on SF.net

## Release Announcements

0.3 - 2007-07-11

    Hi Guys,
      version 0.3 of the code generator is ready. It comes with better documentation
    (a tutorial at http://www.inf.fu-berlin.de/~oezbek/jpf/tutorials/basic/) and
    some additional features like nested extension-point-parameters. I also
    added a small homepage for it at http://www.inf.fu-berlin.de/~oezbek/jpf/
    where you will also find the link for downloading it.

    Suggestions and comments are highly welcome: Send them to oezi[at]oezi.de

    Cheers,
      Christopher

0.2 - 2007-07-05

    Hi Guys,
      I have just extended the code generator a little bit to also support
    extension-point parameter multiplicity, attributes of type fixed and
    a standalone mode:

    1.) If you have a parameter with a multiplicity that might result in several
        parameter values:

    <parameter-def type="string" id="name" multiplicity="any"/>

    then this will now generate this code:

    public Collection<String> getNames(){
      return getStringParameters("name");
    }

    2.) If you have a parameter with a type fixed then this will be mapped to
        an enum in Java:

    <parameter-def type="fixed" id="alignment" custom-data="left|right|top|bottom"/>

    will generate:

    public enum Alignment {
        LEFT, RIGHT, TOP, BOTTOM;
    }

    public Alignment getAlignment(){
        return Alignment.valueOf(getStringParameter("alignment").toUpperCase());
    }

    3.) If you don't want to use the plugin class-attribute as a target
        class to generate, you can now also use plugin-attributes to define
        the name of the class to generate:

    <attributes>
       <attribute id="helperClassName" value="com.example.MyPluginHelper"/>
    </attributes>

    4.) The Code Generator also now comes in 3 handy jars:

    http://page.mi.fu-berlin.de/oezbek/jpf/JPFCodeGenerator-0.2.jar
      -> The code generator as a binary package to run using

    java -jar JPFCodeGenerator-0.2.jar <comma separated plug-in locations> <overwrite:true|false>

    http://page.mi.fu-berlin.de/oezbek/jpf/JPFCodeGenerator-0.2-rt.jar

    The runtime dependencies needed to use the generated classes, add
    this to your buildpath in the project.

    http://page.mi.fu-berlin.de/oezbek/jpf/JPFCodeGenerator-0.2-src.jar

    The source code if anybody is interested to play with it.

    Cheers,
      Christopher

## Contact & License

Copyright (C) Christopher Oezbek (2007) - oezi[at]oezi.de

This tool was created as part of the ongoing migration in the JabRef reference manager to move to a modular plug-in architecture and is released under the LGPL 3.0.

Your improvements and suggestions are welcome.