juplo.de Git - percentcodec/blob - cachecontrol/src/main/java/de/halbekunst/juplo/cachecontrol/annotations/ETag.java

   1 package de.halbekunst.juplo.cachecontrol.annotations;
   2
   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;
   8
   9 /**
  10  * Über diese Annotation kann der Inhalt des <code>ETag/code>-Headers
  11  * gesteuert werden.
  12  * Mit dieser Annotation können Klassen oder Methoden merkiert werden.
  13  * <p>
  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.
  17  * <p>
  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!
  26  * </p>
  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.
  32  * <p>
  33  * Die erzeugten <code>ETag</code>'s können über die Annotations-Parameter
  34  * <code>weak</code> und <code>vary</code> weiter gesteuert werden.
  35  * <ul>
  36  * <li>
  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}).
  41  * </li>
  42  * <li>
  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
  53  * werden können.
  54  * Außerdem wird der <code>Vary</code>-Header entsprechend gesetzt.
  55  *</li>
  56  * </ul>
  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.
  64  *
  65  * @see #getCacheSeconds(javax.servlet.http.HttpServletRequest)
  66  *
  67  * @author kai
  68  * @see Cacheable
  69  * @see CacheSeconds
  70  */
  71 @Retention(RetentionPolicy.RUNTIME)
  72 @Target({ ElementType.TYPE, ElementType.METHOD })
  73 public @interface ETag {
  74
  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";
  79
  80
  81   String value() default "X";
  82   boolean weak() default false;
  83   String[] vary() default {};
  84 }