[cleanup] Fix compiler warnings and add Javadoc for IPropertySet

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

@@ -11,27 +11,140 @@
  * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley.
  * 
  * Contributors:
- * {Name} (company) - description of contribution.
+ * Martin Oberhuber (Wind River) - Added Javadoc.
  ********************************************************************************/
 
 package org.eclipse.rse.core.model;
 
 import java.util.Map;
 
+/**
+ * A Property Set stores key/value pairs, where the keys
+ * are Strings and the values are an {@link IProperty}, 
+ * of a type declared by an {@link IPropertyType}. 
+ * 
+ * The Property Set is identified by a name.
+ * By default, the type of each property is of type String, and
+ * in fact each value can be retrieved in String representation.
+ * 
+ * The key <code>"description"</code> is reserved for internal
+ * use, to store the description of the Property set.
+ */
 public interface IPropertySet 
 {
+	/** The key used to store the description of the Property Set. */
+	public static final String DESCRIPTION_KEY = "description"; //$NON-NLS-1$ 
+	
+	/** 
+	 * Return the name of this Property Set.
+	 * @return String name of the Property Set.
+	 */
 	public String getName();
+
+	/** 
+	 * Return the description of this Property Set.
+	 * 
+	 * Note that in order to set the description, you need to call
+	 * <code>setProperty(IPropertySet.DESCRIPTION_KEY, "Description");</code>
+	 * 
+	 * @return Description of the Property Set, 
+	 * 		or <code>null</code> in case no description has been set.
+	 */
 	public String getDescription();
+
+	/** 
+	 * Return the {@link IProperty} associated with the given key.
+	 * 
+	 * If the key is not in the set, <code>null</code> is returned.
+	 * 
+	 * @param key String key for Property
+	 * @return requested Property, 
+	 * 		or <code>null</code> if the key is not found in the set. 
+	 */
 	public IProperty getProperty(String key);
+
+	/** 
+	 * Return the String representation of a Property. 
+	 * 
+	 * Provided that the key is found in the set, this is a shortcut 
+	 * for getProperty(key).getValue(). If the key is not in the set,
+	 * <code>null</code> is returned.
+	 * 
+	 * @param key String key for Property
+	 * @return String value of requested Property,
+	 * 		or <code>null</code> if the key is not found in the set. 
+	 */
 	public String getPropertyValue(String key);
+
+	/**
+	 * Return the list of Property Keys in this Set.
+	 * 
+	 * Provided that the Set has a description, the 
+	 * @link{DESCRIPTION_KEY} key will also be in the list.
+	 * 
+	 * @return String array of Property keys.
+	 */
 	public String[] getPropertyKeys();
+	
+	/**
+	 * Return the type of the property identified by the given key.
+	 * 
+	 * @param key String key for Property
+	 * @return Type of requested Property,
+	 * 		or <code>null</code> if the key is not found in the set.
+	 */
 	public IPropertyType getPropertyType(String key);
-	
+
+	/**
+	 * Set the name of this Property Set.
+	 * @param name the name to set. Must not be <code>null</code>
+	 */
 	public void setName(String name);
-	public void setProperties(Map map);
 	
+	/**
+	 * Set all the Properties of this set.
+	 * 
+	 * @param map a Map of String to {@link IProperty} associations.
+	 */
+	public void setProperties(Map map);
+
+	/**
+	 * Add a Property with String value to the set.
+	 * 
+	 * In case a Property already exist for the given key, it will be overwritten
+	 * by the new value, note that this will <b>not</b> change the Property's type,
+	 * so if the key identifies an integer Property but you set it to String value
+	 * "foo" the resulting Property Set will be inconsistent.
+	 * 
+	 * If the Property does not yet exist in the set, a new key will be added and
+	 * the new Property will be of type "String".
+	 * 
+	 * @param key Key to add
+	 * @param value Value to add
+	 * @return The added Property
+	 */
 	public IProperty addProperty(String key, String value);
+
+	/**
+	 * Add a typed Property to the set.
+	 * 
+	 * In case a Property already exists for the given key, it will be 
+	 * removed and replaced by the new one.
+	 * 
+	 * @param key Key to add
+	 * @param value Value to add
+	 * @param type Type of the Property to add
+	 * @return The added Property
+	 */
 	public IProperty addProperty(String key, String value, IPropertyType type);
+
+	/**
+	 * Remove a Property from the set.
+	 * 
+	 * @param key The key to remove
+	 * @return <code>true</code> if the Property has been removed,
+	 *      or <code>false</code> if the key has not been part of the set.
+	 */
 	public boolean removeProperty(String key);
 
 }

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

@@ -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) - Added Javadoc.
  ********************************************************************************/
 
 package org.eclipse.rse.core.model;
@@ -21,7 +21,12 @@ import java.util.Map;
 import java.util.Set;
 
 
-
+/**
+ * A Hashmap based implementation of the {@link IPropertySet} interface.
+ * 
+ * Not thread-safe since the underlying {@link java.util.HashMap} is 
+ * not thread-safe.
+ */
 public class PropertySet implements IPropertySet 
 {
 	private String _name;
@@ -29,6 +34,10 @@ public class PropertySet implements IPropertySet
 	
 	protected static IPropertyType _defaultType =  PropertyType.getStringPropertyType();
 	
+	/**
+	 * Construct a new PropertySet based on an existing one (i.e. clone it).
+	 * @param propertySet existing Property Set to clone
+	 */
 	public PropertySet(IPropertySet propertySet)
 	{
 		_name = propertySet.getName();
@@ -43,6 +52,10 @@ public class PropertySet implements IPropertySet
 		}
 	}
 	
