cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From p...@apache.org
Subject svn commit: rev 47316 - cocoon/branches/BRANCH_2_1_X/src/java/org/apache/cocoon/components/source/impl
Date Mon, 27 Sep 2004 17:21:57 GMT
Author: pier
Date: Mon Sep 27 10:21:57 2004
New Revision: 47316

Modified:
   cocoon/branches/BRANCH_2_1_X/src/java/org/apache/cocoon/components/source/impl/MultiSourceValidity.java
Log:
Better living through JavaDOC!
Moved the release of the sources from inside a try/catch into a finally (just to be sure)

Modified: cocoon/branches/BRANCH_2_1_X/src/java/org/apache/cocoon/components/source/impl/MultiSourceValidity.java
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/java/org/apache/cocoon/components/source/impl/MultiSourceValidity.java
(original)
+++ cocoon/branches/BRANCH_2_1_X/src/java/org/apache/cocoon/components/source/impl/MultiSourceValidity.java
Mon Sep 27 10:21:57 2004
@@ -25,103 +25,179 @@
 import org.apache.excalibur.source.impl.validity.AbstractAggregatedValidity;
 
 /**
- * An aggregated validity for multiple sources.
+ * <p>An aggregated {@link SourceValidity} for multiple sources.</p>
  * 
  * @author <a href="http://www.apache.org/~sylvain">Sylvain Wallez</a>
  * @version CVS $Id$
  */
-public class MultiSourceValidity extends AbstractAggregatedValidity implements SourceValidity
{
+public class MultiSourceValidity extends AbstractAggregatedValidity
+implements SourceValidity {
 
+    /** <p>When validity expiration is performed.</p> */
     private long expiry;
+    /** <p>The delay from <b>now</b> used to calculate the expiration time.</p>
*/
     private long delay;
+    /** <p>An ordered list of URIs which should be checked.</p> */
     private List uris = new ArrayList();
+    /** <p>Is this instance is closed (accepts modifications or is validable)? */
     private boolean isClosed = false;
-    
-    /** SourceResolver. Transient in order not to be serialized */
+    /** <p>The {@link SourceResolver} to use (transient not to be serialized). */
     private transient SourceResolver resolver;
-    
+
+    /**
+     * <p>The delay value indicating to check always.</p>
+     */
+    public static final int CHECK_ALWAYS = -1;
+
+    /**
+     * <p>Create a new {@link MultiSourceValidity} instance.</p>
+     *
+     * <p>If the number of milliseconds is less than <b>zero</b>, or it's
sum with
+     * the number of <b>now</b> milliseconds is greater than the biggest long
+     * representable, the expiration date will be set to {@link Long.MAX_VALUE}
+     * milliseconds from the epoch.</p>
+     * 
+     * @param resolver the {@link SourceResolver} used to access the sources.
+     * @param delay the number of milliseconds from <b>now</b> defining for how
long
+     *              this instance will be valid.
+     */
     public MultiSourceValidity(SourceResolver resolver, long delay) {
+        /* Calculate the initial expiration time and calculate the delay */
         this.resolver = resolver;
         this.expiry = System.currentTimeMillis() + delay;
         this.delay = delay;
     }
-    
+
+    /**
+     * <p>Add a {@link Source} to the list of {@link Source}s monitored by this
+     * instance.</p>
+     * 
+     * @param src a <b>non-null</b> {@link Source}.
+     */
     public void addSource(Source src) {
         if (this.uris != null) {
             SourceValidity validity = src.getValidity();
             if (validity == null) {
-                // one of the sources has no validity : this object will always be invalid
+                /* The source has no validity: this will be always be invalid. */
                 this.uris = null;
             } else {
-                // Add the validity and URI to the list
+                /* Add the validity and URI to the list */
                 super.add(validity);
                 this.uris.add(src.getURI());
             }
         }
     }
-    
+
+    /**
+     * <p>Close this instance, or in other words declare that no other sources will
+     * be added to this {@link MultiSourceValidity} and that checkings can be now
+     * performed.</p>
+     */
     public void close() {
         this.isClosed = true;
         this.resolver = null;
     }
     
+    /**
+     * <p>Check the validity of this {@link SourceValidity} instance.</p>
+     *
+     * @see SourceValidity#isValid()
+     */
     public int isValid() {
         if (System.currentTimeMillis() <= expiry) {
-            return 1;
+            /* Validity not expired, so, don't even check */
+            return SourceValidity.VALID;
         }
-        expiry = System.currentTimeMillis() + delay;
         
+        /* Re-calculate the expiry time based on the current time */
+        expiry = System.currentTimeMillis() + delay;
+
         if (uris == null || !isClosed) {
-            return -1;
+            /* We have not been closed (yet) or we were forced to be invalid */
+            return SourceValidity.INVALID;
         } else {
+            /* Compute the status of all the sources listed in this instance */
             return computeStatus(null);
         }
     }
 
+    /**
+     * <p>Check the validity of this instance comparing it with a (recently acquired)
+     * new {@link SourceValidity} object.</p>
+     *
+     * @see SourceValidity#isValid(SourceValidity)
+     */
     public int isValid(SourceValidity newValidity) {
         if (uris == null || !isClosed) {
-            return -1;
+            /* We have not been closed (yet) or we were forced to be invalid */
+            return SourceValidity.INVALID;
         }
-        
+
+        /* Perform a simple class check and compute the validity of the sources */
         if (newValidity instanceof MultiSourceValidity) {
             return computeStatus(((MultiSourceValidity)newValidity).resolver);
         } else {
-            // Don't know
-            return -1;
+            /* The supplied validity is not an instance of ourselves, forget it */
+            return SourceValidity.INVALID;
         }
     }
-    
+
+    /**
+     * <p>Compute the status of this instance by checking every source.</p>
+     * 
+     * @param resolver The {@link SourceResolver} to use to access sources.
+     * @return {@link SourceValidity.VALID}, {@link SourceValidity.INVALID} or
+     *         {@link SourceValidity.UNKNOWN} depending on the status.
+     */
     private int computeStatus(SourceResolver resolver) {
+        /* Get the validities and analyse them one by one */
         List validities = super.getValidities();
         for (int i = 0; i < validities.size(); i++) {
+
+            /* Check the validity status */
             SourceValidity validity = (SourceValidity) validities.get(i);
             switch(validity.isValid()) {
-                case -1:
-                    // invalid : stop examining
-                    return -1;
-                case 1:
-                    // valid : just continue to next source
+
+                /* The current source is valid: just continue to next source */
+                case SourceValidity.VALID:
                     break;
-                case 0:
-                    // don't know : check with the new source
-                    if (resolver == null) {
-                        // we have no resolver : definitely don't know (need to have one)
-                        return 0;
-                    }
+
+                /* The current source is invalid: stop examining */
+                case SourceValidity.INVALID:
+                    return SourceValidity.INVALID;
+
+                /* The source validity is not known: check with the new source */
+                case SourceValidity.UNKNOWN:
+                    /* We have no resolver: definitely don't know */
+                    if (resolver == null) return 0;
+
+                    /* Check the new source by asking to the resolver */
+                    Source newSrc = null;
+                    int newValidity = SourceValidity.INVALID;
                     try {
-                        Source newSrc = resolver.resolveURI((String) uris.get(i));
-                        int value = validity.isValid(newSrc.getValidity());
-                        resolver.release(newSrc);
-                        if (value != 1) {
-                            return -1;
-                        }
+                        newSrc = resolver.resolveURI((String) uris.get(i));
+                        newValidity = validity.isValid(newSrc.getValidity());
                     } catch(IOException ioe) {
-                        return -1;
+                        /* Swallow the IOException, but set the new validity */
+                        newValidity = SourceValidity.INVALID;
+                    } finally {
+                        /* Make sure that the source is released */
+                        if (newSrc != null) resolver.release(newSrc);
                     }
+
+                    /* If the source is still valid, go to the next one */
+                    if (newValidity == SourceValidity.VALID) break;
+                    
+                    /* The source is not valid (or unknown), we invalidate the lot */
+                    return SourceValidity.INVALID;
+
+                /* We got something _really_ odd out tof the validity, dunno. */
+                default:
+                    return SourceValidity.INVALID;
             }
         }
         
-        // All items checked successfully
+        /* All items checked successfully */
         return 1;
     }
 }

Mime
View raw message