From c3cbdec96c9bb9834e6b3802e260c67993190396 Mon Sep 17 00:00:00 2001 From: David Dykstal Date: Tue, 11 Mar 2008 17:10:48 +0000 Subject: [PATCH] [189274] cleanup javadoc and formating prior to bug work https://bugs.eclipse.org/bugs/show_bug.cgi?id=189274 --- .../rse/core/filters/ISystemFilterPool.java | 105 ++++++------------ 1 file changed, 37 insertions(+), 68 deletions(-) diff --git a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilterPool.java b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilterPool.java index f922e4bd62b..947046c24d3 100644 --- a/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilterPool.java +++ b/rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/filters/ISystemFilterPool.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2002, 2007 IBM Corporation and others. + * Copyright (c) 2002, 2008 IBM Corporation and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at @@ -12,7 +12,7 @@ * Emily Bruner, Mazen Faraj, Adrian Storisteanu, Li Ding, and Kent Hawley. * * Contributors: - * {Name} (company) - description of contribution. + * David Dykstal (IBM) - cleanup - format and javadoc *******************************************************************************/ package org.eclipse.rse.core.filters; @@ -22,17 +22,12 @@ import org.eclipse.rse.core.references.IRSEPersistableReferencedObject; /** * This interface represents a system filter pool, which is a means of - * grouping filters.
- * By default this is represented as a folder on disk, with each filter - * stored as a file in that folder. - */ -/** - * @lastgen interface SystemFilterPool extends SystemPersistableReferencedObject, SystemFilterContainer {} + * grouping filters to be referenced together. */ public interface ISystemFilterPool extends IRSEPersistableReferencedObject, ISystemFilterContainer, IRSEModelObject { - // external methods + /** - * Return the caller which instantiated the filter pool manager overseeing this filter framework instance + * @return the object that instantiated the filter pool manager owning this filter pool */ public ISystemFilterPoolManagerProvider getProvider(); @@ -49,44 +44,46 @@ public interface ISystemFilterPool extends IRSEPersistableReferencedObject, ISys public IRSEFilterNamingPolicy getNamingPolicy(); /** - * Does this filter support nested filters? + * @return true if filters in this pool support nested filters. */ public boolean supportsNestedFilters(); /** - * Does this support duplicate filter strings? Calls mof-generated isSupportsDuplicateFilterStrings. + * @return true if filters in this pool supports duplicate filter strings. */ public boolean supportsDuplicateFilterStrings(); /** - * @return The value of the StringsCaseSensitive attribute - * Are filter strings in this filter case sensitive? - * If not set locally, queries the parent filter pool manager's atttribute. + * @return true if the filters in this pool are case sensitive */ public boolean isStringsCaseSensitive(); /** - * Set the filter pool manager. + * Set the filter pool manager for this filter pool. Should only be done when the filter + * pool is created by the manager. + * @param mgr the manager of this filter pool */ public void setSystemFilterPoolManager(ISystemFilterPoolManager mgr); /** - * 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(); /** - * This is to set transient data that is queryable via getFilterPoolData + * Set a data object to be associated with this filter pool. This data is uninterpreted by this + * filter pool. + * @param data the data object */ public void setSystemFilterPoolData(Object data); /** - * Return transient data set via setFilterPoolData. + * @return the data object set using setFilterPoolData. */ public Object getSystemFilterPoolData(); /** - * Clone this filter pools' attributes and filters into another filter pool. + * Clone the attributes from this filter pool into another filter pool. * Assumes the core attributes were already set when filter pool was created: * + * @param targetPool the filter pool that will receive the new attributes */ public void cloneSystemFilterPool(ISystemFilterPool targetPool) throws Exception; /** * Copy a system filter to this or another filter pool. + * @param targetPool the receiving pool + * @param oldFilter the filter to copy + * @param newName the name which to give the new copy of the filter + * @return the newly created filter */ public ISystemFilter copySystemFilter(ISystemFilterPool targetPool, ISystemFilter oldFilter, String newName) throws Exception; /** - * Order filters according to user preferences. - *

- * While the framework has all the code necessary to arrange filters and save/restore - * that arrangement, you may choose to use preferences instead of this support. - * In this case, call this method and pass in the saved and sorted filter name list. - *

- * Called by someone after restore. + * Order filters according to the names in the list. Typically used to enforce + * a particular ordering in the filter list. If a name appears in this list and + * does not name a filter it is ignored. If there are filters in this pool that + * are not named in this list their order in the pool is undefined. + * @param names the names of the filters in this pool in the order they should be returned. */ public void orderSystemFilters(String[] names); @@ -129,66 +129,62 @@ public interface ISystemFilterPool extends IRSEPersistableReferencedObject, ISys */ public void setSavePolicy(int policy); + /** + * @return the id of the filter pool. Used for referencing this filter pool from filter pool references. + */ public String getId(); /** - * @generated This field/method will be replaced during code generation * @return The value of the Name attribute */ String getName(); /** - * @generated This field/method will be replaced during code generation * @param value The new value of the Name attribute */ void setName(String value); /** - * @generated This field/method will be replaced during code generation * @return The value of the Type attribute - * Allows tools to have typed filter pools + * Allows tools to have typed filter pools. + * Type is not interpreted by the filter pool, but may be used by a subsystem. */ String getType(); /** - * @generated This field/method will be replaced during code generation * @param value The new value of the Type attribute + * Allows tools to have typed filter pools. + * Type is not interpreted by the filter pool, but may be used by a subsystem. */ void setType(String value); /** - * @generated This field/method will be replaced during code generation * @return The value of the SupportsNestedFilters attribute */ boolean isSupportsNestedFilters(); /** - * @generated This field/method will be replaced during code generation * @param value The new value of the SupportsNestedFilters attribute */ void setSupportsNestedFilters(boolean value); /** - * @generated This field/method will be replaced during code generation * @return The value of the Deletable attribute */ boolean isDeletable(); /** - * @generated This field/method will be replaced during code generation * @param value The new value of the Deletable attribute */ void setDeletable(boolean value); /** - * @generated This field/method will be replaced during code generation * @return The value of the Default attribute - * Is this a default vendor-supplied pool versus user-created pool + * true if this is a vendor-supplied pool versus user-created pool */ boolean isDefault(); /** - * @generated This field/method will be replaced during code generation * @param value The new value of the Default attribute */ void setDefault(boolean value); @@ -213,45 +209,38 @@ public interface ISystemFilterPool extends IRSEPersistableReferencedObject, ISys boolean isSetStringsCaseSensitive(); /** - * @generated This field/method will be replaced during code generation * @return The list of Filters references */ java.util.List getFilters(); /** - * @generated This field/method will be replaced during code generation * @return The value of the SupportsDuplicateFilterStrings attribute */ boolean isSupportsDuplicateFilterStrings(); /** - * @generated This field/method will be replaced during code generation * @param value The new value of the SupportsDuplicateFilterStrings attribute */ void setSupportsDuplicateFilterStrings(boolean value); /** - * @generated This field/method will be replaced during code generation * @return The value of the Release attribute - * In what release was this created? Typically, will be the version and release - * times 10, as in 40 or 51. + * The release in which this filter pool was initially created. + * Typically, will be the version and release times 10, as in 40 or 51. */ int getRelease(); /** - * @generated This field/method will be replaced during code generation * @param value The new value of the Release attribute */ void setRelease(int value); /** * Returns the value of the 'Single Filter String Only' attribute. - * *

* If true then filters in this filter pool can have only a single filter string unless the * filter has overriden this attribute. *

- * * @return the value of the 'Single Filter String Only' attribute. * @see #isSetSingleFilterStringOnly() * @see #unsetSingleFilterStringOnly() @@ -261,52 +250,41 @@ public interface ISystemFilterPool extends IRSEPersistableReferencedObject, ISys /** * Sets the value of the '{@link org.eclipse.rse.core.filters.ISystemFilterPool#isSingleFilterStringOnly Single Filter String Only}' attribute. - * * If set to true filters in this filter pool can hold only a single filter string unless overridden by the filter itself. * If false then the filter may hold more than one filter string. - * * @param value the new value of the 'Single Filter String Only' attribute. * @see #isSetSingleFilterStringOnly() * @see #unsetSingleFilterStringOnly() * @see #isSingleFilterStringOnly() - * @generated */ void setSingleFilterStringOnly(boolean value); /** * Unsets the value of the '{@link org.eclipse.rse.core.filters.ISystemFilterPool#isSingleFilterStringOnly Single Filter String Only}' attribute. - * * Causes the value of the single filter string attribute to be inherited from the containing filter pool manager. - * * @see #isSetSingleFilterStringOnly() * @see #isSingleFilterStringOnly() * @see #setSingleFilterStringOnly(boolean) - * @generated */ void unsetSingleFilterStringOnly(); /** * Returns whether the value of the '{@link org.eclipse.rse.core.filters.ISystemFilterPool#isSingleFilterStringOnly Single Filter String Only}' attribute is set. - * * This will be true if this attribute has been set for this filter pool. It will be false if this * attribute is inherited from the filter pool manager. - * * @return whether the value of the 'Single Filter String Only' attribute is set. * @see #unsetSingleFilterStringOnly() * @see #isSingleFilterStringOnly() * @see #setSingleFilterStringOnly(boolean) - * @generated */ boolean isSetSingleFilterStringOnly(); /** * Returns the value of the 'Owning Parent Name' attribute. - * *

* If the meaning of the 'Owning Parent Name' attribute isn't clear, * there really should be more of a description here... *

- * * @return the value of the 'Owning Parent Name' attribute. * @see #setOwningParentName(String) */ @@ -314,22 +292,16 @@ public interface ISystemFilterPool extends IRSEPersistableReferencedObject, ISys /** * Sets the value of the '{@link org.eclipse.rse.core.filters.ISystemFilterPool#getOwningParentName Owning Parent Name}' attribute. - * - * * @param value the new value of the 'Owning Parent Name' attribute. * @see #getOwningParentName() - * @generated */ void setOwningParentName(String value); /** * Returns the value of the 'Non Renamable' attribute. - * *

* If the meaning of the 'Non Renamable' attribute isn't clear, * there really should be more of a description here... - *

- * * @return the value of the 'Non Renamable' attribute. * @see #setNonRenamable(boolean) */ @@ -337,11 +309,8 @@ public interface ISystemFilterPool extends IRSEPersistableReferencedObject, ISys /** * Sets the value of the '{@link org.eclipse.rse.core.filters.ISystemFilterPool#isNonRenamable Non Renamable}' attribute. - * - * * @param value the new value of the 'Non Renamable' attribute. * @see #isNonRenamable() - * @generated */ void setNonRenamable(boolean value);