+	/**
+	 * Construct a new empty PropertySet.
+	 * @param name of the new PropertySet
+	 */
 	public PropertySet(String name)
 	{
 		_name= name;
@@ -56,7 +69,8 @@ public class PropertySet implements IPropertySet
 	
 	public String getDescription() 
 	{
-		return getPropertyValue("description");
+		//FIXME it would be better to return an empty String ("") in case no description has been set.
+		return getPropertyValue(DESCRIPTION_KEY);
 	}	
 	
 	public String[] getPropertyKeys() 
@@ -73,9 +87,21 @@ public class PropertySet implements IPropertySet
 
 	public void setProperties(Map map) 
 	{
+		//FIXME should clone the map!!
+		//Since the extrnal map might not be writable, or it might be
+		//modified later on
 		_properties = map;
 	}
 	
+	/**
+	 * Add a typed Property to the set.
+	 * 
+	 * In case a Property already exists for the given key, it will be overwritten.
+	 * 
+	 * @param key Key to add
+	 * @param property The Property to add
+	 * @return The added Property
+	 */
 	public IProperty addProperty(String key, IProperty property)
 	{
 		_properties.put(key, property);
@@ -87,6 +113,8 @@ public class PropertySet implements IPropertySet
 		IProperty property = getProperty(key);
 		if (property != null)
 		{
+			//FIXME should throw a NumberFormatException or similar,
+			//if the value does not fit the type of the existing property.
 			property.setValue(value);
 			return property;
 		}
@@ -121,6 +149,7 @@ public class PropertySet implements IPropertySet
 		}
 		return null;		
 	}
+	
 	public IPropertyType getPropertyType(String key)
 	{
 		IProperty property = getProperty(key);

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

@@ -23,8 +23,6 @@ import java.util.List;
 import java.util.Map;
 
 
-
-
 public class PropertySetContainer implements IPropertySetContainer 
 {
 	private Map _propertySets;
@@ -53,7 +51,7 @@ public class PropertySetContainer implements IPropertySetContainer
 	public IPropertySet createPropertySet(String name, String description) 
 	{
 		IPropertySet newSet = new PropertySet(name);
-		newSet.addProperty("description", description);
+		newSet.addProperty(IPropertySet.DESCRIPTION_KEY, description);
 		_propertySets.put(name, newSet);
 		return newSet;
 	}

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/references/IRSEBasePersistableReferenceManager.java

@@ -59,7 +59,7 @@ public interface IRSEBasePersistableReferenceManager
 
 	/**
 	 * Return an array of the referencing objects currently being managed.
-	 * @param array of the referencing objects currently in this list.
+	 * @return array of the referencing objects currently in this list.
 	 */
 	public IRSEBasePersistableReferencingObject[] getReferencingObjects();
 	/**

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemPersistableReferenceManager.java

@@ -86,7 +86,7 @@ public class SystemPersistableReferenceManager implements IRSEBasePersistableRef
 
 	/**
 	 * Return an array of the referencing objects currently being managed.
-	 * @param array of the referencing objects currently in this list.
+	 * @return array of the referencing objects currently in this list.
 	 */
 	public IRSEBasePersistableReferencingObject[] getReferencingObjects()
 	{
@@ -472,15 +472,11 @@ public class SystemPersistableReferenceManager implements IRSEBasePersistableRef
 		return referencingObjectList;
 	}
 
-	/**
+	//FIXME obsolete?
-	 * @generated This field/method will be replaced during code generation.
-	 */
 	public String toStringGen()
 	{
-		
-
 		StringBuffer result = new StringBuffer(super.toString());
-		result.append(" (name: ");
+		result.append(" (name: "); //$NON-NLS-1$
 		result.append(name);
 		result.append(')');
 		return result.toString();

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemPersistableReferencingObject.java

@@ -83,7 +83,7 @@ public abstract class SystemPersistableReferencingObject extends SystemReferenci
 	 */
 	public String toString() {
 		StringBuffer result = new StringBuffer(super.toString());
-		result.append(" (referencedObjectName: ");
+		result.append(" (referencedObjectName: "); //$NON-NLS-1$
 		result.append(referencedObjectName);
 		result.append(')');
 		return result.toString();

rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemReferencedObjectHelper.java

@@ -55,7 +55,7 @@ public class SystemReferencedObjectHelper implements IRSEBaseReferencedObject
 		int before = referencingObjects.size();
 		referencingObjects.removeElement(ref);
 		int after = referencingObjects.size();
-		assertThis((after == (before - 1)), "removeReference failed for "+ref);
+		assertThis((after == (before - 1)), "removeReference failed for "+ref); //$NON-NLS-1$
 		return referencingObjects.size();
 	}
 
@@ -88,11 +88,12 @@ public class SystemReferencedObjectHelper implements IRSEBaseReferencedObject
 
     /**
      * Little assertion method for debugging purposes
+     * FIXME Move to common place, protected seems not appropriate
      */
     protected void assertThis(boolean assertion, String msg)
     {
     	if (!assertion)
-    	  System.out.println("ASSERTION FAILED IN SystemReferencedObject: " + msg);
+    	  System.out.println("ASSERTION FAILED IN SystemReferencedObject: " + msg); //$NON-NLS-1$
     }
     
 }