This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 171029

Summary: Annotation to register project customizer panels
Product: projects Reporter: Jesse Glick <jglick>
Component: Generic InfrastructureAssignee: Jesse Glick <jglick>
Status: RESOLVED FIXED    
Severity: blocker CC: apireviews
Priority: P3 Keywords: API, API_REVIEW_FAST
Version: 6.x   
Hardware: All   
OS: All   
URL: http://wiki.netbeans.org/DeclarativeRegistrationUsingAnnotations#section-DeclarativeRegistrationUsingAnnotations-ProjectPropertiesDialogPanels
Issue Type: ENHANCEMENT Exception Reporter:
Attachments: Initial patch including API, impl, & test (no apichanges.xml yet), and usage in j2seproject

Description Jesse Glick 2009-08-27 19:28:14 UTC
There are a bunch of these panel classes and currently you are forced to register them manually in a layer.
Comment 1 Jesse Glick 2009-08-27 20:06:49 UTC
Will focus for now on registration of CompositeCategoryProvider instances. There are cases such as
JWSCompositeCategoryProvider where the impl of createCategory unconditionally returns a category with a fixed name and
displayName and no subcategories, and createComponent always returns the same impl class of panel. In such cases it
would be possible to skip the CompositeCategoryProvider and directly register the panel (internally using a "lazy" CCP
instance which loads the panel using reflection upon request), e.g.

@ProjectCustomizerPanel(projectType="org-netbeans-modules-java-j2seproject", category="Application", position=200)
public class JWSCustomizerPanel extends JPanel {
  public JWSCustomizerPanel(ProjectCustomizer.Category category, Lookup context) {
        jwsProps = new JWSProjectProperties(context);
        category.setOkButtonListener(new OkButtonListener(jwsProps, context.lookup(Project.class)));
        category.setStoreListener(new SavePropsListener(jwsProps, context.lookup(Project.class)));
    // ...
  }
  // ...
}

The advantage would be that no class from javawebstart would be loaded unless and until this panel were selected and
displayed, and the programming style is a bit more concise. Such a lazy annotation could be created if there is enough
demand to justify the added work and complexity. The payoff would be limited, however:

1. Most panels are implemented in the project type module itself, so their impls are unlikely to load in a network of
fresh code; very often several panels share a single parametrized CompositeCategoryProvider class.

2. CompositeCategoryProvider impls are usually small classes that are not especially expensive to load, and there are
only a handful of them used for a given project type.

3. Often a CCP injected by another module is displayed only conditionally, meaning createCategory performs some kind of
logic to determine whether to return null or produce the category. For example, many panels for the Maven customizer are
shown only for certain packaging types; the Swing App panel is shown only for projects which use this framework. Such
panels could not use the lazy registration style.

4. Class loading would be avoided only when the customizer dialog is shown for a project of a given type, which may
never happen in an IDE session if the user is performing routine work on a relatively mature project.
Comment 2 Jesse Glick 2009-08-28 00:08:04 UTC
Created attachment 86757 [details]
Initial patch including API, impl, & test (no apichanges.xml yet), and usage in j2seproject
Comment 3 Jesse Glick 2009-08-28 00:09:34 UTC
Please review.
Comment 4 Milos Kleint 2009-08-28 09:37:26 UTC
looks generally ok,

as you mention in point 2. the performance gains are rather small. Even if we didn't have some additional logic in maven
projects, most modules contain additional code next to the customizer that would trigger the classloading of that module
anyway..

MK1: what is the recommended procedure for panels that are to be provided for multiple project types? (eg. Formatting panel)
Comment 5 Jesse Glick 2009-08-28 13:58:10 UTC
To MK1 - you can use @Registrations({@Registration(...), ...}) to register a panel in several project types. I plan to
actually do so for the Formatting panel, which is currently registered in options.editor for freeform, j2seproject, and
maven. As usual there is the dilemma that other project types (e.g. php) need to register this panel as well, and
currently do so using registrations in their own layers which I would leave untouched.

Probably the better solution would be for there to be a Projects/any/Customizer/ folder which would automatically get
merged in with the project-type-specific folder when constructing the dialog, permitting just one @Registration to be
made in options.editor that would work automatically on all projects. I leave that to a separate API enhancement as it
would not be expected to affect this API.
Comment 6 Milos Kleint 2009-08-28 14:03:37 UTC
sounds ok.. not sure about "any" there are some basic constraints in each of the panels that probably prohibit putting
it in all project types.. Eg. even the rather generic formatting panel needs AuxiliaryProperties to be defined in
project in order to work. Other panels might be just ant-based etc..

BTW: The formatting panel has different definition in maven projects. I needed it to accept subpanels (Checkstyle
formatting)
Comment 7 Jesse Glick 2009-08-28 14:21:12 UTC
"basic constraints" - the CCP can always decide to return null from createCategory if it needs to, based on inspection
of the Project's capabilities. In the case of auxiliary properties, this is supported in ProjectUtils for any project
type so the panel could be unconditionally enabled.

AFAICT the maven module's usage of the Formatting panel is no different except that it is defined as a folder ("style
#3" rather than "style #1"). Even using something like Projects/any/Customizer/ the Formatting panel could be safely
defined as style #3, since in project types with no actual subcategories, no expand handle or other artifacts are shown
(it looks the same as style #1).
Comment 8 Jesse Glick 2009-09-11 02:35:04 UTC
core-main #87292c738725
Comment 9 Quality Engineering 2009-09-13 21:03:37 UTC
Integrated into 'main-golden', will be available in build *200909131354* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main-golden/rev/87292c738725
User: Jesse Glick <jglick@netbeans.org>
Log: Issue #171029: permit declarative annotation-based registration of project customizer panels.
Includes registrations for common project types.
Also added LayerBuilder.folder.