[cleanup] Add API "since" Javadoc tags

rse/plugins/org.eclipse.rse.core/.project

@@ -20,9 +20,15 @@
 			<arguments>
 			</arguments>
 		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.api.tools.apiAnalysisBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
 	</buildSpec>
 	<natures>
 		<nature>org.eclipse.pde.PluginNature</nature>
 		<nature>org.eclipse.jdt.core.javanature</nature>
+		<nature>org.eclipse.pde.api.tools.apiAnalysisNature</nature>
 	</natures>
 </projectDescription>

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

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006, 2007 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -8,11 +8,14 @@
  * Kushal Munir (IBM) - Initial API and implementation.
  * David Dykstal (IBM) - updated with comments, removed keys that are not to be used globally
  * David Dykstal (IBM) - [197167] adding notification and waiting for RSE model
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 package org.eclipse.rse.core;
 
 /**
  * These constants define the set of preference names that the RSE core uses.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 
 /*
@@ -23,31 +26,39 @@ package org.eclipse.rse.core;
 public interface IRSEPreferenceNames {
 
 	/**
-	 * The key for the value that specifies that queries should be "deferred", that is, run
+	 * The key for the value that specifies that queries should be "deferred",
-	 * when needed and in the background, as nodes are asked for their children.
+	 * that is, run when needed and in the background, as nodes are asked for
-	 * This value is not part of the API.
+	 * their children. This value is not part of the API.
+	 * 
+	 * @noreference This field is not intended to be referenced by clients.
 	 */
 	public static final String USE_DEFERRED_QUERIES = "useDeferredQueries"; //$NON-NLS-1$
 
 	/**
-	 * The key for the default system type. Used when a system type is needed but not declared
+	 * The key for the default system type. Used when a system type is needed
-	 * when creating new connections (hosts) and for password determination.
+	 * but not declared when creating new connections (hosts) and for password
-	 * This value is not part of the API.
+	 * determination. This value is not part of the API.
+	 * 
+	 * @noreference This field is not intended to be referenced by clients.
 	 */
 	public static final String SYSTEMTYPE = "systemtype"; //$NON-NLS-1$
 
 	/**
-	 * The key for an hash table, encoded as a string, that contains user ids as values
+	 * The key for an hash table, encoded as a string, that contains user ids as
-	 * keyed by some key - usually a system type, a connection name, or a combination of
+	 * values keyed by some key - usually a system type, a connection name, or a
-	 * a connection name and subsystem.
+	 * combination of a connection name and subsystem. This value is not part of
-	 * This value is not part of the API.
+	 * the API.
+	 * 
+	 * @noreference This field is not intended to be referenced by clients.
 	 */
 	public static final String USERIDPERKEY = "useridperkey"; //$NON-NLS-1$
 
 	/**
-	 * The key for the string containing the list of active user profiles in alphabetical order.
+	 * The key for the string containing the list of active user profiles in
-	 * As profiles are activated, deactivated, or renamed this string must be modified.
+	 * alphabetical order. As profiles are activated, deactivated, or renamed
-	 * This value is not part of the API.
+	 * this string must be modified. This value is not part of the API.
+	 * 
+	 * @noreference This field is not intended to be referenced by clients.
 	 */
 	public static final String ACTIVEUSERPROFILES = "activeuserprofiles"; //$NON-NLS-1$
 
