Projekt von de.halbekunst.juplo nach de.juplo verschoben und aufgeräumt

[percentcodec] / accelerator / src / main / java / de / juplo / accelerator / annotations / ETag.java

diff --git a/accelerator/src/main/java/de/juplo/accelerator/annotations/ETag.java b/accelerator/src/main/java/de/juplo/accelerator/annotations/ETag.java
new file mode 100644 (file)
index 0000000..81b6d16
--- /dev/null
+++ b/accelerator/src/main/java/de/juplo/accelerator/annotations/ETag.java
@@ -0,0 +1,84 @@
+package de.juplo.accelerator.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;
+
+/**
+ * Über diese Annotation kann der Inhalt des <code>ETag/code>-Headers
+ * gesteuert werden.
+ * Mit dieser Annotation können Klassen oder Methoden merkiert werden.
+ * <p>
+ * Wenn eine Methode annotiert wird, muss diese eine Instanz von
+ * {@link HttpServletRequest} als (einziges!) Argument akzeptieren und einen
+ * <code>String</code> liefern.
+ * <p>
+ * Wenn eine Klasse Annotiert wird, muss der Annotation der Wert für den
+ * <code>ETag</code>-Header übergeben werden.
+ * Da dieser Wert somit statisch ist, macht es nur Sinn, Klassen mit dieser
+ * Annotation zu markieren, die ausschließlich statische Ressourcen ausliefern,
+ * die sich nur mit der Neuinstallation der Webanwendung ändern.
+ * Wenn sich (z.B. nach einer Neuinstallation der Webanwendung) die statischen
+ * Ressourcen geändert haben, muss der übergebene statische ETag geändert
+ * werden, da Caches sonst weiterhin die alten Ressourcen ausliefern!
+ * </p>
+ * Frei wählbares ETag nach
+ * {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19 RFC 2616, Abschnitt 14.19 ETag}.
+ * Der gelieferte Wert darf die vom RFC geforderten Anführungszeichen noch nicht
+ * enthalten, da er, wenn <code>vary</code> gesetzt ist, noch um je nach
+ * erfolgter Content-Negotiation varriierende Teile ergänzt wird.
+ * <p>
+ * Die erzeugten <code>ETag</code>'s können über die Annotations-Parameter
+ * <code>weak</code> und <code>vary</code> weiter gesteuert werden.
+ * <ul>
+ * <li>
+ * Wenn der Parameter <strong>weak</strong> auf den wert <code>true</code>
+ * gesetzt wird, wird ein schwaches <code>ETag</code> erezeugt und der
+ * Vergleichs-Algorithmus verhält sich entsprechend anders (siehe:
+ * {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.3.3 RFC 2616, Abschnitt 13.3.3 Weak and Strong Validators}).
+ * </li>
+ * <li>
+ * Über den Parameter <strong>vary</strong> kann Juplo-CacheControl damit
+ * beauftragt werden, die Nötigen Maßnahmen für korrektes Content-Negotiating
+ * zu ergreifen (siehe:
+ * {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.6 RFC 2616, Abschnitt 13.6 Caching Negotiated Responses}).
+ * Als Eingabe werden die Header-Namen erwertet, die zu unterschiedlichen
+ * Ergebnissen der Content-Negotiation führen können (hier können folgende
+ * Header angegeben werden: <code>Accept</code>, <code>Accept-Charset</code>,
+ * <code>Accept-Encoding</code> und <code>Accept-Language</code>).
+ * Juplo-CacheControl modifizert den übergebenen <code>ETag</code> dann so,
+ * dass unterschiedliche Resultate der Content-Negotiation unterschieden
+ * werden können.
+ * Außerdem wird der <code>Vary</code>-Header entsprechend gesetzt.
+ *</li>
+ * </ul>
+ * <strong>Zu beachten:</strong>
+ * Wenn zugleich die Annotation {@link CacheSeconds} verwendet wird, wird
+ * die mit dieser Annotation markierte Methode nur aufgerufen, wenn die mit
+ * der Annotation {@link CacheSeconds} markierte Methode einen Wert größer
+ * oder gleich <code>0</code> liefert, bzw. für die mit Annotation
+ * {@link CacheSeconds} markierte Klasse eine Cache-Zeit größer oder gleich
+ * <code>0</code> festgelegt wurde.
+ *
+ * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
+ *
+ * @author kai
+ * @see Cacheable
+ * @see CacheSeconds
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE, ElementType.METHOD })
+public @interface ETag {
+
+  public final static String ACCEPT = "Accept";
+  public final static String ACCEPT_CHARSET = "Accept-Charset";
+  public final static String ACCEPT_ENCODING = "Accept-Encoding";
+  public final static String ACCEPT_LANGUAGE = "Accept-Language";
+
+
+  String value() default "X";
+  boolean weak() default false;
+  String[] vary() default {};
+}