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.
Web project Framework developers need APIs that can Get/Set Project Properties and also has the capability to Add/Remove PropertyChangeListener for Project Properties. This request can apply to the general project API if needed, but Web Project should override them because it involved the 'UpdateHelper' that only found in Web Project. Suggest codes below: public String getProjectProperty(String propName) { UpdateHelper helper = project.getUpdateHelper(); EditableProperties props = helper.getProperties (AntProjectHelper.PROJECT_PROPERTIES_PATH); return props.getProperty(propName); } public void putProjectProperty(String propName, String value) { UpdateHelper helper = project.getUpdateHelper(); EditableProperties props = helper.getProperties (AntProjectHelper.PROJECT_PROPERTIES_PATH); props.setProperty(propName, value); helper.putProperties(AntProjectHelper.PROJECT_PROPERTIES_PATH, props); try { ProjectManager.getDefault().saveProject(project); } catch (Exception e) { ErrorManager.getDefault().notify(e); } } public void addPropertyChangeListener(PropertyChangeListener l) { PropertyEvaluator propEval = helper.getStandardPropertyEvaluator(); propEval.addPropertyChangeListener(l); } public void removePropertyChangeListener(PropertyChangeListener l) { PropertyEvaluator propEval = helper.getStandardPropertyEvaluator(); propEval.removePropertyChangeListener(l); }
Created attachment 29565 [details] New APIs diff with javadoc
Please review/add the attached 5 APIs into the package org.netbeans.modules.web.project.api and make this api public-packages. Note: Will isWebProject just check 'project instanceof WebProject' be a better approach?
AB01: it is not clear to which class should the methods be added. AB02: better to not allow a null WebProject parameter, but just throw NPE in this case. Has simpler semantics, it leads to cleaner API and it it is also consistent with the JDK. AB03: determining if the project is an Ant-based web project by checking if it provides a WebModule is not correct -- any project could provide a WebModule. Casting to WebProject is better, but not correct either -- see the Javadoc of ProjectManager.findProject() for rationale. The correct way is to put the WebProject in the WebProject's lookup. It is true that there are plenty of casts to WebProject in web/project, but those are bugs and should be fixed. AB04: the getProperties/setProperties calls in putProjectProperty() should be enclosed in ProjectManager.mutex().writeAccess() -- see the Javadoc of ProjectManager.mutex() for rationale). Or at least the Javadoc should specify that the caller is supposed to acquire PM.mutex() write access. But I think it is best if putProjectProperty() always acquires write acesss. AB05: Do you have an use case where you need to set more properties at once? If yes, settings them one by one using the putProjectProperty() method could be a performance issue, since the project will be saved with each property. AB06: I slightly don't like that these methods are intended to help implementing a web framework (which is WebModule-based), but still they work with Ant properties, although WebModule-s could be provided by any project, not only Ant-based. But I guess it is OK for a web framework implementation to e.g. provide just generic support for "generic" WebModule-based projects and better support for the Ant-based project in web/project. AB07: I'm not sure it is a good idea to make this as a public API. It exports stuff the Ant-based web project was never intended to export. Friend wouldn't be enough?
> AB01: it is not clear to which class should the methods be added. In the only class WebProjectUtilities of package org.netbeans.modules.web.project.api is OK. But no objection if creating any other new class is needed. > AB02: better to not allow a null WebProject parameter, but just throw NPE in > this case. Has simpler semantics, it leads to cleaner API and it it is also > consistent with the JDK. No objection for NPE! But looks like lots of codes just check null; I guess NPE has worse performance if many checking will perform. > AB03: determining if the project is an Ant-based web project by checking if it > provides a WebModule is not correct -- any project could provide a WebModule. > Casting to WebProject is better, but not correct either -- see the Javadoc of > ProjectManager.findProject() for rationale. The correct way is to put the > WebProject in the WebProject's lookup. It is true that there are plenty of casts > to WebProject in web/project, but those are bugs and should be fixed. No objection. I guess this should still be done inside the web/project module because WebProject class is not public. > AB04: the getProperties/setProperties calls in putProjectProperty() should be > enclosed in ProjectManager.mutex().writeAccess() -- see the Javadoc of > ProjectManager.mutex() for rationale). Or at least the Javadoc should specify > that the caller is supposed to acquire PM.mutex() write access. But I think it > is best if putProjectProperty() always acquires write acesss. Agree. > AB05: Do you have an use case where you need to set more properties at once? If > yes, settings them one by one using the putProjectProperty() method could be a > performance issue, since the project will be saved with each property. Usually the request comes from UI one by one. But one more API for putProjectProperties won't hurt; better actually. > AB06: I slightly don't like that these methods are intended to help implementing > a web framework (which is WebModule-based), but still they work with Ant > properties, although WebModule-s could be provided by any project, not only > Ant-based. But I guess it is OK for a web framework implementation to e.g. > provide just generic support for "generic" WebModule-based projects and better > support for the Ant-based project in web/project. I propose these APIs 'only' to Web Project because it involved the UpdateHelper that is only available to Web Project. > AB07: I'm not sure it is a good idea to make this as a public API. It exports > stuff the Ant-based web project was never intended to export. Friend wouldn't be > enough? Friend only works for NetBeans' modules as I known. How can the 3rd party like Creator's modules call them? (sorry I'm new for this one) Thanks, Po-Ting
'public static void addProjectPropertyListener and 'public static void addProjectPropertyListener' are pretty strange pattern. It is not clear to what is the listener attached / if the operation succeeded or not. Generaly the proposal will not work well with projects that are not based on Ant.
MK1: agreed on the previous posts. This doesn't scale for non ant-based projects types (eg. maven-based). Having static or utility methods that provide such functionality gives the impression it works for all. I would rather have all of this encapsulated in an API class that is optionally provided in the project's lookup. MK2: are the ant properties of web project part of the public contract? or do you intend to get/set/listen to just your own properties? MK3: are you really able to add web framework functionality by adding/changing a few properties? Can you give examples/usecases?
as I've been pointed out by jlahoda, this API is supposed to be in web/project and not the current web API module. Then it's probably obvious that it works just with the ant based project type..
PP01: Could you write up a concrete use case, where you need this extension? For me it's a little dangerous to expose all project properties and make them public. PP02: If you don't need to store ant properties, which are used during building (ant scripts) it's better to use project spi org.netbeans.spi.project.AuxiliaryConfiguration. I aggree with AB01 - AB07 comments.
PP03: With this change we expose properties to be public. So the properties are a part of the API and should be somewhere described. Which properties can user expected here?
Please be careful with exposing properties or targets of build scripts. Even if you believe it is just a contract between you two, it is not. It is also a contract between our users. And as such it has to be more stable then anything else. Otherwise our users are going to kill us when migrating from one version to another, especially if one version contains additional modules and second does not. So please pay attention to the user aspect of such kind of API.
Creator for example, its JSF framework needs to put the following 4 properties into the project.properties file and I think that's the best place to put these 'properties': jsf.current.theme=theme-default jsf.pagebean.package=webapplication25 jsf.project.libraries.dir=lib jsf.startPage=Page1.jsp I believe there are other developers who also like to put extra properties into the project.properties of their project type. And I guess org.netbeans.spi.project.AuxiliaryConfiguration won't store these properties into the project.properties file, just internal settings. Creator GUI also needs to add itself as PropertyChangeListener. E.g., when jsf.startPage changed, the Page node will change its icon as indicator. I believe other developers who also like to synchronize their module GUI when the properties changed.
The basic question is, what you want to store in project.properties. I think that there is basic rule that there should be saved only properties, which are used during headless build. Is it true in this case?
As the one who originally introduced the usage of the property API in Creator, I should probably speak up here :-) There were essentially two use cases for setting and retrieving properties on the project: 1. Creator uses the web project as a container for a web application in much the same way that NetBeans does. In Creator however, other modules have the ability to programatically change certain aspects of the project based on some user interaction, such as applying a project template when the project is created, or adding design-time/run-tine libraries as a result of a web service or component library binding operation. In order to isolate the Creator modules from the specific details of the web/project, a special "JSF project adapter" module was created that exposes an API to Creator modules to perform these extended actions on the web project - essentially creating a semantic layer on top of the generic web project. The adapter uses a combination of project properties to store certain state variables as well as exercise web project Lookup extensions that were added to Creator's forked copy of the web project. In this case, the adapter is indeed acting as a friend module to web/project and great care was taken to not violate any of the NetBeans web/project artifacts or semantics (i.e. the project should still be loadable inside generic NetBeans). 2. We found the project properties to be a useful and simple mechanism to allow any Creator module to attach their own state information to the project, obviously exercising care to establish a namespace for the properties that are added. I agree that allowing free access to a project's property set is equivalent to making all properties a public API. In Creator, we could make sure that we didn't violate any 'private' property settings, but that cannot be enforced for the general case. I think for the two use cases above: 1. Focus on enhancing the NetBeans web/project such that it provides the necessary lookup extension to perform required actions and/or supports a friend interface to the project adapter. I believe that each of the "JSF properties" that Po-Ting identified below could be implemented as API/SPI. Po-Ting is also working on adding certain Creator-specific functionaly as an additional framework to the web project (in a similar manner as the current NB struts, jsf support) so that could help for this case. 2. For modules that want to add metadata to the project, force them to use AuxilaryConfiguration. This is possible, although a simple interface to attach property sets (orthogonal to the project's private properties) would also be desirable - something that does not affect the project.xml. I believe we had some issues with AuxilaryConfiguration that prevented us from using it in certain cases (something to do with project lifecycle) but I don't remember the details.
Nothing I see here indicates to me that anything other than AuxiliaryConfiguration is needed for Creator to associate additional information with a web project. If you have some specific problem with AuxiliaryConfiguration consider filing a more general bug/RFE about that. There are three basic cases: 1. You want to associate some information with the project that is not required by the Ant build. (Which appears to be the case here.) Use AuxiliaryConfiguration. 2. You need to make changes to Ant properties or other bits of metadata which are already defined by web/project and which are not accessible in any other way. Request a minimal accessor API, possibly friend access only, to be added to project Lookup which encapsulates those changes you need, in a reasonably high-level fashion with error checking. ProjectClassPathExtender is a good example of this style. Do not permit it to freely read and write arbitrary properties by name. 3. You maintain your own Ant build script(s) for whatever reason, which may be parallel to the standard web/project script, import it, etc. So define and maintain your own separate properties file(s) providing information needed for your Ant build. No cooperation from web/project is required.
This doesn't qualify as a fast-track review I think since it is controversial.
Two years old api request? must be out of date by now.
Actually org.netbeans.modules.web.project.api.WebPropertyEvaluator has covered the requested feature.