001 package com.croftsoft.core.util.cache;
002
003 import java.io.*;
004
005 import com.croftsoft.core.util.id.Id;
006
007 /*********************************************************************
008 * Stores the content and then returns an Id which may be used to
009 * read the content later, if still available.
010 *
011 * @see
012 * SoftCache
013 *
014 * @version
015 * 2003-06-07
016 * @since
017 * 1999-04-24
018 * @author
019 * <a href="https://www.croftsoft.com/">David Wallace Croft</a>
020 *********************************************************************/
021
022 public interface Cache
023 //////////////////////////////////////////////////////////////////////
024 //////////////////////////////////////////////////////////////////////
025 {
026
027 /*********************************************************************
028 *
029 * "Validates" the content by
030 *
031 * <OL>
032 *
033 * <LI> confirming that identical content already exists in the cache;
034 * or, if otherwise necessary,
035 *
036 * <LI> storing a new copy of the content in the cache.
037 *
038 * </OL>
039 *
040 * @param id
041 *
042 * The content identifier passed to isAvailable() to determine if
043 * the content is already valid. The parameter may be any Id
044 * object that potentially matches via the equals() method.
045 *
046 * @param contentAccessor
047 *
048 * An object capable of making content accessible via an InputStream.
049 * For example, a ContentAccessor might retrieve content from a
050 * website via a URL, a database or file storage, a remote object
051 * such as another cache, or even dynamically generate the content
052 * upon demand. As yet another possibility, a ContentAccessor object
053 * may potentially attempt to access the content from several
054 * different sources sequentially until it is successful.
055 *
056 * @return
057 *
058 * Returns an Id object for the validated content which may be
059 * used later for retrieval.
060 *
061 * <P>
062 *
063 * If valid content was already available in the cache, the returned
064 * Id object will be the id parameter.
065 *
066 * <P>
067 *
068 * If valid content was not already available and the content could
069 * not be accessed and stored via the contentAccessor, the returned
070 * value will be null.
071 *
072 * <P>
073 *
074 * If valid content was not already available and the content could
075 * be accessed and stored via the contentAccessor, the returned
076 * value will be a new Id object with values that may or may
077 * not equal that of the id object parameter, depending on
078 * the actual content available via the contentAccessor.
079 *
080 *********************************************************************/
081 public Id validate ( Id id, ContentAccessor contentAccessor )
082 throws IOException;
083
084 /*********************************************************************
085 * Stores the contents and returns an Id to be used for retrieval.
086 *
087 * <P>
088 *
089 * Reads the stream until completion and closes it before return.
090 *
091 * @return
092 * Returns an Id to be used for later retrieval.
093 * Returns null if the storage was unsuccessful.
094 *********************************************************************/
095 public Id store ( InputStream in ) throws IOException;
096
097 /*********************************************************************
098 * Retrieves the content associated with this Id.
099 *
100 * @param id
101 * Returns the content associated with this id or its equivalent.
102 * @return
103 * May return null.
104 *********************************************************************/
105 public InputStream retrieve ( Id id ) throws IOException;
106
107 /*********************************************************************
108 * Returns false if the content is no longer available.
109 *
110 * @param id
111 * An Id object to be used to retrieve the content.
112 *********************************************************************/
113 public boolean isAvailable ( Id id );
114
115 //////////////////////////////////////////////////////////////////////
116 //////////////////////////////////////////////////////////////////////
117 }