[dali-dev] persistence.xml support

[Paul Fullbright <paul.fullbright@xxxxxxxxxx>]

The support for persistence.xml files has two parts:
   1) Support for editing and validating the document.
   2) Support for managing the document (adding/removing) within the 
project structure.

Part 1 is fairly straightforward, as we can follow the pattern seen 
throughout eclipse:  we associate the file name with a multipage editor, 
similar to how plugin.xml or site.xml file are associated with their 
editors.  This gives us editing support.  Validation is a little 
trickier, as there are two levels of validation:
   A) Validation of the document with respect to its schema
   B) Validation of the document with respect to the project contents.
A we get for free (unless we can't access or include the schema) as part 
of WTP XML support.  B may have to wait until we solve part 2.

Part 2 is definitely trickier.  There are a number of ways that 
persistence.xml may be used with persistence files (annotated java 
and/or orm.xml files):
   - The persistence files may appear in the same "persistence unit" 
root (more than one persistence unit may be defined in a persistence.xml 
file, but they all have the same root) as the persistence.xml file.  A 
root may be a jar or it may be an exploded folder in certain cases.  
Note that the class files in this case are *directly* within the root.  
Note also that this is a deployment configuration, not necessarily a 
development configuration.  In this case the persistence.xml may specify 
the types to scan for annotations, but all types directly within the 
root will be scanned by default.

      root
    | - META-INF
    |    | - persistence.xml
    |    | - orm.xml (optional)
    |
    | - package
         | - AnnotatedType.class (optional)
         | - NonannotatedType.class


   - The persistence files may appear in the same root, but not 
*directly* within the root.  They must be on the application classpath.  
The persistence.xml file must list all class files to scan for annotations.

      root
    | - META-INF
    |    | - persistence.xml
    |    | - orm.xml (optional)
    |
    | - classes
         | - package
              | - AnnotatedType.class (optional)
              | - NonannotatedType.class


   - The persistence files may appear in a jar within the persistence 
unit.  The jars must be on the application classpath, and they must be 
explicitly listed by the persistence.xml.

   root
    | - META-INF
    |    | - persistence.xml
    |
    | - lib
    |    | - AnnotatedTypes.jar
    |    | - NonannotatedTypesWithOrmXml.jar


In all above cases, the persistence.xml is located in the META-INF 
directory within the persistence unit root.

But what does the root correspond to in eclipse?  In the SE case, it 
most likely will correspond to a project root, but in the EE case, it 
isn't clear yet.  We need to dig into WTP to understand more about how 
complicated applications are intended to be developed.  Are we supposed 
to use a single project for each EE "component"?  If that's the case, 
then we might be able to use the project root as the persistence unit 
root, just like for SE.  But that likely isn't the case, as it seems 
complicated applications are intended to be developed as a single 
project, or at least that is made possible within WTP.  In that case, 
there will be multiple places within a project that might be considered 
a persistence unit root.


For now, I believe we can develop persistence.xml support in two phases:
   Phase I (Support for editing, partial support for validation, 
minimal support for configuration)
       - Implement an editor for persistence.xml files, including file 
choosers and type choosers within project scope.
       - Allow users the *option* of creating a persistence.xml file 
when adding the persistence nature. 
       - Always place persistence.xml files within a META-INF directory 
within the project root. 
       - Allow users to determine their deployment configuration on 
their own.
       - If a persistence.xml file is in the "incorrect" place, assume 
a user knows what he/she is doing.
       - Base XML validation.
   Phase II (Extended project-level validation, general configuration 
support)
       - Determine how to define persistence units within the scope of 
a project. (EE or SE)
       - Allow users to create a persistence.xml file in the absence of 
persistence files  (in the case that persistence files are to be 
deployed in a jar)
       - Help users determine deployment configuration.
       - Provide better project-level persistence.xml validation (e.g. 
show whether classes, files, or jars are not on classpath; determine 
valid provider class names; etc.)

I'll begin working on Phase I, probably to be finished within this 
iteration, and then I'll begin researching Phase II.  By that point 
we'll likely be coding to WTP 1.5 MX, which will probably be necessary 
for that phase.


- Paul