[cleanup] Fix some @since tag problems

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/ISubSystemConfigurator.java

@@ -23,10 +23,10 @@ import org.eclipse.rse.core.subsystems.ISubSystemConfiguration;
 
 /**
  * An interface used to drive properties into a subsystem during host creation.
- * 
+ *
- * @noimplement This is an internal interface for use in the framework.
+ * This is an internal interface for use in the framework. Potential clients
- *              Potential clients should extend one of the implementations or
+ * should extend one of the implementations or implement one of the extensions.
- *              implement one of the extensions.
+ *
  * @since org.eclipse.rse.core 3.0
  */
 public interface ISubSystemConfigurator {

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/filters/SystemFilterPoolDialogInputs.java

@@ -7,10 +7,10 @@
  *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
- * component that contains this file: David McKnight, Kushal Munir, 
+ * component that contains this file: David McKnight, Kushal Munir,
- * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, 
+ * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson,
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
- * 
+ *
  * Contributors:
  * David McKnight   (IBM)        - [225506] [api][breaking] RSE UI leaks non-API types
  * David Dykstal (IBM) - [226561] add API markup to javadoc
@@ -27,10 +27,12 @@ import org.eclipse.rse.ui.filters.dialogs.SystemFilterDialogInputs;
 
 
 /**
- * A class capturing the attributes commonly needed by dialogs that
+ * A class capturing the attributes commonly needed by dialogs that work with
- * work with filter pools.
+ * filter pools.
- * @noextend This class is not intended to be subclassed by clients.
+ * 
- * This class is complete and should be used as is.
+ * @noextend This class is not intended to be subclassed by clients. This class
+ * 	is complete and should be used as is.
+ * @since 3.0
  */
 public class SystemFilterPoolDialogInputs extends SystemFilterDialogInputs
 {
@@ -40,10 +42,10 @@ public class SystemFilterPoolDialogInputs extends SystemFilterDialogInputs
 	public ISystemFilterPoolManager[] poolManagers = null;
 	public ISystemFilterPoolReferenceManager refManager = null;
 	public int mgrSelection = 0;
-	public String poolNamePrompt;	
+	public String poolNamePrompt;
-	public String poolNameTip;	
+	public String poolNameTip;
 	public String poolMgrNamePrompt;
-	public String poolMgrNameTip;	
+	public String poolMgrNameTip;
-	
+
     public SystemSimpleContentElement filterPoolTreeRoot;
 }

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/filters/SystemFilterPoolDialogInterface.java

@@ -7,10 +7,10 @@
  *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
- * component that contains this file: David McKnight, Kushal Munir, 
+ * component that contains this file: David McKnight, Kushal Munir,
- * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, 
+ * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson,
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
- * 
+ *
  * Contributors:
  * David McKnight   (IBM)        - [225506] [api][breaking] RSE UI leaks non-API types
  *******************************************************************************/
@@ -21,8 +21,10 @@ import org.eclipse.rse.ui.filters.actions.SystemFilterAbstractFilterPoolAction;
 
 /**
  * Common interface for dialogs or wizards that work with filter pools.
+ * 
+ * @since 3.0
  */
-public interface SystemFilterPoolDialogInterface 
+public interface SystemFilterPoolDialogInterface
 {
 
 
@@ -33,7 +35,7 @@ public interface SystemFilterPoolDialogInterface
     /**
      * Return an object containing user-specified information pertinent to filter pool actions
      */
-    public SystemFilterPoolDialogOutputs getFilterPoolDialogOutputs();    
+    public SystemFilterPoolDialogOutputs getFilterPoolDialogOutputs();
     /**
      * Set the help context id for this wizard
      */

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/filters/SystemFilterPoolDialogOutputs.java

@@ -7,10 +7,10 @@
  *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
- * component that contains this file: David McKnight, Kushal Munir, 
+ * component that contains this file: David McKnight, Kushal Munir,
- * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, 
+ * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson,
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
- * 
+ *
  * Contributors:
  * David McKnight   (IBM)        - [225506] [api][breaking] RSE UI leaks non-API types
  * David Dykstal (IBM) - [226561] add API markup to javadoc
@@ -24,17 +24,19 @@ import org.eclipse.rse.ui.dialogs.SystemSimpleContentElement;
 
 
 /**
- * A class capturing the attributes commonly returned by dialogs that
+ * A class capturing the attributes commonly returned by dialogs that work with
- * work with filter pools.
+ * filter pools.
- * @noextend This class is not intended to be subclassed by clients.
+ * 
- * This class is complete and should be used as is.
+ * @noextend This class is not intended to be subclassed by clients. This class
+ * 	is complete and should be used as is.
+ * @since 3.0
  */
-public class SystemFilterPoolDialogOutputs 
+public class SystemFilterPoolDialogOutputs
 {
 
 
 	public String filterPoolName;
-	public String filterPoolManagerName;	
+	public String filterPoolManagerName;
-    public SystemSimpleContentElement filterPoolTreeRoot;	
+    public SystemSimpleContentElement filterPoolTreeRoot;
     public ISystemFilterPool newPool;
 }

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/view/ISystemResourceSelectionInputProvider.java

@@ -1,13 +1,13 @@
 /********************************************************************************
  * Copyright (c) 2008 IBM Corporation. All rights reserved.
  * This program and the accompanying materials are made available under the terms
- * of the Eclipse Public License v1.0 which accompanies this distribution, and is 
+ * of the Eclipse Public License v1.0 which accompanies this distribution, and is
  * available at http://www.eclipse.org/legal/epl-v10.html
- * 
+ *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
  * component that contains this file: David McKnight.
- * 
+ *
  * Contributors:
  *  David McKnight   (IBM)        - [225506] [api][breaking] RSE UI leaks non-API types
  ********************************************************************************/
@@ -18,12 +18,12 @@ import org.eclipse.rse.core.model.IHost;
 import org.eclipse.rse.core.model.ISystemViewInputProvider;
 
 /**
- * Public interface for the system resource selection input provider
+ * Public interface for the system resource selection input provider that is
- * that is used in the SystemRemoteResourceDialog and the 
+ * used in the SystemRemoteResourceDialog and the SystemResourceSelectionForm
- * SystemResourceSelectionForm
+ * 
- *
+ * @since 3.0
  */
-public interface ISystemResourceSelectionInputProvider 
+public interface ISystemResourceSelectionInputProvider
   extends ISystemViewInputProvider
 {
 	/**
@@ -31,7 +31,7 @@ public interface ISystemResourceSelectionInputProvider
 	 * @return the system connection
 	 */
 	public IHost getSystemConnection();
-	
+
 	/**
 	 * Indicates whether the input provider should allow new connections
 	 * to be created.
@@ -40,25 +40,25 @@ public interface ISystemResourceSelectionInputProvider
 	public void setAllowNewConnection(boolean flag);
 
 	/**
-	 * Returns whether multiple connections can be displayed via the 
+	 * Returns whether multiple connections can be displayed via the
 	 * input provider
 	 * @return true if multiple connections are allowed
 	 */
 	public boolean allowMultipleConnections();
-	
+
 	/**
 	 * Returns whether new connections can be created from the view
 	 * using this input provider.
 	 * @return true if new connections are allowed.
 	 */
 	public boolean allowNewConnection();
-		
+
 	/**
 	 * Returns the category for the view using the input provider (i.e. "files")
 	 * @return the category
 	 */
 	public String getCategory();
-	
+
 	/**
 	 * Sets the system types allowed for this input provider
 	 * @param types the types of systems
@@ -70,7 +70,7 @@ public interface ISystemResourceSelectionInputProvider
 	 * @return the system types
 	 */
 	public IRSESystemType[] getSystemTypes();
-	
+
 	/**
 	 * Sets the associated system connection for the input provider
 	 * @param connection the connection

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/view/ISystemSelectRemoteObjectAPIProvider.java

@@ -1,13 +1,13 @@
 /********************************************************************************
  * Copyright (c) 2008 IBM Corporation. All rights reserved.
  * This program and the accompanying materials are made available under the terms
- * of the Eclipse Public License v1.0 which accompanies this distribution, and is 
+ * of the Eclipse Public License v1.0 which accompanies this distribution, and is
  * available at http://www.eclipse.org/legal/epl-v10.html
- * 
+ *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
  * component that contains this file: David McKnight.
- * 
+ *
  * Contributors:
  * David McKnight   (IBM)        - [225506] [api][breaking] RSE UI leaks non-API types
  ********************************************************************************/
@@ -18,7 +18,10 @@ import org.eclipse.rse.core.filters.ISystemFilter;
 import org.eclipse.rse.core.model.IHost;
 import org.eclipse.rse.core.model.ISystemViewInputProvider;
 
-public interface ISystemSelectRemoteObjectAPIProvider 
+/**
+ * @since 3.0
+ */
+public interface ISystemSelectRemoteObjectAPIProvider
 		extends ISystemViewInputProvider
 {
 	/**
@@ -27,27 +30,27 @@ public interface ISystemSelectRemoteObjectAPIProvider
 	 *  connection.
 	 */
 	public Object[] getConnectionChildren(IHost selectedConnection);
-	
+
 	/**
 	 * Get the name of the item to select when the first filter is expanded.
 	 * Called by the filter adapter.
 	 */
 	public String getPreSelectFilterChild();
-	
+
 	/**
 	 * Get the actual object of the item to select when the first filter is expanded.
 	 * Called by the GUI form after expansion, so it can select this object
 	 */
 	public Object getPreSelectFilterChildObject();
-	
+
 	/**
-	 * Set the filter string to use to resolve the inputs. 
+	 * Set the filter string to use to resolve the inputs.
 	 * If this is an absolute filter string, it gets turned into a quick filter string,
-	 *  so that the user sees it and can expand it. If it is a relative filter string 
+	 *  so that the user sees it and can expand it. If it is a relative filter string
 	 *  to apply to all expansions, it is used to decorate all filtering as the user drills down.
 	 */
 	public void setFilterString(String string);
-	
+
 	/**
 	 * Set actual child object of the first filter to preselect. Called
 	 * by the filter adapter once the children are resolved and a match on
@@ -56,10 +59,10 @@ public interface ISystemSelectRemoteObjectAPIProvider
 	public void setPreSelectFilterChildObject(Object obj);
 
 	/**
-	 * Set child of the first filter to preselect 
+	 * Set child of the first filter to preselect
 	 */
 	public void setPreSelectFilterChild(String name);
-	
+
 	/**
 	 * Set the quick filters to be exposed to the user. These will be shown to the
 	 *  user when they expand a connection.
@@ -67,14 +70,14 @@ public interface ISystemSelectRemoteObjectAPIProvider
 	 */
 	public void setQuickFilters(ISystemFilter[] filters);
 
-	
+
 	/**
 	 * Specify whether the user should see the "New Connection..." special connection prompt
 	 */
 	public void setShowNewConnectionPrompt(boolean show);
-	
+
-	
+
-	/** 
+	/**
 	 * Default or Restrict to a specific connection.
 	 * If default mode, it is preselected.
 	 * If only mode, it is the only connection listed.
@@ -88,7 +91,7 @@ public interface ISystemSelectRemoteObjectAPIProvider
 	 * Specify system types to restrict what types of connections
 	 * the user can create, and see.
 	 * This will override subsystemConfigurationId,if that has been set!
-	 * 
+	 *
      * @param systemTypes An array of system types, or
      *     <code>null</code> to allow all registered valid system types.
      *     A system type is valid if at least one subsystem configuration

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/view/ISystemTableViewColumnManager.java

@@ -1,13 +1,13 @@
 /********************************************************************************
  * Copyright (c) 2008 IBM Corporation. All rights reserved.
  * This program and the accompanying materials are made available under the terms
- * of the Eclipse Public License v1.0 which accompanies this distribution, and is 
+ * of the Eclipse Public License v1.0 which accompanies this distribution, and is
  * available at http://www.eclipse.org/legal/epl-v10.html
- * 
+ *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
  * component that contains this file: David McKnight.
- * 
+ *
  * Contributors:
  * David McKnight   (IBM)        - [225506] [api][breaking] RSE UI leaks non-API types
  ********************************************************************************/
@@ -15,9 +15,12 @@ package org.eclipse.rse.ui.view;
 
 import org.eclipse.ui.views.properties.IPropertyDescriptor;
 
+/**
+ * @since 3.0
+ */
 public interface ISystemTableViewColumnManager {
 
 	public IPropertyDescriptor[] getVisibleDescriptors(ISystemViewElementAdapter adapter);
-	
+
 	public void setCustomDescriptors(ISystemViewElementAdapter adapter, IPropertyDescriptor[] descriptors);
 }

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/view/SystemAbstractAPIProvider.java

@@ -34,8 +34,13 @@ import org.eclipse.rse.ui.RSEUIPlugin;
 
 
 /**
- * This is a base class that a provider of root nodes to the remote systems tree viewer part can
+ * This is a base class that a provider of root nodes to the remote systems tree
- * use as a parent class.
+ * viewer part can use as a parent class.
+ *
+ * This class existed in RSE 1.0, was made "internal" for RSE 2.0 and restored
+ * as API for RSE 3.0.
+ * 
+ * @since 3.0
  */
 public abstract class SystemAbstractAPIProvider
        implements ISystemViewInputProvider

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/widgets/services/FactoryServiceElement.java

@@ -7,10 +7,10 @@
  *
  * Initial Contributors:
  * The following IBM employees contributed to the Remote System Explorer
- * component that contains this file: David McKnight, Kushal Munir, 
+ * component that contains this file: David McKnight, Kushal Munir,
- * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, 
+ * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson,
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
- * 
+ *
  * Contributors:
  * David Dykstal (IBM) - [217556] remove service subsystem types
  *******************************************************************************/
@@ -31,54 +31,66 @@ import org.eclipse.rse.services.IService;
 public class FactoryServiceElement extends ServiceElement
 {
 
-	private ISubSystemConfiguration _factory;	
+	private ISubSystemConfiguration _factory;
 	private ServiceElement[] _children;
 
 
+	/**
+	 * Constructor. Used to accept an IServiceSubSystemConfiguration before RSE
+	 * 3.0
+	 * 
+	 * @since 3.0
+	 */
 	public FactoryServiceElement(IHost host, ISubSystemConfiguration factory)
 	{
 		super(host, null);
 		_factory = factory;
 	}
-	
+
 	public String getName()
 	{
 		return _factory.getId();
 	}
-	
+
 	public String getDescription()
 	{
 		return _factory.getDescription();
 	}
-	
+
+	/**
+	 * Return the subsystem configuration related to this service element. Used
+	 * to return an IServiceSubSystemConfiguration before RSE 3.0.
+	 *
+	 * @since 3.0
+	 */
 	public ISubSystemConfiguration getFactory()
 	{
 		return _factory;
 	}
-	
+
 	public IConnectorService getConnectorService()
 	{
 		IHost host = getHost();
 		IConnectorService connectorService = _factory.getConnectorService(host);
 		return connectorService;
 	}
-	
+
 	public IService getService()
 	{
 		IHost host = getHost();
 		IService service = _factory.getService(host);
 		return service;
 	}
-	
+
 	public ServiceElement[] getChildren()
 	{
 		if (_children == null)
 		{
 			IHost host = getHost();
-			
+
 			ServiceServiceElement serviceElement = new ServiceServiceElement(host, this, getService());
-		
+
-			IConnectorService connectorService = getConnectorService();		
+			IConnectorService connectorService = getConnectorService();
 			if (connectorService != null && !(connectorService instanceof IDelegatingConnectorService))
 			{
 				_children = new ServiceElement[2];
@@ -101,9 +113,9 @@ public class FactoryServiceElement extends ServiceElement
 			}
 		}
 		return _children;
-		
+
 	}
-	
+
 	public boolean hasChildren()
 	{
 		return true;
@@ -141,7 +153,7 @@ public class FactoryServiceElement extends ServiceElement
 		}
 		}
 	}
-	
+
 	public void revert()
 	{
 		ServiceElement[] children = getChildren();

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/wizards/newconnection/ISystemNewConnectionWizardPage.java

@@ -1,9 +1,9 @@
 /*********************************************************************************
  * Copyright (c) 2008 IBM Corporation. All rights reserved.
  * This program and the accompanying materials are made available under the terms
- * of the Eclipse Public License v1.0 which accompanies this distribution, and is 
+ * of the Eclipse Public License v1.0 which accompanies this distribution, and is
  * available at http://www.eclipse.org/legal/epl-v10.html
- * 
+ *
  * Contributors:
  * David Dykstal (IBM) - initial contribution.
  * David Dykstal (IBM) - [168976][api] move ISystemNewConnectionWizardPage from core to UI
@@ -15,12 +15,18 @@ import org.eclipse.rse.core.model.ISubSystemConfigurator;
 
 
 /**
- * Interface that all subsystem configuration supplied pages contributed to the New Connection wizard must implement.
+ * Interface that all subsystem configuration supplied pages contributed to the
+ * New Connection wizard must implement. Moved from Core to UI in RSE 3.0
+ * 
  * @see org.eclipse.rse.ui.wizards.AbstractSystemNewConnectionWizardPage
- * @see org.eclipse.rse.ui.view.SubSystemConfigurationAdapter#getNewConnectionWizardPages(org.eclipse.rse.core.subsystems.ISubSystemConfiguration, org.eclipse.jface.wizard.IWizard)
+ * @see org.eclipse.rse.ui.view.SubSystemConfigurationAdapter#
+ * 	getNewConnectionWizardPages
+ * 	(org.eclipse.rse.core.subsystems.ISubSystemConfiguration,
+ * 	org.eclipse.jface.wizard.IWizard)
+ * @since 3.0
  */
 public interface ISystemNewConnectionWizardPage extends ISubSystemConfigurator {
-	
+
 	/**
 	 * This is called when the users presses Finish. All that should be done here is validation
 	 * of the input.
@@ -29,7 +35,7 @@ public interface ISystemNewConnectionWizardPage extends ISubSystemConfigurator {
 	public boolean performFinish();
 
 	/**
-	 * This is called frequently by the framework to decide whether to enable the Finish and Next buttons. 
+	 * This is called frequently by the framework to decide whether to enable the Finish and Next buttons.
 	 * <p>
 	 * @return true if the page is complete and has no errors.
 	 */

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/wizards/newconnection/RSEDefaultNewConnectionWizard.java

@@ -436,7 +436,11 @@ public class RSEDefaultNewConnectionWizard extends RSEAbstractNewConnectionWizar
 	}
 
 	/**
-	 * Return the first additional page to show when user presses Next on the main page
+	 * Return the first additional page to show when user presses Next on the
+	 * main page. In RSE 3.0, the ISystemNewConnectionWizardPage return type was
+	 * moved from org.eclipse.rse.core into a UI plugin.
+	 * 
+	 * @since 3.0
 	 */
 	protected ISystemNewConnectionWizardPage getFirstAdditionalPage() {
 		if ((subsystemConfigurationSuppliedWizardPages != null) && (subsystemConfigurationSuppliedWizardPages.length > 0)) {

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/ui/wizards/registries/RSEWizardSelectionTreePatternFilter.java

@@ -1,11 +1,11 @@
 /*******************************************************************************
  * Copyright (c) 2007 Wind River Systems, Inc. and others.
- * All rights reserved. This program and the accompanying materials 
+ * All rights reserved. This program and the accompanying materials
- * are made available under the terms of the Eclipse Public License v1.0 
+ * are made available under the terms of the Eclipse Public License v1.0
- * which accompanies this distribution, and is available at 
+ * which accompanies this distribution, and is available at
- * http://www.eclipse.org/legal/epl-v10.html 
+ * http://www.eclipse.org/legal/epl-v10.html
- * 
+ *
- * Contributors: 
+ * Contributors:
  * Uwe Stieber (Wind River) - initial API and implementation.
  * Uwe Stieber (Wind River) - [209193] RSE new connection wizard shows empty categories if typing something into the filter
  *******************************************************************************/
@@ -38,24 +38,27 @@ public class RSEWizardSelectionTreePatternFilter extends PatternFilter {
 
 	/**
 	 * Constructor.<br>
-	 * Creates a new pattern filter instance with the passed in
+	 * Creates a new pattern filter instance with the passed in wizard page
-	 * wizard page associated as parent.
+	 * associated as parent.
-	 * 
+	 *
 	 * @param page The parent wizard page or <code>null</code>.
+	 * @since 3.0
 	 */
 	public RSEWizardSelectionTreePatternFilter(WizardPage page) {
 		parentPage = page;
 	}
+
 	
 	/**
 	 * Returns the associated parent wizard parent.
-	 * 
+	 *
 	 * @return The parent wizard page or <code>null</code> if none.
+	 * @since 3.0
 	 */
 	protected WizardPage getParentWizardPage() {
 		return parentPage;
 	}
-	
+
 	/* (non-Javadoc)
 	 * @see org.eclipse.ui.dialogs.PatternFilter#isElementVisible(org.eclipse.jface.viewers.Viewer, java.lang.Object)
 	 */
@@ -67,7 +70,7 @@ public class RSEWizardSelectionTreePatternFilter extends PatternFilter {
 			// A system type must be associated with such tree element, otherwise it is filtered out
 			IRSESystemType systemType = ((RSENewConnectionWizardSelectionTreeElement)element).getSystemType();
 			if (systemType == null) return false;
-			
+
 			// if the page is restricted to a set of system types, check on them first
 			WizardPage wizardPage = getParentWizardPage();
 			if (wizardPage instanceof RSENewConnectionWizardSelectionPage) {
@@ -76,7 +79,7 @@ public class RSEWizardSelectionTreePatternFilter extends PatternFilter {
 					if (!Arrays.asList(restricted).contains(systemType)) return false;
 				}
 			}
-			
+
 			// First, adapt the system type to a viewer filter and pass on the select request
 			// to the viewer filter adapter if available
 			ViewerFilter filter = (ViewerFilter)(systemType.getAdapter(ViewerFilter.class));
@@ -87,7 +90,7 @@ public class RSEWizardSelectionTreePatternFilter extends PatternFilter {
 			// Second, double check if the system type passed the viewer filter but is disabled.
 			if (!systemType.isEnabled()) return false;
 		}
-		
+
 		return super.isElementVisible(viewer, element);
 	}
 
@@ -113,8 +116,8 @@ public class RSEWizardSelectionTreePatternFilter extends PatternFilter {
 			}
 
 		}
-		
+
 		return super.isLeafMatch(viewer, element);
 	}
-	
+
 }

rse/plugins/org.eclipse.rse.ui/subsystems/org/eclipse/rse/core/subsystems/SubSystem.java

@@ -837,36 +837,45 @@ implements IAdaptable, ISubSystem, ISystemFilterPoolReferenceManagerProvider
 	// Methods for encoding and decoding remote objects for drag and drop, and clipboard copy
 	// --------------------------------------------------------------------------------------
 
+
+	// --------------
+	// Methods for encoding and decoding remote objects for drag and drop, and
+	// clipboard copy
+	// ------------------------------------------------------------------------
+	// --------------
+
 	/**
 	 * Return the remote object that corresponds to the specified unique ID.
 	 * <p>
-	 * Since the abstract subsystem implementation does not know anything
+	 * Since the abstract subsystem implementation does not know anything about
-	 * about the specific kinds of resources managed by concrete
+	 * the specific kinds of resources managed by concrete implementations, this
-	 * implementations, this method can only resolve filter references.
+	 * method can only resolve filter references.
-	 * </p><p>
+	 * </p>
-	 * <strong>subsystem implementations must override this method
+	 * <p>
-	 * in order to resolve IDs for the remote objects they manage,
+	 * <strong>subsystem implementations must override this method in order to
-	 * to support drag and drop, clipboard copy and other remote object
+	 * resolve IDs for the remote objects they manage, to support drag and drop,
-	 * resolving schemes.</strong>
+	 * clipboard copy and other remote object resolving schemes.</strong>
-	 * Extenders that want to support filters should call
+	 * Extenders that want to support filters should call
-	 * <code>super.getObjectWithAbsoluteName(key)</code>
+	 * <code>super.getObjectWithAbsoluteName(key)</code> when they do not find a
-	 * when they do not find a reference for the key themselves.
+	 * reference for the key themselves.
 	 * </p>
-	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectResolver#getObjectWithAbsoluteName(String, IProgressMonitor)
 	 *
-	 * @param key the unique id of the remote object.
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectResolver#
-	 *     Must not be <code>null</code>.
+	 * 	getObjectWithAbsoluteName(String, IProgressMonitor)
+	 *
+	 * @param key the unique id of the remote object. Must not be
+	 * 		<code>null</code>.
 	 * @param monitor the progress monitor
-	 * @return the remote object instance, or <code>null</code> if no
+	 * @return the remote object instance, or <code>null</code> if no object is
-	 *     object is found with the given id.
+	 * 	found with the given id.
-	 * @throws Exception in case an error occurs contacting the remote
+	 * @throws Exception in case an error occurs contacting the remote system
-	 *     system while retrieving the requested remote object.
+	 * 		while retrieving the requested remote object. Extenders are
-	 *     Extenders are encouraged to throw {@link SystemMessageException}
+	 * 		encouraged to throw {@link SystemMessageException} in order to
-	 *     in order to support good user feedback in case of errors.
+	 * 		support good user feedback in case of errors. Since exceptions
-	 *     Since exceptions should only occur while retrieving new
+	 * 		should only occur while retrieving new remote objects during
-	 *     remote objects during startup, clients are typically allowed
+	 * 		startup, clients are typically allowed to ignore these exceptions
-	 *     to ignore these exceptions and treat them as if the remote
+	 * 		and treat them as if the remote object were simply not there.
-	 *     object were simply not there.
+	 * @since 3.0
 	 */
 	public Object getObjectWithAbsoluteName(String key, IProgressMonitor monitor) throws Exception
 	{
@@ -1697,7 +1706,7 @@ implements IAdaptable, ISubSystem, ISystemFilterPoolReferenceManagerProvider
 			msg = SubSystemConfiguration.getConnectingMessage(getHostName(), getConnectorService().getPort());
 			SystemBasePlugin.logInfo(msg);
 
-			if (!isOffline()){	
+			if (!isOffline()){
 				if (!implicitConnect(true, mon, msg, totalWorkUnits)){
 					String msgTxt = NLS.bind(CommonMessages.MSG_CONNECT_FAILED, getHostName());
 					throw new Exception(msgTxt);
@@ -3182,34 +3191,47 @@ implements IAdaptable, ISubSystem, ISystemFilterPoolReferenceManagerProvider
 	/* Service Subsystem support */
 
 	/**
-	 * Perform the subsystem specific processing required to complete a subsystem configuration switch for a
+	 * Perform the subsystem specific processing required to complete a
-	 * service subsystem. The subsystem will typically query this configuration for interesting properties or
+	 * subsystem configuration switch for a service subsystem. The subsystem
-	 * policies. It should also reset any state to a fresh start.
+	 * will typically query this configuration for interesting properties or
-	 * This supplied implementation does nothing. Subclasses may override if they implement a service subsystem.
+	 * policies. It should also reset any state to a fresh start. This supplied
-	 * @param newConfiguration the configuration this subsystem should use from this point.
+	 * implementation does nothing. Subclasses may override if they implement a
+	 * service subsystem.
+	 *
+	 * @param newConfiguration the configuration this subsystem should use from
+	 * 		this point.
+	 * @since 3.0
 	 */
 	protected void internalSwitchSubSystemConfiguration(ISubSystemConfiguration newConfiguration) {
 	}
 
 	/**
-	 * Determine if a service subsystem is capable of switching to this new configuration.
+	 * Determine if a service subsystem is capable of switching to this new
-	 * This is usually a test of this configuration's type against the type expected by this subsystem.
+	 * configuration. This is usually a test of this configuration's type
-	 * This supplied implementation returns false. Subclasses should override if they implement a service subsystem.
+	 * against the type expected by this subsystem. This supplied implementation
+	 * returns false. Subclasses should override if they implement a service
+	 * subsystem.
+	 *
 	 * @param configuration the configuration to which this subsystem may switch
-	 * @return true if this subsystem is capable of switching to this configuration, false otherwise. This implementation
+	 * @return true if this subsystem is capable of switching to this
-	 * returns false.
+	 * 	configuration, false otherwise. This implementation returns false.
 	 * @see ISubSystem#canSwitchTo(ISubSystemConfiguration)
+	 * @since 3.0
 	 */
 	public boolean canSwitchTo(ISubSystemConfiguration configuration) {
 		return false;
 	}
 
 	/**
-	 * Switch to use another subsystem configuration. This default implementation will test if the subsystem is a
+	 * Switch to use another subsystem configuration. This default
-	 * service subsystem and if the subsystem is compatible with the suggested configuration. If it is the switch will
+	 * implementation will test if the subsystem is a service subsystem and if
-	 * be performed and internalSwitchSubSystemConfiguration will be called.
+	 * the subsystem is compatible with the suggested configuration. If it is
+	 * the switch will be performed and internalSwitchSubSystemConfiguration
+	 * will be called.
+	 * 
 	 * @see ISubSystem#switchServiceFactory(ISubSystemConfiguration)
 	 * @see #internalSwitchSubSystemConfiguration(ISubSystemConfiguration)
+	 * @since 3.0
 	 */
 	public void switchServiceFactory(final ISubSystemConfiguration config) {
 		if (config != getSubSystemConfiguration() && canSwitchTo(config)) {
@@ -3227,9 +3249,12 @@ implements IAdaptable, ISubSystem, ISystemFilterPoolReferenceManagerProvider
 
 	/**
 	 * Return the service type for this subsystem.
-	 * @return the default implementation returns null. Subclasses that implement service subsystems
+	 *
-	 * should return a type as specified in the interface.
+	 * @return the default implementation returns null. Subclasses that
-	 * @see org.eclipse.rse.core.subsystems.ISubSystem#getServiceType()
+	 * 	implement service subsystems should return a type as specified in the
+	 * 	interface.
+	 * @see ISubSystem#getServiceType()
+	 * @since 3.0
 	 */
 	public Class getServiceType() {
 		return null;

rse/plugins/org.eclipse.rse.ui/subsystems/org/eclipse/rse/core/subsystems/SubSystemConfiguration.java

@@ -960,25 +960,33 @@ public abstract class SubSystemConfiguration  implements ISubSystemConfiguration
 	}
 
 	/**
-	 * Creates a new subsystem instance that is associated with the given connection object.
+	 * Creates a new subsystem instance that is associated with the given
-	 * SystemRegistryImpl calls this when a new connection is created, and appliesToSystemType returns true.
+	 * connection object. SystemRegistryImpl calls this when a new connection is
+	 * created, and appliesToSystemType returns true.
 	 * <p>
 	 * This method doe sthe following:
 	 * <ul>
-	 *   <li>calls {@link #createSubSystemInternal(IHost)} to create the subsystem
+	 * <li>calls {@link #createSubSystemInternal(IHost)} to create the subsystem
-	 *   <li>does initialization of common attributes
+	 * <li>does initialization of common attributes
-	 *   <li>if {@link #supportsFilters()}, creates a {@link org.eclipse.rse.core.filters.ISystemFilterPoolReferenceManager} for the
+	 * <li>if {@link #supportsFilters()}, creates a {@link
-	 *           subsystem to manage references to filter pools
+	 * org.eclipse.rse.core.filters.ISystemFilterPoolReferenceManager} for the
-	 *   <li>if (@link #supportsServerLaunchProperties()}, calls {@link #createServerLauncher(IConnectorService)}, to create
+	 * subsystem to manage references to filter pools
-	 *           the server launcher instance to associate with this subsystem.}.
+	 * <li>if (@link #supportsServerLaunchProperties()}, calls {@link
-	 *   <li>calls {@link #initializeSubSystem(ISubSystem, ISubSystemConfigurator[])} so subclasses can
+	 * #createServerLauncher(IConnectorService)}, to create the server launcher
-	 *           do their thing to initialize the subsystem.
+	 * instance to associate with this subsystem.}.
-	 *   <li>finally, saves the subsystem to disk.
+	 * <li>calls {@link #initializeSubSystem(ISubSystem,
+	 * ISubSystemConfigurator[])} so subclasses can do their thing to initialize
+	 * the subsystem.
+	 * <li>finally, saves the subsystem to disk.
 	 * </ul>
+	 * 
 	 * @param conn The connection to create a subsystem for
-	 * @param creatingConnection true if we are creating a connection, false if just creating
+	 * @param creatingConnection true if we are creating a connection, false if
-	 *          another subsystem for an existing connection.
+	 * 		just creating another subsystem for an existing connection.
-	 * @param configurators configurators that inject properties into this new subsystem or null if there are none
+	 * @param configurators configurators that inject properties into this new
+	 * 		subsystem or null if there are none. Used to take
+	 * 		ISystemNewConnectionWizardPage[] before RSE 3.0.
+	 * @since 3.0
 	 */
 	public ISubSystem createSubSystem(IHost conn, boolean creatingConnection, ISubSystemConfigurator[] configurators)
 	{
@@ -1193,12 +1201,17 @@ public abstract class SubSystemConfiguration  implements ISubSystemConfiguration
 	public abstract ISubSystem createSubSystemInternal(IHost conn);
 
 	/**
-	 * Initialize subsystems after creation (<i>Overridable</i>).
+	 * Initialize subsystems after creation (<i>Overridable</i>). The default
-	 * The default behavior is to add a reference to the default filter pool for this subsystem configuration,
+	 * behavior is to add a reference to the default filter pool for this
-	 * if there is one. Typically subclasses call <samp>super().initializeSubSystem(...)</samp>
+	 * subsystem configuration, if there is one. Typically subclasses call
-	 * to get this default behavior, then extend it.
+	 * <samp>super().initializeSubSystem(...)</samp> to get this default
+	 * behavior, then extend it.
+	 *
 	 * @param ss - The subsystem that was created via createSubSystemInternal
-	 * @param configurators an array of {@link ISubSystemConfigurator} used to inject values into this subsystem or null if there are none
+	 * @param configurators an array of {@link ISubSystemConfigurator} used to
+	 * 		inject values into this subsystem or null if there are none. Used to
+	 * 		take ISystemNewConnectionWizardPage[] before RSE 3.0
+	 * @since 3.0
 	 */
 	protected void initializeSubSystem(ISubSystem ss, ISubSystemConfigurator[] configurators) {
 		if (supportsFilters()) {
@@ -1422,8 +1435,12 @@ public abstract class SubSystemConfiguration  implements ISubSystemConfiguration
 	}
 
 	/**
-	 * Overridable entry for child classes to supply their own flavour of ISystemFilterPoolWrapperInformation for
+	 * Overridable entry for child classes to supply their own flavor of
-	 *  the new filter wizards.
+	 * ISystemFilterPoolWrapperInformation for the new filter wizards.
+	 *
+	 * @return an ISystemFilterPoolWrapperInformation instead of a
+	 * 	SystemFilterPoolWrapperInformation since 3.0
+	 * @since 3.0
 	 */
 	protected ISystemFilterPoolWrapperInformation getNewFilterWizardPoolWrapperInformation()
 	{
@@ -2776,11 +2793,11 @@ public abstract class SubSystemConfiguration  implements ISubSystemConfiguration
 	}
 
 	/**
-	 * Return true if deferred queries are supported.
+	 * Return true if deferred queries are supported. By default, they are
-	 * By default, they are supported. Override for different behavior.
+	 * supported. Override for different behavior.
 	 *
 	 * @return <code>true</code> if deferred queries are supported.
-	 * @see org.eclipse.rse.core.subsystems.ISubSystemConfiguration#supportsDeferredQueries()
+	 * @see ISubSystemConfiguration#supportsDeferredQueries()
 	 */
 	public boolean supportsDeferredQueries()
 	{
@@ -2792,44 +2809,65 @@ public abstract class SubSystemConfiguration  implements ISubSystemConfiguration
 	 */
 
 	/**
-	 * This default implementation does nothing.
+	 * {@inheritDoc}
-	 * Service subsystems must override as defined in the interface.
+	 * <p>
-	 * @see org.eclipse.rse.core.subsystems.ISubSystemConfiguration#setConnectorService(org.eclipse.rse.core.model.IHost, org.eclipse.rse.core.subsystems.IConnectorService)
+	 * This default implementation does nothing. Service subsystems must
+	 * override as defined in the interface.
+	 *
+	 * @see ISubSystemConfiguration#setConnectorService(IHost,
+	 * 	IConnectorService)
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public void setConnectorService(IHost host, IConnectorService connectorService) {
 	}
 
 	/**
-	 * This default implementation returns null.
+	 * {@inheritDoc}
-	 * Service subsystem configurations must override as defined in the interface.
+	 * <p>
-	 * @see org.eclipse.rse.core.subsystems.ISubSystemConfiguration#getConnectorService(org.eclipse.rse.core.model.IHost)
+	 * This default implementation returns <code>null</code>. Service subsystem
+	 * configurations must override as defined in the interface.
+	 *
+	 * @see ISubSystemConfiguration#getConnectorService(IHost)
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public IConnectorService getConnectorService(IHost host) {
 		return null;
 	}
 
 	/**
-	 * This default implementation returns null.
+	 * {@inheritDoc}
-	 * Service subsystem configurations must override as defined in the interface.
+	 * <p>
-	 * @see org.eclipse.rse.core.subsystems.ISubSystemConfiguration#getServiceType()
+	 * This default implementation returns <code>null</code>. Service subsystem
+	 * configurations must override as defined in the interface.
+	 *
+	 * @see ISubSystemConfiguration#getServiceType()
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public Class getServiceType() {
 		return null;
 	}
 
 	/**
-	 * This default implementation returns null.
+	 * {@inheritDoc}
-	 * Service subsystem configurations must override as defined in the interface.
+	 * <p>
-	 * @see org.eclipse.rse.core.subsystems.ISubSystemConfiguration#getServiceImplType()
+	 * This default implementation returns <code>null</code>. Service subsystem
+	 * configurations must override as defined in the interface.
+	 *
+	 * @see ISubSystemConfiguration#getServiceImplType()
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public Class getServiceImplType() {
 		return null;
 	}
 
 	/**
-	 * This default implementation returns null.
+	 * {@inheritDoc}
-	 * Service subsystem configurations must override as defined in the interface.
+	 * <p>
-	 * @see org.eclipse.rse.core.subsystems.ISubSystemConfiguration#getService(org.eclipse.rse.core.model.IHost)
+	 * This default implementation returns <code>null</code>. Service subsystem
+	 * configurations must override as defined in the interface.
+	 *
+	 * @see ISubSystemConfiguration#getService(IHost)
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public IService getService(IHost host) {
 		return null;