Bug 568153 - Suggest alternate uses of Platform.getBundle

`Platform.getBundle(String)` provides a means to translate a String
bundle identifier into a `Bundle` instance. It performs a reasonable
amount of work, including iterating through all bundles, filtering and
other such processing.

It is generally more efficient, if you already have a class loaded by
OSGi, is to use `FrameworkUtil.getBundle(Class)` instead. This performs
a near direct lookup, since the class' associated `ClassLoader` implicitly
knows what the `Bundle` is.

However, the majority of cases is to write an entry to the log, from
which `Platform.getLog(Class)` is a much simpler implementation.

Add JavaDoc to introduce these patterns that may be of relevance to
callers instead.

Change-Id: I6a8bb35446660391eccec69061a98958d1a833ad
Signed-off-by: Alex Blewitt <alex.blewitt@gmail.com>

bundles/org.eclipse.core.runtime/META-INF/MANIFEST.MF

diff --git a/bundles/org.eclipse.core.runtime/META-INF/MANIFEST.MF b/bundles/org.eclipse.core.runtime/META-INF/MANIFEST.MF
index b4f7b79..22a0221 100644
--- a/bundles/org.eclipse.core.runtime/META-INF/MANIFEST.MF
+++ b/bundles/org.eclipse.core.runtime/META-INF/MANIFEST.MF
@@ -1,7 +1,7 @@
 Manifest-Version: 1.0
 Bundle-ManifestVersion: 2
 Bundle-Name: %pluginName
-Bundle-Version: 3.19.0.qualifier
+Bundle-Version: 3.19.100.qualifier
 Bundle-SymbolicName: org.eclipse.core.runtime; singleton:=true
 Bundle-Vendor: %providerName
 Bundle-Activator: org.eclipse.core.internal.runtime.PlatformActivator

bundles/org.eclipse.core.runtime/pom.xml

diff --git a/bundles/org.eclipse.core.runtime/pom.xml b/bundles/org.eclipse.core.runtime/pom.xml
index 0fabc90..93d9dd2 100644
--- a/bundles/org.eclipse.core.runtime/pom.xml
+++ b/bundles/org.eclipse.core.runtime/pom.xml
@@ -19,6 +19,6 @@
   </parent>
   <groupId>org.eclipse.core</groupId>
   <artifactId>org.eclipse.core.runtime</artifactId>
-  <version>3.19.0-SNAPSHOT</version>
+  <version>3.19.100-SNAPSHOT</version>
   <packaging>eclipse-plugin</packaging>
 </project>

bundles/org.eclipse.core.runtime/src/org/eclipse/core/runtime/Platform.java

diff --git a/bundles/org.eclipse.core.runtime/src/org/eclipse/core/runtime/Platform.java b/bundles/org.eclipse.core.runtime/src/org/eclipse/core/runtime/Platform.java
index f352abf..e9af481 100644
--- a/bundles/org.eclipse.core.runtime/src/org/eclipse/core/runtime/Platform.java
+++ b/bundles/org.eclipse.core.runtime/src/org/eclipse/core/runtime/Platform.java
@@ -1424,6 +1424,17 @@
 	 * highest version. Note that clients may want to filter the results based on
 	 * the state of the bundles.
 	 * </p>
+	 * <p>
+	 * Note that looking up a Bundle by its symbolic name is less efficient than
+	 * looking up a Bundle by a class loaded by that bundle. Callers should consider
+	 * whether or not it is more appropriate to use
+	 * {@link FrameworkUtil#getBundle(Class)} instead.
+	 * </p>
+	 * <p>
+	 * Note also that if the purpose of looking up the Bundle in order to log a
+	 * message, then it would be more appropriate to use the direct
+	 * {@link #getLog(Class)} instead
+	 * </p>
 	 *
 	 * @param symbolicName the symbolic name of the bundle to be returned.
 	 * @return the bundle that has the specified symbolic name with the highest