[182454] improve getAbsoluteName() documentation

rse/examples/org.eclipse.rse.examples.daytime/src/org/eclipse/rse/examples/daytime/model/DaytimeResourceAdapter.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006 IBM Corporation and Wind River Systems, Inc.
+ * Copyright (c) 2006, 2007 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) - adapted template for daytime example.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.examples.daytime.model;
@@ -56,7 +57,6 @@ public class DaytimeResourceAdapter extends AbstractSystemViewAdapter implements
 
 	public String getAbsoluteName(Object object) {
 		//Not used since we dont support clipboard copy, rename or filtering
-		//TODO check if it is still used anywhere? Then we'd want to externalize the String
 		return "daytime:"+getText(object); //$NON-NLS-1$
 	}
 
@@ -76,7 +76,6 @@ public class DaytimeResourceAdapter extends AbstractSystemViewAdapter implements
 		return null;
 	}
 
-	
 	protected Object internalGetPropertyValue(Object key) {
 		return null;
 	}

rse/examples/org.eclipse.rse.examples.tutorial/src/samples/model/DeveloperResourceAdapter.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2007 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) - Adapted original tutorial code to Open RSE.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package samples.model;
@@ -67,8 +68,9 @@ public class DeveloperResourceAdapter extends AbstractSystemViewAdapter
 		return ((DeveloperResource)element).getName();
 	}
 
-	/* (non-Javadoc)
+	/*
-	 * @see org.eclipse.rse.ui.view.AbstractSystemViewAdapter#getAbsoluteName(java.lang.Object)
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object object)
 	{

rse/examples/org.eclipse.rse.examples.tutorial/src/samples/model/TeamResourceAdapter.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2007 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) - Adapted original tutorial code to Open RSE.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package samples.model;
@@ -66,8 +67,9 @@ public class TeamResourceAdapter extends AbstractSystemViewAdapter implements
 		return ((TeamResource)element).getName();
 	}
 
-	/* (non-Javadoc)
+	/*
-	 * @see org.eclipse.rse.ui.view.AbstractSystemViewAdapter#getAbsoluteName(java.lang.Object)
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object object)
 	{

rse/examples/org.eclipse.rse.examples.tutorial/src/samples/subsystems/DeveloperSubSystem.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2007 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) - Adapted original tutorial code to Open RSE.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package samples.subsystems;
@@ -57,21 +58,13 @@ public class DeveloperSubSystem extends SubSystem
 	public void uninitializeSubSystem(IProgressMonitor monitor) {
 	}
 
-	/**
+	/*
-	 * For drag and drop, and clipboard support of remote objects.
+	 * (non-Javadoc)
-	 *   
+	 * @see org.eclipse.rse.core.subsystems.SubSystem#getObjectWithAbsoluteName(java.lang.String)
-	 * Return the remote object within the subsystem that corresponds to
-	 * the specified unique ID.  Because each subsystem maintains it's own
-	 * objects, it's the responsability of the subsystem to determine
-	 * how an ID (or key) for a given object maps to the real object.
-	 * By default this returns null.
-	 *  
-	 * @param key internal unique ID for object 
-	 * @return Object identified by the given key
 	 */
