juplo.de Git - percentcodec/blob - cachecontrol/src/main/java/de/halbekunst/juplo/cachecontrol/Cacheable.java

   1 package de.halbekunst.juplo.cachecontrol;
   2
   3
   4 import java.util.Map;
   5 import javax.servlet.http.HttpServletRequest;
   6 import javax.servlet.http.HttpServletResponse;
   7
   8
   9 /**
  10  * Wenn ein Handler (i.A. eine Impelementierung von {@Controller}),
  11  * dieses Interface implementiert, dann schreibt
  12  * {@link CachingInterceptor} HTTP/1.1-Caching-Header nach
  13  * {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html RFC 2616}
  14  * in den Response.
  15  *
  16  * @see CachingInterceptor
  17  * @author kai
  18  */
  19 public interface Cacheable {
  20   public boolean accepts(HttpServletRequest request);
  21
  22   /**
  23    * Wenn die Methode <code>false</code> zurückliefert, werden von
  24    * {@link CachingDispatcherServlet#isRessourceModified(HttpServletRequest, HttpServletResponse, Cacheable)}
  25    * keinerlei HTTP/1.1-Cache-Header in den Response eingebaut.
  26    * <p>
  27    * Über diese Methode kann z.B. gesteuert werden, dass für eine bestimmte
  28    * HTTP-Methode (z.B. POST) keine Cache-Header generiert werden.
  29    *
  30    * @see CachingDispatcherServlet
  31    * @param request
  32    *          Der aktuelle HTTP-Request
  33    * @return <code>true</code>, wenn Caching-Header in den Response geschrieben
  34    *         werden sollen, sonst <code>false</code>.
  35    * @throws IllegalArgumentException
  36    *           Wenn zu dem Request keine Ressource existiert.
  37    */
  38   public boolean isGenerateCacheHeaders(HttpServletRequest request) throws IllegalArgumentException;
  39
  40   /**
  41    * Diese Methode ermöglicht eine einfache, zentrale Steuerung des
  42    * Caching-Verhaltens.
  43    * <ul>
  44    * <li>Wenn die Methode den Wert <code>0</code> (oder einen anderen Wert
  45    * kleiner <code>1</code>) zurückliefert, werden Cache-Header erzeugt, die das
  46    * Cachen der Antwort für HTTP/1.0 und HTTP/1.1 vollständig untersagen,</li>
  47    * <li>Wenn die Methode einen Wert größer <code>0</code> zurückliefert, wird
  48    * ein für HTTP/1.0-Clients ein <code>Expires</code>-Header generiert und für
  49    * HTTP/1.1-Clients ein <code>Cache-Control</code>-Header mit einem
  50    * entsprechenden <code>max-age</code>-Eintrag. Dies reicht in Kombination mit
  51    * einem sinnvollen Rückgabewert der Methode
  52    * {@link #getLastModified(javax.servlet.http.HttpServletRequest)} vollständig
  53    * für ein einfaches Caching aus.</li>
  54    * </ul>
  55    * <p>
  56    * <strong>Zu beachten:</strong> Wenn die Methode
  57    * {@link #getCacheControl(javax.servlet.http.HttpServletRequest)} weitere
  58    * Schlüssel-Wert-Paare für den <code>Cache-Control</code>-Header liefert,
  59    * werden diese ergänzt. Wenn in der Rückgabe ein Wert für
  60    * <code>max-age</code> enthalten ist, wir er allerdings von dem durch diese
  61    * Methode vorgegebenen Wert überschrieben!
  62    *
  63    * @see #getLastModified(javax.servlet.http.HttpServletRequest)
  64    * @see #getCacheControl(javax.servlet.http.HttpServletRequest)
  65    * @param request
  66    *          Der aktuelle HTTP-Request
  67    * @return Die gewünschte Cache-Zeit in Sekunden, oder <code>0</code>, wenn
  68    *         Caching aktiv unterbunden werden soll bzw. einen Wert kleiner
  69    *         <code>0</code>, wenn kein <code>Expires</code>-Header generiert
  70    *         werden soll.
  71    * @throws IllegalArgumentException
  72    *           Wenn zu dem Request keine Ressource existiert.
  73    */
  74   public int getCacheSeconds(HttpServletRequest request) throws IllegalArgumentException;
  75
  76   /**
  77    * Zeitpunkt, zu dem die Ressource zuletzt verändert wurde. Erwartet wird eine
  78    * Zeitangabe in Millisekunden seit dem Unix-0-Zeitpunkt, wie sie von
  79    * {@link HttpServletResponse#setDateHeader(String, long)} erwartet wird.
  80    * <p>
  81    * <strong>Zu beachten:</strong>
  82    * <ul>
  83    * <li>Diese Methode wird nicht aufgerufen, wenn
  84    * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)}
  85    * <code>0</code> liefert.</li>
  86    * </ul>
  87    *
  88    * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
  89    * @param request
  90    *          Der aktuelle HTTP-Request
  91    * @return Zeitstempel, zu dem die Ressource zuletzt modifiziert wurde.
  92    * @throws IllegalArgumentException
  93    *           Wenn zu dem Request keine Ressource existiert.
  94    */
  95   public long getLastModified(HttpServletRequest request) throws IllegalArgumentException;
  96
  97   /**
  98    * Frei wählbares ETag nach {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19 RFC 2616,
  99    * Abschnitt 14.19 ETag}. Der ETag wird unverändert übernommen und muss den
 100    * Bedingungen aus dem RFC 2616 entsprechen. Beispiele für erlaubte Werte:
 101    * <ul>
 102    * <li><code>"24afh2w3848adf"</code>
 103    * <li><code>W/"839482"</code>
 104    * <li><code>""</code>
 105    * </ul>
 106    * <strong>Merke:</strong> Der wert ist immer in doppelte Anführungszeichen
 107    * einzuschließen!
 108    * <p>
 109    * <strong>Zu beachten:</strong>
 110    * <ul>
 111    * <li>Diese Methode wird nicht aufgerufen, wenn
 112    * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)}
 113    * <code>0</code> liefert.</li>
 114    * </ul>
 115    *
 116    * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
 117    * @param request
 118    *          Der aktuelle HTTP-Request
 119    * @return Das zu verwendende ETag, oder <code>null</code>, wenn der Header
 120    *         nicht generiert werden soll.
 121    * @throws IllegalArgumentException
 122    *           Wenn zu dem Request keine Ressource existiert.
 123    */
 124   public String getETag(HttpServletRequest request) throws IllegalArgumentException;
 125
 126   /**
 127    * Diese Methode liefert eine Map mit Schlüssel-Wert-Paaren für den
 128    * HTTP/1.1-Header <code>Cache-Control</code> (s. {@plainlink
 129    * http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.3 RFC2616,
 130    * Abschnitt 14.9.3}).
 131    * <p>
 132    * <strong>Zu beachten:</strong>
 133    * <ul>
 134    * <li>Die Methode darf nie <code>null</code> zurückliefern!</li>
 135    * <li>Ein Wert für den Schlüssel <code>max-age</code> wird überschrieben,
 136    * wenn die Methode
 137    * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)} einen Wert
 138    * größer <code>0</code> zurückliefert.</li>
 139    * <li>Diese Methode wird nicht aufgerufen, wenn
 140    * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)}
 141    * <code>0</code> liefert.</li>
 142    * </ul>
 143    *
 144    * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
 145    * @param request
 146    *          Der aktuelle HTTP-Request
 147    * @return Eine <code>Map</code> mit den Schlüssel-Wert-Paaren für den
 148    *         <code>Cache-Control</code>-Header.
 149    * @throws IllegalArgumentException
 150    *           Wenn zu dem Request keine Ressource existiert.
 151    */
 152   public Map<String, String> getCacheControl(HttpServletRequest request) throws IllegalArgumentException;
 153 }