X-Git-Url: https://juplo.de/gitweb/?p=percentcodec;a=blobdiff_plain;f=utils%2Fcachecontrol%2Fsrc%2Fmain%2Fjava%2Fde%2Fhalbekunst%2Futils%2Fcachecontrol%2FCacheable.java;fp=utils%2Fcachecontrol%2Fsrc%2Fmain%2Fjava%2Fde%2Fhalbekunst%2Futils%2Fcachecontrol%2FCacheable.java;h=c9f43d85c15ecd897213cd032ee3a9d7f2aa6700;hp=0000000000000000000000000000000000000000;hb=df103dc28bf3d7c9b319c9e6955cd4f4c3c989be;hpb=576bdc0cc542da20480d0ea34ec2bb42011ec4f5

diff --git a/utils/cachecontrol/src/main/java/de/halbekunst/utils/cachecontrol/Cacheable.java b/utils/cachecontrol/src/main/java/de/halbekunst/utils/cachecontrol/Cacheable.java
new file mode 100644
index 00000000..c9f43d85
--- /dev/null
+++ b/utils/cachecontrol/src/main/java/de/halbekunst/utils/cachecontrol/Cacheable.java
@@ -0,0 +1,153 @@
+package de.halbekunst.utils.cachecontrol;
+
+
+import java.util.Map;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+
+/**
+ * Wenn ein Handler (i.A. eine Impelementierung von {@Controller}),
+ * dieses Interface implementiert, dann schreibt
+ * {@link CachingInterceptor} HTTP/1.1-Caching-Header nach
+ * {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html RFC 2616}
+ * in den Response.
+ *
+ * @see CachingInterceptor
+ * @author kai
+ */
+public interface Cacheable {
+  public boolean accepts(HttpServletRequest request);
+
+  /**
+   * Wenn die Methode <code>false</code> zurückliefert, werden von
+   * {@link CachingDispatcherServlet#isRessourceModified(HttpServletRequest, HttpServletResponse, Cacheable)}
+   * keinerlei HTTP/1.1-Cache-Header in den Response eingebaut.
+   * <p>
+   * Über diese Methode kann z.B. gesteuert werden, dass für eine bestimmte
+   * HTTP-Methode (z.B. POST) keine Cache-Header generiert werden.
+   *
+   * @see CachingDispatcherServlet
+   * @param request
+   *          Der aktuelle HTTP-Request
+   * @return <code>true</code>, wenn Caching-Header in den Response geschrieben
+   *         werden sollen, sonst <code>false</code>.
+   * @throws IllegalArgumentException
+   *           Wenn zu dem Request keine Ressource existiert.
+   */
+  public boolean isGenerateCacheHeaders(HttpServletRequest request) throws IllegalArgumentException;
+
+  /**
+   * Diese Methode ermöglicht eine einfache, zentrale Steuerung des
+   * Caching-Verhaltens.
+   * <ul>
+   * <li>Wenn die Methode den Wert <code>0</code> (oder einen anderen Wert
+   * kleiner <code>1</code>) zurückliefert, werden Cache-Header erzeugt, die das
+   * Cachen der Antwort für HTTP/1.0 und HTTP/1.1 vollständig untersagen,</li>
+   * <li>Wenn die Methode einen Wert größer <code>0</code> zurückliefert, wird
+   * ein für HTTP/1.0-Clients ein <code>Expires</code>-Header generiert und für
+   * HTTP/1.1-Clients ein <code>Cache-Controll</code>-Header mit einem
+   * entsprechenden <code>max-age</code>-Eintrag. Dies reicht in Kombination mit
+   * einem sinnvollen Rückgabewert der Methode
+   * {@link #getLastModified(javax.servlet.http.HttpServletRequest)} vollständig
+   * für ein einfaches Caching aus.</li>
+   * </ul>
+   * <p>
+   * <strong>Zu beachten:</strong> Wenn die Methode
+   * {@link #getCacheControll(javax.servlet.http.HttpServletRequest)} weitere
+   * Schlüssel-Wert-Paare für den <code>Cache-Controll</code>-Header liefert,
+   * werden diese ergänzt. Wenn in der Rückgabe ein Wert für
+   * <code>max-age</code> enthalten ist, wir er allerdings von dem durch diese
+   * Methode vorgegebenen Wert überschrieben!
+   *
+   * @see #getLastModified(javax.servlet.http.HttpServletRequest)
+   * @see #getCacheControll(javax.servlet.http.HttpServletRequest)
+   * @param request
+   *          Der aktuelle HTTP-Request
+   * @return Die gewünschte Cache-Zeit in Sekunden, oder <code>0</code>, wenn
+   *         Caching aktiv unterbunden werden soll bzw. einen Wert kleiner
+   *         <code>0</code>, wenn kein <code>Expires</code>-Header generiert
+   *         werden soll.
+   * @throws IllegalArgumentException
+   *           Wenn zu dem Request keine Ressource existiert.
+   */
+  public int getCacheSeconds(HttpServletRequest request) throws IllegalArgumentException;
+
+  /**
+   * Zeitpunkt, zu dem die Ressource zuletzt verändert wurde. Erwartet wird eine
+   * Zeitangabe in Millisekunden seit dem Unix-0-Zeitpunkt, wie sie von
+   * {@link HttpServletResponse#setDateHeader(String, long)} erwartet wird.
+   * <p>
+   * <strong>Zu beachten:</strong>
+   * <ul>
+   * <li>Diese Methode wird nicht aufgerufen, wenn
+   * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)}
+   * <code>0</code> liefert.</li>
+   * </ul>
+   *
+   * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
+   * @param request
+   *          Der aktuelle HTTP-Request
+   * @return Zeitstempel, zu dem die Ressource zuletzt modifiziert wurde.
+   * @throws IllegalArgumentException
+   *           Wenn zu dem Request keine Ressource existiert.
+   */
+  public long getLastModified(HttpServletRequest request) throws IllegalArgumentException;
+
+  /**
+   * Frei wählbares ETag nach {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19 RFC 2616,
+   * Abschnitt 14.19 ETag}. Der ETag wird unverändert übernommen und muss den
+   * Bedingungen aus dem RFC 2616 entsprechen. Beispiele für erlaubte Werte:
+   * <ul>
+   * <li><code>"24afh2w3848adf"</code>
+   * <li><code>W/"839482"</code>
+   * <li><code>""</code>
+   * </ul>
+   * <strong>Merke:</strong> Der wert ist immer in doppelte Anführungszeichen
+   * einzuschließen!
+   * <p>
+   * <strong>Zu beachten:</strong>
+   * <ul>
+   * <li>Diese Methode wird nicht aufgerufen, wenn
+   * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)}
+   * <code>0</code> liefert.</li>
+   * </ul>
+   *
+   * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
+   * @param request
+   *          Der aktuelle HTTP-Request
+   * @return Das zu verwendende ETag, oder <code>null</code>, wenn der Header
+   *         nicht generiert werden soll.
+   * @throws IllegalArgumentException
+   *           Wenn zu dem Request keine Ressource existiert.
+   */
+  public String getETag(HttpServletRequest request) throws IllegalArgumentException;
+
+  /**
+   * Diese Methode liefert eine Map mit Schlüssel-Wert-Paaren für den
+   * HTTP/1.1-Header <code>Cache-Controll</code> (s. {@plainlink
+   * http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.3 RFC2616,
+   * Abschnitt 14.9.3}).
+   * <p>
+   * <strong>Zu beachten:</strong>
+   * <ul>
+   * <li>Die Methode darf nie <code>null</code> zurückliefern!</li>
+   * <li>Ein Wert für den Schlüssel <code>max-age</code> wird überschrieben,
+   * wenn die Methode
+   * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)} einen Wert
+   * größer <code>0</code> zurückliefert.</li>
+   * <li>Diese Methode wird nicht aufgerufen, wenn
+   * {@link #getCacheSeconds(javax.servlet.http.HttpServletRequest)}
+   * <code>0</code> liefert.</li>
+   * </ul>
+   *
+   * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
+   * @param request
+   *          Der aktuelle HTTP-Request
+   * @return Eine <code>Map</code> mit den Schlüssel-Wert-Paaren für den
+   *         <code>Cache-Controll</code>-Header.
+   * @throws IllegalArgumentException
+   *           Wenn zu dem Request keine Ressource existiert.
+   */
+  public Map<String, String> getCacheControll(HttpServletRequest request) throws IllegalArgumentException;
+}