org.eclipse.emf.codegen.ecore.generator
Class Generator

java.lang.Object
  extended by org.eclipse.emf.codegen.ecore.generator.Generator

public class Generator
extends java.lang.Object

An extensible code generator that delegates its work to model-specific adapters created provided by an adapter factory.

Adapter factories are obtained for model objects from a particular EMF or Java package by consulting a registry, which can be local to the generator or globally shared. Local registries typically delegate to the global registry, overriding the adapter factories returned for certain packages. Global registration is usually done via the org.eclipse.emf.codegen.ecore.generatorAdapters extension point.

Here is a typical usage example, where we generate code for a standard GenModel-decorated Ecore model:

   // Globally register the default generator adapter factory for GenModel
   // elements (only needed in stand-alone).
   // 
   GeneratorAdapterFactory.Descriptor.Registry.INSTANCE.addDescriptor
     (GenModelPackage.eNS_URI, GenModelGeneratorAdapterFactory.DESCRIPTOR);
 
   // Create the generator and set the model-level input object.
   // 
   Generator generator = new Generator();
   generator.setInput(genModel);
 
   // Generator model code.
   //
   generator.generate
     (genModel, GenBaseGeneratorAdapter.MODEL_PROJECT_TYPE,
      new BasicMonitor.Printing(System.out));
 

The adapter factories for the input object handle initializing the generator's options, and the generator walks the tree of objects defined by the relevant adapters, invoking code generation for each one.

Since:
2.2.0

Nested Class Summary
static class Generator.Options
          A set of code generation options that should be shared among the generator, adapter factories and adapters.
 
Field Summary
protected  GeneratorAdapterFactory.Descriptor.Registry adapterFactoryDescriptorRegistry
          The local registry from which generator adapter factories are created.
protected  java.util.Set<java.lang.String> badFacadeHelperClasses
           
protected  boolean initializeNeeded
          Whether the adapter factories for the input need to be called to initialize before generating code.
protected  java.lang.Object input
           
protected  JControlModel jControlModel
           
protected  Generator.Options options
           
protected  java.util.Map<java.lang.String,java.util.Collection<GeneratorAdapterFactory>> packageIDToAdapterFactories
          The cached set of generator adapter factories for this generator, keyed by package ID.
 
Constructor Summary
Generator()
          Creates a generator that delegates directly to the global adapter factory descriptor registry.
Generator(GeneratorAdapterFactory.Descriptor.Registry adapterFactoryDescriptorRegistry)
          Creates a generator that delegates to the given adapter factory descriptor registry.
 
Method Summary
protected  boolean canContinue(Diagnostic diagnostic)
          Determines whether code generation can continue, based on the given Diagnostic.
 boolean canGenerate(java.lang.Object object, java.lang.Object projectType)
          Returns whether code can be generated for the given object and project type.
 void dispose()
          Disposes all of the generator's adapter factories, by calling dispose() on each.
 Diagnostic generate(java.lang.Object object, java.lang.Object projectType, Monitor monitor)
          Performs code generation for the given object and project type.
 Diagnostic generate(java.lang.Object object, java.lang.Object projectType, java.lang.String projectTypeName, Monitor monitor)
          Performs code generation for the given object and project type.
protected  java.util.Collection<GeneratorAdapterFactory> getAdapterFactories(java.lang.Object object)
          Returns the generator adapter factories for a given object.
 GeneratorAdapterFactory.Descriptor.Registry getAdapterFactoryDescriptorRegistry()
          Returns the generator's adapter factory descriptor registry.
protected  java.util.Collection<GeneratorAdapter> getAdapters(java.lang.Object object)
          Returns the generator adapters for the given object.
 java.lang.Object getInput()
          Returns the current model-level input object.
 JControlModel getJControlModel()
          Returns a JControlModel that the generator's adapters can use for merging.
 Generator.Options getOptions()
          Returns the Generator.Options for this generator.
protected  java.lang.String getPackageID(java.lang.Object object)
          Returns the package ID for the given object.
protected  void initialize()
          Invokes initialize(object) on each adapter factory for the input object.
 void requestInitialize()
          Signals that initialize(object) should be called on any adapter factories for the input object during the next generate(Object, Object, Monitor) or generate(Object, Object, String, Monitor), when the full tree of objects and adapters has been discovered.
 void setInput(java.lang.Object input)
          Sets the model-level input object, and invokes initialize(Object) on any of its adapter factories.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

