Calls back to inform provider - * @param array of filter pool reference objects to set the list to. + * In one shot, set the filter pool references. Calls back to inform provider. + * @param filterPoolReferences an array of filter pool reference objects to set the list to. * @param deReference true to first de-reference all objects in the existing list. */ public void setSystemFilterPoolReferences(ISystemFilterPoolReference[] filterPoolReferences, boolean deReference) { @@ -385,7 +388,6 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference * must be added to the managed lists by the caller. * That will be attempted to be resolved on first use. */ - // DWD working private ISystemFilterPoolReference createSystemFilterPoolReference(ISystemFilterPoolManager filterPoolManager, String filterPoolName) { ISystemFilterPoolReference filterPoolReference = new SystemFilterPoolReference(filterPoolManager, filterPoolName); invalidateFilterPoolReferencesCache(); @@ -394,11 +396,12 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Add a filter pool referencing object to the list. + * @param filterPoolReference a reference to add to this manager * @return the new count of referencing objects */ public int addSystemFilterPoolReference(ISystemFilterPoolReference filterPoolReference) { int count = addReferencingObject(filterPoolReference); - filterPoolReference.setParentReferenceManager(this); // DWD - should be done in the addReferencingObject method + filterPoolReference.setParentReferenceManager(this); // DWD - should be done in the addReferencingObject method? invalidateFilterPoolReferencesCache(); quietSave(); return count; @@ -406,18 +409,19 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Reset the filter pool a reference points to. Called on a move-filter-pool operation + * @param filterPoolReference the reference to fix up + * @param newPool the new pool to reference */ public void resetSystemFilterPoolReference(ISystemFilterPoolReference filterPoolReference, ISystemFilterPool newPool) { filterPoolReference.removeReference(); filterPoolReference.setReferencedObject(newPool); if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceReset(filterPoolReference); quietSave(); - // don't think we need to invalidate the cache } /** * Remove a filter pool referencing object from the list. - * @param filterPool Reference the reference to remove + * @param filterPoolReference the reference to remove * @param deReference true if we want to dereference the referenced object (call removeReference on it) * @return the new count of referencing objects */ @@ -427,37 +431,39 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference count = super.removeReferencingObject(filterPoolReference); else count = super.removeAndDeReferenceReferencingObject(filterPoolReference); - filterPoolReference.setParentReferenceManager(null); // DWD should be done in remove + filterPoolReference.setParentReferenceManager(null); // DWD should be done in remove? invalidateFilterPoolReferencesCache(); - // callback to provider so they can fire events in their GUI if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceDeleted(filterPoolReference); quietSave(); return count; } /** - * Return count of referenced filter pools + * @return count of referenced filter pools */ public int getSystemFilterPoolReferenceCount() { return super.getReferencingObjectCount(); } /** - * Return the zero-based position of a SystemFilterPoolReference object within this list + * @param filterPoolRef the filter pool reference to search for + * @return the zero-based position of the reference within this manager */ public int getSystemFilterPoolReferencePosition(ISystemFilterPoolReference filterPoolRef) { return super.getReferencingObjectPosition(filterPoolRef); } /** - * Move a given filter pool reference to a given zero-based location - * Calls back to inform provider of the event + * Move a given filter pool reference to a given zero-based location. + * Calls back to inform provider of the event. + * @param filterPoolRef the reference to move + * @param pos the new position at which to move it. References at that position and beyond are + * moved up in the list. */ public void moveSystemFilterPoolReference(ISystemFilterPoolReference filterPoolRef, int pos) { int oldPos = super.getReferencingObjectPosition(filterPoolRef); super.moveReferencingObjectPosition(pos, filterPoolRef); invalidateFilterPoolReferencesCache(); - // callback to provider so they can fire events in their GUI if (!noSave) quietSave(); if (fireEvents && (caller != null) && !noEvents) { ISystemFilterPoolReference[] refs = new ISystemFilterPoolReference[1]; @@ -469,11 +475,10 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Move existing filter pool references a given number of positions. * If the delta is negative, they are all moved up by the given amount. If - * positive, they are all moved down by the given amount.
- *
- * Calls back to inform provider + * positive, they are all moved down by the given amount. + * Calls back to inform provider. * @param filterPoolRefs Array of SystemFilterPoolReferences to move. - * @param newPosition new zero-based position for the filter pool references. + * @param delta the amount by which to move these references. */ public void moveSystemFilterPoolReferences(ISystemFilterPoolReference[] filterPoolRefs, int delta) { int[] oldPositions = new int[filterPoolRefs.length]; @@ -496,7 +501,7 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference // Methods that work on FilterPool master objects // ---------------------------------------------- /** - * Return array of filter pools currently referenced by this manager + * @return array of filter pools currently referenced by this manager. * Result will never be null, although it may be an array of length zero. */ public ISystemFilterPool[] getReferencedSystemFilterPools() { @@ -508,7 +513,8 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference } /** - * Return true if the given filter pool has a referencing object in this list. + * @param filterPool the filter pool to test to see if we have a reference to it + * @return true if the given filter pool has a referencing object in this list. */ public boolean isSystemFilterPoolReferenced(ISystemFilterPool filterPool) { return super.isReferenced(filterPool); @@ -516,6 +522,7 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Given a filter pool, locate the referencing object for it and return it. + * @param filterPool the filter pool we are testing for a reference * @return the referencing object if found, else null */ public ISystemFilterPoolReference getReferenceToSystemFilterPool(ISystemFilterPool filterPool) { @@ -531,12 +538,11 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference filterPoolReference.setParentReferenceManager(this); invalidateFilterPoolReferencesCache(); quietSave(); - // callback to provider so they can fire events in their GUI if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceCreated(filterPoolReference); return filterPoolReference; } - // DWD Working + // DWD Working - the method above and this one can be combined? /* (non-Javadoc) * @see org.eclipse.rse.filters.ISystemFilterPoolReferenceManager#addReferenceToSystemFilterPool(org.eclipse.rse.filters.ISystemFilterPoolManager, java.lang.String) */ @@ -546,7 +552,6 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference filterPoolReference.setParentReferenceManager(this); invalidateFilterPoolReferencesCache(); quietSave(); - // callback to provider so they can fire events in their GUI if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceCreated(filterPoolReference); return filterPoolReference; } @@ -554,15 +559,16 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Given a filter pool, locate the referencing object for it and remove it from the list. * Also removes that reference from the filterPool itself, and calls back to provider when done. + * @param filterPool the filter pool whose references we are to remove * @return the new count of referencing objects */ public int removeReferenceToSystemFilterPool(ISystemFilterPool filterPool) { ISystemFilterPoolReference filterPoolReference = getReferenceToSystemFilterPool(filterPool); int newCount = 0; if (filterPoolReference != null) { - filterPoolReference.removeReference(); // getReferencedFilterPool().removeReference(this) + filterPoolReference.removeReference(); newCount = removeReferencingObject(filterPoolReference); - filterPoolReference.setParentReferenceManager(null); // DWD should be done in removeReferencingObject + filterPoolReference.setParentReferenceManager(null); // DWD should be done in removeReferencingObject? invalidateFilterPoolReferencesCache(); quietSave(); // callback to provider so they can fire events in their GUI @@ -573,8 +579,9 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference } /** - * A reference filter pool has been renamed. Update our stored name... - *
Calls back to inform provider + * A referenced filter pool has been renamed. Update our stored name. + * Calls back to inform provider. + * @param pool the pool that has just been renamed */ public void renameReferenceToSystemFilterPool(ISystemFilterPool pool) { ISystemFilterPoolReference poolRef = null; @@ -587,14 +594,14 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference poolRef.resetReferencedFilterPoolName(pool.getReferenceName()); invalidateFilterPoolReferencesCache(); quietSave(); - // callback to provider so they can fire events in their GUI if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceRenamed(poolRef, oldName); } } /** * In one shot, set the filter pool references to new references to supplied filter pools. - * @param array of filter pool objects to create references for + * Calls back to provider. + * @param filterPools of filter pool objects to create references for * @param deReference true to first de-reference all objects in the existing list. */ public void setSystemFilterPoolReferences(ISystemFilterPool[] filterPools, boolean deReference) { @@ -602,18 +609,16 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference super.removeAndDeReferenceAllReferencingObjects(); else removeAllReferencingObjects(); - // add current if (filterPools != null) { for (int idx = 0; idx < filterPools.length; idx++) { //addReferenceToSystemFilterPool(filterPools[idx]); ISystemFilterPoolReference filterPoolReference = createSystemFilterPoolReference(filterPools[idx]); addReferencingObject(filterPoolReference); - filterPoolReference.setParentReferenceManager(this); // DWD should be done in addReferencingObject + filterPoolReference.setParentReferenceManager(this); // DWD should be done in addReferencingObject? } invalidateFilterPoolReferencesCache(); quietSave(); - // callback to provider so they can fire events in their GUI if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferencesReset(); } } @@ -623,8 +628,11 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference // ------------------------- /** * Create a single filter refererence to a given filter. Needed when a filter - * is added to a pool, and the GUI is not showing pools but rather all filters - * in all pool references. + * is added to a pool, and the UI is not showing pools but rather all filters + * in all pool references. + * @param subSystem the subsystem that uses this reference manager + * @param filter the new filter that is being added + * @return the new reference */ public ISystemFilterReference getSystemFilterReference(ISubSystem subSystem, ISystemFilter filter) { // step 1: find the reference to the filter pool that contains this filter @@ -639,7 +647,9 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Concatenate all filter references from all filter pools we reference, into one - * big list. + * big list. Used when the UI is not showing pools. + * @param subSystem the subsystem for which this manager is providing filter pool reference management + * @return an array of references for this subsystem */ public ISystemFilterReference[] getSystemFilterReferences(ISubSystem subSystem) { ISystemFilterPoolReference[] poolRefs = getSystemFilterPoolReferences(); @@ -657,8 +667,11 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Given a filter reference, return its position within this reference manager - * when you think of all filter references from all filter pool references as - * being concatenated + * when you think of all filter references from all filter pool references as + * being concatenated. + * Used when the UI is not showing pools. + * @param filterRef the reference to locate + * @return the position fo this reference or -1 if not found. */ public int getSystemFilterReferencePosition(ISystemFilterReference filterRef) { ISystemFilterPoolReference[] poolRefs = getSystemFilterPoolReferences(); @@ -678,8 +691,12 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Given a filter, return its position within this reference manager - * when you think of all filter references from all filter pool references as - * being concatenated + * when you think of all filter references from all filter pool references as + * being concatenated. + * Used when the UI is not showing pools. + * @param subSystem the subsystem in which to located the filter + * @param filter the filter to locate + * @return the position of the filter within this manager. */ public int getSystemFilterReferencePosition(ISubSystem subSystem, ISystemFilter filter) { ISystemFilterPoolReference[] poolRefs = getSystemFilterPoolReferences(); @@ -704,25 +721,31 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference try { save(); } catch (Exception exc) { + // TODO log exception } } /** * Save all the filter pools to disk. - * Only called if the save policy is not none. + * Only called if the save policy is not "none". + * No longer used. + * @throws Exception */ public void save() throws Exception { - //System.out.println("Saving filter pool " + this.getName() + "?"); // DWD - debugging switch (savePolicy) { - // ONE FILE PER FILTER POOL REFERENCE MANAGER - case ISystemFilterSavePolicies.SAVE_POLICY_ONE_FILE_PER_MANAGER: - saveToOneFile(); - break; + // ONE FILE PER FILTER POOL REFERENCE MANAGER + case ISystemFilterSavePolicies.SAVE_POLICY_ONE_FILE_PER_MANAGER: + saveToOneFile(); + break; } } /** * Save this reference manager to disk. + * Used only if using the reference manager to save a single file to disk. + * No longer used. + * @return true if the save succeeded + * @throws Exception */ protected boolean saveToOneFile() throws Exception { /* FIXME @@ -763,13 +786,14 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Restore the filter pools from disk. - * After restoration, you must call resolveReferencesAfterRestore! + * After restoring, you must call resolveReferencesAfterRestore. + * No longer used. * @param caller The object that is calling this, which must implement SystemFilterPoolReferenceManagerProvider * @param mgrFolder folder containing filter pool references file. * @param name the name of the manager to restore. File name is derived from it when saving to one file. * @param namingPolicy to get file name prefix, via getFilterPoolReferenceManagerFileNamePrefix(). Pass null to use default. - * @return the restored manager, or null if it does not exist. If anything else went - * wrong, an exception is thrown. + * @return the restored manager, or null if it does not exist. + * @throws Exception if anything else went wrong */ public static ISystemFilterPoolReferenceManager restore(ISystemFilterPoolReferenceManagerProvider caller, IFolder mgrFolder, String name, IRSEFilterNamingPolicy namingPolicy) throws Exception { if (namingPolicy == null) namingPolicy = SystemFilterNamingPolicy.getNamingPolicy(); @@ -781,17 +805,26 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference } /** - * Restore the filter pools from disk, assuming default for prefix of name. + * Restore the filter pools from disk, assuming default for a naming policy. + * No longer used. + * @param caller The object that is calling this, which must implement SystemFilterPoolReferenceManagerProvider + * @param mgrFolder folder containing filter pool references file. + * @param name the name of the manager to restore. File name is derived from it when saving to one file. + * @return the restored manager, or null if it does not exist. + * @throws Exception if anything else went wrong */ public static ISystemFilterPoolReferenceManager restore(ISystemFilterPoolReferenceManagerProvider caller, IFolder mgrFolder, String name) throws Exception { return restore(caller, mgrFolder, name, null); } /** - * Restore filter pools when all are stored in one file + * Restore filter pools when all are stored in one file. + * No longer used. * @param mgrFolder The folder containing the file to restore from. * @param name The name of the manager, from which the file name is derived. * @param namingPolicy Naming prefix information for persisted data file names. + * @return the restored manager, or null if it does not exist. + * @throws Exception if anything else went wrong */ protected static ISystemFilterPoolReferenceManager restoreFromOneFile(IFolder mgrFolder, String name, IRSEFilterNamingPolicy namingPolicy) throws Exception { ISystemFilterPoolReferenceManager mgr = null; @@ -841,17 +874,17 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference * This method is called after restore and for each restored object in the list must: *
* @param mgrs The list of filter pool managers to scan for the given filter pool. * @param mgrName The name of the manager to restrict the search to - * @param poolReferenceName The name of the filter pool as stored on disk. It may be qualified somehow - * to incorporate the manager name too. + * @param poolName The name of the filter pool as stored on disk. It may be qualified somehow + * to incorporate the manager name too. + * @return the filter pool that was found. */ public static ISystemFilterPool getFilterPool(ISystemFilterPoolManager[] mgrs, String mgrName, String poolName) { ISystemFilterPoolManager mgr = getFilterPoolManager(mgrs, mgrName); @@ -910,9 +940,9 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * Utility method to scan across all filter pool managers for a match on a give name. - *
* @param mgrs The list of filter pool managers to scan for the given name * @param mgrName The name of the manager to restrict the search to + * @return the filter pool manager that was found or null if not found. */ public static ISystemFilterPoolManager getFilterPoolManager(ISystemFilterPoolManager[] mgrs, String mgrName) { ISystemFilterPoolManager mgr = null; @@ -928,56 +958,65 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference /** * If saving all info in one file, this returns the fully qualified name of that file, * given the unadorned manager name and the prefix (if any) to adorn with. + * No longer used. + * @param mgrFolder The folder in which to save a reference manager. + * @param name The name of the file for a filter pool reference manager. + * @param namingPolicy The naming policy for a filter pool reference manager + * @return The name of the path to which to save the references in a filter pool reference manager. */ protected static String getSaveFilePathAndName(IFolder mgrFolder, String name, IRSEFilterNamingPolicy namingPolicy) { return SystemFilter.addPathTerminator(getFolderPath(mgrFolder)) + getSaveFileName(namingPolicy.getReferenceManagerSaveFileName(name)); } /** - * Derive and return the unqualified file name used to store this to disk. - * It is unqualified. + * Appends the correct extension to the file name where this manager is saved. + * No longer used. + * @param fileNameNoSuffix the file name sans suffix. + * @return the unqualified file name used to store this to disk. */ protected static String getSaveFileName(String fileNameNoSuffix) { return fileNameNoSuffix + ISystemFilterConstants.SAVEFILE_SUFFIX; } /** - * non-static version. + * @return the full path name of the file in which to save this manager. */ protected String getSaveFilePathAndName() { return SystemFilter.addPathTerminator(getFolderPath(mgrFolder)) + getSaveFileName(); } /** - * non-static version. + * @return the simple name of the file in which to save this manager. */ protected String getSaveFileName() { return getSaveFileName(namingPolicy.getReferenceManagerSaveFileName(getName())); } /** - * Return the folder that this manager is contained in. + * @return the folder that this manager is contained in. */ public IFolder getFolder() { return mgrFolder; } /** - * Reset the folder that this manager is contained in. + * Set the folder that this manager is contained in. + * @param newFolder the new folder */ public void resetManagerFolder(IFolder newFolder) { mgrFolder = newFolder; } /** - * Return the path of the folder + * @return the path of the folder that contains this manager. */ public String getFolderPath() { return getResourceHelpers().getFolderPath(mgrFolder); } /** - * Return the path of the given folder + * @param folder the folder to find the path for + * @return the path of the given folder */ public static String getFolderPath(IFolder folder) { return SystemResourceHelpers.getResourceHelpers().getFolderPath(folder);