You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by cz...@apache.org on 2002/01/08 14:43:48 UTC
cvs commit: jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source ModifiableSource.java Source.java SourceResolver.java SourceValidity.java URLSource.java
cziegeler 02/01/08 05:43:48
Modified: src/scratchpad/org/apache/avalon/excalibur/source
ModifiableSource.java Source.java
SourceResolver.java SourceValidity.java
URLSource.java
Log:
Really finished source handling and added some java docs
Revision Changes Path
1.5 +29 -1 jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/ModifiableSource.java
Index: ModifiableSource.java
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/ModifiableSource.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ModifiableSource.java 8 Jan 2002 12:55:51 -0000 1.4
+++ ModifiableSource.java 8 Jan 2002 13:43:48 -0000 1.5
@@ -9,6 +9,34 @@
/**
* Describes a {@link Source} object whose data content can change.
+ * The overall handling of this object is very similar to the handling
+ * of the source object: using the getInputStream() method you get
+ * always the upto-date content. When you're done with using the
+ * source object, you have to release it.
+ * If you want to track changes of the source object, this interface
+ * offers you some support for it by providing a SourceValidity object.
+ *
+ * How does the caching work?
+ * The first time you get a ModifiableSource object, you simply ask
+ * it for it's content via getInputStream() and then get the validity
+ * object by invoking getValidity. (Further calls to getValidity always
+ * return the same object! This is not updated!)
+ * The caching algorithm can now store this validity object together
+ * with the system identifier of the source.
+ * The next time, the caching algorithm wants to check if the cached
+ * content is still valid. It has a validity object already to check
+ * against.
+ * If it is still the same ModifiableSource than the first time, you
+ * have to call discardValidity() in order to discard the stored validity
+ * in the ModifiableSource object. If it is a new ModifiableSource object,
+ * calling discardValidity() should do no harm.
+ * After that an upto-date validity object can retrieved by calling
+ * getValidity(). This can be used to test if the content is still valid
+ * as discribed in the source validity documentation.
+ * If the content is still valid, the cache knows what to do, if not,
+ * the new content can be get using getInputStream().
+ * So either after a call to getValidity() or the getInputStream the
+ * validity object must be the same until discardValidity is called!
*
* @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
* @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
@@ -28,5 +56,5 @@
* Refresh the content of this object after the underlying data
* content has changed.
*/
- void refresh();
+ void discardValidity();
}
1.10 +7 -1 jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/Source.java
Index: Source.java
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/Source.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- Source.java 8 Jan 2002 12:55:51 -0000 1.9
+++ Source.java 8 Jan 2002 13:43:48 -0000 1.10
@@ -17,9 +17,15 @@
* have a data source that can change its content and you want it to
* reflect it, use a {@link ModifiableSource} object instead.
*
+ * When the <code>Source</code> object is no longer needed
+ * it must be released using the resolver. This is very similar like
+ * looking up components from a <code>ComponentManager</code>.
+ * In fact a source object can implement most lifecycle interfaces
+ * like Composable, Initializable, Disposable etc.
+ *
* @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
* @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
- * @version CVS $Revision: 1.9 $ $Date: 2002/01/08 12:55:51 $
+ * @version CVS $Revision: 1.10 $ $Date: 2002/01/08 13:43:48 $
*/
public interface Source {
1.7 +5 -3 jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/SourceResolver.java
Index: SourceResolver.java
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/SourceResolver.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- SourceResolver.java 11 Dec 2001 09:53:36 -0000 1.6
+++ SourceResolver.java 8 Jan 2002 13:43:48 -0000 1.7
@@ -16,7 +16,7 @@
/**
* Base interface for resolving a source by system identifiers.
* Instead of using the java.net.URL classes which prevent you
- * to add your own custom protocols in a server environment,
+ * from adding your own custom protocols in a server environment,
* you should use this resolver for all URLs.
*
* The resolver creates for each source a <code>Source</code>
@@ -24,11 +24,13 @@
* etc.
*
* When the <code>Source</code> object is no longer needed
- * it must be release using the resolver. This is very similar like
+ * it must be released using the resolver. This is very similar like
* looking up components from a <code>ComponentManager</code>.
+ * In fact a source object can implement most lifecycle interfaces
+ * like Composable, Initializable, Disposable etc.
*
* @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
- * @version CVS $Revision: 1.6 $ $Date: 2001/12/11 09:53:36 $
+ * @version CVS $Revision: 1.7 $ $Date: 2002/01/08 13:43:48 $
*/
public interface SourceResolver
1.3 +3 -3 jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/SourceValidity.java
Index: SourceValidity.java
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/SourceValidity.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- SourceValidity.java 17 Dec 2001 13:20:57 -0000 1.2
+++ SourceValidity.java 8 Jan 2002 13:43:48 -0000 1.3
@@ -13,7 +13,7 @@
* There are two possibilities: The validity object has all information
* to check by itself how long it is valid (e.g. given an expires date).
* The other possibility needs another (newer) validity object to compare
- * agains (e.g. to test a last modification date).
+ * against (e.g. to test a last modification date).
* To avoid testing, what the actual implementation of the validity object
* supports, the invocation order is to first call isValid() and only if
* this results in <code>false</code>, then to call isValid(SourceValidity).
@@ -21,9 +21,9 @@
* is returned by the first invocation!
*
* @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
- * @version CVS $Revision: 1.2 $ $Date: 2001/12/17 13:20:57 $
+ * @version CVS $Revision: 1.3 $ $Date: 2002/01/08 13:43:48 $
*/
-public interface SourceValidity
+public interface SourceValidity
extends java.io.Serializable {
/**
1.11 +2 -2 jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/URLSource.java
Index: URLSource.java
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/src/scratchpad/org/apache/avalon/excalibur/source/URLSource.java,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- URLSource.java 4 Jan 2002 13:21:31 -0000 1.10
+++ URLSource.java 8 Jan 2002 13:43:48 -0000 1.11
@@ -31,7 +31,7 @@
* Description of a source which is described by an URL.
*
* @author <a href="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
- * @version CVS $Revision: 1.10 $ $Date: 2002/01/04 13:21:31 $
+ * @version CVS $Revision: 1.11 $ $Date: 2002/01/08 13:43:48 $
*/
public final class URLSource
@@ -234,7 +234,7 @@
* Refresh this object and update the last modified date
* and content length.
*/
- public void refresh() {
+ public void discardValidity() {
// reset connection
this.connection = null;
this.gotInfos = false;
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>