adapterFactoryDescriptorRegistry

protected GeneratorAdapterFactory.Descriptor.Registry adapterFactoryDescriptorRegistry
The local registry from which generator adapter factories are created.


packageIDToAdapterFactories

protected java.util.Map<java.lang.String,java.util.Collection<GeneratorAdapterFactory>> packageIDToAdapterFactories
The cached set of generator adapter factories for this generator, keyed by package ID.


input

protected java.lang.Object input

options

protected Generator.Options options

initializeNeeded

protected boolean initializeNeeded
Whether the adapter factories for the input need to be called to initialize before generating code.

See Also:
requestInitialize()

jControlModel

protected JControlModel jControlModel

badFacadeHelperClasses

protected java.util.Set<java.lang.String> badFacadeHelperClasses
Constructor Detail

Generator

public Generator()
Creates a generator that delegates directly to the global adapter factory descriptor registry.

See Also:
GeneratorAdapterFactory.Descriptor.Registry.INSTANCE

Generator

public Generator(GeneratorAdapterFactory.Descriptor.Registry adapterFactoryDescriptorRegistry)
Creates a generator that delegates to the given adapter factory descriptor registry.

Method Detail

getInput

public java.lang.Object getInput()
Returns the current model-level input object.

See Also:
setInput(Object)

setInput

public void setInput(java.lang.Object input)
Sets the model-level input object, and invokes initialize(Object) on any of its adapter factories. This initialization will also be repeated in the next generate(Object, Object, Monitor) or generate(Object, Object, String, Monitor), when the full tree of objects and adapters has been discovered.

See Also:
getInput(), generate(Object, Object, Monitor), generate(Object, Object, String, Monitor), GeneratorAdapterFactory.initialize(Object)

requestInitialize

public void requestInitialize()
Signals that initialize(object) should be called on any adapter factories for the input object during the next generate(Object, Object, Monitor) or generate(Object, Object, String, Monitor), when the full tree of objects and adapters has been discovered.

See Also:
getInput(), generate(Object, Object, Monitor), generate(Object, Object, String, Monitor), GeneratorAdapterFactory.initialize(Object)

initialize

protected void initialize()
Invokes initialize(object) on each adapter factory for the input object. Note that adapter factory order is non-deterministic, so if more than one tries to set the same options, the result is undefined.

See Also:
getInput(), GeneratorAdapterFactory.initialize(Object)

getOptions

public Generator.Options getOptions()
Returns the Generator.Options for this generator. Note that these are accessible to (and can be set by) all of the adapter factories and adapters supporting this generator and by clients of the generator itself.


getJControlModel

public JControlModel getJControlModel()
Returns a JControlModel that the generator's adapters can use for merging. It is initialized with the facade helper class and merge rules URI specified in the options.

See Also:
getOptions(), Generator.Options.mergerFacadeHelperClass, Generator.Options.mergeRulesURI

getAdapterFactoryDescriptorRegistry

public GeneratorAdapterFactory.Descriptor.Registry getAdapterFactoryDescriptorRegistry()
Returns the generator's adapter factory descriptor registry.


getAdapterFactories

protected java.util.Collection<GeneratorAdapterFactory> getAdapterFactories(java.lang.Object object)
Returns the generator adapter factories for a given object. The registry for the generator is used to obtain the descriptors for the object's package ID, and those descriptors are used to create the adapter factories, which are cached.

See Also:
getAdapterFactoryDescriptorRegistry(), getPackageID(Object), GeneratorAdapterFactory.Descriptor

getPackageID

protected java.lang.String getPackageID(java.lang.Object object)
Returns the package ID for the given object.

This implementation returns the EPackage nsURI for an EObject, and the Java package name for any other object.

See Also:
EPackage.getNsURI(), Package.getName()

getAdapters

protected java.util.Collection<GeneratorAdapter> getAdapters(java.lang.Object object)
Returns the generator adapters for the given object. The adapter factories are obtained from getAdapterFactories(Object), and each may provide one adapter of type GeneratorAdapter.class.

See Also:
getAdapterFactories(Object), GeneratorAdapter

canGenerate

public boolean canGenerate(java.lang.Object object,
                           java.lang.Object projectType)
