Bug 284650 [CommonNavigator] Misleading JavaDoc of the INavigatorContentService
Build ID: 20090619-0625 Steps To Reproduce: It is stated: "Clients should create instances of the this class using the factory ({@link NavigatorContentServiceFactory}).", which is truth for creation of a new instance only. If the instance of INavigatorContentService is required to configure the existing CNF instance, it should be obtained from the Navigator instead. More information: Here is a chat transcript with Francis Upton: [4:54:09 PM] Simon Zambrovski: NavigatorContentServiceFactory <- this guy is not intended to be used by clients in order to get access to the INavigatorContentService, right? So INavigatorContentService service = new NavigatorContentServiceFactory().createContentService("my.view.id"); is not working, but I should find the view (via IWorkbenchPage.findView()), cast it to the CommonNavigator and finally retrieve the NavigatorContentService from it by calling CommonNavigator.getNavigatorContentService() [4:56:38 PM] Francis Upton: yes [4:56:55 PM] Simon Zambrovski: ok. i'll add this to the wiki, because once you find the INavigatorContentService, its JavaDoc says - use the factory to get an instance of it.... [4:58:39 PM] Francis Upton: the javadoc comments are misleading, it refers to the use of it in a standalone manner which is possible, but not what you want. You want the one assicated with the CN. [4:59:13 PM] Francis Upton: can you file a bug about this? You can copy this transcript into the bug report, and that way I can clean up the doc.
bundles/org.eclipse.ui.navigator/src/org/eclipse/ui/navigator/INavigatorContentService.java
* Clients should use {@link #createCommonContentProvider()} and
 * {@link #createCommonLabelProvider()} for the viewer. Each content service
 * tracks the viewer it is attached to. Clients may create the content service
 * with a viewer using ({@link NavigatorContentServiceFactory#createContentService(String)}).
 * Alternatively, when the content provider is created and set on a viewer,
 * {@link IContentProvider#inputChanged(org.eclipse.jface.viewers.Viewer, Object, Object)}
 * will be called and the content provider will update the viewer used by its
 * backing content service. Therefore, only each content service has exactly one
 * content provider and one label provider.
 * </p>
 * <p>
 * Extensions may also coordinate their behavior through a
 * {@link IExtensionStateModel state model}. The state model holds properties
 * and supports property change listeners. Actions can toggle the setting of
 * properties and the corresponding content/label providers will respond to
 * property change event. Each <b>navigatorContent</b> extension has its own
 * contained state model keyed off of the content extension id.
 * </p>
 * <p>
 * Clients may respond when content extensions are loaded by attaching a
 * {@link INavigatorContentServiceListener} to the content service.
 * </p>
 * <p>
 * Some extensions may provide content or label providers which implement
 * {@link IMemento}. Clients must call {@link #restoreState(IMemento)} and
 * {@link #saveState(IMemento)} at the appropriate times for these extensions to
 * prepare themselves with the memento.
 * </p>
 * <p>
 * This interface is not intended to be implemented by clients.