[jdt-core-dev] jdt support for generated files

["Mike Kaufman" <mkaufman@xxxxxxx>]

This didn't seem to go through the first time I sent it, so I'm trying again.  Sorry if this gets duplicated on the list.


-----Original Message-----
From: Mike Kaufman 
Sent: Wednesday, February 23, 2005 3:10 PM
To: 'jdt-core-dev@xxxxxxxxxxx'
Subject: jdt support for generated files



Hi - 

I'm a BEA Systems employee that is working on BEA's eclipse efforts.  One of the things that BEA needs is eclipse  support for "generated files".  Below is a mini-spec that describes what I mean by "generated files" and the requirements we want to accomplish.  I've been trading emails with Philippe & Jerome over the last few weeks on this subject, and I'm currently playing around with the JDT to make these requirements a reality.  Since BEA is now public with their eclipse support, I wanted to open up the discussion to a broader audience.

I appreciate any feedback and comments from this list.  I also appreciate your patience, as I am still new to JDT code & eclipse.

Thanks!

Mike Kaufman
Software Engineer
BEA Systems




Generated Files in Eclipse Mini-Spec (v 0.4)
============================================

Background
----------
We have various needs for being able to generate a java file during the processing of some other java file.  For example, an implementation of Sun's APT/mirror APIs inside of eclipse will need to support the generation of source files during execution of an APT/mirror AnnotationProcessor.  Also, a jsp compiler would use this feature to generate the servlet corresponding to a .jsp file.     

Requirements
------------

R1.  we need an api as follows that will generate a .java file for the specified primary type name & the specified contents:  
       public ??? generateFile( String typeName, String contents );

R2.  The types in the generated file should be part of the project's JavaModel (e.g., they should be available in code-completion, auto-import, the package view pane, etc...).

R3.  The contents of the generated file should NOT be available for searching.

R4.  A user should not be able to edit a generated file.

R5.  The generated source should NOT be written to disk unless a special flag is specified.  If the special flag is specified, the generated source should not reside in the project's source directory.  We'll write them to a user-specified directory, or some part of the project's output directory.  

R6.  Each generated file must have at least one "parent".  A "parent" is the file whose processing caused the generated file to be generated.  A generated file can generate other generated files.  Following the links from generated file to parent will eventually reach a non-generated file that we will call a "root". 

R7.  The generated .class file should be written into the project's build output directory when the project is built.  Specifically, whenever a generated file's parent is code-gen'd, the generated file should be code-gen'd.

R8.  A generated file's parent should have knowledge of the depdendencies of the generated file.  We will call this "hoisting" a generated file's dependencies to the parent.  The "root" of a chain of generated files will know about all of the dependencies of the generated files.  

R9.  When a dependency of the generated file changes, the generated file should be recompiled.  This may be  accomplished by regenerating the generated file, utilizing the "hoisted" dependencies. 

R10.  The generated file should not be recompiled on an incremental compile unless its contents have changed.

R11.  When the generated file's contents have changed (i.e., the file has been regenerated with a different shape), then the changes should be reported through Eclipse's resource-change listener infrastructure. 

R12.  syntax/semantic errors occuring in the generated source file should be available for some client to do something interesting with.  

R13.  Multiple parents of a single generated file *may* exist, although no guarantee can be made about correctness of the contents of the file, (i.e., the bookkeeping infrastructure shouldsupport multiple parents). 

R14.  When all of the "parent" files of a generated file are deleted, the generated file should be deleted also (i.e., its types should be removed from the JavaModel, etc...)

R15.  A generated file may introduce types that the generated file's parent is dependent on.  Specifically, the generated type may resolve errors in a parent.   

R16.  To be consistent with R4, generated files should be excluded from refactoring and renaming operations.  Rather, a rename or refactor operation that affects a generated file should cause the generated file's parent to regenerate the generated file.  The implementation of this would likely utilize the "hoisted dependencies" discussed in R8. 


Open Questions:
---------------

Q1: what should the return type of generateFile be?  
        ...an org.eclipse.core.resource.IFile?  
        ...an org.eclipse.jdt.internal.compiler.env.ICompilationUnit?
        ...an org.eclipse.jdt.core.ICompilationUnit? 

Q2:  How do we accomplish the "hoisted dependency" thing?

Q3:  Where is the best place to maintain the parent<->generated-file mapping

Q4:  too many to list (how do types get in the java model?  how do we suppress indexing?  How do we get errors from a generated file? ...)