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="http://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         }