KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > excalibur > source > ModifiableSource


1 /*
2  * Copyright (C) The Apache Software Foundation. All rights reserved.
3  *
4  * This software is published under the terms of the Apache Software License
5  * version 1.1, a copy of which has been included with this distribution in
6  * the LICENSE.txt file.
7  */
8 package org.apache.avalon.excalibur.source;
9
10 /**
11  * Describes a {@link Source} object whose data content can change.
12  * The overall handling of this object is very similar to the handling
13  * of the source object: using the getInputStream() method you get
14  * always the upto-date content. When you're done with using the
15  * source object, you have to release it.
16  * If you want to track changes of the source object, this interface
17  * offers you some support for it by providing a SourceValidity object.
18  *
19  * How does the caching work?
20  * The first time you get a ModifiableSource object, you simply ask
21  * it for it's content via getInputStream() and then get the validity
22  * object by invoking getValidity. (Further calls to getValidity always
23  * return the same object! This is not updated!)
24  * The caching algorithm can now store this validity object together
25  * with the system identifier of the source.
26  * The next time, the caching algorithm wants to check if the cached
27  * content is still valid. It has a validity object already to check
28  * against.
29  * If it is still the same ModifiableSource than the first time, you
30  * have to call discardValidity() in order to discard the stored validity
31  * in the ModifiableSource object. If it is a new ModifiableSource object,
32  * calling discardValidity() should do no harm.
33  * After that an upto-date validity object can retrieved by calling
34  * getValidity(). This can be used to test if the content is still valid
35  * as discribed in the source validity documentation.
36  * If the content is still valid, the cache knows what to do, if not,
37  * the new content can be get using getInputStream().
38  * So either after a call to getValidity() or the getInputStream the
39  * validity object must be the same until discardValidity is called!
40  *
41  * @author <a HREF="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
42  * @author <a HREF="mailto:cziegeler@apache.org">Carsten Ziegeler</a>
43  */
44 public interface ModifiableSource
45   extends Source
46 {
47     /**
48      * Get the Validity object. This can either wrap the last modification
49      * date or the expires information or...
50      * If it is currently not possible to calculate such an information
51      * <code>null</code> is returned.
52      */
53     SourceValidity getValidity();
54
55     /**
56      * Refresh the content of this object after the underlying data
57      * content has changed.
58      */
59     void discardValidity();
60 }
61
Popular Tags