1 package de.juplo.accelerator.annotations;
3 import java.lang.annotation.ElementType;
4 import java.lang.annotation.Retention;
5 import java.lang.annotation.RetentionPolicy;
6 import java.lang.annotation.Target;
7 import javax.servlet.http.HttpServletRequest;
10 * Über diese Annotation kann der Inhalt des <code>ETag/code>-Headers
12 * Mit dieser Annotation können Klassen oder Methoden merkiert werden.
14 * Wenn eine Methode annotiert wird, muss diese eine Instanz von
15 * {@link HttpServletRequest} als (einziges!) Argument akzeptieren und einen
16 * <code>String</code> liefern.
18 * Wenn eine Klasse Annotiert wird, muss der Annotation der Wert für den
19 * <code>ETag</code>-Header übergeben werden.
20 * Da dieser Wert somit statisch ist, macht es nur Sinn, Klassen mit dieser
21 * Annotation zu markieren, die ausschließlich statische Ressourcen ausliefern,
22 * die sich nur mit der Neuinstallation der Webanwendung ändern.
23 * Wenn sich (z.B. nach einer Neuinstallation der Webanwendung) die statischen
24 * Ressourcen geändert haben, muss der übergebene statische ETag geändert
25 * werden, da Caches sonst weiterhin die alten Ressourcen ausliefern!
27 * Frei wählbares ETag nach
28 * {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19 RFC 2616, Abschnitt 14.19 ETag}.
29 * Der gelieferte Wert darf die vom RFC geforderten Anführungszeichen noch nicht
30 * enthalten, da er, wenn <code>vary</code> gesetzt ist, noch um je nach
31 * erfolgter Content-Negotiation varriierende Teile ergänzt wird.
33 * Die erzeugten <code>ETag</code>'s können über die Annotations-Parameter
34 * <code>weak</code> und <code>vary</code> weiter gesteuert werden.
37 * Wenn der Parameter <strong>weak</strong> auf den wert <code>true</code>
38 * gesetzt wird, wird ein schwaches <code>ETag</code> erezeugt und der
39 * Vergleichs-Algorithmus verhält sich entsprechend anders (siehe:
40 * {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.3.3 RFC 2616, Abschnitt 13.3.3 Weak and Strong Validators}).
43 * Über den Parameter <strong>vary</strong> kann Juplo-CacheControl damit
44 * beauftragt werden, die Nötigen Maßnahmen für korrektes Content-Negotiating
45 * zu ergreifen (siehe:
46 * {@linkplain http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.6 RFC 2616, Abschnitt 13.6 Caching Negotiated Responses}).
47 * Als Eingabe werden die Header-Namen erwertet, die zu unterschiedlichen
48 * Ergebnissen der Content-Negotiation führen können (hier können folgende
49 * Header angegeben werden: <code>Accept</code>, <code>Accept-Charset</code>,
50 * <code>Accept-Encoding</code> und <code>Accept-Language</code>).
51 * Juplo-CacheControl modifizert den übergebenen <code>ETag</code> dann so,
52 * dass unterschiedliche Resultate der Content-Negotiation unterschieden
54 * Außerdem wird der <code>Vary</code>-Header entsprechend gesetzt.
57 * <strong>Zu beachten:</strong>
58 * Wenn zugleich die Annotation {@link CacheSeconds} verwendet wird, wird
59 * die mit dieser Annotation markierte Methode nur aufgerufen, wenn die mit
60 * der Annotation {@link CacheSeconds} markierte Methode einen Wert größer
61 * oder gleich <code>0</code> liefert, bzw. für die mit Annotation
62 * {@link CacheSeconds} markierte Klasse eine Cache-Zeit größer oder gleich
63 * <code>0</code> festgelegt wurde.
65 * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
71 @Retention(RetentionPolicy.RUNTIME)
72 @Target({ ElementType.TYPE, ElementType.METHOD })
73 public @interface ETag {
75 public final static String ACCEPT = "Accept";
76 public final static String ACCEPT_CHARSET = "Accept-Charset";
77 public final static String ACCEPT_ENCODING = "Accept-Encoding";
78 public final static String ACCEPT_LANGUAGE = "Accept-Language";
81 String value() default "X";
82 boolean weak() default false;
83 String[] vary() default {};