Cache


1   /*
2    * The Apache Software License, Version 1.1
3    *
4    * Copyright (c) 2001-2004 Caucho Technology, Inc.  All rights reserved.
5    *
6    * Redistribution and use in source and binary forms, with or without
7    * modification, are permitted provided that the following conditions
8    * are met:
9    *
10   * 1. Redistributions of source code must retain the above copyright
11   *    notice, this list of conditions and the following disclaimer.
12   *
13   * 2. Redistributions in binary form must reproduce the above copyright
14   *    notice, this list of conditions and the following disclaimer in
15   *    the documentation and/or other materials provided with the
16   *    distribution.
17   *
18   * 3. The end-user documentation included with the redistribution, if
19   *    any, must include the following acknowlegement:
20   *       "This product includes software developed by the
21   *        Caucho Technology (http://www.caucho.com/)."
22   *    Alternately, this acknowlegement may appear in the software itself,
23   *    if and wherever such third-party acknowlegements normally appear.
24   *
25   * 4. The names "Hessian", "Resin", and "Caucho" must not be used to
26   *    endorse or promote products derived from this software without prior
27   *    written permission. For written permission, please contact
28   *    info@caucho.com.
29   *
30   * 5. Products derived from this software may not be called "Resin"
31   *    nor may "Resin" appear in their names without prior written
32   *    permission of Caucho Technology.
33   *
34   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
35   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
36   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
37   * DISCLAIMED.  IN NO EVENT SHALL CAUCHO TECHNOLOGY OR ITS CONTRIBUTORS
38   * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
39   * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
40   * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
41   * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
42   * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
43   * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
44   * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
45   *
46   * @author Sam
47   */
48  
49  
50  package com.caucho.portal.generic;
51  
52  import javax.portlet.RenderRequest;
53  import javax.portlet.RenderResponse;
54  import java.io.IOException  ;
55  import java.io.OutputStream  ;
56  import java.io.Writer  ;
57  import java.util.Map  ;
58  import java.util.logging.Logger  ;
59  
60  
61  abstract public class Cache
62  {
63    protected static final Logger   log = 
64      Logger.getLogger(Cache.class.getName());
65  
66    /**
67     * Send a response from the cache, or return false if there is no
68     * response from the cache.
69     * 
70     * The passed cacheKey can be manipulated by the cache without side-effects,
71     * but the cache cannot take ownership of the cacheKey because it may be 
72     * pooled by the caller.
73     *
74     * Binary responses should be sent to the OutputStream obtained with
75     * response.getOutputStream().
76     *  
77     * Textual response should be sent to the PrintWriter obtained with
78     * response.getWriter().
79     * response.setCharacterEncoding() should be used before getWriter()
80     * to set the character encoding to the character encoding that was in
81     * use when the response was cached.
82     *
83     * If isPrivate is true, then cacheKey.getRequestedSessionId() will have a
84     * non-null value. 
85     *
86     * A cache should first perform a lookup with the CacheKey as provided.
87     * If that fails, it should call cacheKey.setLocale(null) and try again.
88     * 
89     * The cache should also check the value of cacheKey.getContentType().
90     * If the contentType is null, the cache can respond if it has an entry
91     * that matches for one contentType.  If a match is found, the cache
92     * sets the contentType with connection.setContentType().
93     *
94     * @return 0 if no response was written from the cache, otherwise the number 
95     * of seconds that a response written from the cache is good for or -1
96     * if the cached reponse is good forever
97     */
98    abstract public int respondFromCache(CacheKey cacheKey,
99                                         RenderRequest request,
100                                        RenderResponse response);
101 
102   /**
103    * Called to give the Cache an opportunity to cache the response.
104    *
105    * If the response can be cached, the implementation returns a Writer
106    * that receives the response.
107    * 
108    * When the response is completed, finishCaching(Writer) will be called.
109    *
110    * If the response cannot be cached, the implementation returns null.
111    *
112    * At this point, the expirationCache is a best guess and the real value
113    * passed to finishCaching() may be different.
114    *
115    * @param  window the portlet configuration for the portlet about to
116    * be rendered
117    *
118    * @param namespace the namespace for the portlet about to be rendered
119    *
120    * @param expirationCache a best guess at the expiration period in seconds, 
121    * -1 if unlimited
122    *
123    * @return a Writer that intercepts the content and then writes to
124    * response.getWriter(), or null if the response cannot be cached. 
125    */
126   abstract public Writer   getCachingWriter(String   namespace,
127                                           int expirationCache,
128                                           boolean isPrivate)
129     throws IOException  ;
130 
131   /**
132    * Called immediately before a Portlet is rendered to give the Cache
133    * an opportunity to cache the response.
134    *
135    * If the response can be cached, the implementation returns an OutputStream
136    * that receives the response.
137    * 
138    * When the response is completed, finishCaching(OutputStream) will be called.
139    *
140    * If the response cannot be cached, the implementation returns null.
141    *
142    * At this point, the expirationCache is a best guess and the real value
143    * passed to finishCaching() may be different.
144    *
145    * @param  window the portlet window for the portlet about to
146    * be rendered
147    *
148    * @param namespace the namespace for the portlet about to be rendered
149    *
150    * @param expirationCache a best guess at the expiration period in seconds, 
151    * -1 if unlimited
152    *
153    * @return an OutputStream that intercepts the content and then writes to
154    * response.getOutputStream(), or null if the response cannot be cached. 
155    */
156   abstract public OutputStream   getCachingOutputStream(String   namespace,
157                                                       int expirationCache,
158                                                       boolean isPrivate)
159 
160     throws IOException  ;
161 
162   /**
163    * Finish with a Writer previously returned by 
164    * {@link #startCachingWriter}. If the expirationCache is 0 or the cacheKey is
165    * null, the cached response must be discarded.
166    *
167    * @param writer the writer returned from {@link #startCachingWriter}
168    *
169    * @param expirationCache the updated expirationCache, this may the same
170    * value received in {@link  #startWriter}, a new value set by
171    * the portlet while it rendered itself, or 0 if the cache must be
172    * discarded.
173    *
174    * @param cacheKey the {@link CacheKey} that uniquely differentiates this 
175    * response from other responses
176    *
177    * @param encoding the encoding for the Writer, the cache needs to call
178    * response.setEncoding(encoding) if it later responds in respondFromCache().
179    *
180    * @param cachePropertiesMap a map of properties that begin with "Cache-",
181    * these may be directives to the cache or may be keys and values that should
182    * distinguish the uniqueness of the Cached value beyond the uniqueness
183    * established by CacheKey, depending on the portal implementation. 
184    * These properties should be recreated during respondFromCache().
185    * If the value is a String, setProperty is used.  If the value is
186    * an ArrayList<String>, add property is used. 
187    *
188    * @param propertiesMap a map of properties that the Cache must recreate
189    * when the cached response is used in a susbsequent call to respondFromCache
190    * If the value is a String, setProperty is used.  If the value is
191    * an ArrayList<String>, add property is used. 
192    *
193    * @param requestAttributesMap a map of request attributes that the Cache
194    * must recreate when the cached response is used in a susbsequent call to
195    * respondFromCache
196    */ 
197   abstract public void finishCaching( 
198       Writer   writer, 
199       int expirationCache,
200       CacheKey cacheKey,
201       String   encoding,
202       Map  <String  , Object  > cachePropertiesMap,
203       Map  <String  , Object  > propertiesMap,
204       Map  <String  , String  > requestAttributeMap );
205 
206   /**
207    * Finish with an OutputStream previously returned by 
208    * {@link #startCachingOutputStream}. If the cacheKey is null or
209    * the expirationCache is 0, the cached response must be discarded.
210    */ 
211   abstract public void finishCaching(
212       OutputStream   outputStream,
213       int expirationCache,
214       CacheKey cacheKey,
215       Map  <String  , Object  > cachePropertiesMap,
216       Map  <String  , Object  > propertiesMap,
217       Map  <String  , String  > requestAttributeMap );
218 }
219 
220
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags