From 14af215d50a6a49a7fe1b13f4e99fa0f685243a9 Mon Sep 17 00:00:00 2001 From: Martin Oberhuber < martin.oberhuber@windriver.com> Date: Fri, 28 Mar 2008 14:27:50 +0000 Subject: [PATCH] [cleanup] Add @noimplement and similar API Tools Javadoc Markup --- .../eclipse/rse/core/IRSECoreRegistry.java | 11 +- .../org/eclipse/rse/core/IRSESystemType.java | 91 +- .../rse/core/model/ISystemHostPool.java | 120 +-- .../rse/core/model/ISystemRegistry.java | 149 +-- .../subsystems/ISubSystemConfiguration.java | 67 +- .../core/filters/SystemFilterPoolManager.java | 115 ++- .../files/ui/resources/ISystemRemotePath.java | 23 +- .../UniversalFileTransferUtility.java | 911 +++++++++--------- .../ui/resources/SystemRemoteMarker.java | 80 +- .../files/RemoteExportWizard.java | 19 +- .../files/RemoteFileImportOperation.java | 33 +- .../files/RemoteImportWizard.java | 21 +- .../java/BasicClassFileParser.java | 235 ++--- .../clientserver/java/ClassFileUtil.java | 30 +- .../rse/services/files/IFileService.java | 30 +- .../model/SystemFileTransferModeMapping.java | 33 +- .../model/SystemFileTransferModeRegistry.java | 203 ++-- .../files/core/model/RemoteFileUtility.java | 59 +- .../ui/view/SystemComboBoxCellEditor.java | 91 +- .../ui/internal/model/SystemRegistryUI.java | 68 +- .../rse/ui/model/ISystemRegistryUI.java | 31 +- .../tm/internal/terminal/view/PageBook.java | 10 +- .../provisional/api/ITerminalControl.java | 31 +- .../tm/terminal/model/ITerminalTextData.java | 65 +- .../model/ITerminalTextDataSnapshot.java | 143 +-- 25 files changed, 1349 insertions(+), 1320 deletions(-) diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSECoreRegistry.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSECoreRegistry.java index c3de0597c8f..72b24e92b16 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSECoreRegistry.java +++ b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSECoreRegistry.java @@ -18,10 +18,11 @@ package org.eclipse.rse.core; /** - * Interface for RSE core registry. Clients should use this interface as the starting point for querying and - * manipulating model objects in the RSE framework. - * - * This interface is not intended to be implemented by clients. + * Interface for RSE core registry. Clients should use this interface as the + * starting point for querying and manipulating model objects in the RSE + * framework. + * + * @noimplement This interface is not intended to be implemented by clients. */ public interface IRSECoreRegistry { @@ -45,7 +46,7 @@ public interface IRSECoreRegistry { * @deprecated Use {@link #getSystemTypeById(String)}. */ public IRSESystemType getSystemType(String name); - + /** * Returns a system type object given by the id. * diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSESystemType.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSESystemType.java index 2c662d6e2bd..4cd6ac3979c 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSESystemType.java +++ b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSESystemType.java @@ -1,13 +1,13 @@ /******************************************************************************** * 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 + * of the Eclipse Public License v1.0 which accompanies this distribution, and is * available at http://www.eclipse.org/legal/epl-v10.html * * Initial Contributors: * The following IBM employees contributed to the Remote System Explorer - * component that contains this file: David McKnight, Kushal Munir, - * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, + * component that contains this file: David McKnight, Kushal Munir, + * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley. * * Contributors: @@ -29,10 +29,11 @@ import org.osgi.framework.Bundle; * Interface for a system type. Constants are defined for various system types. * These constants are kept in sync with definitions in plugin.xml. *

- * This interface is not intended to be implemented by clients. System type - * implementations must subclass {@link AbstractRSESystemType} rather than - * implementing this interface directly. - *

+ * @noimplement This interface is not intended to be implemented by clients. + * System type implementations must subclass + * {@link AbstractRSESystemType} rather than implementing this + * interface directly. + *

*/ public interface IRSESystemType extends IAdaptable { @@ -41,7 +42,7 @@ public interface IRSESystemType extends IAdaptable { * @deprecated Use {@link #SYSTEMTYPE_LINUX_ID}. */ public static final String SYSTEMTYPE_LINUX = "Linux"; //$NON-NLS-1$ - + /** * Linux system type, "org.eclipse.rse.systemtype.linux". */ @@ -52,7 +53,7 @@ public interface IRSESystemType extends IAdaptable { * @deprecated Use {@link #SYSTEMTYPE_POWER_LINUX_ID}. */ public static final String SYSTEMTYPE_POWER_LINUX = "Power Linux"; //$NON-NLS-1$ - + /** * Power Linux type, "org.eclipse.rse.systemtype.linux.power". */ @@ -68,7 +69,7 @@ public interface IRSESystemType extends IAdaptable { * Power Linux type, "org.eclipse.rse.systemtype.linux.zseries". */ public static final String SYSTEMTYPE_ZSERIES_LINUX_ID = "org.eclipse.rse.systemtype.linux.zSeries"; //$NON-NLS-1$ - + /** * Unix system type, "Unix". * @deprecated Use {@link #SYSTEMTYPE_UNIX_ID}. @@ -79,7 +80,7 @@ public interface IRSESystemType extends IAdaptable { * Unix system type, "org.eclipse.rse.systemtype.unix". */ public static final String SYSTEMTYPE_UNIX_ID = "org.eclipse.rse.systemtype.unix"; //$NON-NLS-1$ - + /** * AIX system type, "AIX". * @deprecated Use {@link #SYSTEMTYPE_AIX_ID}. @@ -90,7 +91,7 @@ public interface IRSESystemType extends IAdaptable { * AIX system type, "org.eclipse.rse.systemtype.aix". */ public static final String SYSTEMTYPE_AIX_ID = "org.eclipse.rse.systemtype.aix"; //$NON-NLS-1$ - + /** * PASE system type, "PASE". * @deprecated Use {@link #SYSTEMTYPE_PASE_ID}. @@ -101,7 +102,7 @@ public interface IRSESystemType extends IAdaptable { * PASE system type, "org.eclipse.rse.systemtype.PASE". */ public static final String SYSTEMTYPE_PASE_ID = "org.eclipse.rse.systemtype.iseries.PASE"; //$NON-NLS-1$ - + /** * iSeries system type, "iSeries". * @deprecated Use {@link #SYSTEMTYPE_ISERIES_ID}. @@ -112,7 +113,7 @@ public interface IRSESystemType extends IAdaptable { * iSeries system type, "org.eclipse.rse.systemtype.iseries". */ public static final String SYSTEMTYPE_ISERIES_ID = "org.eclipse.rse.systemtype.iseries"; //$NON-NLS-1$ - + /** * Local system type, "Local". * @deprecated Use {@link #SYSTEMTYPE_LOCAL_ID}. @@ -123,7 +124,7 @@ public interface IRSESystemType extends IAdaptable { * Local system type, "org.eclipse.rse.systemtype.local". */ public static final String SYSTEMTYPE_LOCAL_ID = "org.eclipse.rse.systemtype.local"; //$NON-NLS-1$ - + /** * z/OS system type, "z/OS". * @deprecated Use {@link #SYSTEMTYPE_ZSERIES_ID}. @@ -134,7 +135,7 @@ public interface IRSESystemType extends IAdaptable { * z/OS system type, "org.eclipse.rse.systemtype.zseries". */ public static final String SYSTEMTYPE_ZSERIES_ID = "org.eclipse.rse.systemtype.zseries"; //$NON-NLS-1$ - + /** * Windows system type, "Windows". * @deprecated Use {@link #SYSTEMTYPE_WINDOWS_ID}. @@ -143,7 +144,7 @@ public interface IRSESystemType extends IAdaptable { /** Windows system type, "org.eclipse.rse.systemtype.windows". */ public static final String SYSTEMTYPE_WINDOWS_ID = "org.eclipse.rse.systemtype.windows"; //$NON-NLS-1$ - + /** Discovery system type, "org.eclipse.rse.systemtype.discovery". */ public static final String SYSTEMTYPE_DISCOVERY_ID = "org.eclipse.rse.systemtype.discovery"; //$NON-NLS-1$ /** FTP Only system type, "org.eclipse.rse.systemtype.ftp". */ @@ -152,9 +153,9 @@ public interface IRSESystemType extends IAdaptable { public static final String SYSTEMTYPE_SSH_ONLY_ID = "org.eclipse.rse.systemtype.ssh"; //$NON-NLS-1$ /** Telnet Only system type, "org.eclipse.rse.systemtype.telnet". */ public static final String SYSTEMTYPE_TELNET_ONLY_ID = "org.eclipse.rse.systemtype.telnet"; //$NON-NLS-1$ - - /** - * System type Property Key (value: "isLocal") indicating whether + + /** + * System type Property Key (value: "isLocal") indicating whether * a system type is declared in plugin.xml to refers to the local * system. * On a the local system, the following properties are expected: @@ -165,13 +166,13 @@ public interface IRSESystemType extends IAdaptable { * @see #testProperty(String, boolean) */ public static final String PROPERTY_IS_LOCAL = "isLocal"; //$NON-NLS-1$ - - /** - * System type Property Key (value: "isWindows") indicating whether + + /** + * System type Property Key (value: "isWindows") indicating whether * a system type is declared in plugin.xml to refers to a Windows * system. - *

- * This is an "aggregate" property consisting of several smaller + *

+ * This is an "aggregate" property consisting of several smaller * properties like isCaseSensitive. In the future, we'll want more * fine granular properties to check against. On a Windows system, * the following properties are expected: @@ -187,14 +188,14 @@ public interface IRSESystemType extends IAdaptable { * @see #testProperty(String, boolean) */ public static final String PROPERTY_IS_WINDOWS = "isWindows"; //$NON-NLS-1$ - + /** * System type Property Key (value: "isCaseSensitive") indicating * whether a given system type is in general case sensitive. * @see #testProperty(String, boolean) */ public static final String PROPERTY_IS_CASE_SENSITIVE = "isCaseSensitive"; //$NON-NLS-1$ - + /** * Returns the id of the system type. * @return the id of the system type @@ -203,11 +204,11 @@ public interface IRSESystemType extends IAdaptable { /** * Returns the translatable label for use in the UI. - * + * * @return The UI label or null if not set. */ public String getLabel(); - + /** * Returns the name of the system type. * @return the name of the system type @@ -230,7 +231,7 @@ public interface IRSESystemType extends IAdaptable { * @return the value associated with the given key or null if none */ public String getProperty(String key); - + /** * Tests whether the given boolean property matches the expected value * for this system type. @@ -238,7 +239,7 @@ public interface IRSESystemType extends IAdaptable { * Clients can use their own properties with system types, but should * use reverse DNS notation to qualify their property keys (e.g. * com.acme.isFoobarSystem. Property keys without qualifying - * namespace are reserved for RSE internal use. + * namespace are reserved for RSE internal use. * * @param key the name of the property to return * @param expectedValue the expected boolean value of the property. @@ -247,7 +248,7 @@ public interface IRSESystemType extends IAdaptable { * is not set or does not match. */ public boolean testProperty(String key, boolean expectedValue); - + /** * Tests whether the system type is currently enabled. * @@ -259,7 +260,7 @@ public interface IRSESystemType extends IAdaptable { * Implementers of custom system types (which are registered by a SystemTypeProvider) * can override this method to provide more advanced enabled checks e.g. based on * license availability. - * + * * @return true if the system type is currently enabled, or false otherwise. */ public boolean isEnabled(); @@ -267,11 +268,11 @@ public interface IRSESystemType extends IAdaptable { /** * Tests whether the system type refers to the local system. * This is a shortcut for - *

 
-	 *   getId().equals(SYSTEMTYPE_LOCAL_ID) || 
+	 * 
+	 *   getId().equals(SYSTEMTYPE_LOCAL_ID) ||
 	 *   || testProperty(PROPERTY_IS_LOCAL, true)
 	 * 
- * See {@link #PROPERTY_IS_LOCAL} for properties expected on + * See {@link #PROPERTY_IS_LOCAL} for properties expected on * a Local system. * Extenders (contributors of custom system types) may override. * @return true if the system type refers to the local system. @@ -281,14 +282,14 @@ public interface IRSESystemType extends IAdaptable { /** * Tests whether the system type refers to the Windows system. * This is a shortcut for - *
 
+	 * 
 	 *   getId().equals(SYSTEMTYPE_WINDOWS_ID)
 	 *   || isLocal() && System.getProperty("os.name").toLowerCase().startsWith("win")
 	 *   || testProperty(PROPERTY_IS_WINDOWS, true)
 	 * 
- * See {@link #PROPERTY_IS_WINDOWS} for properties expected on + * See {@link #PROPERTY_IS_WINDOWS} for properties expected on * a Windows system. This is an "aggregate" property consisting - * of several smaller properties like isCaseSensitive. In the + * of several smaller properties like isCaseSensitive. In the * future, we'll want more fine granular properties to check against. * Extenders (contributors of custom system types) may override. * @return true if the system type refers to a Windows system. @@ -297,16 +298,16 @@ public interface IRSESystemType extends IAdaptable { /** * Returns the bundle which is responsible for the definition of this system type. - * Typically this is used as a base for searching for images and other files + * Typically this is used as a base for searching for images and other files * that are needed in presenting the system type. * * @return the bundle which defines this system type or null if none */ public Bundle getDefiningBundle(); - + /** * Returns a list of fully qualified known subsystem configuration id's that - * this system type wants to be registered against. + * this system type wants to be registered against. * More subsystem configurations can be added through the subsystemConfigurations * extension point. *

@@ -316,9 +317,9 @@ public interface IRSESystemType extends IAdaptable { * * @return The list of subsystem configuration id's. May be empty, * but never null. - */ + */ public String[] getSubsystemConfigurationIds(); - + /** * Creates a new IHost object instance. This method is * called from {@link SystemHostPool#createHost(IRSESystemType, String, String, String, String, int)}. @@ -326,5 +327,5 @@ public interface IRSESystemType extends IAdaptable { * @param profile The system profile to associate with the host. * @return A new IHost object instance. */ - public IHost createNewHostInstance(ISystemProfile profile); + public IHost createNewHostInstance(ISystemProfile profile); } \ No newline at end of file diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/ISystemHostPool.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/ISystemHostPool.java index 8144a40fcc0..6410b2830ce 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/ISystemHostPool.java +++ b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/ISystemHostPool.java @@ -1,13 +1,13 @@ /******************************************************************************** * 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 + * of the Eclipse Public License v1.0 which accompanies this distribution, and is * available at http://www.eclipse.org/legal/epl-v10.html * * Initial Contributors: * The following IBM employees contributed to the Remote System Explorer - * component that contains this file: David McKnight, Kushal Munir, - * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, + * component that contains this file: David McKnight, Kushal Munir, + * Michael Berger, David Dykstal, Phil Coulthard, Don Yantzi, Eric Simpson, * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley. * * Contributors: @@ -22,14 +22,14 @@ import org.eclipse.rse.core.IRSESystemType; import org.eclipse.rse.core.IRSEUserIdConstants; /** - * An ordered list of connections ({@link IHost} objects), owned by an {@link ISystemProfile}. + * An ordered list of connections ({@link IHost} objects), owned by an + * {@link ISystemProfile}. *

* Implementations of this interface are expected to be thread-safe in the sense - * that integrity of the host list is maintained even if multiple threads call + * that integrity of the host list is maintained even if multiple threads call * multiple methods in this interface concurrently. - *

- * This interface is not intended to be implemented by clients. *

+ * @noimplement This interface is not intended to be implemented by clients. */ public interface ISystemHostPool extends IRSEPersistableContainer { @@ -62,48 +62,48 @@ public interface ISystemHostPool extends IRSEPersistableContainer { */ public IHost[] getHosts(); - /** - * Create a connection object, given only the minimal information. - *

- * THE RESULTING CONNECTION OBJECT IS ADDED TO THE LIST OF EXISTING CONNECTIONS FOR YOU. - * @param systemType system type matching one of the system types - * defined via the systemTypes extension point. - * @param aliasName unique connection name. - * @param hostName IP name or address of the host. - * @return IHost object, or null if it failed to create - * because the aliasName is not unique. All other errors throw an exception. - */ + /** + * Create a connection object, given only the minimal information. + *

+ * THE RESULTING CONNECTION OBJECT IS ADDED TO THE LIST OF EXISTING CONNECTIONS FOR YOU. + * @param systemType system type matching one of the system types + * defined via the systemTypes extension point. + * @param aliasName unique connection name. + * @param hostName IP name or address of the host. + * @return IHost object, or null if it failed to create + * because the aliasName is not unique. All other errors throw an exception. + */ public IHost createHost(IRSESystemType systemType, String aliasName, String hostName); - /** - * Create a connection object, given all the possible attributes except default userId. - *

- * THE RESULTING CONNECTION OBJECT IS ADDED TO THE LIST OF EXISTING CONNECTIONS FOR YOU. - * @param systemType system type matching one of the system types - * defined via the systemTypes extension point. - * @param aliasName unique connection name. - * @param hostName IP name or address of the host. - * @param description optional description of the connection. Can be null. - * @return IHost object, or null if it failed to create - * because the aliasName is not unique. All other errors throw an exception. - */ + /** + * Create a connection object, given all the possible attributes except default userId. + *

+ * THE RESULTING CONNECTION OBJECT IS ADDED TO THE LIST OF EXISTING CONNECTIONS FOR YOU. + * @param systemType system type matching one of the system types + * defined via the systemTypes extension point. + * @param aliasName unique connection name. + * @param hostName IP name or address of the host. + * @param description optional description of the connection. Can be null. + * @return IHost object, or null if it failed to create + * because the aliasName is not unique. All other errors throw an exception. + */ public IHost createHost(IRSESystemType systemType, String aliasName, String hostName, String description); - /** - * Create a connection object, given all the possible attributes. - *

- * The new connection is added to the list and saved to disk. - * @param systemType system type matching one of the system types - * defined via the systemTypes extension point. - * @param aliasName unique connection name. - * @param hostName IP name or address of the host. - * @param description optional description of the connection. Can be null. - * @param defaultUserId userId to use as the default for the subsystems. - * @param defaultUserIdLocation where to set the given default user Id. See IRSEUserIdConstants for values. - * @return IHost object, or null if it failed to create - * because the aliasName is not unique. - * @see IRSEUserIdConstants - */ + /** + * Create a connection object, given all the possible attributes. + *

+ * The new connection is added to the list and saved to disk. + * @param systemType system type matching one of the system types + * defined via the systemTypes extension point. + * @param aliasName unique connection name. + * @param hostName IP name or address of the host. + * @param description optional description of the connection. Can be null. + * @param defaultUserId userId to use as the default for the subsystems. + * @param defaultUserIdLocation where to set the given default user Id. See IRSEUserIdConstants for values. + * @return IHost object, or null if it failed to create + * because the aliasName is not unique. + * @see IRSEUserIdConstants + */ public IHost createHost(IRSESystemType systemType, String aliasName, String hostName, String description, String defaultUserId, int defaultUserIdLocation); /** @@ -118,7 +118,7 @@ public interface ISystemHostPool extends IRSEPersistableContainer { * @param systemType system type matching one of the system types * defined via the systemType extension point. * @param aliasName unique connection name. - * @param hostName IP name or address of the host. + * @param hostName IP name or address of the host. * @param description optional description of the connection. Can be null. * @param defaultUserId userId to use as the default for the subsystems. * @param defaultUserIdLocation where to set the given default user Id from IRSEUserIdConstants. @@ -126,29 +126,29 @@ public interface ISystemHostPool extends IRSEPersistableContainer { */ public void updateHost(IHost conn, IRSESystemType systemType, String aliasName, String hostName, String description, String defaultUserId, int defaultUserIdLocation); - /** - * Return a connection object, given its alias name. - * - * Can be used to test if an alias name is already used (non-null return). - * - * @param aliasName unique aliasName (case insensitive) to search on. - * @return IHost object with unique aliasName, or null if - * no connection object with this name exists. - */ + /** + * Return a connection object, given its alias name. + * + * Can be used to test if an alias name is already used (non-null return). + * + * @param aliasName unique aliasName (case insensitive) to search on. + * @return IHost object with unique aliasName, or null if + * no connection object with this name exists. + */ public IHost getHost(String aliasName); /** * Return the connection at the given zero-based offset. * @param pos zero-based offset of requested connection in the connection list. - * @return IHost object requested. + * @return IHost object requested. */ public IHost getHost(int pos); /** * Add a new connection to the list. *

- * This method will not ensure that the added connection's alias name is - * different (case-insensitive) than all other existing alias names. + * This method will not ensure that the added connection's alias name is + * different (case-insensitive) than all other existing alias names. * Clients are responsible for maintaining this invariant. *

* @param conn Connection to add. Must not be null. @@ -163,7 +163,7 @@ public interface ISystemHostPool extends IRSEPersistableContainer { * + * *

* @param conn IHost object to remove */ @@ -212,7 +212,7 @@ public interface ISystemHostPool extends IRSEPersistableContainer { /** * Move existing connections a given number of positions in the same pool. - * If the delta is negative, they are all moved up (left) by the given amount. If + * If the delta is negative, they are all moved up (left) by the given amount. If * positive, they are all moved down (right) by the given amount.

*