From 92630ad270118b86b3c0ffc0a6474f8d25283293 Mon Sep 17 00:00:00 2001 From: Martin Oberhuber < martin.oberhuber@windriver.com> Date: Wed, 30 Aug 2006 18:35:17 +0000 Subject: [PATCH] [cleanup] Fix compiler warnings and add Javadoc for IPropertySet --- .../eclipse/rse/core/model/IPropertySet.java | 119 +++++++++++++++++- .../eclipse/rse/core/model/PropertySet.java | 35 +++++- .../rse/core/model/PropertySetContainer.java | 4 +- .../IRSEBasePersistableReferenceManager.java | 2 +- .../SystemPersistableReferenceManager.java | 10 +- .../SystemPersistableReferencingObject.java | 2 +- .../SystemReferencedObjectHelper.java | 5 +- 7 files changed, 157 insertions(+), 20 deletions(-) diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/IPropertySet.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/IPropertySet.java index 5a3cbc708b0..ffba4949615 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/IPropertySet.java +++ b/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 "description" 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 + * setProperty(IPropertySet.DESCRIPTION_KEY, "Description"); + * + * @return Description of the Property Set, + * or null 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, null is returned. + * + * @param key String key for Property + * @return requested Property, + * or null 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, + * null is returned. + * + * @param key String key for Property + * @return String value of requested Property, + * or null 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 null 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 null + */ 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 not 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 true if the Property has been removed, + * or false if the key has not been part of the set. + */ public boolean removeProperty(String key); } \ No newline at end of file diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/PropertySet.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/PropertySet.java index fe7fae90088..88d144f8992 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/PropertySet.java +++ b/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); diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/PropertySetContainer.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/PropertySetContainer.java index fee34d3c5fa..a1326e1165a 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/PropertySetContainer.java +++ b/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; } diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/references/IRSEBasePersistableReferenceManager.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/references/IRSEBasePersistableReferenceManager.java index 62b103f20ee..4abae979162 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/references/IRSEBasePersistableReferenceManager.java +++ b/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(); /** diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemPersistableReferenceManager.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemPersistableReferenceManager.java index 14e1bfefdc2..e6b3e708991 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemPersistableReferenceManager.java +++ b/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; } - /** - * @generated This field/method will be replaced during code generation. - */ + //FIXME obsolete? 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(); diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemPersistableReferencingObject.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemPersistableReferencingObject.java index c77a699d517..7ff4b016937 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemPersistableReferencingObject.java +++ b/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(); diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemReferencedObjectHelper.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemReferencedObjectHelper.java index c06f5e46d43..77d76c7256d 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/references/SystemReferencedObjectHelper.java +++ b/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$ } } \ No newline at end of file