readme.md

Delegator Generator

This project contains a Maven plugin that creates Delegator Interfaces and Decorator Classes and a module that shows how to use it.

What is a Delegator Interface

A Delegator Interface is a pattern that only became feasible in Java 8 with the introduction of default methods on interfaces. It aims to take out the pain of creating classes that implement an interface and delegate the implementation of most of the methods to a wrapped instance of that same interface. This is most often seen in the decorator pattern but may be seen in other contexts.

A Delegator Interface extends the primary interface and consists of a getXXXDelegate() method and a complete set of default methods for the primary interface methods that delegate to the instance returned by the getXXXDelegate() method.

A class wishing to perform delegation simply implements the relevant Delegator Interface, implements the getXXXDelegate() method and overrides only the methods that it wishes to override.

This class may choose to implement multiple Delegator interface interfaces where it does not violate separation of concerns.

To better understand this pattern please take a look at the examples in the example module.

Usage

To use, please add the plugin to your project's pom.xml as:

    <plugin>
        <groupId>com.robertboothby</groupId>
        <artifactId>delegator-generator-maven-plugin</artifactId>
        <version>0.2.0</version>
        <executions>
            <execution>
                <id>generate-delegators-from-sources</id>
                <!--
                  This goal generates Delegator Interfaces from any Interface source files defined in the configuration 
                  below.
                  -->
                <goals>
                    <goal>generate-delegators-from-sources</goal>
                </goals>
                <configuration>
                    <!--
                      Define the source files for which to generate Delegator Interfaces. Uses standard file set 
                      wildcards.
                      -->
                    <fileSets>
                        <fileSet>
                            <directory>${project.build.sourceDirectory}</directory>
                            <includes>**/*.java</includes>
                        </fileSet>
                        ...
                    </fileSets>
                    <!--
                      Define the output directory for the project. Default is '${project.build.directory}/generated-sources/java'
                      -->
                    <outputDirectory>${project.build.directory}/generated-test-sources</javaoutputDirectory>
                    <!--
                      Define the source type of the output directory so that the generated files are added to the 
                      project build correctly. Default is 'SOURCE'. For detail of available source types see below.
                      -->
                    <outputDirectoryType>TEST_SOURCE</outputDirectoryType>
                </configuration>
            </execution>
            <execution>
                <id>generate-decorators-from-sources</id>
                <!--
                  This goal generates Decorator classes from any Interface or Class (with no arguments constructor) 
                  source files defined in the configuration below.
                  -->
                <goals>
                    <goal>generate-decorators-from-sources</goal>
                </goals>
                <configuration>
                    <!--
                      The configuration options for this goal is the same as the one above.
                      -->
                    ...  
                </configuration>
            </execution>
        </executions>
    </plugin>

Source Types

The plugin will add the generated sources to the project build as specified below: - SOURCE - the generated source files will be automatically added to the project's main compile sources (equivalent to src/main/java). - TEST_SOURCE - the generated source files will be automatically added to project' main test sources (equivalent to src/test/java). - RESOURCE - the generated source files will be automatically added to the project's main resources (equivalent to src/main/resources). - TEST_RESOURCE - the generated source files will be automatically added to project' main test resources (equivalent to src/test/resources). - NONE - the generated source files will not be automatically added to the project at all.

It is unlikely that you will want to add the generated file as any form of project resources but... you never know.