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.
Currently the freeform project type is implemented as a single module, though domain-specific metadata is split into three schemas: general, Java-specific, and web-specific. Would like to introduce SPIs to permit the domain-specific functionality to be factored into physically distinct modules that could be independently maintained. Would also perhaps permit full J2EE support to add its own hooks. Precise design TBD - modules should be able to add to lookup, maybe merge into lookup items? Should be able to add to list of supported schemas. Should be able to add panels to properties dialog.
Seems it will be needed for E.
Seems it will be needed soon. The Web Apps team has a dependency and their tentative plan expects it to be done by end of November. Is it feasible?
We talked about it last week and I agreed we needed to begin work on this immediately - David I will want to talk with you next week on how ProjectModel etc. should be modularized.
OK, I'm going to look at that and prepare some answers.
Created attachment 19086 [details] zipped FreeformProjectSPI Javadoc
Created attachment 19087 [details] zipped JavaFreeformProjectSPI Javadoc
Created attachment 19088 [details] arch answers html file for web/freeform
I would like to ask for review of newly introduced SPI which I created as part of freeform module split. Originally monolithic freeform module was split into domain specific ones which now implement the SPI in order to plug itself into the base freeform project type. This issue already went through the DevRev and that's why I'm submitting this as fast-track although the SPI is not trivial. The planned stability of SPI is "friend" and it is expected that SPI will be implemented/used only by java/freeform, web/freeform and soon also by j2ee/freeform. Attached to this issue you can find #1) generated Javadoc of ant/freeform module with updated arch answers, #2) generated Javadoc of java/freeform module with updated arch answers and finally #3) updated arch answers of web/freeform which does not have any public SPI. From API point of view the most important is only one package: org.netbeans.modules.ant.freeform.spi. There exist also org.netbeans.modules.ant.freeform.spi.support and org.netbeans.modules.java.freeform.spi.support which both contain mostly support methods for wizard creation which are not very impressive, but it is just optional support which may or may not be used by the modules. Let me know if you have any questions or recommendations. Thanks.
Advice: Should not other project apis be referenced as official? As they are going to be official for promoe. imho request: In the arch-usecases describe how the API can be used. The architecture schetch just seems to describe overall arch, but not direct the usecases for module writers. I would like to see an explanation why the xsd is exported and what I can do with it as well as explanation of interface in lookup. Uses and especially flow of calls to methods in NewFreeformProjectSupport could be explained. What is TargetDescriptor for? How do you find out which Natures should be activated? document: "Project type is registered in META-INF/services." is an imported lookup API from a certain module. api tag should imho be used and it should be verified that the other module really exposes this api. question: what is the files structure, what files are generated, what is stability of their location and format? E.g. can user rely on that, edit them, etc? document: use url="@TOP@/org/netbeans/modules/ant/freeform/spi/ProjectNature.html" in api definition of ProjectNature api (at least I hope it works)
Thanks. Re. "Advice:" - can be done. Re. "why the xsd is exported" - users can and are encouraged to modify project.xml by hand. And (versioned) XML schema defines the format. Re. "ProjectNature interface in lookup" + "which Natures should be activated" - will improve its Javadoc. The base project queries all natures installed in the IDE and asks them whether they want to enhance the project or not. It's up to the nature to decide that, i.e. they can read project.xml and check presence of their namespaced metadata. Re. "flow of calls to methods in NewFreeformProjectSupport" - will improve its Javadoc. In practice you will not be woried about this because you are implementing wizard and you know that you need panels, then you need to instantiate them and then you have to clean them up. All what NFPS contains are exactly these methods. Re. "What is TargetDescriptor for" - will link its Javadoc to ProjetcNature.getExtraTargets(). Re. two "document:" - will fix that. Re. "files structure" - will mention project structure - i.e. the project.xml file always under nbproject directory whose structure is described by XML schemas which (as already said) are versioned.
David make sure to include all these explanations in the arch.xml (or Javadoc), not just write them here...
Created attachment 19110 [details] diff of changes based on Yarda's suggestions
Yarda, I just attached diff which I hope impl your comments. Feel free to further comment. Thanks.
Thanks, I think this is good enough for friend api with one additional suggestion: As you may know the "arch-usecases" section is displayed at http://www.netbeans.org/download/dev/javadoc/usecases.html and is base for unofficial (but we do not have any other) NetBeans faqs. In order to be really useful, please not only enumerate possible usecases, but also describe how to achieve them. One sentence with a url to the javadoc is enough I guess.
Since this is a friend SPI, IMHO details of how to achieve usecases are best described by the source code of the known actual users of the SPI, in java/freeform and web/freeform. If we were trying to make a general-purpose public SPI, it would make more sense to describe hypothetical usecases for interesting portions of the SPI and show code snippets, but here that just seems completely redundant. What do you think?
There is a bit of truth in your reasoning. Would it be possible to add at least links to WebCVS of the files that implemenent each usecase? That should be easy to do and would serve well for future references.
I think the stability level should not be Friend, it should be Under Development. It will be used in another cluster. Friend API implies that API will be used by the same group of people that provides the API. Frient API also implies that "the author of this API does not have the intent to create a general purpose API" which is not good for an API used by multiple modules in multiple clusters. I am not saying the API needs to be stabilizes immediately (maybe no even in the next release?) but the general goal should be to create a stable API in this case. http://openide.netbeans.org/tutorial/api-design.html#life
Re. usecases: I will add links to SPI impls. Re. Friend API also implies that "the author of this API does not have the intent to create a general purpose API": but this is exactly what these APIs are about. They are not general purpose APIs in the sense that anybody should/could use them. They are more about private-like communication in between limited number of well known modules. Speaking more technically, without regard of crossing cluster boundaries we would like to mark these APIs as evolving and designed for limited number of known clients; nobody should use them without letting us know; there is high probability that APIs may change in future and known clients will be fixed. They may become stable in future but at the moment it is not goal/requirement. Anyway, I guess this is not show stopper so I'm going to merge impl to trunk and we can alter stability later.
Integrated to trunk.
Sorry for removing the keyword. I reread Review Steps again and now I see that instead of removing it I should add reviews@ to CC. Done too.