@@ -59,9 +70,11 @@ public interface IRSEPreferenceNames {
 	public static final String DEFAULT_PERSISTENCE_PROVIDER = "DEFAULT_PERSISTENCE_PROVIDER"; //$NON-NLS-1$
 
 	/**
-	 * The key of the string containing the id of the boolean value to create a local connection.
+	 * The key of the string containing the id of the boolean value to create a
-	 * Value is "CREATE_LOCAL_CONNECTION".
+	 * local connection. Value is "CREATE_LOCAL_CONNECTION". This value is part
-	 * This value is part of the API and may be used to customize products.
+	 * of the API and may be used to customize products.
+	 * 
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static final String CREATE_LOCAL_CONNECTION = "CREATE_LOCAL_CONNECTION"; //$NON-NLS-1$
 

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

@@ -15,6 +15,7 @@
  * Martin Oberhuber (Wind River) - [185098] Provide constants for all well-known system types
  * Martin Oberhuber (Wind River) - [186640] Add IRSESystemType.testProperty()
  * Martin Oberhuber (Wind River) - [218655][api] Provide SystemType enablement info in non-UI
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core;
@@ -254,14 +255,16 @@ public interface IRSESystemType extends IAdaptable {
 	 * 
 	 * The enabled state is a dynamic property of a system type, compared to the
 	 * static configuration by plugin markup. Enablement is a non-UI property,
-	 * which can be set by a Product in the Preferences or modified by a user
+	 * which can be set by a Product in the Preferences or modified by a user to
-	 * to hide certain system types.
+	 * hide certain system types.
 	 * <p>
-	 * Implementers of custom system types (which are registered by a SystemTypeProvider)
+	 * Implementers of custom system types (which are registered by a
-	 * can override this method to provide more advanced enabled checks e.g. based on
+	 * SystemTypeProvider) can override this method to provide more advanced
-	 * license availability.
+	 * enabled checks e.g. based on license availability.
 	 * 
-	 * @return <code>true</code> if the system type is currently enabled, or <code>false</code> otherwise.
+	 * @return <code>true</code> if the system type is currently enabled, or
+	 *         <code>false</code> otherwise.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public boolean isEnabled();
 

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

@@ -1,19 +1,21 @@
 /********************************************************************************
- * Copyright (c) 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * Kushal Munir (IBM) - Initial API and implementation.
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 package org.eclipse.rse.core;
 
 /**
- * These constants define the set of properties that the UI expects to
+ * These constants define the set of properties that the UI expects to be
- * be available via <code>IRSESystemType.getProperty(String)</code>.
+ * available via <code>IRSESystemType.getProperty(String)</code>.
  * 
  * @see org.eclipse.rse.core.IRSESystemType#getProperty(String)
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface IRSESystemTypeConstants {
 

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

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2000, 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2000, 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -11,14 +11,16 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core;
 
 /**
- * Constants for user id management. Used when specifying the scope of a user id when 
+ * Constants for user id management. Used when specifying the scope of a user id
- * setting a user id.
+ * when setting a user id.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface IRSEUserIdConstants {
 

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

@@ -17,6 +17,7 @@
  * Martin Oberhuber (Wind River) - [177523] Unify singleton getter methods
  * Martin Oberhuber (Wind River) - [186640] Add IRSESystemType.testProperty()
  * Martin Oberhuber (Wind River) - [218655][api] Provide SystemType enablement info in non-UI
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core;
@@ -37,10 +38,14 @@ import org.eclipse.rse.internal.core.RSECoreMessages;
 
 
 /**
- * PasswordPersistenceManager manages the saving and retreiving of user ID / passwords
+ * PasswordPersistenceManager manages the saving and retrieving of user ID /
- * to the Eclipse keyring for registered system types.
+ * passwords to the Eclipse keyring for registered system types.
  * 
  * @author yantzi
+ * @noextend This class is not intended to be subclassed by clients.
+ * @noinstantiate This class is not intended to be instantiated by clients. Use
+ *                the {@link #getInstance()} method to get the singleton
+ *                instance.
  */
 public class PasswordPersistenceManager {
 
@@ -145,7 +150,7 @@ public class PasswordPersistenceManager {
 	}
 
 	/**
-	 * Retrieve the singleton isntance of the PasswordPersistenceManger
+	 * Retrieve the singleton instance of the PasswordPersistenceManger
 	 */
 	public static final synchronized PasswordPersistenceManager getInstance()
 	{

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

@@ -21,6 +21,7 @@
  * Martin Oberhuber (Wind River) - [165674] Sort subsystem configurations by priority then Id
  * Martin Oberhuber (Wind River) - [215820] Move SystemRegistry implementation to Core
  * David Dykstal (IBM) - [197167] adding notification and waiting for RSE model
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 package org.eclipse.rse.core;
 
@@ -39,8 +40,8 @@ import org.eclipse.rse.core.comm.SystemKeystoreProviderManager;
 import org.eclipse.rse.core.model.ISystemProfileManager;
 import org.eclipse.rse.core.model.ISystemRegistry;
 import org.eclipse.rse.core.subsystems.ISubSystemConfigurationProxy;
-import org.eclipse.rse.internal.core.RSEInitJob;
 import org.eclipse.rse.internal.core.RSECoreRegistry;
+import org.eclipse.rse.internal.core.RSEInitJob;
 import org.eclipse.rse.internal.core.model.SystemProfileManager;
 import org.eclipse.rse.internal.core.model.SystemRegistry;
 import org.eclipse.rse.internal.core.subsystems.SubSystemConfigurationProxy;
@@ -53,14 +54,19 @@ import org.osgi.framework.Bundle;
 import org.osgi.framework.BundleContext;
 
 /**
- * RSECorePlugin provides the activation for the RSE core and acts as the primary
+ * RSECorePlugin provides the activation for the RSE core and acts as the
- * registry for logging, persistence, and the main RSE service registries.
+ * primary registry for logging, persistence, and the main RSE service
- * It should not be extended by other classes.
+ * registries.
+ * 
+ * @noextend This class is not intended to be subclassed by clients.
+ * @noinstantiate This class is not intended to be instantiated by clients.
  */
 public class RSECorePlugin extends Plugin {
 
 	/**
 	 * The plugin id for this plugin. Value "org.eclipse.rse.core".
+	 * 
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static final String PLUGIN_ID = "org.eclipse.rse.core"; //$NON-NLS-1$
 
@@ -75,29 +81,32 @@ public class RSECorePlugin extends Plugin {
 	public static final String CURRENT_RELEASE_NAME = "2.0.0";  //$NON-NLS-1$
 
 	/**
-	 * Value 0.
+	 * Initialization phase constant, value 0. Used in
-	 * Used in isInitComplete(int) which will return true if all phases of  
+	 * {@link #isInitComplete(int)} which will return true if all phases of
-	 * initialization are complete.
+	 * initialization are complete. Clients must not assume any particular
-	 * Clients must not assume any particular ordering 
+	 * ordering among phases based on the value.
-	 * among phases based on the value.
+	 * 
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static final int INIT_ALL = 0;
 
 	/**
-	 * Value 1.
+	 * Initialization phase constant, value 1. Used in
-	 * Used in isInitComplete(int) which will return true if the model phase of the 
+	 * {@link #isInitComplete(int)} which will return true if the model phase of
-	 * initialization is complete.
+	 * the initialization is complete. Clients must not assume any particular
-	 * Clients must not assume any particular ordering 
+	 * ordering among phases based on the value.
-	 * among phases based on the value.
+	 * 
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static final int INIT_MODEL = 1;
 
 	/**
-	 * Value 2.
+	 * Initialization phase constant, value 2. Used in
-	 * Used in isInitComplete(int) which will return true if the initializer phase of the 
+	 * {@link #isInitComplete(int)} which will return true if the initializer
-	 * initialization is complete.
+	 * phase of the initialization is complete. Clients must not assume any
-	 * Clients must not assume any particular ordering 
+	 * particular ordering among phases based on the value.
-	 * among phases based on the value.
+	 * 
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static final int INIT_INITIALIZER = 2;
 
@@ -116,10 +125,13 @@ public class RSECorePlugin extends Plugin {
 	}
 
 	/**
-	 * Waits until the RSE model has been fully restored from its persistent form. Should be used 
+	 * Waits until the RSE model has been fully restored from its persistent
-	 * before accessing pieces of the model.
+	 * form. Should be used before accessing pieces of the model.
+	 * 
 	 * @return an IStatus indicating how the initialization ended.
-	 * @throws InterruptedException if this wait was interrupted for some reason.
+	 * @throws InterruptedException if this wait was interrupted for some
+	 *             reason.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static IStatus waitForInitCompletion() throws InterruptedException {
 		return RSEInitJob.getInstance().waitForCompletion();
@@ -127,46 +139,56 @@ public class RSECorePlugin extends Plugin {
 
 	/**
 	 * Waits until the RSE has completed a specific phase of its initialization.
+	 * 
 	 * @param phase the phase to wait for completion.
-	 * @throws InterruptedException if this wait was interrupted for some reason.
+	 * @throws InterruptedException if this wait was interrupted for some
+	 *             reason.
 	 * @throws IllegalArgumentException if the phase is undefined.
 	 * @see #INIT_ALL
 	 * @see #INIT_INITIALIZER
 	 * @see #INIT_MODEL
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static void waitForInitCompletion(int phase) throws InterruptedException {
 		RSEInitJob.getInstance().waitForCompletion(phase);
 	}
 
 	/**
+	 * Check whether the initialization of the RSE model is complete for a given
+	 * phase.
+	 * 
 	 * @param phase the phase identifier.
-	 * @return true if initialization of the RSE model is complete for that phase.
+	 * @return <code>true</code> if the initialization for the given phase has
-	 * It will return true if the 
+	 *         completed regardless of its status of that completion.
-	 * initialization for that phase has completed regardless its status of that completion.
 	 * @throws IllegalArgumentException if the phase is undefined.
 	 * @see #INIT_ALL
 	 * @see #INIT_INITIALIZER
 	 * @see #INIT_MODEL
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static boolean isInitComplete(int phase) {
 		return RSEInitJob.getInstance().isComplete(phase);
 	}
 
 	/**
-	 * Adds a new listener to the set of listeners to be notified when initialization phases complete.
+	 * Adds a new listener to the set of listeners to be notified when
-	 * If the listener is added after the phase has completed it will not be invoked.
+	 * initialization phases complete. If the listener is added after the phase
-	 * If the listener is already in the set it will not be added again.
+	 * has completed it will not be invoked. If the listener is already in the
-	 * Listeners may be notified in any order.
+	 * set it will not be added again. Listeners may be notified in any order.
+	 * 
 	 * @param listener the listener to be added
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static void addInitListener(IRSEInitListener listener) {
 		RSEInitJob.getInstance().addInitListener(listener);
 	}
 
 	/**
-	 * Removes a listener to the set of listeners to be notified when phases complete.
+	 * Removes a listener to the set of listeners to be notified when phases
-	 * If the listener is not in the set this does nothing.
+	 * complete. If the listener is not in the set this does nothing.
+	 * 
 	 * @param listener the listener to be removed
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static void removeInitListener(IRSEInitListener listener) {
 		RSEInitJob.getInstance().removeInitListener(listener);
@@ -192,17 +214,22 @@ public class RSECorePlugin extends Plugin {
 
 	/**
 	 * Return the master profile manager singleton.
+	 * 
 	 * @return the RSE Profile Manager Singleton.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static ISystemProfileManager getTheSystemProfileManager() {
 		return SystemProfileManager.getDefault();
 	}
 
 	/**
-     * Check if the SystemRegistry has been instantiated already.
+	 * Check if the SystemRegistry has been instantiated already. Use this when
-     * Use this when you don't want to start the system registry as a
+	 * you don't want to start the system registry as a side effect of
-     * side effect of retrieving it.
+	 * retrieving it.
-     * @return <code>true</code> if the System Registry has been instantiated already.
+	 * 
+	 * @return <code>true</code> if the System Registry has been instantiated
+	 *         already.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static boolean isTheSystemRegistryActive()
 	{

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

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2007 IBM Corporation and others. All rights reserved.
+ * Copyright (c) 2007, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -9,6 +9,7 @@
  * Martin Oberhuber (Wind River) - [184095] Replace systemTypeName by IRSESystemType
  * Martin Oberhuber (Wind River) - [177523] Unify singleton getter methods
  * David Dykstal (IBM) - [197167] adding notification and waiting for RSE model
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 package org.eclipse.rse.core;
 
@@ -21,6 +22,12 @@ import java.util.TreeSet;
 
 import org.eclipse.core.runtime.Preferences;
 
+/**
+ * Preferences Manager utility class.
+ * 
+ * @noextend This class is not intended to be subclassed by clients.
+ * @noinstantiate This class is not intended to be instantiated by clients.
+ */
 public class RSEPreferencesManager {
 
 	/**
@@ -390,9 +397,10 @@ public class RSEPreferencesManager {
 	}
 
 	/**
-	 * Make a single string out of an array of strings. A semi-colon is
+	 * Make a single string out of an array of strings. A semicolon is used as a
-	 * used as a delimiter between the separate values. No value in the
+	 * delimiter between the separate values. No value in the array can contain
-	 * array can contain a semi-colon.
+	 * a semicolon.
+	 * 
 	 * @param values the array of strings to condense into a single one
 	 * @return the condensed string
 	 */
@@ -422,10 +430,11 @@ public class RSEPreferencesManager {
 	}
 
 	/**
-	 * Parse out list of key-value pairs into a hashtable. This is the inverse of the
+	 * Parse out list of key-value pairs into a Hashtable. This is the inverse
-	 * {@link SystemPreferencesManager#makeString(Hashtable)} operation.
+	 * of the {@link SystemPreferencesManager#makeString(Hashtable)} operation.
-	 * @param allValues the string containing the key-value pairs. If empty or null returns
+	 * 
-	 * and empty Hashtable.
+	 * @param allValues the string containing the key-value pairs. If empty or
+	 *            null returns and empty Hashtable.
 	 * @return the reconstituted Hashtable
 	 */
 	private static Hashtable parseString(String allValues) {
@@ -449,7 +458,12 @@ public class RSEPreferencesManager {
 	}
 
 	/**
-	 * @return the boolean value indicating whether or not to create a local connection on a fresh workspace.
+	 * Get the Preference setting whether the local connection should be created
+	 * by default or not.
+	 * 
+	 * @return the boolean value indicating whether or not to create a local
+	 *         connection on a fresh workspace.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static boolean getCreateLocalConnection() {
 		Preferences prefs = RSECorePlugin.getDefault().getPluginPreferences();

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/events/ISystemModelChangeEvents.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2007 IBM Corporation and others. All rights reserved.
+ * Copyright (c) 2002, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -13,6 +13,7 @@
  * Contributors:
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
  * David Dykstal (IBM) - [186589] Move User Actions events to the user actions plugin
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.events;
@@ -27,7 +28,9 @@ package org.eclipse.rse.core.events;
  * <p>
  * If you are interesting in firing model change events, see
  * {@link org.eclipse.rse.core.model.ISystemRegistry#fireModelChangeEvent(int, int, Object, String)}.
- * These events will typically be signalled in an implementation of ISystemRegistry. 
+ * These events will typically be signaled in an implementation of ISystemRegistry.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface ISystemModelChangeEvents {
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/events/ISystemPreferenceChangeEvents.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2007 IBM Corporation and others. All rights reserved.
+ * Copyright (c) 2002, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -12,12 +12,15 @@
  * 
  * Contributors:
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.events;
 
 /**
  * Interface of event ID constants for preferences changed
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface ISystemPreferenceChangeEvents {
 	/**

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/events/ISystemRemoteChangeEvents.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2007 IBM Corporation and others. All rights reserved.
+ * Copyright (c) 2002, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -13,14 +13,16 @@
  * Contributors:
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
  * David McKnight (IBM) - [207100] Events for after a resource is downloaded and uploaded
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.events;
 
 /**
- * The event IDs sent when remote resources in the model change
+ * The event IDs sent when remote resources in the model change These IDs are
- * These IDs are used when creating ISystemRemoteChangeEvent objects.  
+ * used when creating ISystemRemoteChangeEvent objects.
  * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface ISystemRemoteChangeEvents
 {
@@ -98,11 +100,19 @@ public interface ISystemRemoteChangeEvents
 	 * 
 	 * The event stores the following event parameters:
 	 * <ul>
-	 *  <li>resource - the remote resource object, or absolute name of the resource as would be given by calling getAbsoluteName on its remote adapter
+	 * <li>resource - the remote resource object, or absolute name of the
-	 *  <li>resourceParent - the remote resource's parent object, or absolute name, if that is known. If it is non-null, this will aid in refreshing occurrences of that parent.
+	 * resource as would be given by calling getAbsoluteName on its remote
-	 *  <li>subsystem - the subsystem which contains this remote resource. This allows the search for impacts to be 
+	 * adapter
-	 *   limited to subsystems of the same parent factory, and to connections with the same hostname as the subsystem's connection.
+	 * <li>resourceParent - the remote resource's parent object, or absolute
+	 * name, if that is known. If it is non-null, this will aid in refreshing
+	 * occurrences of that parent.
+	 * <li>subsystem - the subsystem which contains this remote resource. This
+	 * allows the search for impacts to be limited to subsystems of the same
+	 * parent factory, and to connections with the same hostname as the
+	 * subsystem's connection.
 	 * </ul>
+	 * 
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static final int SYSTEM_REMOTE_RESOURCE_UPLOADED = 20;
 
@@ -111,11 +121,19 @@ public interface ISystemRemoteChangeEvents
 	 * 
 	 * The event stores the following event parameters:
 	 * <ul>
-	 *  <li>resource - the remote resource object, or absolute name of the resource as would be given by calling getAbsoluteName on its remote adapter
+	 * <li>resource - the remote resource object, or absolute name of the
-	 *  <li>resourceParent - the remote resource's parent object, or absolute name, if that is known. If it is non-null, this will aid in refreshing occurrences of that parent.
+	 * resource as would be given by calling getAbsoluteName on its remote
-	 *  <li>subsystem - the subsystem which contains this remote resource. This allows the search for impacts to be 
+	 * adapter
-	 *   limited to subsystems of the same parent factory, and to connections with the same hostname as the subsystem's connection.
+	 * <li>resourceParent - the remote resource's parent object, or absolute
+	 * name, if that is known. If it is non-null, this will aid in refreshing
+	 * occurrences of that parent.
+	 * <li>subsystem - the subsystem which contains this remote resource. This
+	 * allows the search for impacts to be limited to subsystems of the same
+	 * parent factory, and to connections with the same hostname as the
+	 * subsystem's connection.
 	 * </ul>
+	 * 
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public static final int SYSTEM_REMOTE_RESOURCE_DOWNLOADED = 24;
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/events/ISystemResourceChangeEvents.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2007 IBM Corporation and others. All rights reserved.
+ * Copyright (c) 2002, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -12,6 +12,7 @@
  * 
  * Contributors:
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.events;
@@ -20,6 +21,8 @@ import org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier;
 
 /**
  * Interface of event ID constants
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface ISystemResourceChangeEvents
 {

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilter.java

@@ -13,6 +13,7 @@
  * 
  * Contributors:
  * David Dykstal (IBM) - cleanup format and javadoc
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 
 package org.eclipse.rse.core.filters;
@@ -443,14 +444,17 @@ public interface ISystemFilter extends IRSEReferencedObject, ISystemFilterContai
 	public boolean isSetSingleFilterStringOnly();
 
 	/**
-	 * Returns the value of the '<em><b>Nested Filters</b></em>' containment reference list.
+	 * Returns the value of the '<em><b>Nested Filters</b></em>'
-	 * The list contents are of type {@link org.eclipse.rse.core.filters.ISystemFilter}.
+	 * containment reference list. It is bidirectional and its opposite is '{@link org.eclipse.rse.core.filters.ISystemFilter#getParentFilter <em>Parent Filter</em>}'.
-	 * It is bidirectional and its opposite is '{@link org.eclipse.rse.core.filters.ISystemFilter#getParentFilter <em>Parent Filter</em>}'.
 	 * <p>
-	 * If this filter can contain child filters this will return the list of children.
+	 * If this filter can contain child filters this will return the list of
+	 * children.
 	 * </p>
-	 * @return the value of the '<em>Nested Filters</em>' containment reference list.
+	 * 
+	 * @return the value of the '<em>Nested Filters</em>' containment
+	 *         reference list.
 	 * @see org.eclipse.rse.core.filters.ISystemFilter#getParentFilter
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilter[] getNestedFilters();
 
@@ -476,9 +480,12 @@ public interface ISystemFilter extends IRSEReferencedObject, ISystemFilterContai
 	public void setParentFilter(ISystemFilter value);
 
 	/**
-	 * Returns the value of the '<em><b>Strings</b></em>' containment reference list.
+	 * Returns the value of the '<em><b>Strings</b></em>' containment
-	 * The list contents are of type {@link org.eclipse.rse.core.filters.ISystemFilterString}.
+	 * reference list.
-	 * @return the value of the '<em>Strings</em>' containment reference list.
+	 * 
+	 * @return the value of the '<em>Strings</em>' containment reference
+	 *         list.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilterString[] getStrings();
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilterContainer.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2002, 2007 IBM Corporation and others.
+ * Copyright (c) 2002, 2008 IBM Corporation and others.
  * 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 available at
@@ -12,7 +12,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 package org.eclipse.rse.core.filters;
 
@@ -29,18 +29,23 @@ public interface ISystemFilterContainer extends IRSEPersistableContainer {
 	public ISystemFilterPoolManager getSystemFilterPoolManager();
 
 	/**
-	 * @return The value of the StringsCaseSensitive attribute
+	 * @return The value of the StringsCaseSensitive attribute Are filters in
-	 * Are filters in this filter container case sensitive?
+	 *         this filter container case sensitive? If not set locally, queries
-	 * If not set locally, queries the parent filter pool manager's atttribute.
+	 *         the parent filter pool manager's attribute.
 	 */
 	public boolean areStringsCaseSensitive();
 
 	/**
-	 * Adds a new system filter to this container (SystemFilterPool or SystemFilter) and
+	 * Adds a new system filter to this container (SystemFilterPool or
-	 * populates it with the filter strings created from the strings provided.
+	 * SystemFilter) and populates it with the filter strings created from the
-	 * Does nothing if this filter already exists in this container.
+	 * strings provided. Does nothing if this filter already exists in this
-	 * @param aliasName The name to give the new filter. Must be unique for this pool.
+	 * container.
-	 * @param filterStrings The list of String objects that represent the filter strings.
+	 * 
+	 * @param aliasName The name to give the new filter. Must be unique for this
+	 *            pool.
+	 * @param filterStrings The list of String objects that represent the filter
+	 *            strings.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilter createSystemFilter(String aliasName, String[] filterStrings);
 
@@ -52,8 +57,11 @@ public interface ISystemFilterContainer extends IRSEPersistableContainer {
 	public boolean addSystemFilter(ISystemFilter filter);
 
 	/**
-	 * @return Vector of String objects: the names of existing filters in this container.
+	 * Get the names of existing filters in this container. Typically used by
-	 * Typically used by name validators for New and Rename actions to verify new name is unique.
+	 * name validators for New and Rename actions to verify new name is unique.
+	 * 
+	 * @return String array of the names of existing filters in this container.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public String[] getSystemFilterNames();
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilterPool.java

@@ -13,6 +13,7 @@
  * 
  * Contributors:
  * David Dykstal (IBM) - cleanup - format and javadoc
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 
 package org.eclipse.rse.core.filters;
@@ -187,7 +188,10 @@ public interface ISystemFilterPool extends IRSEPersistableReferencedObject, ISys
 	public boolean isSetStringsCaseSensitive();
 
 	/**
+	 * Return the filters in this pool.
+	 * 
 	 * @return An array of filters in this pool
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilter[] getFilters();
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilterPoolManager.java

@@ -15,6 +15,7 @@
  * David Dykstal (IBM) - [197036] All filter pools created on clean workspace
  * cleaned javadoc for renameSystemFilterPool
  * David Dykstal (IBM) - [222270] clean up interfaces in org.eclipse.rse.core.filters
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 
 package org.eclipse.rse.core.filters;
@@ -30,6 +31,8 @@ import org.eclipse.rse.core.model.ISystemProfile;
  * Further, this is the front door for working with filters too. By forcing all
  * filter related activity through a single point like this, we can ensure that
  * all changes are saved to disk, and events are fired properly.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface ISystemFilterPoolManager extends IRSEPersistableContainer {
 	// ---------------------------------
@@ -252,88 +255,120 @@ public interface ISystemFilterPoolManager extends IRSEPersistableContainer {
 	// FILTER METHODS
 	// ---------------------------------
 	/**
-	 * Creates a new system filter within the given filter container (either a filter pool, or
+	 * Creates a new system filter within the given filter container (either a
-	 * a filter). This creates the filter, and then saves the filter pool. 
+	 * filter pool, or a filter). This creates the filter, and then saves the
-	 * <p>Calls back to provider to inform of the event (filterEventFilterCreated)
+	 * filter pool.
-	 * @param parent The parent which is either a SystemFilterPool or a SystemFilter
+	 * <p>
-	 * @param aliasName The name to give the new filter. Must be unique for this pool.
+	 * Calls back to provider to inform of the event (filterEventFilterCreated)
-	 * @param filterStrings The list of String objects that represent the filter strings.
+	 * 
+	 * @param parent The parent which is either a SystemFilterPool or a
+	 *            SystemFilter
+	 * @param aliasName The name to give the new filter. Must be unique for this
+	 *            pool.
+	 * @param filterStrings The list of String objects that represent the filter
+	 *            strings.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilter createSystemFilter(ISystemFilterContainer parent, String aliasName, String[] filterStrings) throws Exception;
 
 	/**
-	 * Creates a new system filter within the given filter container (either a filter pool, or
+	 * Creates a new system filter within the given filter container (either a
-	 * a filter). This creates the filter, and then saves the filter pool. 
+	 * filter pool, or a filter). This creates the filter, and then saves the
-	 * <p>Calls back to provider to inform of the event (filterEventFilterCreated)
+	 * filter pool.
-	 * @param parent The parent which is either a SystemFilterPool or a SystemFilter
+	 * <p>
-	 * @param aliasName The name to give the new filter. Must be unique for this pool.
+	 * Calls back to provider to inform of the event (filterEventFilterCreated)
-	 * @param filterStrings The list of String objects that represent the filter strings.
+	 * 
+	 * @param parent The parent which is either a SystemFilterPool or a
+	 *            SystemFilter
+	 * @param aliasName The name to give the new filter. Must be unique for this
+	 *            pool.
+	 * @param filterStrings The list of String objects that represent the filter
+	 *            strings.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilter createSystemFilter(ISystemFilterContainer parent, String aliasName, List filterStrings) throws Exception;
 
 	/**
-	 * Creates a new system filter that is typed.
+	 * Creates a new system filter that is typed. Same as
-	 * Same as {@link #createSystemFilter(ISystemFilterContainer, String, String[])} but 
+	 * {@link #createSystemFilter(ISystemFilterContainer, String, String[])} but
 	 * takes a filter type as an additional parameter.
 	 * <p>
-	 * A filter's type is an arbitrary string that is not interpreted or used by the base framework. This
+	 * A filter's type is an arbitrary string that is not interpreted or used by
-	 * is for use entirely by tools who wish to support multiple types of filters and be able to launch unique
+	 * the base framework. This is for use entirely by tools who wish to support
-	 * actions per type, say.
+	 * multiple types of filters and be able to launch unique actions per type,
+	 * say.
 	 * 
-	 * @param parent The parent which is either a SystemFilterPool or a SystemFilter
+	 * @param parent The parent which is either a SystemFilterPool or a
-	 * @param aliasName The name to give the new filter. Must be unique for this pool.
+	 *            SystemFilter
-	 * @param filterStrings The list of String objects that represent the filter strings.
+	 * @param aliasName The name to give the new filter. Must be unique for this
+	 *            pool.
+	 * @param filterStrings The list of String objects that represent the filter
+	 *            strings.
 	 * @param type The type of this filter
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilter createSystemFilter(ISystemFilterContainer parent, String aliasName, String[] filterStrings, String type) throws Exception;
 
 	/**
-	 * Creates a new system filter that is typed.
+	 * Creates a new system filter that is typed. Same as
-	 * Same as {@link #createSystemFilter(ISystemFilterContainer, String, String[])} but 
+	 * {@link #createSystemFilter(ISystemFilterContainer, String, String[])} but
 	 * takes a filter type as an additional parameter.
 	 * <p>
-	 * A filter's type is an arbitrary string that is not interpreted or used by the base framework. This
+	 * A filter's type is an arbitrary string that is not interpreted or used by
-	 * is for use entirely by tools who wish to support multiple types of filters and be able to launch unique
+	 * the base framework. This is for use entirely by tools who wish to support
-	 * actions per type, say.
+	 * multiple types of filters and be able to launch unique actions per type,
+	 * say.
 	 * 
-	 * @param parent The parent which is either a SystemFilterPool or a SystemFilter
+	 * @param parent The parent which is either a SystemFilterPool or a
-	 * @param aliasName The name to give the new filter. Must be unique for this pool.
+	 *            SystemFilter
-	 * @param filterStrings The list of String objects that represent the filter strings.
+	 * @param aliasName The name to give the new filter. Must be unique for this
+	 *            pool.
+	 * @param filterStrings The list of String objects that represent the filter
+	 *            strings.
 	 * @param type The type of this filter
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilter createSystemFilter(ISystemFilterContainer parent, String aliasName, List filterStrings, String type) throws Exception;
 
 	/**
-	 * Creates a new system filter that is typed and promptable
+	 * Creates a new system filter that is typed and promptable Same as
-	 * Same as {@link #createSystemFilter(ISystemFilterContainer, String ,String[], String)} but 
+	 * {@link #createSystemFilter(ISystemFilterContainer, String ,String[], String)}
-	 *  takes a boolean indicating if it is promptable.
+	 * but takes a boolean indicating if it is promptable.
 	 * <p>
-	 * A promptable filter is one in which the user is prompted for information at expand time.
+	 * A promptable filter is one in which the user is prompted for information
-	 * There is no base filter framework support for this, but tools can query this attribute and
+	 * at expand time. There is no base filter framework support for this, but
-	 * do their own thing at expand time.
+	 * tools can query this attribute and do their own thing at expand time.
 	 * 
-	 * @param parent The parent which is either a SystemFilterPool or a SystemFilter
+	 * @param parent The parent which is either a SystemFilterPool or a
-	 * @param aliasName The name to give the new filter. Must be unique for this pool.
+	 *            SystemFilter
-	 * @param filterStrings The list of String objects that represent the filter strings.
+	 * @param aliasName The name to give the new filter. Must be unique for this
+	 *            pool.
+	 * @param filterStrings The list of String objects that represent the filter
+	 *            strings.
 	 * @param type The type of this filter
 	 * @param promptable Pass true if this is a promptable filter
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilter createSystemFilter(ISystemFilterContainer parent, String aliasName, String[] filterStrings, String type, boolean promptable) throws Exception;
 
 	/**
-	 * Creates a new system filter that is typed and promptable
+	 * Creates a new system filter that is typed and promptable Same as
-	 * Same as {@link #createSystemFilter(ISystemFilterContainer, String ,String[], String)} but 
+	 * {@link #createSystemFilter(ISystemFilterContainer, String ,String[], String)}
-	 *  takes a boolean indicating if it is promptable.
+	 * but takes a boolean indicating if it is promptable.
 	 * <p>
-	 * A promptable filter is one in which the user is prompted for information at expand time.
+	 * A promptable filter is one in which the user is prompted for information
-	 * There is no base filter framework support for this, but tools can query this attribute and
+	 * at expand time. There is no base filter framework support for this, but
-	 * do their own thing at expand time.
+	 * tools can query this attribute and do their own thing at expand time.
 	 * 
-	 * @param parent The parent which is either a SystemFilterPool or a SystemFilter
+	 * @param parent The parent which is either a SystemFilterPool or a
-	 * @param aliasName The name to give the new filter. Must be unique for this pool.
+	 *            SystemFilter
-	 * @param filterStrings The list of String objects that represent the filter strings.
+	 * @param aliasName The name to give the new filter. Must be unique for this
+	 *            pool.
+	 * @param filterStrings The list of String objects that represent the filter
+	 *            strings.
 	 * @param type The type of this filter
 	 * @param promptable Pass true if this is a promptable filter
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilter createSystemFilter(ISystemFilterContainer parent, String aliasName, List filterStrings, String type, boolean promptable) throws Exception;
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilterPoolReferenceManager.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2002, 2007 IBM Corporation and others.
+ * Copyright (c) 2002, 2008 IBM Corporation and others.
  * 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 available at
@@ -26,9 +26,6 @@ import org.eclipse.rse.core.subsystems.ISubSystem;
  * offering convenience versions of the parent methods that are typed to the
  * classes in the filters framework.
  */
-/**
- * @lastgen interface SystemFilterPoolReferenceManager extends SystemPersistableReferenceManager {}
- */
 public interface ISystemFilterPoolReferenceManager extends IRSEBasePersistableReferenceManager {
 	/**
 	 * Get the object which instantiated this instance of the filter pool reference manager.

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilterStartHere.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2005, 2007 IBM Corporation and others.
+ * Copyright (c) 2005, 2008 IBM Corporation and others.
  * 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 available at
@@ -7,6 +7,7 @@
  *
  * Contributors:
  *     IBM Corporation - initial API and implementation
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 package org.eclipse.rse.core.filters;
 
@@ -33,17 +34,21 @@ public interface ISystemFilterStartHere {
 	public ISystemFilterPoolManager createSystemFilterPoolManager(ISystemProfile profile, Logger logger, ISystemFilterPoolManagerProvider caller, String name, boolean allowNestedFilters);
 
 	/**
-	 * Create a SystemFilterPoolReferenceManager instance, when you  do NOT want it 
+	 * Create a SystemFilterPoolReferenceManager instance, when you do NOT want
-	 *  to be saved and restored to its own file. Rather, you will save and restore it
+	 * it to be saved and restored to its own file. Rather, you will save and
-	 *  yourself.
+	 * restore it yourself.
+	 * 
 	 * @param caller Objects which instantiate this class should implement the
-	 *   SystemFilterPoolReferenceManagerProvider interface, and pass "this" for this parameter.
+	 *            SystemFilterPoolReferenceManagerProvider interface, and pass
-	 *   Given any filter framework object, it is possible to retrieve the caller's
+	 *            "this" for this parameter. Given any filter framework object,
-	 *   object via the getProvider method call.
+	 *            it is possible to retrieve the caller's object via the
-	 * @param relatedPoolMgrProvider The creator of the managers that own the master list of filter pools that 
+	 *            getProvider method call.
-	 *   this manager will contain references to.
+	 * @param relatedPoolMgrProvider The creator of the managers that own the
-	 * @param name the name of the filter pool reference manager. This is not currently 
+	 *            master list of filter pools that this manager will contain
-	 *   used, but you may find a use for it. 
+	 *            references to.
+	 * @param name the name of the filter pool reference manager. This is not
+	 *            currently used, but you may find a use for it.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilterPoolReferenceManager createSystemFilterPoolReferenceManager(ISystemFilterPoolReferenceManagerProvider caller, ISystemFilterPoolManagerProvider relatedPoolMgrProvider,
 			String name);

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

@@ -14,6 +14,7 @@
  * Contributors:
  * David Dykstal (IBM) - [197036] added commitSystemProfile operation to interface
  * David Dykstal (IBM) - [202630] getDefaultPrivateProfile() and ensureDefaultPrivateProfile() are inconsistent
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 
 package org.eclipse.rse.core.model;
@@ -21,10 +22,12 @@ package org.eclipse.rse.core.model;
 import org.eclipse.core.runtime.IStatus;
 
 /**
- * Manages a list of SystemProfile objects. System profiles
+ * Manages a list of SystemProfile objects. System profiles should be created,
- * should be created, deleted, restored, activated, and deactivated though
+ * deleted, restored, activated, and deactivated though this interface if event
- * this interface if event processing is not desired. If events are necessary
+ * processing is not desired. If events are necessary then the system registry
- * then the system registry should be used.
+ * should be used.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface ISystemProfileManager {
 
@@ -116,8 +119,10 @@ public interface ISystemProfileManager {
 
 	/**
 	 * Commit a system profile
+	 * 
 	 * @param profile the profile to commit
 	 * @return a status object indicating the result of the commit
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public IStatus commitSystemProfile(ISystemProfile profile);
 

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

@@ -25,6 +25,7 @@
  * David Dykstal (IBM) - [217556] remove service subsystem types
  * Martin Oberhuber (Wind River) - [215820] Move SystemRegistry implementation to Core
  * David Dykstal (IBM) - [202630] getDefaultPrivateProfile() and ensureDefaultPrivateProfile() are inconsistent
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.model;
@@ -102,24 +103,34 @@ public interface ISystemRegistry extends ISchedulingRule, IAdaptable, ISystemVie
 
 	/**
 	 * Return all subsystem configurations which support the given system type.
-	 * If the type is null, returns all subsystem confgurations.
+	 * If the type is null, returns all subsystem configurations. Fully
-	 * Fully equivalent to getSubSystemConfigurationsBySystemType(systemType, filterDuplicates, <code>true</code>)
+	 * equivalent to getSubSystemConfigurationsBySystemType(systemType,
-	 * which is preferred since we do not want to load subsystem configurations unless necessary.
+	 * filterDuplicates, <code>true</code>) which is preferred since we do
+	 * not want to load subsystem configurations unless necessary.
+	 * 
 	 * @param systemType system type to filter
-	 * @param filterDuplicates if true and the subsystem configuration uses services then return only one
+	 * @param filterDuplicates if true and the subsystem configuration uses
-	 * subsystem configuration that supports this service. Which configuration is returned is undefined.
+	 *            services then return only one subsystem configuration that
+	 *            supports this service. Which configuration is returned is
+	 *            undefined.
 	 * @return an array of subsystem configurations meeting the criteria
 	 */
 	public ISubSystemConfiguration[] getSubSystemConfigurationsBySystemType(IRSESystemType systemType, boolean filterDuplicates);
 
 	/**
 	 * Return all subsystem configurations which support the given system type.
-	 * If the type is null, returns all subsystem confgurations.
+	 * If the type is null, returns all subsystem configurations.
+	 * 
 	 * @param systemType system type to filter
-	 * @param filterDuplicates if true and the subsystem configuration uses services then return only one
+	 * @param filterDuplicates if true and the subsystem configuration uses
-	 * subsystem configuration that supports this service. Which configuration is returned is undefined.
+	 *            services then return only one subsystem configuration that
-	 * @param activate if true activate the respective configurations if not already active, if false return only those that are already active.
+	 *            supports this service. Which configuration is returned is
+	 *            undefined.
+	 * @param activate if true activate the respective configurations if not
+	 *            already active, if false return only those that are already
+	 *            active.
 	 * @return an array of subsystem configurations meeting the criteria
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISubSystemConfiguration[] getSubSystemConfigurationsBySystemType(IRSESystemType systemType, boolean filterDuplicates, boolean activate);
 
@@ -496,22 +507,28 @@ public interface ISystemRegistry extends ISchedulingRule, IAdaptable, ISystemVie
 	public IHost createHost(IRSESystemType systemType, String connectionName, String hostAddress, String description) throws Exception;
 
 	/**
-	 * Create a host object. The resulting host object is added to the list of existing host objects
+	 * Create a host object. The resulting host object is added to the list of
-	 * in the specified profile.
+	 * existing host objects in the specified profile.
 	 * <ul>
 	 * <li>creates and saves a new host within the given profile
 	 * <li>optionally creates subsystem instances
-	 * <li>fires an ISystemResourceChangeEvent event of type EVENT_ADD to all registered listeners
+	 * <li>fires an ISystemResourceChangeEvent event of type EVENT_ADD to all
+	 * registered listeners
 	 * </ul>
 	 * <p>
-	 * @param profileName Name of the system profile to which the host is to be added.
+	 * 
+	 * @param profileName Name of the system profile to which the host is to be
+	 *            added.
 	 * @param systemType system type of the new host.
 	 * @param hostName unique host name within the profile.
 	 * @param hostAddress ip name of host.
 	 * @param description optional description of the connection. May be null.
-	 * @param createSubSystems <code>true</code> to create subsystems for the host, <code>false</code> otherwise.
+	 * @param createSubSystems <code>true</code> to create subsystems for the
-	 * @return IHost object, or null if it failed to create. This is typically because the hostName is not unique. Call getLastException() if necessary.
+	 *            host, <code>false</code> otherwise.
-	 * @since 3.0
+	 * @return IHost object, or null if it failed to create. This is typically
+	 *         because the hostName is not unique. Call getLastException() if
+	 *         necessary.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public IHost createHost(String profileName, IRSESystemType systemType, String hostName, String hostAddress, String description, boolean createSubSystems) throws Exception;
 
@@ -735,13 +752,17 @@ public interface ISystemRegistry extends ISchedulingRule, IAdaptable, ISystemVie
 	public void addSystemRemoteChangeListener(ISystemRemoteChangeListener l);
 
 	/**
-	 * De-Register your interest in being told when a remote resource is changed.
+	 * Unregister your interest in being told when a remote resource is changed.
 	 */
 	public void removeSystemRemoteChangeListener(ISystemRemoteChangeListener l);
 
 
 	/**
-	 * Query if the ISystemRemoteChangeListener is already listening for SystemRemoteChange events
+	 * Query if the ISystemRemoteChangeListener is already listening for
+	 * SystemRemoteChange events.
+	 * 
+	 * @param l the listener instance to check
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public boolean isRegisteredSystemRemoteChangeListener(ISystemRemoteChangeListener l);
 
@@ -792,7 +813,7 @@ public interface ISystemRegistry extends ISchedulingRule, IAdaptable, ISystemVie
 	public void addSystemPreferenceChangeListener(ISystemPreferenceChangeListener l);
 
 	/**
-	 * De-Register your interest in being told when a system preference changes
+	 * Unregister your interest in being told when a system preference changes
 	 */
 	public void removeSystemPreferenceChangeListener(ISystemPreferenceChangeListener l);
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/IConnectorService.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2007 IBM Corporation and others. All rights reserved.
+ * Copyright (c) 2002, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -15,6 +15,7 @@
  * Martin Oberhuber (Wind River) - [175262] IHost.getSystemType() should return IRSESystemType
  * Martin Oberhuber (Wind River) - [185750] Remove IConnectorService.getHostType()
  * Martin Oberhuber (Wind River) - [187218] Fix error reporting for connect()
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
@@ -25,23 +26,27 @@ import org.eclipse.rse.core.model.IRSEModelObject;
 import org.eclipse.rse.services.clientserver.messages.SystemMessageException;
 
 /**
- * A connector service provides the means of establishing a connection from 
+ * A connector service provides the means of establishing a connection from a
- * a subsystem (or a number of subsystems) to a target system (a host).
+ * subsystem (or a number of subsystems) to a target system (a host).
  * <p>
  * A connector service manages a live connection to a remote system, with
  * operations for connecting and disconnecting, and storing information
  * typically cached from a subsystem: credentials (such as a userId/password),
  * port, etc.
  * <p>
- * The SubSystem interface includes a method, getConnectorService(),
+ * The SubSystem interface includes a method, getConnectorService(), which
- * which returns an instance of an object that implements this interface
+ * returns an instance of an object that implements this interface for that
- * for that subsystem.
+ * subsystem.
  * <p>
  * A single connector service object can be unique to a subsystem instance, but
  * it can also be shared across multiple subsystems in a single host if those
- * subsystems share a physical connection to the remote system.
+ * subsystems share a physical connection to the remote system. This sharing is
- * This sharing is done using implementers of {@link IConnectorServiceManager} 
+ * done using implementers of {@link IConnectorServiceManager} which are
- * which are returned by another getter method in SubSystem.
+ * returned by another getter method in SubSystem.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
+ *              Clients should subclass {@link AbstractConnectorService}
+ *              instead.
  */
 public interface IConnectorService extends IRSEModelObject {
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/IConnectorServiceManager.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2007 IBM Corporation and others.
+ * Copyright (c) 2006, 2008 IBM Corporation and others.
  * 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 available at
@@ -12,13 +12,20 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
 
 import org.eclipse.rse.core.model.IHost;
 
+/**
+ * Connector Service Manager Interface.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
+ *              Clients should subclass {@link AbstractConnectorServiceManager}
+ *              instead.
+ */
 public interface IConnectorServiceManager {
 	IConnectorService getConnectorService(IHost host, Class commonSSinterface);
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/IDelegatingConnectorService.java

@@ -14,8 +14,8 @@
 package org.eclipse.rse.core.subsystems;
 
 /**
- * A delegating connector service forwards all requests for infomation
+ * A delegating connector service forwards all requests for information to
- * to another connector service. 
+ * another connector service.
  */
 public interface IDelegatingConnectorService extends IConnectorService
 {

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/IFileConstants.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2007 IBM Corporation and others.
+ * Copyright (c) 2000, 2008 IBM Corporation and others.
  * 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 available at
@@ -12,13 +12,15 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
 
 /**
- * Constants used in the remote file system support
+ * Constants used in the remote file system support.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface IFileConstants {
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/IRemoteObjectResolver.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2007 IBM Corporation and others. All rights reserved.
+ * Copyright (c) 2002, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -13,6 +13,7 @@
  * Contributors:
  * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  * David McKnight   (IBM) - [211472] [api][breaking] IRemoteObjectResolver.getObjectWithAbsoluteName() needs a progress monitor
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
@@ -32,65 +33,73 @@ public interface IRemoteObjectResolver {
 	 * Return the remote object that corresponds to the specified unique ID.
 	 * <p>
 	 * This must be implemented by subsystems in order to find remote objects
-	 * for drag and drop, clipboard, and other object retrieval mechanisms
+	 * for drag and drop, clipboard, and other object retrieval mechanisms in
-	 * in support of remote objects. It is the functional opposite of 
+	 * support of remote objects. It is the functional opposite of
 	 * {@link IRemoteObjectIdentifier#getAbsoluteName(Object)}.
-	 * </p><p>
+	 * </p>
+	 * <p>
 	 * Because each subsystem maintains it's own objects, it is the
-	 * responsibility of the subsystem to determine how an ID (or key)
+	 * responsibility of the subsystem to determine how an ID (or key) for a
-	 * for a given object maps to the real object. Subsystems also need
+	 * given object maps to the real object. Subsystems also need to ensure that
-	 * to ensure that objects of different type (such as filters, actual
+	 * objects of different type (such as filters, actual resources or error
-	 * resources or error messages) all have different IDs. See
+	 * messages) all have different IDs. See
-	 * {@link IRemoteObjectIdentifier#getAbsoluteName(Object)} for an
+	 * {@link IRemoteObjectIdentifier#getAbsoluteName(Object)} for an example.
-	 * example.
-	 * </p><p>
-	 * In case a cached copy of remote object is available locally, 
-	 * this method will <strong>not</strong> contact the remote side
-	 * in order to check whether the cached copy is up-to-date.
-	 * Clients are responsible themselves for refreshing the remote 
-	 * object when they think it is necessary.
-	 * </p><p>
-	 * In case a cached local copy is not available, the remote system
-	 * may be contacted to retrieve the remote object. In this case,
-	 * this call may be a long-running operation and may throw an
-	 * exception. Note, however, that since keys used as IDs are 
-	 * generated by a remote object adapter that implements 
-	 * {@link IRemoteObjectIdentifier}, a cached copy of the remote 
-	 * object will typically be in memory from generating the key.
-	 * A notable exception to this case is when the system view is 
-	 * restored to its previous state during startup.  
 	 * </p>
-	 * <p><strong>Uniqueness and Multiple Contexts</strong><br/>
+	 * <p>
-	 * The RSE SystemView allows the same remote object to be displayed
+	 * In case a cached copy of remote object is available locally, this method
-	 * in multiple different contexts, i.e. under multiple different 
+	 * will <strong>not</strong> contact the remote side in order to check
-	 * filters. In this case, each occurrence of the same object must
+	 * whether the cached copy is up-to-date. Clients are responsible themselves
-	 * return the same absolute name. For the reverse mapping, however,
+	 * for refreshing the remote object when they think it is necessary.
-	 * this method may return only one context object even though 
-	 * multiple different ones are shown in the SystemView.
 	 * </p>
+	 * <p>
+	 * In case a cached local copy is not available, the remote system may be
+	 * contacted to retrieve the remote object. In this case, this call may be a
+	 * long-running operation and may throw an exception. Note, however, that
+	 * since keys used as IDs are generated by a remote object adapter that
+	 * implements {@link IRemoteObjectIdentifier}, a cached copy of the remote
+	 * object will typically be in memory from generating the key. A notable
+	 * exception to this case is when the system view is restored to its
+	 * previous state during startup.
+	 * </p>
+	 * <p>
+	 * <strong>Uniqueness and Multiple Contexts</strong><br/> The RSE
+	 * SystemView allows the same remote object to be displayed in multiple
+	 * different contexts, i.e. under multiple different filters. In this case,
+	 * each occurrence of the same object must return the same absolute name.
+	 * For the reverse mapping, however, this method may return only one context
+	 * object even though multiple different ones are shown in the SystemView.
+	 * </p>
+	 * 
 	 * @see IRemoteObjectIdentifier#getAbsoluteName(Object)
 	 * 
-	 * @param key the unique id of the remote object.
+	 * @param key the unique id of the remote object. Must not be
-	 *     Must not be <code>null</code>.
+	 *            <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
-	 *     object is found with the given id.
+	 *         is 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
-	 *     in order to support good user feedback in case of errors.
+	 *             to support good user feedback in case of errors. Since
-	 *     Since exceptions should only occur while retrieving new 
+	 *             exceptions should only occur while retrieving new remote
-	 *     remote objects during startup, clients are typically allowed 
+	 *             objects during startup, clients are typically allowed to
-	 *     to ignore these exceptions and treat them as if the remote 
+	 *             ignore these exceptions and treat them as if the remote
 	 *             object were simply not there.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public Object getObjectWithAbsoluteName(String key, IProgressMonitor monitor) throws Exception;
 
 	/**
-	 * @deprecated - use getObjectwithAbsoluteName(String key, IProgressMonitor monitor)
+	 * Return the remote object that corresponds to the specified unique ID.
-	 * @param key
+	 * 
-	 * @return
+	 * @param key the unique id of the remote object. Must not be
-	 * @throws Exception
+	 *            <code>null</code>.
+	 * @return the remote object instance, or <code>null</code> if no object
+	 *         is found with the given id.
+	 * @throws Exception in case an error occurs contacting the remote system
+	 *             while retrieving the requested remote object.
+	 * @deprecated - use getObjectwithAbsoluteName(String key, IProgressMonitor
+	 *             monitor)
 	 */
 	public Object getObjectWithAbsoluteName(String key) throws Exception;
 }

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/ISubSystem.java

@@ -17,6 +17,7 @@
  * David McKnight (IBM) - [207095] Implicit connect needs to run in the same job as caller
  * David McKnight (IBM) - [186363] get rid of obsolete calls to ISubSystem.connect()
  * David Dykstal (IBM) - [217556] remove service subsystem types
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
@@ -38,12 +39,16 @@ import org.eclipse.rse.services.clientserver.messages.SystemMessageException;
 /**
  * Interface implemented by SubSystem objects.
  * 
- * While connections contain information to identify a particular remote
+ * While connections contain information to identify a particular remote system,
- * system, it is the subsystem objects within a connection that contain
+ * it is the subsystem objects within a connection that contain information
- * information unique to a particular tool for that remote system, such as
+ * unique to a particular tool for that remote system, such as the port the tool
- * the port the tool uses and the user ID for making the connection.
+ * uses and the user ID for making the connection. There are a set of default
- * There are a set of default properties, but these can be extended by 
+ * properties, but these can be extended by subsystem providers, by extending
- * subsystem providers, by extending SubSystem. 
+ * SubSystem.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
+ *              Clients must extend the abstract <code>SubSystem</code> class
+ *              instead.
  */
 public interface ISubSystem extends ISystemFilterPoolReferenceManagerProvider, IRemoteObjectResolver, ISchedulingRule, IRSEModelObject {
 	// -------------------------------------
@@ -66,7 +71,8 @@ public interface ISubSystem extends ISystemFilterPoolReferenceManagerProvider, I
 
 	/**
 	 * Set the connector service for this subsystem
-	 * @param connectorService
+	 * 
+	 * @param connectorService connector service object to set
 	 */
 	public void setConnectorService(IConnectorService connectorService);
 
@@ -133,10 +139,17 @@ public interface ISubSystem extends ISystemFilterPoolReferenceManagerProvider, I
 	public void deletingConnection();
 
 	/**
-	 * This is a helper method you can call when performing actions that must be certain there
+	 * Check if the subsystem is connected, and connect if it's not.
-	 * is a connection. If there is no connection it will attempt to connect, and if that fails
+	 * 
-	 * will throw a SystemMessageException you can easily display to the user by using a method
+	 * This is a convenience method which first checks whether the subsystem is
-	 * in it.
+	 * already connected. If not, it automatically checks if it's running on the
+	 * dispatch thread or not, and calls the right <code>connect()</code>
+	 * method as appropriate. It also performs some exception parsing,
+	 * converting Exceptions from connect() into SystemMessageException that can
+	 * be displayed to the user by using a method in it.
+	 * 
+	 * @throws SystemMessageException in case of an error connecting
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public void checkIsConnected(IProgressMonitor monitor) throws SystemMessageException;
 
@@ -603,28 +616,39 @@ public interface ISubSystem extends ISystemFilterPoolReferenceManagerProvider, I
 	Object getTargetForFilter(ISystemFilterReference filterRef);
 
 	/**
-	 * Returns the interface type (i.e. a Class object that is an Interface) of a service subsystem. 
+	 * Returns the interface type (i.e. a Class object that is an Interface) of
-	 * @return the service interface on which this service subsystem is implemented. If this
+	 * a service subsystem.
-	 * subsystem is not a service subsystem it must return null.
+	 * 
+	 * @return the service interface on which this service subsystem is
+	 *         implemented. If this subsystem is not a service subsystem it must
+	 *         return <code>null</code>.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public Class getServiceType();
 
 	/**
-	 * Requests a service subsystem to switch to a new configuration. If the configuration
+	 * Requests a service subsystem to switch to a new configuration. If the
-	 * is compatible with this subsystem then it must disconnect, possibly reset its
+	 * configuration is compatible with this subsystem then it must disconnect,
-	 * filter pool references, and request new services and parameters from its new configuration.
+	 * possibly reset its filter pool references, and request new services and
-	 * It must also answer true to {@link #canSwitchTo(ISubSystemConfiguration)}.
+	 * parameters from its new configuration. It must also answer true to
-	 * If the configuration is not compatible with this subsystem then this must do nothing and must answer
+	 * {@link #canSwitchTo(ISubSystemConfiguration)}. If the configuration is
-	 * false to {@link #canSwitchTo(ISubSystemConfiguration)}.
+	 * not compatible with this subsystem then this must do nothing and must
+	 * answer false to {@link #canSwitchTo(ISubSystemConfiguration)}.
+	 * 
 	 * @param configuration the configuration to which to switch.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public void switchServiceFactory(ISubSystemConfiguration configuration);
 
 	/**
-	 * Determine is this subsystem is compatible with this specified configuration.
+	 * Determine is this subsystem is compatible with this specified
+	 * configuration.
+	 * 
 	 * @param configuration the configuration which may be switched to
-	 * @return true if the subsystem can switch to this configuration, false otherwise.
+	 * @return true if the subsystem can switch to this configuration, false
-	 * Subsystems which are not service subsystems must return false.
+	 *         otherwise. Subsystems which are not service subsystems must
+	 *         return false.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public boolean canSwitchTo(ISubSystemConfiguration configuration);
 

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/ISubSystemConfiguration.java

@@ -18,6 +18,7 @@
  * David Dykstal (IBM) - [197036] change signature of getFilterPoolManager method to be able to control the creation of filter pools
  * David Dykstal (IBM) - [217556] remove service subsystem types
  * Xuan Chen (IBM) - [223126] [api][breaking] Remove API related to User Actions in RSE Core/UI
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
@@ -38,8 +39,8 @@ import org.eclipse.rse.services.IService;
  * 
  * @noimplement This interface is not intended to be implemented by clients.
  *              Subsystem configuration implementations must subclass
- *              SubSystemConfiguration rather than implementing this interface
+ *              <code>SubSystemConfiguration</code> rather than implementing
- *              directly.
+ *              this interface directly.
  */
 public interface ISubSystemConfiguration extends ISystemFilterPoolManagerProvider, IRSEPersistableContainer {
 	// ---------------------------------
@@ -397,39 +398,55 @@ public interface ISubSystemConfiguration extends ISystemFilterPoolManagerProvide
 	public IConnectorService getConnectorService(IHost host);
 
 	/**
-	 * Sets the connector service for a particular host.
+	 * Set the connector service for a particular host. This is usually managed
-	 * This is usually mangaged by a connector service manager known
+	 * by a connector service manager known to this configuration. This must be
-	 * to this configuration.
+	 * implemented by service subsystem configurations. Service subsystems allow
-	 * This must be implemented by service subsystem configurations.
+	 * a connector service to be changed.
-	 * Service subsystems allow a connector service to be changed.
+	 * 
 	 * @param host the host for which to set this connector service.
 	 * @param connectorService the connector service associated with this host.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public void setConnectorService(IHost host, IConnectorService connectorService);
 
 	/**
-	 * Get the service type associated with this subsystem configuration.
+	 * Get the service type associated with this subsystem configuration. If the
-	 * If the configuration is not a service subsystem configuration it must return null, otherwise
+	 * configuration is not a service subsystem configuration it must return
-	 * it must return the interface class that the underlying service layer implements.
+	 * <code>null</code>, otherwise it must return the interface class that
-	 * @return an interface class that is implemented by the service layer used by subsystems that have this configuration.
+	 * the underlying service layer implements.
+	 * 
+	 * @return an interface class that is implemented by the service layer used
+	 *         by subsystems that have this configuration, or <code>null</code>
+	 *         if this is not a service subsystem configuration.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public Class getServiceType();
 
 	/**
-	 * Get the implementation type of the service associated with this subsystem configuration.
+	 * Get the implementation type of the service associated with this subsystem
-	 * If the configuration is not a service subsystem configuration then this must return null, otherwise
+	 * configuration. If the configuration is not a service subsystem
-	 * it must return the class that implements the interface specified in {@link #getServiceType()}.
+	 * configuration then this must return <code>null</code>, otherwise it
-	 * @return an implementation class that implements the interface specified in {@link #getServiceType()}.
+	 * must return the class that implements the interface specified in
+	 * {@link #getServiceType()}.
+	 * 
+	 * @return an implementation class that implements the interface specified
+	 *         in {@link #getServiceType()}, or <code>null</code> if this is
+	 *         not a service subsystem configuration.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public Class getServiceImplType();
 
 	/**
-	 * Get the actual service associated with a particular host.
+	 * Get the actual service associated with a particular host. If the
-	 * If the configuration is not a service subsystem this must return null.
+	 * configuration is not a service subsystem this must return null. Otherwise
-	 * Otherwise this must return the particular instance of the class returned by {@link #getServiceImplType()}
+	 * this must return the particular instance of the class returned by
-	 * that is associated with this host instance.
+	 * {@link #getServiceImplType()} that is associated with this host instance.
+	 * 
 	 * @param host The host for which to retrieve the service.
-	 * @return The instance of {@link IService} which is associated with this host.
+	 * @return The instance of {@link IService} which is associated with this
+	 *         host, or <code>null</code> if this is not a service subsystem
+	 *         configuration.
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public IService getService(IHost host);
 
@@ -522,20 +539,24 @@ public interface ISubSystemConfiguration extends ISystemFilterPoolManagerProvide
 	// FILTER POOL METHODS...
 	// ---------------------------------
 	/**
-	 * A subsystem configuration has a filter pool manager for each profile.
+	 * Get the filter pool manager for the given profile. A subsystem
-	 * Get the filter pool manager for the given profile.
+	 * configuration has a filter pool manager for each profile.
+	 * 
 	 * @param profile The system profile for which to get the manager.
-	 * @param force if true then create the default filters for this subsystem configuration in this profile. This should only be
+	 * @param force if true then create the default filters for this subsystem
-	 * done during initial subsystem creation, not during subsystem restore.
+	 *            configuration in this profile. This should only be done during
+	 *            initial subsystem creation, not during subsystem restore.
 	 * @return a filter pool manager
+	 * @since org.eclipse.rse.core 3.0
 	 */
 	public ISystemFilterPoolManager getFilterPoolManager(ISystemProfile profile, boolean force);
 
 	/**
-	 * A subsystem configuration has a filter pool manager for each profile.
+	 * Get the filter pool manager for the given profile. A subsystem
-	 * Get the filter pool manager for the given profile.
+	 * configuration has a filter pool manager for each profile. Do not force
-	 * Do not force the creation of default filter pools.
+	 * the creation of default filter pools. Fully equivalent to
-	 * Fully equivalent to getFilterPoolManager(profile, false).
+	 * getFilterPoolManager(profile, false).
+	 * 
 	 * @param profile The system profile for which to get the manager.
 	 * @return a filter pool manager
 	 */

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/RemoteServerLauncherConstants.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006, 2007 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2008 IBM Corporation and others. 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
  * available at http://www.eclipse.org/legal/epl-v10.html
@@ -12,12 +12,15 @@
  * 
  * Contributors:
  * David Dykstal (IBM) - 168977: refactoring IConnectorService and ServerLauncher hierarchies
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  ********************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
 
 /**
  * This interface defines constants for the Remote Server Launcher.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface RemoteServerLauncherConstants
 {

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/ServerLaunchType.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2004, 2007 IBM Corporation and others.
+ * Copyright (c) 2004, 2008 IBM Corporation and others.
  * 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 available at
@@ -12,7 +12,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
@@ -20,188 +20,126 @@ package org.eclipse.rse.core.subsystems;
 import java.util.Arrays;
 import java.util.List;
 
+/**
+ * Server Launch Type Enum type.
+ * 
+ * @noextend This class is not intended to be subclassed by clients.
+ * @noinstantiate This class is not intended to be instantiated by clients. Use
+ *                the {@link #get(int)} or {@link #get(String)} factory methods
+ *                instead.
+ */
 public final class ServerLaunchType {
 	/**
-	 * The '<em><b>Daemon</b></em>' literal value.
+	 * The '<em><b>Daemon</b></em>' literal value (value 0). The server
-	 * <!-- begin-user-doc -->
+	 * code is to be launched by calling a daemon that is listening on a port.
-	 * The server code is to be launched by calling a daemon that is listening on a port.
+	 * 
-	 * <!-- end-user-doc -->
 	 * @see #DAEMON_LITERAL
-	 * @model name="Daemon"
-	 * @generated
-	 * @ordered
 	 */
 	public static final int DAEMON = 0;
 
 	/**
-	 * The '<em><b>Rexec</b></em>' literal value.
+	 * The '<em><b>Rexec</b></em>' literal value (value 1). The server code
-	 * <!-- begin-user-doc -->
+	 * is to be launched using REXEC
-	 * The server code is to be launched using REXEC
+	 * 
-	 * <!-- end-user-doc -->
 	 * @see #REXEC_LITERAL
-	 * @model name="Rexec"
-	 * @generated
-	 * @ordered
 	 */
 	public static final int REXEC = 1;
 
 	/**
-	 * The '<em><b>Running</b></em>' literal value.
+	 * The '<em><b>Running</b></em>' literal value (value 2). The server
-	 * <!-- begin-user-doc -->
+	 * code is to already running, and doesn't need to be launched.
-	 * The server code is to already running, and doesn't need to be launched.
+	 * 
-	 * <!-- end-user-doc -->
 	 * @see #RUNNING_LITERAL
-	 * @model name="Running"
-	 * @generated
-	 * @ordered
 	 */
 	public static final int RUNNING = 2;
 
 	/**
-	 * The '<em><b>Telnet</b></em>' literal value.
+	 * The '<em><b>Telnet</b></em>' literal value (value 3). The server
-	 * <!-- begin-user-doc -->
+	 * code is to be launched using TELNET.
-	 * The server code is to be launched using TELNET.
+	 * 
-	 * <!-- end-user-doc -->
 	 * @see #TELNET_LITERAL
-	 * @model name="Telnet"
-	 * @generated
-	 * @ordered
 	 */
 	public static final int TELNET = 3;
 
 	/**
-	 * The '<em><b>SSH</b></em>' literal value.
+	 * The '<em><b>SSH</b></em>' literal value (value 4). The server code
-	 * <!-- begin-user-doc -->
+	 * is to be launched using SSH.
-	 * The server code is to be launched using SSH.
+	 * 
-	 * <!-- end-user-doc -->
 	 * @see #SSH_LITERAL
-	 * @model 
-	 * @generated
-	 * @ordered
 	 */
 	public static final int SSH = 4;
 
 	/**
-	 * The '<em><b>FTP</b></em>' literal value.
+	 * The '<em><b>FTP</b></em>' literal value (value 5). The server code
-	 * <!-- begin-user-doc -->
+	 * is to be launched using FTP
-	 * The server code is to be launched using FTP
+	 * 
-	 * <!-- end-user-doc -->
 	 * @see #FTP_LITERAL
-	 * @model 
-	 * @generated
-	 * @ordered
 	 */
 	public static final int FTP = 5;
 
 	/**
-	 * The '<em><b>HTTP</b></em>' literal value.
+	 * The '<em><b>HTTP</b></em>' literal value (value 6). The server code
-	 * <!-- begin-user-doc -->
+	 * is to be launched using HTTP
-	 * The server code is to be launched using HTTP
+	 * 
-	 * <!-- end-user-doc -->
 	 * @see #HTTP_LITERAL
-	 * @model 
-	 * @generated
-	 * @ordered
 	 */
 	public static final int HTTP = 6;
 
 	/**
 	 * The '<em><b>Daemon</b></em>' literal object.
-	 * <!-- begin-user-doc -->
-	 * <p>
 	 * The server code is to be launched by calling a daemon that is listening on a port.
-	 * </p>
-	 * <!-- end-user-doc -->
 	 * @see #DAEMON
-	 * @generated
-	 * @ordered
 	 */
 	public static final ServerLaunchType DAEMON_LITERAL = new ServerLaunchType(DAEMON, "Daemon"); //$NON-NLS-1$
 
 	/**
-	 * The '<em><b>Rexec</b></em>' literal object.
+	 * The '<em><b>Rexec</b></em>' literal object. The server code is to be
-	 * <!-- begin-user-doc -->
+	 * launched using REXEC.
-	 * <p>
+	 * 
-	 * The server code is to be launched using REXEC
-	 * </p>
-	 * <!-- end-user-doc -->
 	 * @see #REXEC
-	 * @generated
-	 * @ordered
 	 */
 	public static final ServerLaunchType REXEC_LITERAL = new ServerLaunchType(REXEC, "Rexec"); //$NON-NLS-1$
 
 	/**
 	 * The '<em><b>Running</b></em>' literal object.
-	 * <!-- begin-user-doc -->
-	 * <p>
 	 * The server code is to already running, and doesn't need to be launched.
-	 * </p>
-	 * <!-- end-user-doc -->
 	 * @see #RUNNING
-	 * @generated
-	 * @ordered
 	 */
 	public static final ServerLaunchType RUNNING_LITERAL = new ServerLaunchType(RUNNING, "Running"); //$NON-NLS-1$
 
 	/**
 	 * The '<em><b>Telnet</b></em>' literal object.
-	 * <!-- begin-user-doc -->
-	 * <p>
 	 * The server code is to be launched using TELNET.
-	 * </p>
-	 * <!-- end-user-doc -->
 	 * @see #TELNET
-	 * @generated
-	 * @ordered
 	 */
 	public static final ServerLaunchType TELNET_LITERAL = new ServerLaunchType(TELNET, "Telnet"); //$NON-NLS-1$
 
 	/**
 	 * The '<em><b>SSH</b></em>' literal object.
-	 * <!-- begin-user-doc -->
-	 * <p>
 	 * If the meaning of '<em><b>SSH</b></em>' literal object isn't clear,
 	 * there really should be more of a description here...
-	 * </p>
-	 * <!-- end-user-doc -->
 	 * @see #SSH
-	 * @generated
-	 * @ordered
 	 */
 	public static final ServerLaunchType SSH_LITERAL = new ServerLaunchType(SSH, "SSH"); //$NON-NLS-1$
 
 	/**
-	 * The '<em><b>FTP</b></em>' literal object.
+	 * The '<em><b>FTP</b></em>' literal object. The server code is to be
-	 * <!-- begin-user-doc -->
+	 * launched using FTP.
-	 * <p>
+	 * 
-	 * The server code is to be launched using FTP
-	 * </p>
-	 * <!-- end-user-doc -->
 	 * @see #FTP
-	 * @generated
-	 * @ordered
 	 */
 	public static final ServerLaunchType FTP_LITERAL = new ServerLaunchType(FTP, "FTP"); //$NON-NLS-1$
 
 	/**
-	 * The '<em><b>HTTP</b></em>' literal object.
+	 * The '<em><b>HTTP</b></em>' literal object. The server code is to be
-	 * <!-- begin-user-doc -->
+	 * launched using HTTP.
-	 * <p>
+	 * 
-	 * The server code is to be launched using HTTP
-	 * </p>
-	 * <!-- end-user-doc -->
 	 * @see #HTTP
-	 * @generated
-	 * @ordered
 	 */
 	public static final ServerLaunchType HTTP_LITERAL = new ServerLaunchType(HTTP, "HTTP"); //$NON-NLS-1$
 
 	/**
 	 * An array of all the '<em><b>Server Launch Type</b></em>' enumerators.
-	 * <!-- begin-user-doc -->
-	 * <!-- end-user-doc -->
-	 * @generated
 	 */
 	private static final ServerLaunchType[] VALUES_ARRAY = new ServerLaunchType[] { DAEMON_LITERAL, REXEC_LITERAL, RUNNING_LITERAL, TELNET_LITERAL, SSH_LITERAL, FTP_LITERAL, HTTP_LITERAL, };
 
@@ -210,17 +148,11 @@ public final class ServerLaunchType {
 
 	/**
 	 * A public read-only list of all the '<em><b>Server Launch Type</b></em>' enumerators.
-	 * <!-- begin-user-doc -->
-	 * <!-- end-user-doc -->
-	 * @generated
 	 */
 	public static final List VALUES = Arrays.asList(VALUES_ARRAY);
 
 	/**
 	 * Returns the '<em><b>Server Launch Type</b></em>' literal with the specified name.
-	 * <!-- begin-user-doc -->
-	 * <!-- end-user-doc -->
-	 * @generated
 	 */
 	public static ServerLaunchType get(String name) {
 		for (int i = 0; i < VALUES_ARRAY.length; ++i) {
@@ -234,9 +166,6 @@ public final class ServerLaunchType {
 
 	/**
 	 * Returns the '<em><b>Server Launch Type</b></em>' literal with the specified value.
-	 * <!-- begin-user-doc -->
-	 * <!-- end-user-doc -->
-	 * @generated
 	 */
 	public static ServerLaunchType get(int value) {
 		switch (value) {

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/SubSystemHelpers.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2007 IBM Corporation and others.
+ * Copyright (c) 2006, 2008 IBM Corporation and others.
  * 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 available at
@@ -12,7 +12,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
@@ -26,7 +26,10 @@ import org.eclipse.rse.core.filters.ISystemFilterReference;
 import org.eclipse.rse.core.model.ISystemProfile;
 
 /**
- * Static helper methods
+ * Static helper methods for subsystems.
+ * 
+ * @noextend This class is not intended to be subclassed by clients.
+ * @noinstantiate This class is not intended to be instantiated by clients.
  */
 public class SubSystemHelpers
 {
@@ -40,10 +43,6 @@ public class SubSystemHelpers
 		return (ISubSystem)poolReference.getProvider();
 	}
 
-
-    
-
-
 	/**
 	 * Give a filter pool, return parent subsystem factory
 	 */

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/core/SystemResourceConstants.java

@@ -20,6 +20,8 @@ package org.eclipse.rse.internal.core;
 
 /**
  * Constants related to project and folder names.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface SystemResourceConstants
 {

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/persistence/dom/IRSEDOMConstants.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006, 2007 IBM Corporation and others.
+ * Copyright (c) 2006, 2008 IBM Corporation and others.
  * 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 available at
@@ -12,11 +12,16 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [cleanup] Add API "since" Javadoc tags
  *******************************************************************************/
 
 package org.eclipse.rse.persistence.dom;
 
+/**
+ * Constants used in RSE DOMs.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
+ */
 public interface IRSEDOMConstants {
 	// node types
 	public static final String TYPE_PROFILE = "Profile"; //$NON-NLS-1$

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

@@ -491,11 +491,10 @@ public abstract class SubSystem extends RSEModelObject
 			system.clearCredentials();
 	}
 
-    /**
+	/*
-     * This is a helper method you can call when performing actions that must be certain there
+	 * (non-Javadoc)
-     * is a connection. If there is no connection it will attempt to connect, and if that fails
+	 * 
-     * will throw a SystemMessageException you can easily display to the user by using a method
+	 * @see org.eclipse.rse.core.subsystems.ISubSystem#checkIsConnected(org.eclipse.core.runtime.IProgressMonitor)
-     * in it.
 	 */
 	public void checkIsConnected(IProgressMonitor monitor) throws SystemMessageException
 	{