CacheControl so umgebaut, dass es sich über Annotationen einbinden lässt

[percentcodec] / cachecontrol / src / main / java / de / halbekunst / juplo / cachecontrol / annotations / CacheSeconds.java

diff --git a/cachecontrol/src/main/java/de/halbekunst/juplo/cachecontrol/annotations/CacheSeconds.java b/cachecontrol/src/main/java/de/halbekunst/juplo/cachecontrol/annotations/CacheSeconds.java
new file mode 100644 (file)
index 0000000..e076e08
--- /dev/null
+++ b/cachecontrol/src/main/java/de/halbekunst/juplo/cachecontrol/annotations/CacheSeconds.java
@@ -0,0 +1,52 @@
+package de.halbekunst.juplo.cachecontrol.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import javax.servlet.http.HttpServletRequest;
+
+/**
+ * Mit dieser Annotation können Klassen oder Methoden merkiert werden.
+ * <p>
+ * Wenn eine Methode markiert wird, muss diese eine Instanz von
+ * {@link HttpServletRequest} als (einziges!) Argument akzeptieren und einen
+ * Wert liefern, der sich nach <code>int</code> casten lässt.
+ * Die annotierte Methode ermöglicht eine einfache, zentrale aber Request-
+ * Abhängige Steuerung des Caching-Verhaltens.
+ * <p>
+ * Wenn eine Klasse annotiert wird, muss der Anotation die dann statisch für
+ * alle von der Klasse erzeugten Antworten gültige Cache-Zeit als Argument
+ * übergeben werden.
+ * Wird keine Cache-Zeit spezifiziert, wird der Wert <code>86400</code>
+ * (ein Tag) verwendet.
+ * <ul>
+ * <li>Wenn negativer Wert als Cache-Seconds festgelet wird, werden Cache-Header
+ * erzeugt, die das Cachen der Antwort für HTTP/1.0 und HTTP/1.1 vollständig
+ * untersagen.</li>
+ * <li>Wenn einen Wert größer oder gleich <code>0</code> festgelegt wird, wird
+ * für HTTP/1.0-Clients ein <code>Expires</code>-Header generiert und für
+ * HTTP/1.1-Clients ein <code>Cache-Control</code>-Header mit einem
+ * entsprechenden <code>max-age</code>-Eintrag. Dies reicht in Kombination mit
+ * der Annotation {@link LastModified} vollständig für ein einfaches aber
+ * effektives Caching aus.</li>
+ * </ul>
+ * <p>
+ * TODO
+ * <strong>Zu beachten:</strong> Wenn die Methode
+ * {@link #getCacheControl(javax.servlet.http.HttpServletRequest)} weitere
+ * Schlüssel-Wert-Paare für den <code>Cache-Control</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!
+ *
+ * @author kai
+ * @See Cacheable
+ * @See LastModified
+ * @See CacheControl
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE, ElementType.METHOD })
+public @interface CacheSeconds {
+  int value() default 86400; /** Default: 1 Tag */
+}