Stabilize the API in web/webapi and make it public.
Development is taking place in
on the webapi_public_112441 branch.
Made the API stable as much as possible given the backward compatibility constraint. Ataching the commit log.
Created attachment 48938 [details]
Log of webapi_public_112441 merge to trunk
Created attachment 49243 [details]
I would like to ask for a fast-track API review for making the web/webapi a public API. This API has been in use for
more than three years now as a friend API with public packages. It is already used by external contributors, mostly
implementors of web frameworks. The web frameworks API is documented in "Rich Client Programming: Plugging into the
Y01 Make sure the API is published on http://bits.netbeans.org/dev/javadoc/
Y02 The attached javadoc still says "Friend" API. Make sure you change that to "stable"
Y03 The intro page of the javadoc has link to Arch Document and API Changes Document. This is old format of the page
(probably influenced by some property in project.properties), disable this, the default content is better. It lists
usecases, etc on the intro page.
Y04 One method of the API returns org.netbeans.modules.j2ee.dd.api.web.WebAppMetadata, imho that should be also public
API then. At least it has to be published at http://bits.netbeans.org/dev/javadoc/
Y05 In the list of arch-usecases I see nothing about WebFrameworks. Can you add a case describing how to register new
mk01: WebPrivilegedTemplates class was probably rendered obsolete by the introduction of LookupProviders. Anyone can now
place any privileged templates in any project type (that supports composite project lookup) by creating a LookupProvider
and adding a PrivilegedTemplates implementation in the lookup it provides.
mk02: WebModule marks the getJavaSources() method as deprecated, but the WebModuleImplementation doesn't. Can we
actually remove it from the WebModuleImplementation class?
Created attachment 49473 [details]
Created attachment 49474 [details]
Patch to make web/webapi public
Re Y01, Y02: sure, I was planning to do that after the review. See the attached patch. (I haven't build the javadoc for
the whole IDE yet, but I will before committing.)
Re Y03: done.
Re Y04: you're right, that is a flaw. j2ee/ddapi is currently not a public API (nor is it exactly in the shape to become
one for 6.0), but I will at least publish it. It should have low impact: people using WebModule, but not calling
getMetadataModel() will still be able to compile, and those needing getMetadataModel() will be able to depend on
j2ee/ddapi, since it has public packages and it is only declared as friend in arch.xml (and it used in the book, so this
can't be changed). This situation is temporary, j2ee/ddapi should be made public too in a future release.
Re Y05: there is a paragraph about web frameworks, but the use cases were not clearly separated using <usecase>
elements. I did that, is it better now?
Re mk01: an implementor would then need to get the WebModule from the project, which is not possible (there may be more
WebModule's in a project, and they are retrieved based on a FileObject (see WebModule.getWebModule()).
Re mk02: I deprecated WebModuleImplementation.getJavaSources(). I don't want to remove it, because that is semantically
incompatible. Also, I just realized it might have at least one client in NetBeans after all -- see issue 109426 desc12.
If there are no more comments I will commit tomorrow. Thank you for the review.
Checking in nbbuild/build.properties;
/cvs/nbbuild/build.properties,v <-- build.properties
new revision: 1.535; previous revision: 1.534
Checking in web/arch/arch-web-webapi.xml;
/cvs/web/arch/arch-web-webapi.xml,v <-- arch-web-webapi.xml
new revision: 1.12; previous revision: 1.11
Checking in web/webapi/apichanges.xml;
/cvs/web/webapi/apichanges.xml,v <-- apichanges.xml
new revision: 1.9; previous revision: 1.8
Checking in web/webapi/manifest.mf;
/cvs/web/webapi/manifest.mf,v <-- manifest.mf
new revision: 1.13; previous revision: 1.12