<commit_before><chapter id="Cache_NoCache_CacheControl">
   <title>Resteasy Caching Features</title>
   <para>
     Resteasy provides numerous annotations and facilities to support HTTP caching semantics.  Annotations to make setting Cache-Control
     headers easier and both server-side and client-side in-memory caches are available.
   </para>
  <sect1 id="Cache_Annotation">
  <title>@Cache and @NoCache Annotations</title>
   <para>
      Resteasy provides an extension to JAX-RS that allows you to automatically set Cache-Control headers on a successful
      GET request.  It can only be used on @GET annotated methods.  A successful @GET request is any request
      that returns 200 OK response.
   </para>
   <programlisting>
package org.jboss.resteasy.annotations.cache;

public @interface Cache
{
   int maxAge() default -1;
   int sMaxAge() default -1;
   boolean noStore() default false;
   boolean noTransform() default false;
   boolean mustRevalidate() default false;
   boolean proxyRevalidate() default false;
   boolean isPrivate() default false;
}

public @interface NoCache
{
   String[] fields() default {};
}

   </programlisting>
   <para>
      While @Cache builds a complex Cache-Control header, @NoCache is a simplified notation to say that you don't
      want anything cached i.e. Cache-Control: nocache.
   </para>
   <para>
      These annotations can be put on the resource class or interface and specifies a default cache value for each
      @GET resource method.  Or they can be put individually on each @GET resource method.
   </para>
   </sect1>
   <sect1 id="Http_Precondition">
    <title>HTTP preconditions</title>
    <para>
        JAX-RS provides an API for evaluating HTTP preconditions based on <literal>"If-Match"</literal>, <literal>"If-None-Match"</literal>, <literal>"If-Modified-Since"</literal> and <literal>"If-Unmodified-Since"</literal> headers.
    </para>
    <programlisting>
        Response.ResponseBuilder rb = request.evaluatePreconditions(lastModified, etag);
    </programlisting>
    <para>
        By default Resteasy will return status code 304 (Not modified) or 412 (Precondition failed) if any of conditions fails.
        However it is not compliant with RFC 7232 which states that headers <literal>"If-Match"</literal>, <literal>"If-None-Match"</literal> MUST have higher precedence.
        You can enable RFC 7232 compatible mode by setting <literal>resteasy.rfc7232preconditions</literal> property to <literal>true</literal>
    </para>
   </sect1>
   <sect1 id="client_cache">
     <title>Client "Browser" Cache</title>
     <para>
        Resteasy has the ability to set up a client-side, browser-like, cache.  You can use it with the Client Proxy Framework, or with raw
        ClientRequests.  This cache looks for Cache-Control headers sent back with a server response.  If the Cache-Control headers specify
       that the client is allowed to cache the response, Resteasy caches it within local memory.  The cache obeys max-age requirements 
       and will also automatically do HTTP 1.1 cache revalidation if either or both the Last-Modified and/or ETag headers are sent back with the
       original response.  See the HTTP 1.1 specification for details on how Cache-Control or cache revalidation works.
     </para>
     <para>It is very simple to enable caching.  Here's an example of using the client cache with the Client Proxy Framework</para>
<programlisting>
@Path("/orders")
public interface OrderServiceClient {

   @Path("{id}")
   @GET
   @Produces("application/xml")
   public Order getOrder(@PathParam("id") String id);
}
</programlisting>
    <para>To create a proxy for this interface and enable caching for that proxy requires only a few simple steps:</para><commit_msg>Documentation: use words "context parameter" instead of "property"<commit_after><chapter id="Cache_NoCache_CacheControl">
   <title>Resteasy Caching Features</title>
   <para>
     Resteasy provides numerous annotations and facilities to support HTTP caching semantics.  Annotations to make setting Cache-Control
     headers easier and both server-side and client-side in-memory caches are available.
   </para>
  <sect1 id="Cache_Annotation">
  <title>@Cache and @NoCache Annotations</title>
   <para>
      Resteasy provides an extension to JAX-RS that allows you to automatically set Cache-Control headers on a successful
      GET request.  It can only be used on @GET annotated methods.  A successful @GET request is any request
      that returns 200 OK response.
   </para>
   <programlisting>
package org.jboss.resteasy.annotations.cache;

public @interface Cache
{
   int maxAge() default -1;
   int sMaxAge() default -1;
   boolean noStore() default false;
   boolean noTransform() default false;
   boolean mustRevalidate() default false;
   boolean proxyRevalidate() default false;
   boolean isPrivate() default false;
}

public @interface NoCache
{
   String[] fields() default {};
}

   </programlisting>
   <para>
      While @Cache builds a complex Cache-Control header, @NoCache is a simplified notation to say that you don't
      want anything cached i.e. Cache-Control: nocache.
   </para>
   <para>
      These annotations can be put on the resource class or interface and specifies a default cache value for each
      @GET resource method.  Or they can be put individually on each @GET resource method.
   </para>
   </sect1>
   <sect1 id="Http_Precondition">
    <title>HTTP preconditions</title>
    <para>
        JAX-RS provides an API for evaluating HTTP preconditions based on <literal>"If-Match"</literal>, <literal>"If-None-Match"</literal>, <literal>"If-Modified-Since"</literal> and <literal>"If-Unmodified-Since"</literal> headers.
    </para>
    <programlisting>
        Response.ResponseBuilder rb = request.evaluatePreconditions(lastModified, etag);
    </programlisting>
    <para>
        By default Resteasy will return status code 304 (Not modified) or 412 (Precondition failed) if any of conditions fails.
        However it is not compliant with RFC 7232 which states that headers <literal>"If-Match"</literal>, <literal>"If-None-Match"</literal> MUST have higher precedence.
        You can enable RFC 7232 compatible mode by setting <literal>resteasy.rfc7232preconditions</literal> context parameter to <literal>true</literal>
    </para>
   </sect1>
   <sect1 id="client_cache">
     <title>Client "Browser" Cache</title>
     <para>
        Resteasy has the ability to set up a client-side, browser-like, cache.  You can use it with the Client Proxy Framework, or with raw
        ClientRequests.  This cache looks for Cache-Control headers sent back with a server response.  If the Cache-Control headers specify
       that the client is allowed to cache the response, Resteasy caches it within local memory.  The cache obeys max-age requirements 
       and will also automatically do HTTP 1.1 cache revalidation if either or both the Last-Modified and/or ETag headers are sent back with the
       original response.  See the HTTP 1.1 specification for details on how Cache-Control or cache revalidation works.
     </para>
     <para>It is very simple to enable caching.  Here's an example of using the client cache with the Client Proxy Framework</para>
<programlisting>
@Path("/orders")
public interface OrderServiceClient {

   @Path("{id}")
   @GET
   @Produces("application/xml")
   public Order getOrder(@PathParam("id") String id);
}
</programlisting>
    <para>To create a proxy for this interface and enable caching for that proxy requires only a few simple steps:</para>
{'fraction_non_alphanumeric': 0.08348672100972916, 'fraction_numerical': 0.008414409676571128, 'mean_word_length': 3.73366521468575, 'pattern_counts': {'":': 0, '<': 111, '<?xml version=': 0, '>': 111, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5147412', 'n_tokens_mistral': 2106, 'n_tokens_neox': 1981, 'n_words': 857}