Created attachment 109498 [details]
Running patch ('hg pdi template_anno_200175' to refresh)

Please review.

Note that the basic @Template cannot be used to register Java sources as these require a custom iterator; instead there is a variant annotation sharing processor logic with the basic annotation. (Unfortunately this cannot be used in the java.project module itself, though that module could still use @Template on the definition of createJavaTemplateIterator to register e.g. Class.java.) The same mechanism could be used to define annotations for other specialized kinds of templates using a predefined iterator: Maven archetypes based on coordinates; sample projects based on simple.project.templates; etc. (Technically Templates.category would merit a separate annotation in projectuiapi using this system, but that seems like overkill for such a commonly used and simple attribute.)

There is an editor hint (currently functional only on "pure" templates with an iterator but no static content); the apisupport wizards are not yet updated to generate @Template, but they can be.

By the way I am unsure whether the Templates/Privileged folder is still used for anything; it seems not to be, in which case I can delete the handful of shadows still registered there.

Y01 So far our annotations registering something were suffixed by Registration. Should not the new annotation be @TemplateRegistration?

Y02 I don't like AbstractTemplateProcessor in the API. Find different solution.

Y02a I am not convinced you need JavaTemplates.Registration(s) as all. For example instead of annotatiting org.netbeans.modules.beans.resources.templates; you can annotation static method:

@Templates(....)
static InstantiatingIterator beansTemplates() {
  return JavaTemplates.createJavaTemplateIterator();
}

Y03 Can we put these (DataObject independent) classes to org.netbeans.api.templates? They can stay in openide.loaders for now, but having them in separate package may help splitting them away in future.

Y04 Include examples in description of Template.content(). I am not sure I patient enough to parse the current javadoc.

Y05 There should be code completion on the Template.folder() value (you can use this as an opportunity to show me how this should be done after your devastating critique of @ActionReference.path()). General, easy to use solution for other annotations referencing layer is welcomed.

(In reply to comment #3)
> Y01 So far our annotations registering something were suffixed by Registration.
> Should not the new annotation be @TemplateRegistration?

It could be.

> Y02 I don't like AbstractTemplateProcessor in the API. Find different solution.

I do not like it much either but I could not find any other solution that permitted specialized template annotation types.

> Y02a ... you can annotate static method:
> 
> @Templates(....)
> static InstantiatingIterator beansTemplates() {
>   return JavaTemplates.createJavaTemplateIterator();
> }

This is a possible approach, though it means creating extra class files in each module registering Java templates. Ditto for other specialized template subtypes. Perhaps that is worth the cost.

> Y03 Can we put these (DataObject independent) classes to
> org.netbeans.api.templates?

I think that would not be a problem.

> They can stay in openide.loaders for now, but
> having them in separate package may help splitting them away in future.

Well, the template system is pretty heavily tied to DataObject and TemplateWizard.

> Y04 Include examples in description of Template.content(). I am not sure I
> patient enough to parse the current javadoc.

Can do.

> Y05 There should be code completion on the Template.folder() value

Will treat this as a TCA.

Y01-Y04 implemented in branch, by the way.

Also in branch: I found it was necessary to add an id() attribute (disjunctive with content()), for purposes of Templates/Classes/Package.

(In reply to comment #4)
> (In reply to comment #3)
> > Y02 I don't like AbstractTemplateProcessor in the API. Find different solution.
> 
> I do not like it much either but I could not find any other solution that
> permitted specialized template annotation types.
> 
> > Y02a ... you can annotate static method:
> > @Templates(....) static InstantiatingIterator beansTemplates() {
> >   return JavaTemplates.createJavaTemplateIterator();
> > }
> 
> This is a possible approach, though it means creating extra class files in each
> module registering Java templates. 

I don't think you need a special class. There always is some class in the module, so you can just add the method into it. E.g. no need to create special org.netbeans.modules.beans.resources.templates.Templates.

> > Y05 There should be code completion on the Template.folder() value
> 
> Will treat this as a TCA.

OK.

(In reply to comment #7)
> I don't think you need a special class. There always is some class in the
> module, so you can just add the method into it. E.g. no need to create special
> org.netbeans.modules.beans.resources.templates.Templates.

It could be in an existing class, but then the relative resource paths would all need to be changed, and template-related configuration would not be in one place, so I just created Templates.java in the same package for clarity.

core-main #d4c6057a3f4f

Integrated into 'main-golden'
Changeset: http://hg.netbeans.org/main-golden/rev/d4c6057a3f4f
User: Jesse Glick <jglick@netbeans.org>
Log: #200175: annotation to register templates.