-	public Object getObjectWithAbsoluteName(String key)
+	public Object getObjectWithAbsoluteName(String key) throws Exception
 	{
-		//  Functional opposite of getAbsoluteName(Object) in our resource adapters
+		// Functional opposite of getAbsoluteName(Object) in our resource adapters
 		if (key.startsWith("Team_")) //$NON-NLS-1$
 		{
 			String teamName = key.substring(5);
@@ -88,7 +81,8 @@ public class DeveloperSubSystem extends SubSystem
 			  if (devrs[idx].getId().equals(devrId))
 			    return devrs[idx];            	
 		}
-		return null; 
+		// Not a remote object: fall back to return filter reference
+		return super.getObjectWithAbsoluteName(key); 
 	}
 
 	/**

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

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2002, 2007 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
@@ -11,17 +11,90 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
 
+import org.eclipse.rse.services.search.IHostSearchResult;
+
+/**
+ * Interface that remote objects must implement in order to be 
+ * identifiable for drag and drop, and clipboard support.
+ * This is the functional opposite of {@link IRemoteObjectResolver}.
+ * 
+ * @see IRemoteObjectIdentifier
+ */
 public interface IRemoteObjectIdentifier {
 
 	/**
-	 * For drag and drop, and clipboard, support of remote objects.
+	 * Return a String ID for the given remote object, that is unique
+	 * within the subsystem.
 	 * <p>
-	 * Return the unique ID for the given remote object within the subsystem.
+	 * This must be implemented by subsystem element adapters in order to 
+	 * marshal a reference to the remote object for drag and drop, and 
+	 * clipboard support. It is also used for uniquely identifying 
+	 * objects with changing properties in the SystemView. This method 
+	 * is the functional opposite of 
+	 * {@link IRemoteObjectResolver#getObjectWithAbsoluteName(String)}.
+	 * </p><p>
+	 * The unique ID for an object must remain the same over the entire
+	 * lifetime of that object, such that it can always be identified.
+	 * When an object is renamed, it should be removed from the views 
+	 * with the old ID and then re-added with the new ID. This is 
+	 * especially important for the SystemView, where the String ID
+	 * is used for finding multiple occurrences of the same remote 
+	 * resource in different contexts during refresh events. In this 
+	 * case, the String ID can be used to find the remote object even 
+	 * if its hashCode changes due to updated properties.
+	 * So even if a subsystem does not support drag and drop, or 
+	 * clipboard operations, it does need to return unique IDs for 
+	 * its object to support refresh in the SystemView.
+	 * </p><p>
+	 * Because each subsystem maintains its own objects, it is the 
+	 * responsability of the subsystem and its adapters to come up
+	 * with a mapping that is unique for the subsystem. Some subsystems
+	 * use fully qualified path names, while others may use other methods. 
+	 * Extenders just need to ensure that objects of different type (such 
+	 * as filters, actual resources or error messages) all have different
+	 * IDs within the subsystem, and the corresponding 
+	 * {@link IRemoteObjectResolver#getObjectWithAbsoluteName(String)}
+	 * method actually finds the object by the given ID. Other subsystems
+	 * do not need to be considered.
+	 * </p><p>
+	 * </p>
+	 * <p><strong>Examples</strong>
+	 * In the File Subsystem, a fully qualified pathname is used to 
+	 * uniquely identify remote objects. For other kinds of objects
+	 * maintained by the same subsystem, the following schemes are used:
+	 * <ul>
+	 *    <li>The subsystem itself is identified as<br/> 
+	 *       subsystemID ::= (profileName).(connectionName).(subsystemName)<br/>
+	 *       - see SystemViewSubSystemAdapter</li>
+	 *    <li>Filter Pool References are identified as<br/>
+	 *       filterPoolID ::= (subsystemID).(poolManagerName).(poolReferenceName)<br/>
+	 *       - see SystemViewFilterPoolReferenceAdapter</li>
+	 *    <li>Filter References are identified as <br/>
+	 *       filterRefID ::= (filterPoolID).(filterName)<br/>
+	 *       - see SystemViewFilterReferenceAdapter</li>
+	 *    <li>Search Results are identified by the 
+	 *       {@link IHostSearchResult#SEARCH_RESULT_DELIMITER}
+	 *       embedded in the ID.</li>
+	 * </ul>
+	 * All these IDs for internal elements like the subsystem itself
+	 * or the filters start with a profile name which must not contain
+	 * any of the / \ or : characters. Fully qualified path names, on 
+	 * the other hand, always start with a / or \ character (UNIX style 
+	 * pathes, Windows UNC pathes) or have a : character on the second 
+	 * position (Windows drive letters). The SEARCH_RESULT_DELIMITER
+	 * is ":SEARCH" which cannot be part of a valid filename.
+	 * Therefore, this naming scheme is guaranteed to be unique.
+	 * </p>
+	 * @see IRemoteObjectResolver#getObjectWithAbsoluteName(String)
+	 * 
+	 * @param object the remote element to be identified.
+	 * @return a String uniquely identifying the remote object within the subsystem.
+	 *     Must not return <code>null</code>.
 	 */
 	public String getAbsoluteName(Object object);
 

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

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2002, 2007 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
@@ -11,21 +11,67 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
 
+import org.eclipse.rse.services.clientserver.messages.SystemMessageException;
+
 /**
- * Interface for resolving an object in a subsystem from a unique ID
+ * Interface for resolving an object in a subsystem from a unique ID.
+ * This is the functional opposite of {@link IRemoteObjectIdentifier}.
+ * 
+ * @see IRemoteObjectIdentifier
  */
 public interface IRemoteObjectResolver {
 
 	/**
-	 * For drag and drop, clipboard, and other object retrieval mechanisms in support of remote objects.
+	 * Return the remote object that corresponds to the specified unique ID.
 	 * <p>
-	 * Return the remote object within the subsystem that corresponds to
+	 * This must be implemented by subsystems in order to find remote objects
-	 * the specified unique ID.
+	 * for drag and drop, clipboard, and other object retrieval mechanisms
+	 * in support of remote objects. It is the functional opposite of 
+	 * {@link IRemoteObjectIdentifier#getAbsoluteName(Object)}.
+	 * </p><p>
+	 * Because each subsystem maintains it's own objects, it is the 
+	 * responsability of the subsystem to determine how an ID (or key)
+	 * for a given object maps to the real object. Subsystems also need
+	 * to ensure that objects of different type (such as filters, actual
+	 * resources or error messages) all have different IDs. See
+	 * {@link IRemoteObjectIdentifier#getAbsoluteName(Object)} for an
+	 * 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>
+	 * @see IRemoteObjectIdentifier#getAbsoluteName(Object)
+	 * 
+	 * @param key the unique id of the remote object.
+	 *     Must not be <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.
+	 *     Extenders are encouraged to throw {@link SystemMessageException}
+	 *     in order to support good user feedback in case of errors.
+	 *     Since exceptions should only occur while retrieving new 
+	 *     remote objects during startup, clients are typically allowed 
+	 *     to ignore these exceptions and treat them as if the remote 
+	 *     object were simply not there.
 	 */
 	public Object getObjectWithAbsoluteName(String key) throws Exception;
 }

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

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2007 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
@@ -11,7 +11,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
@@ -31,12 +31,14 @@ import org.eclipse.rse.core.model.ISystemProfile;
 import org.eclipse.rse.services.clientserver.messages.SystemMessageException;
 
 /**
- * Interface implemented by SubSystem objects. While connections contain information to identify a 
+ * Interface implemented by SubSystem objects.
- * particular remote system, it is the subsystem objects within a connection that contain information
+ * 
- * unique to a particular tool, for that remote system, such as the port the tool uses and the 
+ * While connections contain information to identify a particular remote
- * user ID for making the connection. There are a set of default properties, but these can be
+ * system, it is the subsystem objects within a connection that contain
- * extended by subsystem providers, by extending SubSystem. 
+ * information unique to a particular tool for that remote system, such as
- * <p>
+ * the port the tool uses and the user ID for making the connection.
+ * There are a set of default properties, but these can be extended by 
+ * subsystem providers, by extending SubSystem. 
  */
 public interface ISubSystem extends ISystemFilterPoolReferenceManagerProvider, IRemoteObjectResolver, ISchedulingRule, IRSEModelObject {
 	// -------------------------------------
@@ -356,7 +358,7 @@ public interface ISubSystem extends ISystemFilterPoolReferenceManagerProvider, I
 	/**
 	 * Connect to the remote system. Does not force a prompt for a password.
 	 * 
-	 * @deprecated
+	 * @deprecated use {@link #connect(IProgressMonitor, boolean)}
 	 */
 	public void connect() throws Exception;
 	
@@ -368,7 +370,7 @@ public interface ISubSystem extends ISystemFilterPoolReferenceManagerProvider, I
 	 * @param forcePrompt forces the prompt dialog to be displayed even if the password is currently
 	 * in memory.
 	 * 
-	 * @deprecated
+	 * @deprecated use {@link #connect(IProgressMonitor, boolean)}
 	 */
 	public void connect(boolean forcePrompt) throws Exception;
 	
@@ -376,18 +378,18 @@ public interface ISubSystem extends ISystemFilterPoolReferenceManagerProvider, I
 	/**
 	 * Connect to the remote system from a background job
 	 * 
-	 * @param monitor the process monitor
+	 * @param monitor the process monitor. Must not be <code>null</code>.
 	 * 
-	 * @deprecated use connect(IProgressMonitor, boolean)
+	 * @deprecated use {@link #connect(IProgressMonitor, boolean)}
 	 */
 	public void connect(IProgressMonitor monitor) throws Exception;
 
 	/**
 	 * Connect to the remote system from a background job
 	 * 
-	 * @param monitor the process monitor
+	 * @param monitor the process monitor. Must not be <code>null</code>.
-	 * @param forcePrompt forces the prompt dialog to be displayed even if the password is currently
+	 * @param forcePrompt forces the prompt dialog to be displayed
-	 * in memory
+	 *     even if the password is currently in memory.
 	 */
 	public void connect(IProgressMonitor monitor, boolean forcePrompt) throws Exception;
 

rse/plugins/org.eclipse.rse.files.ui/src/org/eclipse/rse/internal/files/ui/view/SystemViewRemoteFileAdapter.java

@@ -13,6 +13,7 @@
  * Contributors:
  * Martin Oberhuber (Wind River) - [175262] IHost.getSystemType() should return IRSESystemType 
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.files.ui.view;
@@ -41,6 +42,7 @@ import org.eclipse.jface.resource.ImageDescriptor;
 import org.eclipse.jface.viewers.AbstractTreeViewer;
 import org.eclipse.jface.viewers.IStructuredSelection;
 import org.eclipse.jface.viewers.Viewer;
+import org.eclipse.rse.core.IRSESystemType;
 import org.eclipse.rse.core.RSECorePlugin;
 import org.eclipse.rse.core.SystemBasePlugin;
 import org.eclipse.rse.core.events.ISystemResourceChangeEvents;
@@ -1527,7 +1529,7 @@ public class SystemViewRemoteFileAdapter
 		{
 			IHost connection = connections[i];
 			IRemoteFileSubSystem anFS = RemoteFileUtility.getFileSubSystem(connection);
-			if ((anFS != null) && (anFS.getHost().getSystemType().getName().equals("Local"))) //$NON-NLS-1$
+			if ( anFS != null && IRSESystemType.SYSTEMTYPE_LOCAL_ID.equals(anFS.getHost().getSystemType().getId()))
 			{
 				return anFS;
 			}
@@ -2622,16 +2624,20 @@ public class SystemViewRemoteFileAdapter
 	// --------------------------------------------------------------------
 	// METHODS PRESCRIBED BY THE ISYSTEMREMOTEELEMENT ADAPTER INTERFACE...
 	// --------------------------------------------------------------------	
-	/**
+
-	 * Return fully qualified name that uniquely identifies this object within its subsystem
+	/*
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{
 		IRemoteFile file = (IRemoteFile) element;
 		return file.getAbsolutePath();
 	}
-	/**
+
-	 * Return fully qualified name that uniquely identifies this remote object's remote parent within its subsystem
+	/*
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.ui.view.ISystemRemoteElementAdapter#getAbsoluteParentName(java.lang.Object)
 	 */
 	public String getAbsoluteParentName(Object element)
 	{

rse/plugins/org.eclipse.rse.files.ui/src/org/eclipse/rse/internal/files/ui/view/SystemViewRemoteSearchResultAdapter.java

@@ -13,6 +13,7 @@
  * Contributors:
  * Martin Oberhuber (Wind River) - [180562] dont implement ISystemOutputRemoteTypes
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.files.ui.view;
@@ -308,9 +309,10 @@ public class SystemViewRemoteSearchResultAdapter extends AbstractSystemViewAdapt
 		return null;
 	}
 
-	/**
+	/*
-	  * Return the fully qualified name of this remote object. 
+	 * (non-Javadoc)
-	  */
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
+	 */
 	public String getAbsoluteName(Object element)
 	{
 		if (element instanceof IHostSearchResult)

rse/plugins/org.eclipse.rse.files.ui/src/org/eclipse/rse/internal/files/ui/view/SystemViewRemoteSearchResultSetAdapter.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2002, 2007 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
@@ -11,7 +11,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.files.ui.view;
@@ -39,14 +39,14 @@ import org.eclipse.rse.ui.view.ISystemRemoveElementAdapter;
 import org.eclipse.swt.widgets.Shell;
 import org.eclipse.ui.views.properties.IPropertyDescriptor;
 
-
 /**
  * Adapter for a search result set.
  */
 public class SystemViewRemoteSearchResultSetAdapter extends AbstractSystemViewAdapter implements ISystemRemoteElementAdapter, ISystemRemoveElementAdapter
 {
-
+	/**
-
+	 * Constructor.
+	 */
 	public SystemViewRemoteSearchResultSetAdapter()
 	{
 	}
@@ -173,7 +173,10 @@ public class SystemViewRemoteSearchResultSetAdapter extends AbstractSystemViewAd
 		return null;
 	} 
 	
-	
+	/*
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
+	 */
 	public String getAbsoluteName(Object element)
 	{
 		return null;

rse/plugins/org.eclipse.rse.processes.ui/src/org/eclipse/rse/internal/processes/ui/view/SystemViewRemoteProcessAdapter.java

@@ -12,6 +12,7 @@
  * 
  * Contributors:
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.processes.ui.view;
@@ -126,6 +127,10 @@ public class SystemViewRemoteProcessAdapter extends AbstractSystemViewAdapter
 		return allProperties.replace('|', '\t');
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
+	 */
 	public String getAbsoluteName(Object object)
 	{
 		IRemoteProcess process = (IRemoteProcess) object;

rse/plugins/org.eclipse.rse.shells.ui/src/org/eclipse/rse/shells/ui/view/SystemViewRemoteOutputAdapter.java

@@ -13,6 +13,7 @@
  * Contributors:
  * Martin Oberhuber (Wind River) - [180562] dont implement ISystemOutputRemoteTypes
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.shells.ui.view;
@@ -681,9 +682,10 @@ implements  ISystemViewElementAdapter, ISystemRemoteElementAdapter
 		return null;
 	}
 
-	/**
+	/*
-	  * Return the fully qualified name of this remote object. 
+	 * (non-Javadoc)
-	  */
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
+	 */
 	public String getAbsoluteName(Object element)
 	{
 		if (element instanceof IRemoteCommandShell)

rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/subsystems/IRemoteFileSubSystem.java

@@ -244,8 +244,16 @@ public interface IRemoteFileSubSystem extends ISubSystem {
 	public SystemRemoteResourceSet getRemoteFileObjects(List folderOrFileNames) throws SystemMessageException;
 	
 	/**
-	 * Given a fully qualified file or folder name, return an IRemoteFile object for it.
+	 * Given a fully qualified file or folder name, return an IRemoteFile
-	 * @param folderOrFileName Fully qualified folder or file name
+	 * object for it.
+	 * <p>
+	 * This may be a long-running operation involving remote system access
+	 * if the file with the given key is not found in the internal cache.
+	 * </p>
+	 * @param folderOrFileName Fully qualified folder or file name.
+	 * @return the requested IRemoteFile object.
+	 * @throws SystemMessageException in case an error occurs contacting the
+	 *     remote system while retrieving the requested remote object.
 	 */
 	public IRemoteFile getRemoteFileObject(String folderOrFileName) throws SystemMessageException;
 

rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/subsystems/RemoteFileSubSystem.java

@@ -14,6 +14,7 @@
  * Contributors:
  * Martin Oberhuber (Wind River) - Fix 162962 - recursive removeCachedRemoteFile()
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  *******************************************************************************/
 
 package org.eclipse.rse.subsystems.files.core.subsystems;
@@ -1065,21 +1066,35 @@ public abstract class RemoteFileSubSystem extends SubSystem implements IRemoteFi
 
 	/**
 	 * Return the object within the subsystem that corresponds to
-	 * the specified unique ID.  For remote files, assuming the key 
+	 * the specified unique ID.
-	 * is the absolute path of a file, this is simply a wrapper to
+	 * 
-	 * getRemoteFileObject(). 
+	 * For remote files, assuming the key is the absolute path of
+	 * a file, this is simply a wrapper to getRemoteFileObject().
+	 *  
+	 * @see SubSystem#getObjectWithAbsoluteName(String)
+	 * @param key the unique id of the remote object.
+	 *     Must not be <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.
+	 *     Extenders are encouraged to throw {@link SystemMessageException}
+	 *     in order to support good user feedback in case of errors.
+	 *     Since exceptions should only occur while retrieving new 
+	 *     remote objects during startup, clients are typically allowed 
+	 *     to ignore these exceptions and treat them as if the remote 
+	 *     object were simply not there.
 	 */
 	public Object getObjectWithAbsoluteName(String key) throws Exception
 	{
-		Object filterRef = getFilterReferenceWithAbsoluteName(key);
+		Object filterRef = super.getObjectWithAbsoluteName(key);
-		
 		if (filterRef != null) {
 			return filterRef;
 		}
 
 		// look to see if there is a search result delimiter
 		// if not, the key must be for a file
-		if (key.lastIndexOf(IHostSearchResult.SEARCH_RESULT_DELIMITER) == -1) {
+		if (key.lastIndexOf(IHostSearchResult.SEARCH_RESULT_DELIMITER) < 0) {
 		    
 		    IRemoteFile remoteFile = getRemoteFileObject(key);
 		

rse/plugins/org.eclipse.rse.subsystems.processes.core/src/org/eclipse/rse/subsystems/processes/core/subsystem/impl/RemoteProcessImpl.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2005, 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2005, 2007 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
@@ -11,11 +11,12 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.subsystems.processes.core.subsystem.impl;
 
+import org.eclipse.core.runtime.NullProgressMonitor;
 import org.eclipse.core.runtime.Platform;
 import org.eclipse.rse.core.SystemBasePlugin;
 import org.eclipse.rse.core.model.IHost;
@@ -32,8 +33,6 @@ import org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessSubSyst
  * with methods for returning information about the underlying process, as well
  * as more client-oriented methods for returning information about the associated
  * subsystem, connection, and filter string.
- * @author mjberger
- *
  */
 public class RemoteProcessImpl implements IRemoteProcess
 {
@@ -45,7 +44,7 @@ public class RemoteProcessImpl implements IRemoteProcess
     /**
      * Constructor that takes a context object containing important information.
      * @param context An object holding contextual information about this object
-     * @see org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessContext
+     * @see IRemoteProcessContext
      */ 
     public RemoteProcessImpl(IRemoteProcessContext context, IHostProcess process)
     {
@@ -55,7 +54,7 @@ public class RemoteProcessImpl implements IRemoteProcess
     	  try
     	  {
     	  	// deduce active shell from display
-    	    context.getParentRemoteProcessSubSystem().connect();
+    	    context.getParentRemoteProcessSubSystem().connect(new NullProgressMonitor(), false);
     	  } catch (Exception exc) {}
     	  
     	  _underlyingProcess = process;

rse/plugins/org.eclipse.rse.subsystems.processes.core/src/org/eclipse/rse/subsystems/processes/core/subsystem/impl/RemoteProcessSubSystemImpl.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2007 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
@@ -11,7 +11,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.subsystems.processes.core.subsystem.impl;
@@ -27,23 +27,18 @@ import org.eclipse.rse.core.subsystems.IConnectorService;
 import org.eclipse.rse.core.subsystems.SubSystem;
 import org.eclipse.rse.services.clientserver.messages.SystemMessageException;
 import org.eclipse.rse.services.clientserver.processes.HostProcessFilterImpl;
-import org.eclipse.rse.services.clientserver.processes.IHostProcessFilter;
 import org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcess;
 import org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessContext;
-import org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessSubSystemConfiguration;
 import org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessSubSystem;
+import org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessSubSystemConfiguration;
 
 /**
- * The implementation of the RemoteProcessSubSystem interface. 
+ * Default implementation of the IRemoteProcessSubSystem interface.
+ * <p> 
  * Some of the methods are simply convenience methods - these are
  * implemented here, whereas the real work takes place in the
- * ProcessServiceSubSystem. 
+ * ProcessServiceSubSystem.
- * @author mjberger
+ * </p>
- *
- */
-/**
- * @author mjberger
- *
  */
 public abstract class RemoteProcessSubSystemImpl extends SubSystem implements
 		IRemoteProcessSubSystem, ICommunicationsListener
@@ -55,7 +50,7 @@ public abstract class RemoteProcessSubSystemImpl extends SubSystem implements
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.RemoteProcessSubSystem#getParentRemoteProcessSubSystemConfiguration()
+	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessSubSystem#getParentRemoteProcessSubSystemConfiguration()
 	 */
 	public IRemoteProcessSubSystemConfiguration getParentRemoteProcessSubSystemConfiguration()
 	{
@@ -63,7 +58,7 @@ public abstract class RemoteProcessSubSystemImpl extends SubSystem implements
 	}
 
 	/* (non-Javadoc)
-	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.RemoteProcessSubSystem#isCaseSensitive()
+	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessSubSystem#isCaseSensitive()
 	 */
 	public boolean isCaseSensitive()
 	{
@@ -109,7 +104,7 @@ public abstract class RemoteProcessSubSystemImpl extends SubSystem implements
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.RemoteProcessSubSystem#getParentProcess(org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcess)
+	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessSubSystem#getParentProcess(org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcess)
 	 */
 	public IRemoteProcess getParentProcess(IRemoteProcess process)
 	{
@@ -158,34 +153,6 @@ public abstract class RemoteProcessSubSystemImpl extends SubSystem implements
 		return roots;
 	}
 
-	/* (non-Javadoc)
-	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.RemoteProcessSubSystem#listAllProcesses(org.eclipse.rse.services.clientserver.processes.IHostProcessFilter, org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcessContext)
-	 */
-	public abstract IRemoteProcess[] listAllProcesses(
-			IHostProcessFilter processNameFilter,
-			IRemoteProcessContext context,
-			IProgressMonitor monitor) throws InterruptedException,
-			SystemMessageException;
-
-	/* (non-Javadoc)
-	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.RemoteProcessSubSystem#getRemoteProcessObject(long)
-	 */
-	public abstract IRemoteProcess getRemoteProcessObject(long pid)
-			throws SystemMessageException;
-	
-	/* (non-Javadoc)
-	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.RemoteProcessSubSystem#kill(org.eclipse.rse.subsystems.processes.core.subsystem.IRemoteProcess, java.lang.String)
-	 */
-	public abstract boolean kill(IRemoteProcess process, String signal)
-			throws SystemMessageException;
-
-	/* (non-Javadoc)
-	 * @see org.eclipse.rse.subsystems.processes.core.subsystem.RemoteProcessSubSystem#getSignalTypes()
-	 */
-	public abstract String[] getSignalTypes() throws SystemMessageException;
-
-
-
 	/* (non-Javadoc)
 	 * @see org.eclipse.rse.core.subsystems.ICommunicationsListener#isPassiveCommunicationsListener()
 	 */

rse/plugins/org.eclipse.rse.subsystems.processes.core/src/org/eclipse/rse/subsystems/processes/servicesubsystem/ProcessServiceSubSystem.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2007 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
@@ -11,7 +11,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.subsystems.processes.servicesubsystem;
@@ -34,8 +34,6 @@ import org.eclipse.rse.subsystems.processes.core.subsystem.impl.RemoteProcessSub
 /**
  * The subsystem that, coupled with a ProcessService implementation,
  * can query and kill remote processes on a remote system.
- * @author mjberger
- *
  */
 public class ProcessServiceSubSystem extends RemoteProcessSubSystemImpl implements IProcessServiceSubSystem 
 {

rse/plugins/org.eclipse.rse.subsystems.shells.core/src/org/eclipse/rse/subsystems/shells/core/subsystems/RemoteCmdSubSystem.java

@@ -12,6 +12,7 @@
  * 
  * Contributors:
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.subsystems.shells.core.subsystems;
@@ -483,9 +484,23 @@ public abstract class RemoteCmdSubSystem extends SubSystem implements IRemoteCmd
 	}
 
 	/**
-	 * Return the object within the subsystem that corresponds to the specified
+	 * Return the object within the subsystem that corresponds to the 
-	 * unique ID. For remote command, the key is determined by the command ID
+	 * specified unique ID.
-	 * and the ouput ID
+	 * For remote command, the key is determined by the command ID
+	 * and the ouput ID.
+	 * 
+	 * @param key the unique id of the remote object.
+	 *     Must not be <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.
+	 *     Extenders are encouraged to throw {@link SystemMessageException}
+	 *     in order to support good user feedback in case of errors.
+	 *     Since exceptions should only occur while retrieving new 
+	 *     remote objects during startup, clients are typically allowed 
+	 *     to ignore these exceptions and treat them as if the remote 
+	 *     object were simply not there.
 	 */
 	public Object getObjectWithAbsoluteName(String key) throws Exception
 	{
@@ -510,15 +525,15 @@ public abstract class RemoteCmdSubSystem extends SubSystem implements IRemoteCmd
 				theCmd = cmd;
 			}
 		}
-		if (theCmd != null && outKey != null)
+		if (theCmd != null) {
-		{
+			if (outKey != null) {
-			int outIndex = Integer.parseInt(outKey);
+				int outIndex = Integer.parseInt(outKey);
-			return theCmd.getOutputAt(outIndex);
+				return theCmd.getOutputAt(outIndex);
-		}
+			}
-		else
-		{
 			return theCmd;
 		}
+		//fallback to return filter reference or similar
+		return super.getObjectWithAbsoluteName(key);
 	}
 
 	// called by subsystem on disconnect
@@ -858,7 +873,7 @@ public abstract class RemoteCmdSubSystem extends SubSystem implements IRemoteCmd
 	 * @param input the command to invoke in the shell.
 	 * @param commandObject the shell or command to send the invocation to.
 	 * 
-	 * @deprecated
+	 * @deprecated use {@link #sendCommandToShell(IProgressMonitor, String, Object)}
 	 */
 	public void sendCommandToShell(String input,  Object commandObject) throws Exception
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemView.java

@@ -19,6 +19,7 @@
  *                          - Several bugfixes.
  * David Dykstal (IBM) - moved SystemPreferencesManager to a new package
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -4313,30 +4314,31 @@ public class SystemView extends SafeTreeViewer
 	      {
 	          if(a==b) return true;
 	          if(a==null || b==null) return false;
+	          //TODO not sure if this equals() check is a good idea
+	          //It may be expensive and unnecessary
 	          if(a.equals(b)) return true;
 	 
-	          ISystemViewElementAdapter identa= null;
+	          if( (a instanceof IAdaptable) && (b instanceof IAdaptable) ) {
-	          if(a instanceof IAdaptable) {
+	        	  ISystemViewElementAdapter identa =
-	              identa = (ISystemViewElementAdapter)
+	        		  (ISystemViewElementAdapter)
-	                 ((IAdaptable)a).getAdapter(ISystemViewElementAdapter.class);
+	        		  ((IAdaptable)a).getAdapter(ISystemViewElementAdapter.class);
+	        	  ISystemViewElementAdapter identb = 
+	        		  (ISystemViewElementAdapter)
+	        		  ((IAdaptable)b).getAdapter(ISystemViewElementAdapter.class);
+	        	  if(identa != null && identb != null) {
+	        		  // first need to check subsystems
+	        		  ISubSystem ssa = identa.getSubSystem(a);
+	        		  ISubSystem ssb = identb.getSubSystem(b);
+	        		  if (ssa == ssb) {
+	        			  // if the subsystems are the same OR if both are null
+	        			  // (the absolute name will distinguish them)
+	        			  String ana = identa.getAbsoluteName(a);
+	        			  if (ana!=null) {
+	        				  return ana.equals(identb.getAbsoluteName(b));
+	        			  }
+		              }
+		          }
 	          }
-	          if(identa != null) {
-	              ISystemViewElementAdapter identb = null;
-	               if(b instanceof IAdaptable) {
-	                  identb = (ISystemViewElementAdapter)
-	                     ((IAdaptable)b).getAdapter(ISystemViewElementAdapter.class);
-	              }
-	              if (identb != null){
-	            	  // first need to check subsystems
-	            	  ISubSystem ssa = identa.getSubSystem(a);
-	            	  ISubSystem ssb = identb.getSubSystem(b);
-	            	  if (ssa == ssb) // if the subsystems are the same OR if both are not subsystems (the absolute name will distinguish them)
-	            	  {
-	            		  if(identa.getAbsoluteName(a).equals(identb.getAbsoluteName(b))) return true;
-	            	  }
-	              }
-	          }
-	          
 	          return false;
 	      }
 	      

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewConnectionAdapter.java

@@ -17,6 +17,7 @@
  * David Dykstal (IBM) - 180562: remove implementation of IRSEUserIdConstants
  * Martin Oberhuber (Wind River) - [175262] IHost.getSystemType() should return IRSESystemType 
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -365,8 +366,9 @@ public class SystemViewConnectionAdapter
 		return conn.getAliasName();
 	}
 
-	/**
+	/*
-	 * Return the absolute name, versus just display name, of this object
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewFilterAdapter.java

@@ -12,6 +12,7 @@
  * 
  * Contributors:
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -140,8 +141,10 @@ public class SystemViewFilterAdapter extends AbstractSystemViewAdapter
 	{
 		return getFilter(element).getName();
 	}
-	/**
+	
-	 * Return the absolute name, versus just display name, of this object
+	/*
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewFilterPoolAdapter.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2002, 2007 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
@@ -11,7 +11,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -120,8 +120,10 @@ public class SystemViewFilterPoolAdapter extends AbstractSystemViewAdapter
 	{
 		return ((ISystemFilterPool)element).getName();
 	}
-	/**
+	
-	 * Return the absolute name, versus just display name, of this object
+	/*
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewFilterPoolReferenceAdapter.java

@@ -12,6 +12,7 @@
  * 
  * Contributors:
  * Tobias Schwarz (Wind River) - [181394] Include Context in getAbsoluteName() for filter and pool references
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -168,8 +169,9 @@ public class SystemViewFilterPoolReferenceAdapter
 		return getFilterPool(element).getName();
 	}
 	
-	/**
+	/*
-	 * Return the absolute name, versus just display name, of this object
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewFilterReferenceAdapter.java

@@ -14,6 +14,7 @@
  * David Dykstal (IBM) - moved SystemsPreferencesManager to a new package
  * Tobias Schwarz (Wind River) - [181394] Include Context in getAbsoluteName() for filter and pool references
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -189,8 +190,9 @@ public class SystemViewFilterReferenceAdapter
 		return getFilter(element).getName();
 	}
 	
-	/**
+	/*
-	 * Return the absolute name, versus just display name, of this object
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewFilterStringAdapter.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2002, 2007 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
@@ -11,7 +11,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -104,8 +104,10 @@ public class SystemViewFilterStringAdapter extends AbstractSystemViewAdapter
 	{
 		return getFilterString(element).getString();
 	}
-	/**
+	
-	 * Return the absolute name, versus just display name, of this object
+	/*
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewMessageAdapter.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2002, 2007 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
@@ -11,7 +11,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -75,9 +75,10 @@ public class SystemViewMessageAdapter
 		ISystemMessageObject msg = (ISystemMessageObject)element;
 		return msg.getMessage();
 	}
-	/**
+	
-	 * Return the absolute name, versus just display name, of this object. 
+	/*
-	 * Just uses getText(element);
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewPromptableAdapter.java

@@ -12,6 +12,7 @@
  * 
  * Contributors:
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -75,9 +76,10 @@ public class SystemViewPromptableAdapter
 	{
 		return ((ISystemPromptableObject)element).getText();
 	}
-	/**
+	
-	 * Return the absolute name, versus just display name, of this object. 
+	/*
-	 * Just uses getText(element);
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewRootInputAdapter.java

@@ -13,6 +13,7 @@
  * Contributors:
  * David Dykstal (IBM) - moved SystemsPreferencesManager to a new package
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -78,9 +79,10 @@ public class SystemViewRootInputAdapter extends AbstractSystemViewAdapter
 	{
 		return SystemResources.RESID_SYSTEMREGISTRY_CONNECTIONS; 
 	}
-	/**
+	
-	 * Return the absolute name, versus just display name, of this object. 
+	/*
-	 * Just uses getText(element);
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewScratchpadAdapter.java

@@ -12,6 +12,7 @@
  * 
  * Contributors:
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -80,9 +81,10 @@ public class SystemViewScratchpadAdapter extends AbstractSystemViewAdapter imple
 		//return SystemResources.RESID_SYSTEMREGISTRY_CONNECTIONS); 
 		return "Remote Scratchpad"; //$NON-NLS-1$
 	}
-	/**
+	
-	 * Return the absolute name, versus just display name, of this object. 
+	/*
-	 * Just uses getText(element);
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemViewSubSystemAdapter.java

@@ -12,6 +12,7 @@
  * 
  * Contributors:
  * David Dykstal (IBM) - 180562: remove implementation of IRSEUserIdConstants
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view;
@@ -139,9 +140,10 @@ public class SystemViewSubSystemAdapter extends AbstractSystemViewAdapter
 	{
 		return ((ISubSystem)element).getName();
 	}
-	/**
+	
-	 * Return the absolute name, versus just display name, of this object. 
+	/*
-	 * Returns profileName.connectionName.subsystemName;
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/team/SystemTeamViewCategoryAdapter.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2007 IBM Corporation. All rights reserved.
+ * Copyright (c) 2002, 2007 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:
  * David Dykstal (IBM) - 180562: remove implementation of IRSEUserIdConstants
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view.team;
@@ -98,8 +99,9 @@ public class SystemTeamViewCategoryAdapter
 		return category.getLabel();
 	}
 
-	/**
+	/*
-	 * Return the absolute name, versus just display name, of this object
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/team/SystemTeamViewProfileAdapter.java

@@ -13,6 +13,7 @@
  * Contributors:
  * David Dykstal (IBM) - 180562: remove implementation of IRSEUserIdConstants
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view.team;
@@ -169,8 +170,9 @@ public class SystemTeamViewProfileAdapter
 		return ((ISystemProfile)element).getName();
 	}
 
-	/**
+	/*
-	 * Return the absolute name, versus just display name, of this object
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/team/SystemTeamViewSubSystemConfigurationAdapter.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2006, 2007 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
@@ -11,7 +11,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.internal.ui.view.team;
@@ -127,8 +127,9 @@ public class SystemTeamViewSubSystemConfigurationAdapter
 		return ((SystemTeamViewSubSystemConfigurationNode)element).getLabel();
 	}
 
-	/**
+	/*
-	 * Return the absolute name, versus just display name, of this object
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element)
 	{

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

@@ -14,6 +14,7 @@
  * Uwe Stieber (Wind River) - Allow to extend action filter by dynamic system type providers.
  * Martin Oberhuber (Wind River) - [175262] IHost.getSystemType() should return IRSESystemType 
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.ui.view;
@@ -423,15 +424,6 @@ public abstract class AbstractSystemViewAdapter implements ISystemViewElementAda
 	{
 		return getText(element);
 	}
-    /**
-     * <i><b>Abstract</b></i>. <i>Must be overridden.</i><br>.
-     * Return the fully-qualified name, versus just the displayable name, for this object.
-     * For remote objects, this should be sufficient to uniquely identify this object within its
-     *  subsystem.
-	 * @see #getText(Object)
-	 * @see #getName(Object)
-	 */
-	public abstract String getAbsoluteName(Object object);	
 	
 	/**
      * <i>Internal use. Can be safely ignored.</i><br>

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

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2002, 2006 IBM Corporation. All rights reserved.
+ * Copyright (c) 2002, 2007 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
@@ -11,7 +11,7 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.ui.view;
@@ -33,89 +33,150 @@ public interface ISystemRemoteElementAdapter extends IRemoteObjectIdentifier
 {
 	/**
 	 * Return the name of this object, which may be different than
-	 * the display text ({#link #getText(Object)}.
+	 * the display text ({@link #getText(Object)}).
+	 * <p>
+	 * The unqualified name is used for checking uniqueness during rename
+	 * operations.
+	 * </p>
+	 * @param element the element for which to return the internal name.
+	 * @return a String representing the internal name of the given element.
 	 */
 	public String getName(Object element);
 	
 	/**
-   * Return the label for this object.
+	 * Return the label for this object.
-   * @see #getName(Object)
+	 * @see #getName(Object)
-   * @see #getAbsoluteName(Object)
+	 * @param element the element for which to return the internal name.
-   */
+	 * @return a String representing the UI visible label of the given element.
-  public String getText(Object element);
-
-	/**
-	 * Return the fully qualified name of this remote object. 
-	 * Unlike getName, this should include the full path to the name.
-	 * This should be enough information to uniquely identify this object within its subsystem.
 	 */
-	public String getAbsoluteName(Object element);
+	public String getText(Object element);
+
     /**
-     * Return fully qualified name that uniquely identifies this remote object's remote parent within its subsystem.
+     * Return fully qualified name that uniquely identifies this remote object's
-     * This is used when deleting a remote resource for example, all occurrences of its parent are found and refreshed in the RSE views.
+     * remote parent within its subsystem.
+     * <p>
+     * This is used when deleting a remote resource for example, all occurrences of
+     * its parent are found and refreshed in the RSE views.
+     * </p><p>
+     * Note that when using filters, there is no unique parent since the same object
+     * may be found in multiple contexts, below multiple filters. Still, returning
+     * the parent absolute name here may help finding potentially affected parents
+     * more easily.
+     * </p>
+     * @see #getAbsoluteName(Object)
+     * 
+     * @return a String uniquely identifying the parent of this remote object,
+     *     if it is known and exists. May also return <code>null</code> if the
+     *     parent can not be determined or is not unique. 
      */
     public String getAbsoluteParentName(Object element);
+    
 	/**
 	 * Return the subsystem that is responsible for getting this remote object.
-	 * When used together with getAbsoluteName, allows for unique identification of this object.
+	 * <p>
+	 * When used together with getAbsoluteName, allows for unique
+	 * identification of this object.
+	 * </p>
+	 * @return the subsystem owning this remote object.
+	 *     Must not return <code>null</code>.
 	 */
 	public ISubSystem getSubSystem(Object element);
+
 	/**
-	 * Return the subsystem factory id that owns this remote object
+	 * Return the subsystem factory id that owns this remote object.
-	 * The value must not be translated, so that property pages registered via xml can subset by it.
+	 * <p>
+	 * The value must not be translated, so that property pages registered
+	 * via xml can subset by it.
+	 * </p>
+	 * @return the ID of the subsystem configuration that created
+	 *     the subsystem which owns this remote object.
 	 */
 	public String getSubSystemConfigurationId(Object element);	
+
 	/**
-	 * Return a value for the type category property for this object
+	 * Return a value for the type category property for this object.
-	 * The value must not be translated, so that property pages registered via xml can subset by it.
+	 * <p>
+	 * The value must not be translated, so that property pages registered
+	 * via xml can subset by it.
+	 * </p>
+	 * @return the category id of this remote object for filtering.
 	 */
 	public String getRemoteTypeCategory(Object element);	
+
 	/**
-	 * Return a value for the type property for this object
+	 * Return a value for the type property for this object.
-	 * The value must not be translated, so that property pages registered via xml can subset by it.
+	 * <p>
+	 * The value must not be translated, so that property pages registered
+	 * via xml can subset by it.
+	 * </p>
+	 * @return the type id of this remote object for filtering.
 	 */
 	public String getRemoteType(Object element);	
+
 	/**
 	 * Return a value for the subtype property for this object.
+	 * <p>
 	 * Not all object types support a subtype, so returning null is ok.
-	 * The value must not be translated, so that property pages registered via xml can subset by it.
+	 * The value must not be translated, so that property pages registered
+	 * via xml can subset by it.
+	 * </p>
+	 * @return the subtype id of this remote object for filtering.
+	 *     May return <code>null</code>.
 	 */
 	public String getRemoteSubType(Object element);	
+
 	/**
 	 * Return a value for the sub-subtype property for this object.
+	 * <p>
 	 * Not all object types support a sub-subtype, so returning null is ok.
-	 * The value must not be translated, so that property pages registered via xml can subset by it.
+	 * The value must not be translated, so that property pages registered
+	 * via xml can subset by it.
+	 * </p>
+	 * @return the subsubtype id of this remote object for filtering.
+	 *     May return <code>null</code>.
 	 */
 	public String getRemoteSubSubType(Object element);	
+
 	/**
-	 * Return the source type of the selected object. Typically, this only makes sense for compilable
+	 * Return the source type of the selected object.
-	 *  source members. For non-compilable remote objects, this typically just returns null.
+	 * <p>
+	 * Typically, this only makes sense for compilable source members.
+	 * For non-compilable remote objects, this typically just returns null.
+	 * </p>
+	 * @return the sourcetype id of this remote object,
+	 *     or <code>null</code> if not applicable.
 	 */
 	public String getRemoteSourceType(Object element);
+
 	/**
-	 * <p>Short answer: treat this like clone(), and just copy any important instance variables</p>
+	 * Update a visible remote object with fresh data from a new object.
 	 * <p>
+	 * Short answer: treat this like clone(), and just copy any important
+	 * instance variables. This allows keeping TreeItem references intact
+	 * but refreshing the data shown, such that selections and expand state
+	 * in the tree remain intact. 
+	 * </p><p>
 	 * Imagine the same remote resource is shown multiple times in the same tree view.... say
-	 *  because multiple filters resolve to it, or there are two connections to the same host. 
+	 * because multiple filters resolve to it, or there are two connections to the same host. 
-	 *  Typically it is a different object in memory within the tree, but it refers to the same
+	 * Typically it is a different object in memory within the tree, but it refers to the same
-	 *  remote resource. <br>
+	 * remote resource. <br>
 	 * Now imagine one of the references is selected by the user and renamed via the rename action. This
-	 *  might only update the selected reference. What about the other objects which refer to the same
+	 * might only update the selected reference. What about the other objects which refer to the same
-	 *  remote resource... they need to update their in-memory "name" variable too. <br>
+	 * remote resource... they need to update their in-memory "name" variable too. <br>
 	 * That is what this method. Every reference to the same remote resource is found (they have the 
-	 *  same absolute name and come from a system with the same hostname) and this method is called
+	 * same absolute name and come from a system with the same hostname) and this method is called
-	 *  on those other references. This is your opportunity to copy the attributes from the new element
+	 * on those other references. This is your opportunity to copy the attributes from the new element
-	 *  to the old element. 
+	 * to the old element. 
-	 * <p>
+	 * </p><p>
 	 * Some view has updated the name or properties of this remote object. As a result, the 
-	 *  remote object's contents need to be refreshed. You are given the old remote object that has
+	 * remote object's contents need to be refreshed. You are given the old remote object that has
-	 *  old data, and you are given the new remote object that has the new data. For example, on a
+	 * old data, and you are given the new remote object that has the new data. For example, on a
-	 *  rename the old object still has the old name attribute while the new object has the new 
+	 * rename the old object still has the old name attribute while the new object has the new 
-	 *  new attribute. You can copy the new name into the old object. Similar for any properties
+	 * new attribute. You can copy the new name into the old object. Similar for any properties
-	 *  you allow the user to edit via the property sheet.
+	 * you allow the user to edit via the property sheet.
-	 * <p>
+	 * </p><p>
 	 * This is called by viewers like SystemView in response to rename and property change events.
-	 * <p>
+	 * </p><p>
 	 * @param oldElement the element that was found in the tree
 	 * @param newElement the updated element that was passed in the REFRESH_REMOTE event
 	 * @return true if you want the viewer that called this to refresh the children of this object,
@@ -124,9 +185,9 @@ public interface ISystemRemoteElementAdapter extends IRemoteObjectIdentifier
 	 */
 	public boolean refreshRemoteObject(Object oldElement, Object newElement);
 	
-	
 	/**
 	 * Return the remote edit wrapper for this object.
+	 * 
 	 * @param object the object to edit
 	 * @return the editor wrapper for this object
 	 */
@@ -147,23 +208,43 @@ public interface ISystemRemoteElementAdapter extends IRemoteObjectIdentifier
 	public String getFilterStringFor(Object object);
 	
 	/**
-	 * Given a remote object, returns it remote parent object. Eg, given a file, return the folder
+	 * Given a remote object, returns it remote parent object.
-	 *  it is contained in.
+	 * <p>
+	 * For instance, given a file, return the folder it is contained in.
+	 * Not all subsystems support a unique parent-child relationship.
+	 * Therefore, it is acceptable to return <code>null</code>.
+	 * </p>
+	 * @see #getAbsoluteParentName(Object)
+	 * 
+	 * @param shell FIXME why is this needed? Should be removed
+	 * @param element The element for which to get the parent
+	 * @return the parent element, or <code>null</code> if not applicable.
 	 */
 	public Object getRemoteParent(Shell shell, Object element) throws Exception;
+
 	/**
-	 * Given a remote object, return the unqualified names of the objects <i>contained</i> in that parent. This is
+	 * Given a remote object, return the unqualified names of the objects
-	 *  used for testing for uniqueness on a rename operation, for example. Sometimes, it is not 
+	 * <i>contained</i> in that parent.
-	 *  enough to just enumerate all the objects in the parent for this purpose, because duplicate
+	 * <p>
-	 *  names are allowed if the types are different, such as on iSeries. In this case return only 
+	 * This is used for testing for uniqueness on a rename operation, for example.
-	 *  the names which should be used to do name-uniqueness validation on a rename operation.
+	 * Sometimes, it is not enough to just enumerate all the objects in the parent
+	 * for this purpose, because duplicate names are allowed if the types are
+	 * different, such as on iSeries. In this case return only the names which
+	 * should be used to do name-uniqueness validation on a rename operation.
+	 * </p>
+	 * @param shell FIXME why is this needed? Should be removed
+	 * @param element The element for which to get names in use
+	 * @return a list of unqualified names contained in this folder to check
+	 *    for uniqueness. FIXME may this return null? 
 	 */
 	public String[] getRemoteParentNamesInUse(Shell shell, Object element) throws Exception;
 	
 	/**
 	 * Returns whether user defined actions should be shown for the object.
+	 * 
 	 * @param object the object.
-	 * @return <code>true</code> if the object supports user defined actions, <code>false</code> otherwise.
+	 * @return <code>true</code> if the object supports user defined actions,
+	 *     <code>false</code> otherwise.
 	 */
 	public boolean supportsUserDefinedActions(Object object);
 }

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

@@ -18,6 +18,7 @@
  * David Dykstal (IBM) - 142806: refactoring persistence framework
  * Martin Oberhuber (Wind River) - [168975] Move RSE Events API to Core
  * Martin Oberhuber (Wind River) - [183165] Do not implement constant interfaces
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  ********************************************************************************/
 
 package org.eclipse.rse.core.subsystems;
@@ -754,35 +755,49 @@ public abstract class SubSystem extends RSEModelObject
 	// --------------------------------------------------------------------------------------
 	// Methods for encoding and decoding remote objects for drag and drop, and clipboard copy
 	// --------------------------------------------------------------------------------------
-		
+
-	
 	/**
-	 * For drag and drop, and clipboard, support of remote objects.
+	 * Return the remote object that corresponds to the specified unique ID.
 	 * <p>
-	 * Return the object within the subsystem that corresponds to
+	 * Since the abstract subsystem implementation does not know anything
-	 * the specified unique ID.  Because each subsystem maintains it's own
+	 * about the specific kinds of resources managed by concrete
-	 * objects, it's the responsability of the subsystem to determine
+	 * implementations, this method can only resolve filter references.
-	 * how an ID (or key) for a given object maps to the real object.
+	 * </p><p>
-	 * By default this returns null. 
+	 * <strong>subsystem implementations must override this method
-	 * <p>
+	 * in order to resolve IDs for the remote objects they manage, 
-	 * This is the functional opposite of {@link org.eclipse.rse.ui.view.ISystemRemoteElementAdapter#getAbsoluteName(Object)}.
+	 * to support drag and drop, clipboard copy and other remote object 
+	 * resolving schemes.</strong>
+	 * Extenders that want to support filters should call
+	 * <code>super.getObjectWithAbsoluteName(key)</code>
+	 * when they do not find a reference for the key themselves.
+	 * </p>
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectResolver#getObjectWithAbsoluteName(java.lang.String)
+	 * 
+	 * @param key the unique id of the remote object.
+	 *     Must not be <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.
+	 *     Extenders are encouraged to throw {@link SystemMessageException}
+	 *     in order to support good user feedback in case of errors.
+	 *     Since exceptions should only occur while retrieving new 
+	 *     remote objects during startup, clients are typically allowed 
+	 *     to ignore these exceptions and treat them as if the remote 
+	 *     object were simply not there.
 	 */
 	public Object getObjectWithAbsoluteName(String key) throws Exception
 	{
-		// by default, the subsystem will attempt to find a filter reference for the key
+		// by default, the subsystem will attempt to find a filter reference for the key.
-		Object filterRef = getFilterReferenceWithAbsoluteName(key);
+		// Return null when no such filter is found.
-		if (filterRef != null)
+		return getFilterReferenceWithAbsoluteName(key);
-		{
-			return filterRef;
-		}
-		return null;	
 	}
-	
+
 	/**
 	 * Return the filter reference that corresponds to the specified key.  If there
-	 * is no such filter reference, return null;
 	 * @param key the absolute name for an object.
-	 * @return a filter reference if there is one matching the key
+	 * @return a filter reference if there is one matching the key,
+	 *     or <code>null</code> if no such filter is found.
 	 */
 	protected Object getFilterReferenceWithAbsoluteName(String key)
 	{

rse/plugins/org.eclipse.rse.useractions/src/org/eclipse/rse/internal/useractions/ui/compile/teamview/SystemTeamViewCompileCommandAdapter.java

@@ -1,5 +1,3 @@
-package org.eclipse.rse.internal.useractions.ui.compile.teamview;
-
 /*******************************************************************************
  * Copyright (c) 2002, 2007 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
@@ -9,7 +7,11 @@ package org.eclipse.rse.internal.useractions.ui.compile.teamview;
  * 
  * Contributors:
  *     IBM Corporation - initial API and implementation
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  *******************************************************************************/
+
+package org.eclipse.rse.internal.useractions.ui.compile.teamview;
+
 import org.eclipse.core.runtime.IAdaptable;
 import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.jface.resource.ImageDescriptor;
@@ -80,8 +82,9 @@ public class SystemTeamViewCompileCommandAdapter extends AbstractSystemViewAdapt
 		return ((SystemTeamViewCompileCommandNode) element).getLabel();
 	}
 
-	/**
+	/*
-	 * Return the absolute name, versus just display name, of this object
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element) {
 		SystemTeamViewCompileCommandNode cmd = (SystemTeamViewCompileCommandNode) element;

rse/plugins/org.eclipse.rse.useractions/src/org/eclipse/rse/internal/useractions/ui/compile/teamview/SystemTeamViewCompileTypeAdapter.java

@@ -1,5 +1,3 @@
-package org.eclipse.rse.internal.useractions.ui.compile.teamview;
-
 /*******************************************************************************
  * Copyright (c) 2002, 2007 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
@@ -9,7 +7,11 @@ package org.eclipse.rse.internal.useractions.ui.compile.teamview;
  * 
  * Contributors:
  *     IBM Corporation - initial API and implementation
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  *******************************************************************************/
+
+package org.eclipse.rse.internal.useractions.ui.compile.teamview;
+
 import org.eclipse.core.runtime.IAdaptable;
 import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.jface.resource.ImageDescriptor;
@@ -80,8 +82,9 @@ public class SystemTeamViewCompileTypeAdapter extends AbstractSystemViewAdapter
 		return ((SystemTeamViewCompileTypeNode) element).getLabel();
 	}
 
-	/**
+	/*
-	 * Return the absolute name, versus just display name, of this object
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element) {
 		SystemTeamViewCompileTypeNode type = (SystemTeamViewCompileTypeNode) element;

rse/plugins/org.eclipse.rse.useractions/src/org/eclipse/rse/internal/useractions/ui/compile/teamview/SystemTeamViewUserActionAdapter.java

@@ -1,5 +1,3 @@
-package org.eclipse.rse.internal.useractions.ui.compile.teamview;
-
 /*******************************************************************************
  * Copyright (c) 2002, 2007 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
@@ -9,7 +7,11 @@ package org.eclipse.rse.internal.useractions.ui.compile.teamview;
  * 
  * Contributors:
  *     IBM Corporation - initial API and implementation
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  *******************************************************************************/
+
+package org.eclipse.rse.internal.useractions.ui.compile.teamview;
+
 import org.eclipse.core.runtime.IAdaptable;
 import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.jface.resource.ImageDescriptor;
@@ -88,8 +90,9 @@ public class SystemTeamViewUserActionAdapter extends AbstractSystemViewAdapter i
 		return action.getName();
 	}
 
-	/**
+	/*
-	 * Return the absolute name, versus just display name, of this object
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element) {
 		SystemUDActionElement action = (SystemUDActionElement) element;

rse/tests/org.eclipse.rse.tests/src/org/eclipse/rse/tests/internal/testsubsystem/TestSubSystem.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006 Wind River Systems, Inc. and others.
+ * Copyright (c) 2006, 2007 Wind River Systems, Inc. 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: 
  * Tobias Schwarz (Wind River) - initial API and implementation
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  *******************************************************************************/
 package org.eclipse.rse.tests.internal.testsubsystem;
 
@@ -66,15 +67,14 @@ public class TestSubSystem extends SubSystem implements ITestSubSystem {
 	/* (non-Javadoc)
 	 * @see org.eclipse.rse.core.subsystems.SubSystem#getObjectWithAbsoluteName(java.lang.String)
 	 */
-	public Object getObjectWithAbsoluteName(String key) {
+	public Object getObjectWithAbsoluteName(String key) throws Exception {
 		ITestSubSystemNode[] childs = getChildNodes();
 		for (int i = 0; i < childs.length; i++) {
 			if (childs[i].getName().equalsIgnoreCase(key)) {
 				return childs[i];
 			}
 		}
-
+		return super.getObjectWithAbsoluteName(key);
-		return null;
 	}
 
 	/* (non-Javadoc)

rse/tests/org.eclipse.rse.tests/src/org/eclipse/rse/tests/internal/testsubsystem/TestSubSystemNodeAdapter.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2006 Wind River Systems, Inc. and others.
+ * Copyright (c) 2006, 2007 Wind River Systems, Inc. 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: 
  * Tobias Schwarz (Wind River) - initial API and implementation
+ * Martin Oberhuber (Wind River) - [182454] improve getAbsoluteName() documentation
  *******************************************************************************/
 package org.eclipse.rse.tests.internal.testsubsystem;
 
@@ -75,8 +76,9 @@ public class TestSubSystemNodeAdapter extends AbstractSystemViewAdapter
 		return null;
 	}
 
-	/* (non-Javadoc)
+	/*
-	 * @see org.eclipse.rse.ui.view.AbstractSystemViewAdapter#getAbsoluteName(java.lang.Object)
+	 * (non-Javadoc)
+	 * @see org.eclipse.rse.core.subsystems.IRemoteObjectIdentifier#getAbsoluteName(java.lang.Object)
 	 */
 	public String getAbsoluteName(Object element) {
 		if (isTestSubSystemNode(element)) {