Returns whether code can be generated for the given object and project type. A project type is represented by an arbitrary object that is meaningful to the generator adapters for the relevant objects.

This result is obtained as follows:

  1. The adapters for the object are obtained.
  2. A complete collection of objects to be considered is formed by iteratively invoking the getCanGenerateParent(Object, Object) and getCanGenerateChildren(Object, Object) methods on the adapters for the object, the adapters for the object's parent and children, and so on. It is the adapters' responsibility to determine the relevant objects through their implementations of these methods.
  3. The canGenerate(Object, Object) method is invoked on all the adapters for every object in the set formed in step 2. If any adapter returns true for any object, this method returns true.
  4. Otherwise, false is returned.

See Also:
GeneratorAdapter.getCanGenerateParent(Object, Object), GeneratorAdapter.getCanGenerateChildren(Object, Object), GeneratorAdapter.canGenerate(Object, Object)

generate

public Diagnostic generate(java.lang.Object object,
                           java.lang.Object projectType,
                           Monitor monitor)
Performs code generation for the given object and project type. A project type is represented by an arbitrary object that is meaningful to the generator adapters for the relevant objects. Since this is a long-running operation, it reports progress using the given Monitor. Its final status is returned as a Diagnostic.

This method operates exactly as generate(Object, Object, String, Monitor) does when null is specified as the projectTypeName.

It is not necessary to call canGenerate(Object, Object) before this method. If that method would return false, this method should generate nothing when invoked with the same arguments.

See Also:
generate(Object, Object, String, Monitor), canGenerate(Object, Object)

generate

public Diagnostic generate(java.lang.Object object,
                           java.lang.Object projectType,
                           java.lang.String projectTypeName,
                           Monitor monitor)
Performs code generation for the given object and project type. A project type is represented by an arbitrary object that is meaningful to the generator adapters for the relevant objects. Since this is a long-running operation, it reports progress using the given Monitor. Its final status is returned as a Diagnostic. The projectTypeName, if non-null, is used only to provide to the Monitor a more specific message for the task.

It is not necessary to call canGenerate(Object, Object) before this method. If that method would return false, this method should generate nothing when invoked with the same arguments.

Code generation is performed as follows:

  1. The adapters for the object are obtained.
  2. A complete collection of objects to be considered is formed by iteratively invoking the getGenerateParent(Object, Object) and getGenerateChildren(Object, Object) methods on the adapters for the object, the adapters for the object's parent and children, and so on. It is the adapters' responsibility to determine the relevant objects through their implementations of these methods.
  3. If this is the first invocation of generate(Object, Object, String, Monitor) or initialization has been requested, initialize(Object) is invoked on each adapter factory for the input object.
  4. The preGenerate(Object, Object) method is invoked on all the adapters for every object in the set formed in step 2, giving the adapters a chance to perform setup before any code is generated.
  5. The generate(Object, Object, Monitor) method is invoked on all the adapters for every object in the set formed in step 2. This is where code generation actually occurs.
  6. The postGenerate(Object, Object) method is invoked on all the adapters for every object in the set formed in step 2, giving adapters a chance to clean up from code generation.

The operation may be canceled during step 4 or 5, either based on the Monitor or the Diagnostic returned by any generator adapter invocation. By default, only a CANCEL severity will cause code generation to stop; however, this can be customized by overriding canContinue(Diagnostic). Even if code generation is canceled, postGenerate(Object, Object) will still be called on all the adapters on which preGenerate(Object, Object) has been called.

See Also:
canGenerate(Object, Object), requestInitialize(), GeneratorAdapter.getGenerateParent(Object, Object), GeneratorAdapter.getGenerateChildren(Object, Object), GeneratorAdapter.preGenerate(Object, Object), GeneratorAdapter.generate(Object, Object, Monitor), GeneratorAdapter.postGenerate(Object, Object), GeneratorAdapterFactory.initialize(Object)

canContinue

protected boolean canContinue(Diagnostic diagnostic)
Determines whether code generation can continue, based on the given Diagnostic. This implementation returns true unless the severity is CANCEL.

See Also:
Diagnostic.getSeverity()

dispose

public void dispose()
Disposes all of the generator's adapter factories, by calling dispose() on each.

See Also:
GeneratorAdapterFactory.dispose()

Copyright 2001-2006 IBM Corporation and others.
All Rights Reserved.