API Stabilization

Public APIs

db: P1

NetBeans official API (org.netbeans.api) which should have been declared stable in 5.5. See also db/dbapi.

html/lexer: P2

Does not have an arch document, but it is intended to become a public API in 6.0.

web/el/lexer: P2

Does not have an arch document, but it is intended to become a public API in 6.0.

web/jspsyntax/lexer: P2

Does not have an arch document, but it is intended to become a public API in 6.0. Depends on html/lexer and web/el/lexer, so they must be made public together.

xml/lexer: P2

Does not have an arch document. Future owner and evolution not clear, should probably not be public and stable in 6.0.

xml/api

Already public and under development. But it is an official NetBeans API, and as such it should have been made public a few releases ago.

Friend APIs declared using public-packages

j2ee/ddapi

This should be stabilized if web/webapi and j2ee/ejbapi are stabilized and methods to retrieve the deployment descriptor models are introduced to WebModule and EjbJar.

Issues:

• not thread safe, although accessed from multiple threads.

• DDProviders methods for retrieving the merged deployment descriptor models should be removed. These methods get a class (MetadataUnit) tying together the DD XML file and the respective module's classpath as a parameter. This both introduces an artificial and counter-intuitive artifact to the API, and makes implementation hard and prone to memory leaks (it "attaches" a piece of data to the module, instead of just letting the module just hold that data).

j2ee/ejbapi: P2

• getJavaSources(), addPropertyChangeListener() and deployment descriptor method as mentioned for web/webapi.

• J2eeProjectView and EjbEnterpriseReferenceContainerSupport do not belong in this module. They just hold some code common to projects, so we should perhaps have a separate project support module for it (other than j2ee/utilities).

• should split the client application API (Car and friends) and enterprise application API (Ear and friends) into another module. Car is a very bad name, perhaps we can fix this as well.

• perhaps we could rename CarsInProject and EjbJarsInProject as they are actually not tied to any project, they just provide a bunch of Cars and EjbJars, respectively.

j2ee/metadata: P3

Contains the infrastructure for the deployment descriptor / annotations merged model and will also contain the new model. Not clear if it needs to be public, probably not.

j2eeserver: P2

A reason to make this stable is getting people to write server plugins. For this reason it probably shouldn't be a friend API. On the other hand the module was clearly not written with compatible evolution in mind, which is visible from its release number (4). There are many issues and the module cannot be made stable enough in 6.0. Best we can do it turn it into "under development" and perhaps warn people about areas that are likely to change incompatibly (those we will not address in 6.0).

Not clear why and to whom this module exports the API.

web/webapi: P1

Needs to be stabilized because of the upcoming NetBeans API book.

Issues to be solved before stabilization:

• WebModule needs an addPropertyChangeListener() method and PROP_* constants. Aspects of the web module, such as its document base, can change during its lifetime, so we need a mechanism for notifying these changes.

• methods are needed in WebModule to obtain the web module's deployment descriptor model and the annotation / deployment descriptor merged model. Details unclear yet.

• perhaps WebModule.getJavaSources() should not return FileObjects, but SourceGroups, because the web module's Java sources can actually be a project's source groups. Not all file in the source group's root belong to that source group (see SourceGroup.contains()}), so a root FileObject and a SourceGroup are not equivalent. OTOH this could introduce an unwanted dependency on the project API.

• WebModule.J2EE_13_LEVEL and similar constants should not be there.

• WebFrameworkSupport (an API class) returns instances of WebFrameworkProviders (an SPI class). This is not right, as it makes SPI visible to API users, which can become a problem when the SPI is extended with other classes. Fortunately WebFrameworkProvider is a class, not an interface, so it can be extended.

• not clear if the WebProjectConstants.COMMAND_REDEPLOY is needed, it seems to be only used from web/project.

We will probably not be able to address all these issues because we need to keep the API stable to some degree because of the API book.

websvc/core: P2
websvc/registry: P2

Covered by NetBeans APIs for Web Services.

Friend APIs declared using friend-packages

db/core: P3

Small API which ties the core part of the SQL editor with its UI. Its only friend is db/sqleditor.

db/dbapi: P2

Provides various services to various modules in at least three clusters:

1. sending notifications when tables under a db connection node in the Runtime tab are refreshed
2. supports d'n'd of tables (and in the future connections, views and columns)
3. provides a list of SQL 99 keywords

Out of these, #2 and #3 can be stabilized and moved somewhere else. #2 clearly belongs in the DB Explorer. Not clear where #3 belongs, it isn't really related to the DB Explorer.

db/derby: P3

Provides API for creating databases and a SPI support for registering a Derby instance. The former can be stabilized, but the latter should be refactored before that. The list of friend is not likely to increase. Stabilization probably not urgent.

db/model: P4

DB Schema. Only has three friends in the same (enterprise) cluster. Stabilization is too expensive and the gain is small.

j2ee/clientproject: P3

This only provides an API allowing the EAR and archive project types to create a client application project. We should consider addressing issue 74272.

j2ee/ejbcore: P3

There does not seem to be a need to make this public. The modules exports the inexistent package org.netbeans.modules.j2ee.ejbcore.api.dd.

j2ee/ejbjarproject: P3

Same as j2ee/clientproject.

j2ee/persistence: P1

Many packages exported, used by various modules. In 6.0 the form editor will depend on it as well. At least some parts need to be moved to the ide cluster and to stabilize. Details still hazy.

j2ee/persistenceapi: P1

API allowing projects to provide information about JPA scopes. Implemented by all project types and the Maven project. Designed with evolution in mind, should be quite easy to stabilize.

To be done before stabilization:

• decide if PersistenceScopeProvider.findPersistenceScope(FileObject) can actually return more than one persistence scope. E.g. have an EAR with web project with a persistence.xml file depending on an EJB project with a persistence.xml file. Does a servlet in the web project have one or two persistence scopes available?

j2ee/utilities: P5

No intention to stabilize this module.

serverplugins/sun/appsrv: P5

Common stuff for Sun servers. No intention to stabilize this module, there does not seem to be a need for it.

serverplugins/sun/sunddapi: P5

Common stuff for Sun servers. No intention to stabilize this module, there does not seem to be a need for it.

serverplugins/sun/sunddui: P5

Common stuff for Sun servers. No intention to stabilize this module, there does not seem to be a need for it.

web/libs/glassfish_logging: P5

Contains Apache Commons Logging repackaged in com.sun packages; used by the JSP parser. No need to this to become public.

web/project: P3

Implements the same API that j2ee/clientproject and j2ee/ejbjarproject provide, the note that applies to those modules is valid for this one too.

Also provides an API/SPI allowing VWP to handle a web project instead of the default NetBeans web project. Probably no need to stabilize this, it should be rather removed in the long term.

websvc/clientapi: P2
websvc/jaxws20: P2
websvc/jaxwsapi: P2
websvc/jaxwsmodel: P2
websvc/websvcapi: P2

Covered by NetBeans APIs for Web Services.

xml/multiview: P2

The API was not written with evolution in mind and was probably never intended to become a public API. On the other hand NetBeans module writers could want to use this API, e.g. for visual editors for web frameworks configuration files. Hard to stabilize, there are known issues and parts of the module are not very comprehensible.

xml/tageditorsupport: P3

Designed with evaluation in mind except for the newly added TagBasedFormatter class. Could be probably made public if necessary, but there doesn't seem to be a huge need for it.