Package org.netbeans.spi.editor.codegen

The Code Generator SPI gives modules a chance to plug their own code generators into the popup that appears in the editor on the Insert Code action invocation.

See:
Description

Interface Summary

CodeGenerator	Interface to be implemented by all generators inserting their code snippets into documents using the Insert Code editor action.
CodeGenerator.Factory	Factory creating code generators. The factory instances are looked up by the MimeLookup so they should be registered in an xml-layer in Editors/<mime-type>/CodeGenerators directory.
CodeGeneratorContextProvider	Serves for adding an additonal content to the context which is passed as a parameter to the CodeGenerator.Factory.create(org.openide.util.Lookup) method. Instances of this interface are looked up by the MimeLookup so they should be registered in an xml-layer in Editors/<mime-type>/CodeGeneratorContextProviders directory.
CodeGeneratorContextProvider.Task	Represents the task passed to the CodeGeneratorContextProvider.runTaskWithinContext(org.openide.util.Lookup,Task) method.

Package org.netbeans.spi.editor.codegen Description

The Code Generator SPI gives modules a chance to plug their own code generators into the popup that appears in the editor on the Insert Code action invocation.

Key parts of the SPI

The whole SPI is organized around the CodeGenerator interface, which is the ultimate thing that modules need to implement in order to generate code snippets and insert them into a document on the Insert Code action invocation. The CodeGenerators are created by CodeGenerator.Factory instances.

Instances of the CodeGeneratorContextProvider interface serve for adding an additonal content to the context which is passed as a parameter to the CodeGenerator.Factory.create method.

CodeGenerator and CodeGeneratorContextProvider registration

The registration of CodeGenerators has to be done through an instance of the CodeGenerator.Factory class. The factory should be registered in MimeLookup under the mime-type of documents, which the CodeGenerator should be used for, in the CodeGenerators folder. For example, if a module wants to provide CodeGenerator for text/x-something documents, it should implement its own CodeGenerator.Factory (e.g. org.some.module.CGFactory class) and register it in MimeLookup using its XML layer as it is shown on the example below.

<folder name="Editors">
  <folder name="text">
    <folder name="x-something">
      <folder name="CodeGenerators">
        <file name="org-some-module-CGFactory.instance" />
      </folder>
    </folder>
  </folder>
</folder>
  

The CGFactory class will simply return a new instance of the module's implementation of the CodeGenerator interface from its create method. The method can create and return multiple CodeGenerators.

The parameter of the create method provides by default access to the JTextComponent, which the generator is being created for. However, a group of factories could exist for a mime-type which require access to an additional data (e.g. some parser result, etc.) when creating their CodeGenerators. To that purpose, an instance of CodeGeneratorContextProvider interface could be created and registered in MimeLookup under the mime-type in the CodeGeneratorContextProviders folder. For example, if a module wants to provide an additional context for text/x-something CodeGenerator.Factory it should implement its own CodeGeneratorContextProvider (e.g. org.some.module.CGContextProvider class) and register it in MimeLookup using its XML layer as it is shown on the example below.

<folder name="Editors">
  <folder name="text">
    <folder name="x-something">
      <folder name="CodeGeneratorContextProviders">
        <file name="org-some-module-CGContextProvider.instance" />
      </folder>
    </folder>
  </folder>
</folder>
  

The CGContextProvider class in its runTaskWithinContext method creates the new context by merging the original context content with the additional data and runs the task obtained as the parameter with the newly created context.

Use cases

TBD