Skip to main content
Jump to: navigation, search

Difference between revisions of "M2E/Extension Development"

< M2E
(Replaced content with "[https://www.eclipse.org/m2e/documentation/m2e-extension-development.html This page is now here]")
 
(18 intermediate revisions by 9 users not shown)
Line 1: Line 1:
== Prerequisites ==
+
[https://www.eclipse.org/m2e/documentation/m2e-extension-development.html This page is now here]
 
+
Some OSGi bundle development and PDE knowledge is assumed. TODO link to some PDE documentation and tutorials
+
 
+
 
+
== Java code generation overview ==
+
 
+
Although there are no strict rules, usually maven java code generation plugins like antlr3-maven-plugin or maven-jaxb-plugin take one or more input files from project source tree and generate a number java source files in a subdirectory of target/generated-sources/ directory. These generated sources are usually required to compile and/or run project tests.
+
 
+
To properly support code generation inside Eclipse IDE workspace, the IDE generally needs to perform some configuration (semi) statically during project import and then do actually code generation either on request or automatically as part of workspace build.
+
 
+
m2e extension that provides support for generation will typically need to
+
* implement a subclass of org.eclipse.m2e.jdt.AbstractJavaProjectConfigurator to perform necessary project configuration
+
* implement subclass of MojoExecutionBuildParticipant to delegate actual code generation to underlying maven plugin goal
+
* provide metadata to metadata to register the project configurator with m2e and to map maven plugin execution to the project configurator
+
 
+
=== m2e/antlr3 code generation support explained ===
+
 
+
As an example, here is explanation of how different parts of [[https://github.com/sonatype/m2eclipse-extras/tree/0.13.0.20110622-1538/org.sonatype.m2e.antlr m2e/antlr]] fit together
+
 
+
On command line, [[http://www.antlr.org/antlr3-maven-plugin/usage.html antlr3-maven-plugin]], reads ANTLR grammar files from directory specified by ${sourceDirectory} plugin configuration parameter (defaults to src/main/antlr3) and generates output files in directory specified by ${outputDirectory} plugin configuration parameter (defaults to target/generated-sources/antlr3).
+
 
+
==== AntlrProjectConfigurator and corresponding metadata ====
+
 
+
[[http://git.eclipse.org/c/m2e/m2e-core.git/tree/org.eclipse.m2e.jdt/src/org/eclipse/m2e/jdt/AbstractJavaProjectConfigurator.java?id=releases/1.0/1.0.0.20110607-2117 AbstractJavaProjectConfigurator]] is a convenience abstract implementation of AbstractProjectConfigurator that provides default behaviour common to many java code generation m2e extensions. AbstractJavaProjectConfigurator assumes single additional java source folder needs to be configured for the project and the source folder location is defined by ${outputDirectory} maven plugin configuration parameter. This allows very simple ANTLR project configurator implementation (is explained below)
+
 
+
    public class AntlrProjectConfigurator
+
        extends AbstractJavaProjectConfigurator
+
    {
+
        @Override
+
        public AbstractBuildParticipant getBuildParticipant( IMavenProjectFacade projectFacade,
+
                                                            MojoExecution execution,
+
                                                            IPluginExecutionMetadata executionMetadata )
+
        {
+
            return new AntlrBuildParticipant( execution );
+
        }
+
    }
+
 
+
The follow extension in plugin.xml registers ANTLR project configurator with m2e
+
 
+
  <extension
+
        point="org.eclipse.m2e.core.projectConfigurators">
+
      <configurator
+
            class="org.sonatype.m2e.antlr.internal.AntlrProjectConfigurator"
+
            id="org.sonatype.m2e.antlr.antlrConfigurator"
+
            name="ANTLR Project Configurator">
+
      </configurator>
+
  </extension>
+
 
+
lifecycle-mapping-metadata.xml located at the root of the project (and at the root of OSGi bundle jar at runtime) maps antlr3-maven-plugin antlr goal to ANTLR project configurator. Note that configurator id in the mapping matches configurator id defined in the extension point above.
+
 
+
    <pluginExecution>
+
      <pluginExecutionFilter>
+
        <groupId>org.antlr</groupId>
+
        <artifactId>antlr3-maven-plugin</artifactId>
+
        <versionRange>[3.1.1,)</versionRange>
+
        <goals>
+
          <goal>antlr</goal>
+
        </goals>
+
      </pluginExecutionFilter>
+
      <action>
+
        <configurator>
+
          <id>org.sonatype.m2e.antlr.antlrConfigurator</id>
+
        </configurator>
+
      </action>
+
    </pluginExecution>
+
+
And finally, the following extension in plugin.xml registers m2e extension as lifecycle mapping metadata source with m2e. This is mostly needed as performance optimization, because without this extension m2e would have to search lifecycle-mapping-metadata.xml file in all installed eclipse plugins.
+
 
+
  <extension
+
        point="org.eclipse.m2e.core.lifecycleMappingMetadataSource">
+
  </extension>
+
 
+
==== AntlrBuildParticipant ====
+
 
+
AntlrBuildParticipant generates java source files (any resources generated by ANTLR, to be precise) during eclipse incremental and full builds.
+
 
+
First AntlrBuildParticipant checks if any of the grammar files have changed and short-cuts code generation if there were no changes.
+
 
+
        File source = maven.getMojoParameterValue(getSession(), getMojoExecution(), "sourceDirectory", File.class);
+
        Scanner ds = buildContext.newScanner( source ); // delta or full scanner
+
        ds.scan();
+
        String[] includedFiles = ds.getIncludedFiles();
+
        if (includedFiles == null || includedFiles.length <= 0 )
+
        {
+
            return null;
+
        }
+
 
+
Then, AntlrBuildParticipant delegates to MojoExecutionBuildParticipant.build to execute antlr3-maven-plugin antlr goal. This generates resources on filesystem, but does not update eclipse workspace
+
+
        Set<IProject> result = super.build( kind, monitor );
+
 
+
Finally, AntlrBuildParticipant refreshes generation output folder in workspace
+
 
+
        File generated = maven.getMojoParameterValue(getSession(), getMojoExecution(), "outputDirectory", File.class);
+
        if (generated != null) {
+
            buildContext.refresh( generated );
+
        }
+
 
+
=== Testing m3e/antlr code generation support ===
+
 
+
== Project directory structure overview ==
+
 
+
  org.somecatchyname/                  <= project basedir, all project files are under this directory
+
    org.somecatchyname.m2e/            <= main bundle project
+
      src/
+
      pom.xml
+
    org.somecatchyname.m2e.tests/      <= automated tests (optional, but highly recommended)
+
      src/
+
      pom.xml
+
    org.somecatchyname.m2e.feature/    <= eclipse feature project
+
      feature.xml
+
      pom.xml
+
    pom.xml                            <= aggregator pom.xml
+
 
+
 
+
 
+
----
+
 
+
[[Category:M2E]]
+
 
+
[[Submitting M2E marketplace entries]]
+
 
+
[[M2E extension development environment]]
+

Latest revision as of 07:27, 14 November 2014

This page is now here

Back to the top