[cleanup] format, javadoc, method order, logging

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/RSECorePlugin.java

@@ -18,9 +18,7 @@ package org.eclipse.rse.core;
 import java.net.InetAddress;
 import java.net.UnknownHostException;
 
-import org.eclipse.core.runtime.IStatus;
 import org.eclipse.core.runtime.Plugin;
-import org.eclipse.core.runtime.Status;
 import org.eclipse.rse.core.internal.RSECoreRegistry;
 import org.eclipse.rse.core.model.ISystemRegistry;
 import org.eclipse.rse.internal.persistence.RSEPersistenceManager;
@@ -30,34 +28,36 @@ import org.eclipse.rse.persistence.IRSEPersistenceManager;
 import org.osgi.framework.BundleContext;
 
 /**
- * The RSE core plugin class. Clients may extend this class.
+ * RSECorePlugin provides the activation for the RSE core and acts as the primary
+ * registry for logging, persistence, and the main RSE service registries.
+ * It should not be extended by other classes.
  */
 public class RSECorePlugin extends Plugin {
 
-	// the shared instance
+	private static RSECorePlugin plugin; // the singleton instance of this plugin
-	private static RSECorePlugin plugin;
 	private Logger logger = null;
-
 	private ISystemRegistry _registry;
 	private IRSEPersistenceManager _persistenceManager = null;
 
-    public static IRSEPersistenceManager getThePersistenceManager()
+	/**
-    {
+	 * Returns the singleton instance of RSECorePlugin.
+	 * @return the singleton instance.
+	 */
+	public static RSECorePlugin getDefault() {
+		return plugin;
+	}
+
+	/**
+	 * A static convenience method - fully equivalent to 
+	 * <code>RSECorePlugin.getDefault().getPersistenceManager()</code>.
+	 * @return the persistence manager currently in use for RSE
+	 */
+	public static IRSEPersistenceManager getThePersistenceManager() {
 		return getDefault().getPersistenceManager();
 	}
+
 	/**
-     * @return the persistence manager used for persisting RSE profiles
+	 * @return the IP host name of this machine
-     */
-    public IRSEPersistenceManager getPersistenceManager()
-    {
-    	if (_persistenceManager == null)
-    	{
-    		_persistenceManager = new RSEPersistenceManager(_registry);
-    	}
-    	return _persistenceManager;
-    }
-	/**
-	 * @return the local machine name
 	 */
 	public static String getLocalMachineName() {
 		String machineName = null;
@@ -70,7 +70,7 @@ public class RSECorePlugin extends Plugin {
 	}
 
 	/**
-	 * @return the local IP address
+	 * @return the local IP address of this machine
 	 */
 	public static String getLocalMachineIPAddress() {
 		String machineAddress = null;
@@ -83,22 +83,12 @@ public class RSECorePlugin extends Plugin {
 	}
 
 	/**
-	 * The constructor.
+	 * The constructor. This may be called only by plugin activation.
 	 */
 	public RSECorePlugin() {
 		plugin = this;
 	}
 
-	public void setSystemRegistry(ISystemRegistry registry)
-	{
-		_registry = registry;
-	}
-	
-	public ISystemRegistry getSystemRegistry()
-	{
-		return _registry;
-	}
-
 	/*
 	 * (non-Javadoc)
 	 * @see org.eclipse.core.runtime.Plugin#start(org.osgi.framework.BundleContext)
@@ -120,29 +110,65 @@ public class RSECorePlugin extends Plugin {
 	}
 
 	/**
-	 * Returns the shared instance.
+	 * @return the persistence manager used for persisting RSE profiles
-	 * @return the shared instance.
 	 */
-	public static RSECorePlugin getDefault() {
+	public IRSEPersistenceManager getPersistenceManager() {
-		return plugin;
+		if (_persistenceManager == null) {
+			_persistenceManager = new RSEPersistenceManager(_registry);
+		}
+		return _persistenceManager;
+	}
+
+	/**
+	 * Sets the system registry. This is the main registry that can be used by RSE components
+	 * that require a user interface. This should be set only by RSE startup components and 
+	 * not by any external client.
+	 * @param registry the implementation of ISystemRegistry that the core should remember.
+	 */
+	public void setSystemRegistry(ISystemRegistry registry) {
+		_registry = registry;
+	}
+
+	/**
+	 * Gets the system registry set by {@link #setSystemRegistry(ISystemRegistry)}.
+	 * This registry is used to gain access to the basic services and components used in 
+	 * the RSE user interface. 
+	 * @return the RSE system registry
+	 */
+	public ISystemRegistry getSystemRegistry() {
+		return _registry;
 	}
 
 	/**
 	 * Returns the RSE core registry. Clients should use this method to get the registry which
-	 * is the starting point for working with the RSE framework.
+	 * is the starting point for working with the RSE framework. It contains methods to access
+	 * core services and components. It is distinct from, and more basic than, an implementation
+	 * of ISystemRegistry.
+	 * <p>
+	 * This may return null if the registry has not yet been set.
 	 * @return the RSE core registry.
 	 */
 	public IRSECoreRegistry getRegistry() {
 		return RSECoreRegistry.getDefault();
 	}
 
+	/**
+	 * Returns an instance of the logger being used by the core. All core services, or extensions to 
+	 * core services, should use this logger to log any messages. The RSE logger provides run-time 
+	 * filtering according to user preference and uses the platform's logging capabilities. RSE services
+	 * should use this logger rather than a platform logger. The logger is defined at plugin start and 
+	 * should always be available.
+	 * @return the instance of System#Logger used by the core RSE
+	 */
 	public Logger getLogger() {
 		return logger;
 	}
 
+	/**
+	 * Log an unexpected exception that occurs during the functioning of this class.
+	 * @param t the exception to log
+	 */
 	private void log(Throwable t) {
-		String pluginId = this.getBundle().getSymbolicName();
+		getLogger().logError("Unexpected Exception", t); //$NON-NLS-1$
-		IStatus status = new Status(IStatus.ERROR, pluginId, 0, "Unexpected Exception", t); //$NON-NLS-1$
-		getLog().log(status);
 	}
 }