[cleanup] extensive javadoc, some formatting

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

@@ -13,9 +13,7 @@
  * Contributors:
  * {Name} (company) - description of contribution.
  ********************************************************************************/
-
 package org.eclipse.rse.core.filters;
-//
 
 import java.util.Vector;
 
@@ -25,87 +23,105 @@ import org.eclipse.rse.core.persistance.IRSEPersistableContainer;
  * Filter containers are any objects that contain filters.
  * This includes filter pools and filters themselves.
  */
-public interface ISystemFilterContainer extends IRSEPersistableContainer 
+public interface ISystemFilterContainer extends IRSEPersistableContainer {
-{
+	/**
-    /**
+	 * @return the filter pool manager managing this collection of filter pools and their filters.
-     * Return the filter pool manager managing this collection of filter pools and their filters.
+	 */
-     */
+	public ISystemFilterPoolManager getSystemFilterPoolManager();
-    public ISystemFilterPoolManager getSystemFilterPoolManager();
+
 	/**
 	 * @return The value of the StringsCaseSensitive attribute
-	 * Are filter strings in this filter case sensitive?
+	 * Are filters in this filter container case sensitive?
 	 * If not set locally, queries the parent filter pool manager's atttribute.
 	 */
 	public boolean areStringsCaseSensitive();
-    /**
+
-     * Creates a new system filter within this container (SystemFilterPool or SystemFilter)
+	/**
-     * @param data Optional transient data you want stored in the created filter. Can be null.
+	 * Adds a new system filter to this container (SystemFilterPool or SystemFilter) and
-     * @param aliasName The name to give the new filter. Must be unique for this pool.
+	 * populates it with the filter strings created from the strings provided.
-     * @param filterStrings The list of String objects that represent the filter strings.
+	 * Does nothing if this filter already exists in this container.
-     */    
+	 * @param aliasName The name to give the new filter. Must be unique for this pool.
-    public ISystemFilter createSystemFilter(String aliasName, Vector filterStrings);     
+	 * @param filterStrings The list of String objects that represent the filter strings.
-    /**
+	 */
-     * Adds given filter to the list.
+	public ISystemFilter createSystemFilter(String aliasName, Vector filterStrings);
-     * <p>PLEASE NOTE:
+
-     * <ul>
+	/**
-     *  <li> createSystemFilter calls this method for you!
+	 * Adds given filter to the list without populating the filter strings.
-     *  <li> this is a no-op if a filter with the same aliasname already exists
+	 * @param filter SystemFilter object to add
-     * </ul>
+	 * @return true if added, false if a filter with this aliasname already existed.
-     * @param filter SystemFilter object to add
+	 */
-     * @return true if added, false if filter with this aliasname already existed.
+	public boolean addSystemFilter(ISystemFilter filter);
-     */
+
-    public boolean addSystemFilter(ISystemFilter filter);
+	/**
-    /**
+	 * @return Vector of String objects: the names of existing filters in this container.
-     * Return Vector of String objects: the names of existing filters in this container.
+	 * Typically used by name validators for New and Rename actions to verify new name is unique.
-     * Needed by name validators for New and Rename actions to verify new name is unique.
+	 */
-     */
+	public Vector getSystemFilterNames();
-    public Vector getSystemFilterNames();
+
-    /**
+	/**
-     * Return a Vector of the filters contained in this filter container.
+	 * @return a Vector of the ISystemFilter objects contained in this filter container.
-     */
+	 */
-    public Vector getSystemFiltersVector();
+	public Vector getSystemFiltersVector();
-    /**
+
-     * Return an array of the filters contained in this filter container.
+	/**
-     */
+	 * @return an array of the ISystemFilter objects contained in this filter container.
-    public ISystemFilter[] getSystemFilters();   
+	 */
-    /**
+	public ISystemFilter[] getSystemFilters();
-     * Return a system filter given its name
+
-     */
+	/**
-    public ISystemFilter getSystemFilter(String filterName);   
+	 * @return a system filter given its name. Will return null if no filter by this name is found.
-    /**
+	 */
-     * Return the parent pool of this container.
+	public ISystemFilter getSystemFilter(String filterName);
-     * If this is itself a pool, returns "this".
+
-     * Else, for a nested filter, returns the pool that is the ultimate parent of this filter.
+	/**
-     */
+	 * @return the parent pool of this container.
-    public ISystemFilterPool getSystemFilterPool(); 
+	 * If this is itself a pool, returns "this".
-    /**
+	 * For a nested filter, returns the pool that is the ultimate parent of this filter.
-     * Return how many filters are defined in this filter container
+	 */
-     */
+	public ISystemFilterPool getSystemFilterPool();
-    public int getSystemFilterCount();
+
-    /**
+	/**
-     * Removes a given filter from the list.
+	 * @return how many filters are directly defined in this filter container.
-     * @param filter SystemFilter object to remove
+	 */
-     */
+	public int getSystemFilterCount();
-    public void deleteSystemFilter(ISystemFilter filter);
+
-    /**
+	/**
-     * Renames a given filter in the list.
+	 * Removes a given filter from the list. Will do nothing if the specified filter 
-     * @param filter SystemFilter object to rename
+	 * is not in this filter container.
-     * @param newName New name to assign it. Assumes unique checking already done.
+	 * @param filter SystemFilter object to remove
-     */
+	 */
-    public void renameSystemFilter(ISystemFilter filter, String newName);
+	public void deleteSystemFilter(ISystemFilter filter);
-    /**
+
-     * Return a given filter's zero-based location
+	/**
-     */
+	 * Renames a given filter in the list. The new name is assumed to be valid. 
-    public int getSystemFilterPosition(ISystemFilter filter);
+	 * Will perform the rename whether or not the filter is contained in this
-    /**
+	 * container.
-     * Move a given filter to a given zero-based location
+	 * @param filter SystemFilter object to rename
-     */
+	 * @param newName New name to assign it.
-    public void moveSystemFilter(int pos, ISystemFilter filter);
+	 */
-    /**
+	public void renameSystemFilter(ISystemFilter filter, String newName);
-     * Updates a given filter in the list.
+
-     * @param filter SystemFilter object to update
+	/**
-     * @param newName New name to assign it. Assumes unique checking already done.
+	 * @return a given filter's zero-based location. Will return -1 if the filter
-     * @param newStrings New strings to assign it. Replaces current strings.
+	 * is not present in this container.
-     */
+	 */
-    public void updateSystemFilter(ISystemFilter filter, String newName, String[] newStrings);
+	public int getSystemFilterPosition(ISystemFilter filter);
+
+	/**
+	 * Move a given filter to a given zero-based location.
+	 * Does nothing if the filter is not in this container.
+	 * @param pos the new position of the filter.
+	 * @param filter the filter to move.
+	 */
+	public void moveSystemFilter(int pos, ISystemFilter filter);
+
+	/**
+	 * Updates a given filter.
+	 * The filter need not be present in this container but will operate on
+	 * any filter.
+	 * @param filter SystemFilter object to update
+	 * @param newName New name to assign it. Assumes unique checking already done.
+	 * @param newStrings New strings to assign it. Replaces current strings.
+	 */
+	public void updateSystemFilter(ISystemFilter filter, String newName, String[] newStrings);
 }