Extend javadoc for org.eclipse.core.runtime.preferences.InstanceScope.INSTANCE to clarify under which circumstances it may fail

[kwin]

In eclipse-jdt/eclipse.jdt.debug#684 I ran into the following exception:

java.lang.IllegalStateException: The instance data location has not been specified yet.
	at org.eclipse.core.internal.runtime.DataArea.assertLocationInitialized(DataArea.java:61)
	at org.eclipse.core.internal.runtime.DataArea.getStateLocation(DataArea.java:146)
	at org.eclipse.core.internal.preferences.InstancePreferences.getBaseLocation(InstancePreferences.java:43)
	at org.eclipse.core.internal.preferences.SingletonEclipsePreferences.initializeChildren(SingletonEclipsePreferences.java:97)
	at org.eclipse.core.internal.preferences.SingletonEclipsePreferences.<init>(SingletonEclipsePreferences.java:37)
	at org.eclipse.core.internal.preferences.InstancePreferences.<init>(InstancePreferences.java:57)
	at org.eclipse.core.internal.preferences.InstancePreferences.internalCreate(InstancePreferences.java:64)
	at org.eclipse.core.internal.preferences.EclipsePreferences.create(EclipsePreferences.java:370)
	at org.eclipse.core.internal.preferences.EclipsePreferences.create(EclipsePreferences.java:358)
	at org.eclipse.core.internal.preferences.PreferencesService.createNode(PreferencesService.java:354)
	at org.eclipse.core.internal.preferences.EclipsePreferences.getOrCreate(EclipsePreferences.java:1162)
	at org.eclipse.core.internal.preferences.RootPreferences.getNode(RootPreferences.java:65)
	at org.eclipse.core.internal.preferences.RootPreferences.node(RootPreferences.java:53)
	at org.eclipse.core.internal.preferences.AbstractScope.getNode(AbstractScope.java:38)

when using org.eclipse.core.runtime.preferences.InstanceScope.INSTANCE.getNode(...)

Similar to https://help.eclipse.org/latest/rtopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/resources/ResourcesPlugin.html#getWorkspace() there should be a disclaimer stating that this may fail and one should wait for the service org.eclipse.osgi.service.datalocation.Location to be registered with type=osgi.*.area before using this.

Update: Probably waiting for the service registration Location is not even enough, as this may happen too early. Compare with https://bugs.eclipse.org/bugs/show_bug.cgi?id=514333. Not sure what is the proper way to synchronize here as with regular startup workspace selection (and therefore configuring the location for InstanceScope) happens quite late. Is waiting for the Workspace service the right thing to do?

[kwin]

The Location service reference looks like this prior to workspace selection

{org.eclipse.osgi.service.datalocation.Location}={service.id=8, service.bundleid=0, service.scope=singleton, defaultUrl=file:/Users/715508/eclipse-workspace/, type=osgi.instance.area}

and like this afterwards

{org.eclipse.osgi.service.datalocation.Location}={service.id=8, service.bundleid=0, service.scope=singleton, defaultUrl=file:/Users/715508/eclipse-workspace/, url=file:/Users/715508/eclipse-workspaces/maven/, type=osgi.instance.area}

So probably waiting for a Location service with url property is necessary.