1 package de.halbekunst.juplo.cachecontrol;
5 import javax.servlet.http.HttpServletRequest;
6 import javax.servlet.http.HttpServletResponse;
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}
16 * @see CachingInterceptor
19 public interface Cacheable {
20 public boolean accepts(HttpServletRequest request);
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.
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.
30 * @see CachingDispatcherServlet
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.
38 public boolean isGenerateCacheHeaders(HttpServletRequest request) throws IllegalArgumentException;
41 * Diese Methode ermöglicht eine einfache, zentrale Steuerung des
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>
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!
63 * @see #getLastModified(javax.servlet.http.HttpServletRequest)
64 * @see #getCacheControl(javax.servlet.http.HttpServletRequest)
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
71 * @throws IllegalArgumentException
72 * Wenn zu dem Request keine Ressource existiert.
74 public int getCacheSeconds(HttpServletRequest request) throws IllegalArgumentException;
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.
81 * <strong>Zu beachten:</strong>
83 * <li>Diese Methode wird nicht aufgerufen, wenn
84 * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)}
85 * <code>0</code> liefert.</li>
88 * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
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.
95 public long getLastModified(HttpServletRequest request) throws IllegalArgumentException;
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:
102 * <li><code>"24afh2w3848adf"</code>
103 * <li><code>W/"839482"</code>
104 * <li><code>""</code>
106 * <strong>Merke:</strong> Der wert ist immer in doppelte Anführungszeichen
109 * <strong>Zu beachten:</strong>
111 * <li>Diese Methode wird nicht aufgerufen, wenn
112 * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)}
113 * <code>0</code> liefert.</li>
116 * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
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.
124 public String getETag(HttpServletRequest request) throws IllegalArgumentException;
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}).
132 * <strong>Zu beachten:</strong>
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,
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>
144 * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
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.
152 public Map<String, String> getCacheControl(HttpServletRequest request) throws IllegalArgumentException;