Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 15113200CD8 for ; Wed, 28 Jun 2017 03:50:03 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id 0FBE7160BE9; Wed, 28 Jun 2017 01:50:03 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 95318160BFC for ; Wed, 28 Jun 2017 03:50:00 +0200 (CEST) Received: (qmail 16273 invoked by uid 500); 28 Jun 2017 01:49:59 -0000 Mailing-List: contact commits-help@juneau.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@juneau.incubator.apache.org Delivered-To: mailing list commits@juneau.incubator.apache.org Received: (qmail 16254 invoked by uid 99); 28 Jun 2017 01:49:59 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd4-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 28 Jun 2017 01:49:59 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd4-us-west.apache.org (ASF Mail Server at spamd4-us-west.apache.org) with ESMTP id D28BAC0620 for ; Wed, 28 Jun 2017 01:49:58 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd4-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -4.222 X-Spam-Level: X-Spam-Status: No, score=-4.222 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, RCVD_IN_DNSWL_HI=-5, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, RP_MATCHES_RCVD=-0.001, SPF_PASS=-0.001] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd4-us-west.apache.org [10.40.0.11]) (amavisd-new, port 10024) with ESMTP id wyvQyS8g1SkN for ; Wed, 28 Jun 2017 01:49:45 +0000 (UTC) Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with SMTP id 637225FAE1 for ; Wed, 28 Jun 2017 01:49:42 +0000 (UTC) Received: (qmail 16069 invoked by uid 99); 28 Jun 2017 01:49:41 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 28 Jun 2017 01:49:41 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 000B2E96B8; Wed, 28 Jun 2017 01:49:40 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: jamesbognar@apache.org To: commits@juneau.incubator.apache.org Date: Wed, 28 Jun 2017 01:49:41 -0000 Message-Id: <829afa25dfab4c74bcb6b91fd084ce28@git.apache.org> In-Reply-To: <743e138056c244cebaf9b30454828e36@git.apache.org> References: <743e138056c244cebaf9b30454828e36@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [2/9] incubator-juneau git commit: Clean up javadocs. archived-at: Wed, 28 Jun 2017 01:50:03 -0000 http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java index 8e20a3e..ac330a1 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocSerializerSession.java @@ -26,8 +26,10 @@ import org.apache.juneau.serializer.*; /** * Context object that lives for the duration of a single serialization of {@link HtmlSerializer} and its subclasses. + * *

* See {@link SerializerContext} for details. + * *

* This class is NOT thread safe. It is meant to be discarded after one-time use. */ @@ -42,18 +44,25 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Create a new session using properties specified in the context. * - * @param ctx The context creating this session object. + * @param ctx + * The context creating this session object. * The context contains all the configuration settings for this object. - * @param output The output object. See {@link JsonSerializerSession#getWriter()} for valid class types. - * @param op The override properties. + * @param output + * The output object. + * See {@link JsonSerializerSession#getWriter()} for valid class types. + * @param op + * The override properties. * These override any context properties defined in the context. * @param javaMethod The java method that called this serializer, usually the method in a REST servlet. - * @param locale The session locale. + * @param locale + * The session locale. * If null, then the locale defined on the context is used. - * @param timeZone The session timezone. + * @param timeZone + * The session timezone. * If null, then the timezone defined on the context is used. * @param mediaType The session media type (e.g. "application/json"). - * @param uriContext The URI context. + * @param uriContext + * The URI context. * Identifies the current request URI used for resolution of URIs to absolute or root-relative form. */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -95,8 +104,10 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_cssUrl} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_cssUrl} setting value in this context. - * null if not specified. Never an empty string. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_cssUrl} setting value in this context. + * null if not specified. + * Never an empty string. */ public final String getCssUrl() { return cssUrl; @@ -105,7 +116,8 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_css} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_css} setting value in this context. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_css} setting value in this context. * null if not specified. Never an empty array. */ public final String[] getCss() { @@ -124,8 +136,9 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_title} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_title} setting value in this context. - * null if not specified. Never an empty string. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_title} setting value in this context. + * null if not specified. Never an empty string. */ public final String getTitle() { return title; @@ -134,8 +147,10 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_description} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_description} setting value in this context. - * null if not specified. Never an empty string. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_description} setting value in this context. + * null if not specified. + * Never an empty string. */ public final String getDescription() { return description; @@ -144,8 +159,10 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_branding} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_branding} setting value in this context. - * null if not specified. Never an empty string. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_branding} setting value in this context. + * null if not specified. + * Never an empty string. */ public final String getBranding() { return branding; @@ -154,8 +171,10 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_header} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_header} setting value in this context. - * null if not specified. Never an empty string. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_header} setting value in this context. + * null if not specified. + * Never an empty string. */ public final String getHeader() { return header; @@ -164,8 +183,10 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_links} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_links} setting value in this context. - * null if not specified. Never an empty map. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_links} setting value in this context. + * null if not specified. + * Never an empty map. */ public final Map getLinks() { return links; @@ -174,8 +195,9 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the template to use for generating the HTML page. * - * @return The HTML page generator. - * Never null. + * @return + * The HTML page generator. + * Never null. */ public final HtmlDocTemplate getTemplate() { return template; @@ -184,8 +206,10 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_nav} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_nav} setting value in this context. - * null if not specified. Never an empty string. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_nav} setting value in this context. + * null if not specified. + * Never an empty string. */ public final String getNav() { return nav; @@ -194,8 +218,10 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_aside} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_aside} setting value in this context. - * null if not specified. Never an empty string. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_aside} setting value in this context. + * null if not specified. + * Never an empty string. */ public final String getAside() { return aside; @@ -204,8 +230,10 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_footer} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_footer} setting value in this context. - * null if not specified. Never an empty string. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_footer} setting value in this context. + * null if not specified. + * Never an empty string. */ public final String getFooter() { return footer; @@ -214,8 +242,10 @@ public final class HtmlDocSerializerSession extends HtmlSerializerSession { /** * Returns the {@link HtmlDocSerializerContext#HTMLDOC_noResultsMessage} setting value in this context. * - * @return The {@link HtmlDocSerializerContext#HTMLDOC_noResultsMessage} setting value in this context. - * null if not specified. Never an empty string. + * @return + * The {@link HtmlDocSerializerContext#HTMLDOC_noResultsMessage} setting value in this context. + * null if not specified. + * Never an empty string. */ public final String getNoResultsMessage() { return noResultsMessage; http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplate.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplate.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplate.java index 2e743f6..cc8b2b8 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplate.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplate.java @@ -15,6 +15,7 @@ package org.apache.juneau.html; /** * Defines the interface for rendering the contents of an HTML page produced by the {@link HtmlDocSerializer} * serializer. + * *

* The HTML doc serializer produces the following document structure with the typical contents: *

@@ -45,6 +46,7 @@ package org.apache.juneau.html; * </body> * </html> *

+ * *

* This interface allows you to control how these sections get rendered. */ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplateBasic.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplateBasic.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplateBasic.java index 99a9688..3360770 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplateBasic.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlDocTemplateBasic.java @@ -18,6 +18,7 @@ import org.apache.juneau.internal.*; /** * A basic template for the HTML doc serializer. + * *

* This class can be subclassed to customize page rendering. */ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlLink.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlLink.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlLink.java index 5748815..39fba6f 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlLink.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlLink.java @@ -19,10 +19,13 @@ import java.lang.annotation.*; /** * Used in conjunction with the {@link HtmlSerializer} class to define hyperlinks. + * *

* This annotation is applied to classes. + * *

* Annotation that can be used to specify that a class has a URL associated with it. + * *

* When rendered using the {@link org.apache.juneau.html.HtmlSerializer HtmlSerializer} class, this class will get * rendered as a hyperlink like so... http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlParser.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlParser.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlParser.java index b28e73b..093c411 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlParser.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlParser.java @@ -514,7 +514,7 @@ public class HtmlParser extends XmlParser { + JsonSerializer.DEFAULT.toString(expected), r.getLocation()); } - /** + /* * Skips over the current element and advances to the next element. *

* Precondition: Pointing to opening tag. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserBuilder.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserBuilder.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserBuilder.java index 7418e1b..b5e11dc 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserBuilder.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserBuilder.java @@ -36,6 +36,7 @@ public class HtmlParserBuilder extends XmlParserBuilder { /** * Constructor. + * * @param propertyStore The initial configuration settings for this builder. */ public HtmlParserBuilder(PropertyStore propertyStore) { http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserContext.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserContext.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserContext.java index 5541aba..e1abc7f 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserContext.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserContext.java @@ -17,9 +17,11 @@ import org.apache.juneau.xml.*; /** * Configurable properties on the {@link HtmlParser} class. + * *

* Context properties are set by calling {@link PropertyStore#setProperty(String, Object)} on the property store * passed into the constructor. + * *

* See {@link PropertyStore} for more information about context properties. * @@ -40,6 +42,7 @@ public final class HtmlParserContext extends XmlParserContext { /** * Constructor. + * *

* Typically only called from {@link PropertyStore#getContext(Class)}. * http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserSession.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserSession.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserSession.java index 5e7881f..21ccd9a 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserSession.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlParserSession.java @@ -28,6 +28,7 @@ import org.apache.juneau.xml.*; /** * Session object that lives for the duration of a single use of {@link HtmlParser}. + * *

* This class is NOT thread safe. It is meant to be discarded after one-time use. */ @@ -42,9 +43,11 @@ public final class HtmlParserSession extends XmlParserSession { /** * Create a new session using properties specified in the context. * - * @param ctx The context creating this session object. - * The context contains all the configuration settings for this object. - * @param input The input. Can be any of the following types: + * @param ctx + * The context creating this session object. + * The context contains all the configuration settings for this object. + * @param input + * The input. Can be any of the following types: *

    *
  • null *
  • {@link Reader} @@ -52,14 +55,17 @@ public final class HtmlParserSession extends XmlParserSession { *
  • {@link InputStream} containing UTF-8 encoded text. *
  • {@link File} containing system encoded text. *
- * @param op The override properties. - * These override any context properties defined in the context. + * @param op + * The override properties. + * These override any context properties defined in the context. * @param javaMethod The java method that called this parser, usually the method in a REST servlet. * @param outer The outer object for instantiating top-level non-static inner classes. - * @param locale The session locale. - * If null, then the locale defined on the context is used. - * @param timeZone The session timezone. - * If null, then the timezone defined on the context is used. + * @param locale + * The session locale. + * If null, then the locale defined on the context is used. + * @param timeZone + * The session timezone. + * If null, then the timezone defined on the context is used. * @param mediaType The session media type (e.g. "application/json"). */ public HtmlParserSession(HtmlParserContext ctx, ObjectMap op, Object input, Method javaMethod, Object outer, @@ -69,6 +75,7 @@ public final class HtmlParserSession extends XmlParserSession { /** * Parses CHARACTERS data. + * *

* Precondition: Pointing to event immediately following opening tag. * Postcondition: Pointing to closing tag. @@ -158,8 +165,8 @@ public final class HtmlParserSession extends XmlParserSession { } /** - * Identical to {@link #parseText(XMLStreamReader)} except assumes the current event - * is the opening tag. + * Identical to {@link #parseText(XMLStreamReader)} except assumes the current event is the opening tag. + * *

* Precondition: Pointing to opening tag. * Postcondition: Pointing to closing tag. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlRender.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlRender.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlRender.java index b3dba1b..90e9898 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlRender.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlRender.java @@ -17,18 +17,21 @@ import org.apache.juneau.serializer.*; /** * Allows custom rendering of bean property values when serialized as HTML. + * *

* Associated with bean properties using the {@link Html#render() @Html.render()} annotation. + * *

* Using this class, you can alter the CSS style and HTML content of the bean property. + * *

* The following example shows two render classes that customize the appearance of the pctFull and - * status columns shown below: + * status columns shown below: + * *

* * *

- * * // Our bean class * public class FileSpace { * @@ -116,6 +119,7 @@ import org.apache.juneau.serializer.*; * } * } *

+ * * @param The bean property type. */ public abstract class HtmlRender { @@ -123,7 +127,8 @@ public abstract class HtmlRender { /** * Returns the CSS style of the element containing the bean property value. * - * @param session The current serializer session. + * @param session + * The current serializer session. * Can be used to retrieve properties and session-level information. * @param value The bean property value. * @return The CSS style string, or null if no style should be added. @@ -134,11 +139,13 @@ public abstract class HtmlRender { /** * Returns the delegate value for the specified bean property value. + * *

* The default implementation simply returns the same value. * A typical use is to return an HTML element using one of the HTML5 DOM beans. * - * @param session The current serializer session. + * @param session + * The current serializer session. * Can be used to retrieve properties and session-level information. * @param value The bean property value. * @return The new bean property value. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlSchemaDocSerializer.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSchemaDocSerializer.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSchemaDocSerializer.java index 7420331..d4fcdd6 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSchemaDocSerializer.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSchemaDocSerializer.java @@ -30,14 +30,17 @@ import org.apache.juneau.transform.*; *

Media types:
*

* Handles Accept types: text/html+schema + * *

* Produces Content-Type types: text/html * *

Description:
*

* Essentially the same as {@link HtmlSerializer}, except serializes the POJO metamodel instead of the model itself. + * *

* Produces output that describes the POJO metamodel similar to an XML schema document. + * *

* The easiest way to create instances of this class is through the {@link HtmlSerializer#getSchemaSerializer()}, * which will create a schema serializer with the same settings as the originating serializer. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializer.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializer.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializer.java index 022fdab..22805bd 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializer.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializer.java @@ -34,28 +34,31 @@ import org.apache.juneau.xml.annotation.*; *

Media types:
*

* Handles Accept types: text/html + * *

* Produces Content-Type types: text/html * *

Description:
*

* The conversion is as follows... - *

    - *
  • - * {@link Map Maps} (e.g. {@link HashMap}, {@link TreeMap}) and beans are converted to HTML tables with - * 'key' and 'value' columns. - *
  • - * {@link Collection Collections} (e.g. {@link HashSet}, {@link LinkedList}) and Java arrays are converted - * to HTML ordered lists. - *
  • - * {@code Collections} of {@code Maps} and beans are converted to HTML tables with keys as headers. - *
  • - * Everything else is converted to text. - *
+ *
    + *
  • + * {@link Map Maps} (e.g. {@link HashMap}, {@link TreeMap}) and beans are converted to HTML tables with + * 'key' and 'value' columns. + *
  • + * {@link Collection Collections} (e.g. {@link HashSet}, {@link LinkedList}) and Java arrays are converted + * to HTML ordered lists. + *
  • + * {@code Collections} of {@code Maps} and beans are converted to HTML tables with keys as headers. + *
  • + * Everything else is converted to text. + *
+ * *

* This serializer provides several serialization options. Typically, one of the predefined DEFAULT * serializers will be sufficient. * However, custom serializers can be constructed to fine-tune behavior. + * *

* The {@link HtmlLink} annotation can be used on beans to add hyperlinks to the output. * @@ -228,8 +231,9 @@ public class HtmlSerializer extends XmlSerializer { * @param out The writer. * @param o The object to serialize. * @param eType The expected type of the object if this is a bean property. - * @param name The attribute name of this object if this object was a field in a JSON object (i.e. key of a - * {@link java.util.Map.Entry} or property name of a bean). + * @param name + * The attribute name of this object if this object was a field in a JSON object (i.e. key of a + * {@link java.util.Map.Entry} or property name of a bean). * @param indent The current indentation value. * @param pMeta The bean property being serialized, or null if we're not serializing a bean property. * @param isRoot true if this is the root element of the document. @@ -773,6 +777,7 @@ public class HtmlSerializer extends XmlSerializer { /** * Returns the schema serializer based on the settings of this serializer. + * * @return The schema serializer. */ @Override /* XmlSerializer */ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerBuilder.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerBuilder.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerBuilder.java index c6cb528..0633abd 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerBuilder.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerBuilder.java @@ -54,6 +54,7 @@ public class HtmlSerializerBuilder extends XmlSerializerBuilder { /** * Configuration property: Anchor text source. + * *

*

    *
  • Name: "HtmlSerializer.uriAnchorText" @@ -61,9 +62,11 @@ public class HtmlSerializerBuilder extends XmlSerializerBuilder { *
  • Default: "toString" *
  • Session-overridable: true *
+ * *

* When creating anchor tags (e.g. <a href='...'>text</a>) * in HTML, this setting defines what to set the inner text to. + * *

* Possible values: *

    @@ -97,6 +100,7 @@ public class HtmlSerializerBuilder extends XmlSerializerBuilder { /** * Configuration property: Look for URLs in {@link String Strings}. + * *

    *

      *
    • Name: "HtmlSerializer.detectLinksInStrings" @@ -104,9 +108,10 @@ public class HtmlSerializerBuilder extends XmlSerializerBuilder { *
    • Default: true *
    • Session-overridable: true *
    + * *

    * If a string looks like a URL (e.g. starts with "http://" or "https://", then treat it like a URL - * and make it into a hyperlink based on the rules specified by {@link HtmlSerializerContext#HTML_uriAnchorText}. + * and make it into a hyperlink based on the rules specified by {@link HtmlSerializerContext#HTML_uriAnchorText}. * *

    Notes:
    *
      @@ -124,6 +129,7 @@ public class HtmlSerializerBuilder extends XmlSerializerBuilder { /** * Configuration property: Look for link labels in the "label" parameter of the URL. + * *

      *

        *
      • Name: "HtmlSerializer.lookForLabelParameters" @@ -131,8 +137,10 @@ public class HtmlSerializerBuilder extends XmlSerializerBuilder { *
      • Default: true *
      • Session-overridable: true *
      + * *

      * If the URL has a label parameter (e.g. "?label=foobar"), then use that as the anchor text of the link. + * *

      * The parameter name can be changed via the {@link HtmlSerializerContext#HTML_labelParameter} property. * @@ -151,8 +159,8 @@ public class HtmlSerializerBuilder extends XmlSerializerBuilder { } /** - * Configuration property: The parameter name to use when using - * {@link HtmlSerializerContext#HTML_lookForLabelParameters}. + * Configuration property: The parameter name to use when using {@link HtmlSerializerContext#HTML_lookForLabelParameters}. + * *

      *

        *
      • Name: "HtmlSerializer.labelParameter" @@ -177,6 +185,7 @@ public class HtmlSerializerBuilder extends XmlSerializerBuilder { /** * Configuration property: Add key/value headers on bean/map tables. + * *

        *

          *
        • Name: "HtmlSerializer.addKeyValueTableHeaders" http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerContext.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerContext.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerContext.java index f66b94f..cbead45 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerContext.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerContext.java @@ -18,9 +18,11 @@ import org.apache.juneau.xml.*; /** * Configurable properties on the {@link HtmlSerializer} class. + * *

          * Context properties are set by calling {@link PropertyStore#setProperty(String, Object)} on the property store * passed into the constructor. + * *

          * See {@link PropertyStore} for more information about context properties. * @@ -41,6 +43,7 @@ public class HtmlSerializerContext extends XmlSerializerContext { /** * Configuration property: Anchor text source. + * *

          *

            *
          • Name: "HtmlSerializer.uriAnchorText" @@ -48,9 +51,11 @@ public class HtmlSerializerContext extends XmlSerializerContext { *
          • Default: "toString" *
          • Session-overridable: true *
          + * *

          * When creating anchor tags (e.g. <a href='...' * >text</a>) in HTML, this setting defines what to set the inner text to. + * *

          * Possible values: *

            @@ -84,6 +89,7 @@ public class HtmlSerializerContext extends XmlSerializerContext { /** * Configuration property: Look for URLs in {@link String Strings}. + * *

            *

              *
            • Name: "HtmlSerializer.detectLinksInStrings" @@ -91,6 +97,7 @@ public class HtmlSerializerContext extends XmlSerializerContext { *
            • Default: true *
            • Session-overridable: true *
            + * *

            * If a string looks like a URL (e.g. starts with "http://" or "https://", then treat it like a URL * and make it into a hyperlink based on the rules specified by {@link #HTML_uriAnchorText}. @@ -99,6 +106,7 @@ public class HtmlSerializerContext extends XmlSerializerContext { /** * Configuration property: Look for link labels in the "label" parameter of the URL. + * *

            *

              *
            • Name: "HtmlSerializer.lookForLabelParameters" @@ -106,8 +114,10 @@ public class HtmlSerializerContext extends XmlSerializerContext { *
            • Default: true *
            • Session-overridable: true *
            + * *

            * If the URL has a label parameter (e.g. "?label=foobar"), then use that as the anchor text of the link. + * *

            * The parameter name can be changed via the {@link #HTML_labelParameter} property. */ @@ -115,6 +125,7 @@ public class HtmlSerializerContext extends XmlSerializerContext { /** * Configuration property: The parameter name to use when using {@link #HTML_lookForLabelParameters}. + * *

            *

              *
            • Name: "HtmlSerializer.labelParameter" @@ -127,6 +138,7 @@ public class HtmlSerializerContext extends XmlSerializerContext { /** * Configuration property: Add key/value headers on bean/map tables. + * *

              *

                *
              • Name: "HtmlSerializer.addKeyValueTableHeaders" @@ -139,6 +151,7 @@ public class HtmlSerializerContext extends XmlSerializerContext { /** * Configuration property: Add "_type" properties when needed. + * *

                *

                  *
                • Name: "HtmlSerializer.addBeanTypeProperties" @@ -146,12 +159,14 @@ public class HtmlSerializerContext extends XmlSerializerContext { *
                • Default: false *
                • Session-overridable: true *
                + * *

                * If true, then "_type" properties will be added to beans if their type cannot be inferred * through reflection. * This is used to recreate the correct objects during parsing if the object types cannot be inferred. * For example, when serializing a {@code Map} field, where the bean class cannot be determined * from the value type. + * *

                * When present, this value overrides the {@link SerializerContext#SERIALIZER_addBeanTypeProperties} setting and is * provided to customize the behavior of specific serializers in a {@link SerializerGroup}. @@ -169,6 +184,7 @@ public class HtmlSerializerContext extends XmlSerializerContext { /** * Constructor. + * *

                * Typically only called from {@link PropertyStore#getContext(Class)}. * http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerSession.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerSession.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerSession.java index 5377a8a..8a4f27f 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerSession.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlSerializerSession.java @@ -27,6 +27,7 @@ import org.apache.juneau.xml.*; /** * Session object that lives for the duration of a single use of {@link HtmlSerializer}. + * *

                * This class is NOT thread safe. It is meant to be discarded after one-time use. */ @@ -50,18 +51,23 @@ public class HtmlSerializerSession extends XmlSerializerSession { /** * Create a new session using properties specified in the context. * - * @param ctx The context creating this session object. + * @param ctx + * The context creating this session object. * The context contains all the configuration settings for this object. * @param output The output object. See {@link JsonSerializerSession#getWriter()} for valid class types. - * @param op The override properties. + * @param op + * The override properties. * These override any context properties defined in the context. * @param javaMethod The java method that called this serializer, usually the method in a REST servlet. - * @param locale The session locale. + * @param locale + * The session locale. * If null, then the locale defined on the context is used. - * @param timeZone The session timezone. + * @param timeZone + * The session timezone. * If null, then the timezone defined on the context is used. * @param mediaType The session media type (e.g. "application/json"). - * @param uriContext The URI context. + * @param uriContext + * The URI context. * Identifies the current request URI used for resolution of URIs to absolute or root-relative form. */ protected HtmlSerializerSession(HtmlSerializerContext ctx, ObjectMap op, Object output, Method javaMethod, @@ -99,8 +105,9 @@ public class HtmlSerializerSession extends XmlSerializerSession { * Returns true if the specified object is a URL. * * @param cm The ClassMeta of the object being serialized. - * @param pMeta The property metadata of the bean property of the object. - * Can be null if the object isn't from a bean property. + * @param pMeta + * The property metadata of the bean property of the object. + * Can be null if the object isn't from a bean property. * @param o The object. * @return true if the specified object is a URL. */ @@ -117,8 +124,9 @@ public class HtmlSerializerSession extends XmlSerializerSession { /** * Returns the anchor text to use for the specified URL object. * - * @param pMeta The property metadata of the bean property of the object. - * Can be null if the object isn't from a bean property. + * @param pMeta + * The property metadata of the bean property of the object. + * Can be null if the object isn't from a bean property. * @param o The URL object. * @return The anchor text to use for the specified URL object. */ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/HtmlStrippedDocSerializer.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/HtmlStrippedDocSerializer.java b/juneau-core/src/main/java/org/apache/juneau/html/HtmlStrippedDocSerializer.java index a43f1e7..d73319c 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/HtmlStrippedDocSerializer.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/HtmlStrippedDocSerializer.java @@ -25,6 +25,7 @@ import org.apache.juneau.serializer.*; *

                Media types:
                *

                * Handles Accept types: text/html+stripped + * *

                * Produces Content-Type types: text/html * @@ -39,6 +40,7 @@ public class HtmlStrippedDocSerializer extends HtmlSerializer { /** * Constructor. + * * @param propertyStore The property store containing all the settings for this object. */ public HtmlStrippedDocSerializer(PropertyStore propertyStore) { http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/html/annotation/Html.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/html/annotation/Html.java b/juneau-core/src/main/java/org/apache/juneau/html/annotation/Html.java index 3ada90e..b385ac7 100644 --- a/juneau-core/src/main/java/org/apache/juneau/html/annotation/Html.java +++ b/juneau-core/src/main/java/org/apache/juneau/html/annotation/Html.java @@ -20,8 +20,7 @@ import java.lang.annotation.*; import org.apache.juneau.html.*; /** - * Annotation that can be applied to classes, fields, and methods to tweak how - * they are handled by {@link HtmlSerializer}. + * Annotation that can be applied to classes, fields, and methods to tweak how they are handled by {@link HtmlSerializer}. */ @Documented @Target({TYPE,FIELD,METHOD}) @@ -31,12 +30,16 @@ public @interface Html { /** * Treat as XML. + * + *

                * Useful when creating beans that model HTML elements. */ boolean asXml() default false; /** * Treat as plain text. + * + *

                * Object is serialized to a String using the toString() method and written directly to output. * Useful when you want to serialize custom HTML. */ @@ -44,18 +47,23 @@ public @interface Html { /** * When true, collections of beans should be rendered as trees instead of tables. + * + *

                * Default is false. */ boolean noTables() default false; /** * When true, don't add headers to tables. + * + *

                * Default is false. */ boolean noTableHeaders() default false; /** * Associates an {@link HtmlRender} with a bean property for custom HTML rendering of the property. + * *

                * This annotation applies to bean properties and classes. */ @@ -64,8 +72,10 @@ public @interface Html { /** * Adds a hyperlink to a bean property when rendered as HTML. + * *

                * The text can contain any bean property values resolved through variables of the form "{property-name}". + * *

                * The URLs can be any of the following forms: *

                  http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/Accept.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/Accept.java b/juneau-core/src/main/java/org/apache/juneau/http/Accept.java index 48d6373..4ea7bec 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/Accept.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/Accept.java @@ -21,6 +21,7 @@ import org.apache.juneau.internal.*; /** * Represents a parsed Accept HTTP request header. + * *

                  * Content-Types that are acceptable for the response. * @@ -46,10 +47,12 @@ import org.apache.juneau.internal.*; * accept-params = ";" "q" "=" qvalue *( accept-extension ) * accept-extension = ";" token [ "=" ( token | quoted-string ) ] *

                  + * *

                  * The asterisk "*" character is used to group media types into ranges, with "* /*" indicating all media types and * "type/*" indicating all subtypes of that type. * The media-range MAY include media type parameters that are applicable to that range. + * *

                  * Each media-range MAY be followed by one or more accept-params, beginning with the "q" parameter for indicating a * relative quality factor. @@ -57,6 +60,7 @@ import org.apache.juneau.internal.*; * Quality factors allow the user or user agent to indicate the relative degree of preference for that media-range, * using the qvalue scale from 0 to 1 (section 3.9). * The default value is q=1. + * *

                  * Note: Use of the "q" parameter name to separate media type parameters from Accept extension parameters is due to * historical practice. @@ -64,6 +68,7 @@ import org.apache.juneau.internal.*; * believed to be unlikely given the lack of any "q" parameters in the IANA * media type registry and the rare usage of any media type parameters in Accept. * Future media types are discouraged from registering any parameter named "q". + * *

                  * The example *

                  @@ -72,21 +77,26 @@ import org.apache.juneau.internal.*; *

                  * SHOULD be interpreted as "I prefer audio/basic, but send me any audio type if it is the best available after an 80% * mark-down in quality." + * *

                  * If no Accept header field is present, then it is assumed that the client accepts all media types. + * *

                  * If an Accept header field is present, and if the server cannot send a response which is acceptable according to the * combined Accept field value, then the server SHOULD send a 406 (not acceptable) response. + * *

                  * A more elaborate example is *

                  * Accept: text/plain; q=0.5, text/html, * text/x-dvi; q=0.8, text/x-c *

                  + * *

                  * Verbally, this would be interpreted as "text/html and text/x-c are the preferred media types, but if they do not * exist, then send the * text/x-dvi entity, and if that does not exist, send the text/plain entity." + * *

                  * Media ranges can be overridden by more specific media ranges or specific media types. * If more than one media range applies to a given type, the most specific reference has precedence. @@ -102,6 +112,7 @@ import org.apache.juneau.internal.*; *

                • text/* *
                • * /* * + * *

                  * The media type quality factor associated with a given type is determined by finding the media range with the highest * precedence which matches that type. @@ -120,6 +131,7 @@ import org.apache.juneau.internal.*; * text/html;level=2 = 0.4 * text/html;level=3 = 0.7 *

                  + * *

                  * Note: A user agent might be provided with a default set of quality values for certain media ranges. * However, unless the user agent is a closed system which cannot interact with other rendering agents, this default @@ -164,6 +176,7 @@ public final class Accept { /** * Returns the list of the media ranges that make up this header. + * *

                  * The media ranges in the list are sorted by their q-value in descending order. * @@ -175,6 +188,7 @@ public final class Accept { /** * Given a list of media types, returns the best match for this Accept header. + * *

                  * Note that fuzzy matching is allowed on the media types where the Accept header may * contain additional subtype parts. @@ -183,10 +197,10 @@ public final class Accept { * isn't found. *
                  The purpose for this is to allow serializers to match when artifacts such as id properties are * present in the header. + * *

                  * See * ActivityPub / Retrieving Objects - *

                  * * @param mediaTypes The media types to match against. * @return The index into the array of the best match, or -1 if no suitable matches could be found. @@ -218,8 +232,9 @@ public final class Accept { } /** - * Convenience method for searching through all of the subtypes of all the media ranges in this header - * for the presence of a subtype fragment. + * Convenience method for searching through all of the subtypes of all the media ranges in this header for the + * presence of a subtype fragment. + * *

                  * For example, given the header "text/json+activity", calling * hasSubtypePart("activity") returns true. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/AcceptCharset.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/AcceptCharset.java b/juneau-core/src/main/java/org/apache/juneau/http/AcceptCharset.java index 295aceb..c17ec3f 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/AcceptCharset.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/AcceptCharset.java @@ -19,6 +19,7 @@ import org.apache.juneau.internal.*; /** * Represents a parsed Accept-Charset HTTP request header. + * *

                  * Character sets that are acceptable. * @@ -30,6 +31,7 @@ import org.apache.juneau.internal.*; *

                  RFC2616 Specification
                  * * The Accept-Charset request-header field can be used to indicate what character sets are acceptable for the response. + * *

                  * This field allows clients capable of understanding more comprehensive or special- purpose character sets to signal * that capability to a server which is capable of representing documents in those character sets. @@ -37,6 +39,7 @@ import org.apache.juneau.internal.*; * Accept-Charset = "Accept-Charset" ":" * 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] ) *

                  + * *

                  * Character set values are described in section 3.4. Each charset MAY be given an associated quality value which * represents the user's preference for that charset. @@ -45,14 +48,18 @@ import org.apache.juneau.internal.*; *

                  * Accept-Charset: iso-8859-5, unicode-1-1;q=0.8 *

                  + * *

                  * The special value "*", if present in the Accept-Charset field, matches every character set (including ISO-8859-1) * which is not mentioned elsewhere in the Accept-Charset field. + * *

                  * If no "*" is present in an Accept-Charset field, then all character sets not explicitly mentioned get a quality * value of 0, except for ISO-8859-1, which gets a quality value of 1 if not explicitly mentioned. + * *

                  * If no Accept-Charset header is present, the default is that any character set is acceptable. + * *

                  * If an Accept-Charset header is present, and if the server cannot send a response which is acceptable according to * the Accept-Charset header, then the server SHOULD send an error response with the 406 (not acceptable) status code, http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/AcceptEncoding.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/AcceptEncoding.java b/juneau-core/src/main/java/org/apache/juneau/http/AcceptEncoding.java index c9e7fef..c0cf845 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/AcceptEncoding.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/AcceptEncoding.java @@ -18,6 +18,7 @@ import org.apache.juneau.internal.*; /** * Represents a parsed Accept-Encoding HTTP request header. + * *

                  * List of acceptable encodings. * @@ -36,6 +37,7 @@ import org.apache.juneau.internal.*; * 1#( codings [ ";" "q" "=" qvalue ] ) * codings = ( content-coding | "*" ) *

                  + * *

                  * Examples of its use are: *

                  @@ -45,6 +47,7 @@ import org.apache.juneau.internal.*; * Accept-Encoding: compress;q=0.5, gzip;q=1.0 * Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0 *

                  + * *

                  * A server tests whether a content-coding is acceptable, according to an Accept-Encoding field, using these rules: *

                    @@ -60,20 +63,24 @@ import org.apache.juneau.internal.*; * "identity" content-coding. * If the Accept-Encoding field-value is empty, then only the "identity" encoding is acceptable. *
                  + * *

                  * If an Accept-Encoding field is present in a request, and if the server cannot send a response which is acceptable * according to the Accept-Encoding header, then the server SHOULD send an error response with the 406 (Not Acceptable) * status code. + * *

                  * If no Accept-Encoding field is present in a request, the server MAY assume that the client will accept any content * coding. * In this case, if "identity" is one of the available content-codings, then the server SHOULD use the "identity" * content-coding, unless it has additional information that a different content-coding is meaningful to the client. + * *

                  * Note: If the request does not include an Accept-Encoding field, and if the "identity" content-coding is unavailable, * then content-codings commonly understood by HTTP/1.0 clients (i.e.,"gzip" and "compress") are preferred; some older * clients improperly display messages sent with other content-codings. * The server might also make this decision based on information about the particular user-agent or client. + * *

                  * Note: Most HTTP/1.0 applications do not recognize or obey qvalues associated with content-codings. * This means that qvalues will not work and are not permitted with x-gzip or x-compress. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/AcceptLanguage.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/AcceptLanguage.java b/juneau-core/src/main/java/org/apache/juneau/http/AcceptLanguage.java index 0eb3454..cd187d9 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/AcceptLanguage.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/AcceptLanguage.java @@ -18,6 +18,7 @@ import org.apache.juneau.internal.*; /** * Represents a parsed Accept-Language HTTP request header. + * *

                  * List of acceptable human languages for response. * @@ -37,6 +38,7 @@ import org.apache.juneau.internal.*; * 1#( language-range [ ";" "q" "=" qvalue ] ) * language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" ) *

                  + * *

                  * Each language-range MAY be given an associated quality value which represents an estimate of the user's preference * for the languages specified by that range. @@ -47,36 +49,46 @@ import org.apache.juneau.internal.*; *

                  *

                  * ...would mean: "I prefer Danish, but will accept British English and other types of English." + * *

                  * A language-range matches a language-tag if it exactly equals the tag, or if it exactly equals a prefix of the tag * such that the first tag character following the prefix is "-". + * *

                  * The special range "*", if present in the Accept-Language field, matches every tag not matched by any other range * present in the Accept-Language field. + * *

                  * Note: This use of a prefix matching rule does not imply that language tags are assigned to languages in such a way * that it is always true that if a user understands a language with a certain * tag, then this user will also understand all languages with tags for which this tag is a prefix. * The prefix rule simply allows the use of prefix tags if this is the case. + * *

                  * The language quality factor assigned to a language-tag by the Accept-Language field is the quality value of the * longest language- range in the field that matches the language-tag. + * *

                  * If no language- range in the field matches the tag, the language quality factor assigned is 0. + * *

                  * If no Accept-Language header is present in the request, the server SHOULD assume that all languages are equally * acceptable. + * *

                  * If an Accept-Language header is present, then all languages which are assigned a quality factor greater than 0 are * acceptable. + * *

                  * It might be contrary to the privacy expectations of the user to send an Accept-Language header with the complete * linguistic preferences of the user in every request. * For a discussion of this issue, see section 15.1.4. + * *

                  * As intelligibility is highly dependent on the individual user, it is recommended that client applications make the * choice of linguistic preference available to the user. * If the choice is not made available, then the Accept-Language header field MUST NOT be given in the request. + * *

                  * Note: When making the choice of linguistic preference available to the user, we remind implementors of the fact that * users are not familiar with the details of language matching as described above, and should provide appropriate http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/AcceptRanges.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/AcceptRanges.java b/juneau-core/src/main/java/org/apache/juneau/http/AcceptRanges.java index 0ce6df4..18023b8 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/AcceptRanges.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/AcceptRanges.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Accept-Range HTTP response header. + * *

                  * What partial content range types this server supports via byte serving. * @@ -30,6 +31,7 @@ package org.apache.juneau.http; * Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges * acceptable-ranges = 1#range-unit | "none" *

                  + * *

                  * Origin servers that accept byte-range requests MAY send... *

                  @@ -37,10 +39,13 @@ package org.apache.juneau.http; *

                  *

                  * ...but are not required to do so. + * *

                  * Clients MAY generate byte-range requests without having received this header for the resource involved. + * *

                  * Range units are defined in section 3.12. + * *

                  * Servers that do not accept any kind of range request for a resource MAY send... *

                  http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/Age.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/Age.java b/juneau-core/src/main/java/org/apache/juneau/http/Age.java index b1b1ce9..8cbdff0 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/Age.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/Age.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Age HTTP response header. + * *

                  * The age the object has been in a proxy cache in seconds. * @@ -33,14 +34,18 @@ package org.apache.juneau.http; * Age = "Age" ":" age-value * age-value = delta-seconds *

                  + * *

                  * Age values are non-negative decimal integers, representing time in seconds. + * *

                  * If a cache receives a value larger than the largest positive integer it can represent, or if any of its age * calculations overflows, it MUST transmit an Age header with a value of 2147483648 (2^31). + * *

                  * An HTTP/1.1 server that includes a cache MUST include an Age header field in every response generated from its own * cache. + * *

                  * Caches SHOULD use an arithmetic type of at least 31 bits of range. * http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/Allow.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/Allow.java b/juneau-core/src/main/java/org/apache/juneau/http/Allow.java index 7baa277..b0fab92 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/Allow.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/Allow.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Allow HTTP response header. + * *

                  * Valid methods for a specified resource. To be used for a 405 Method not allowed. * @@ -31,22 +32,28 @@ package org.apache.juneau.http; *

                  * Allow = "Allow" ":" #Method *

                  + * *

                  * Example of use: *

                  * Allow: GET, HEAD, PUT *

                  + * *

                  * This field cannot prevent a client from trying other methods. * However, the indications given by the Allow header field value SHOULD be followed. + * *

                  * The actual set of allowed methods is defined by the origin server at the time of each request. + * *

                  * The Allow header field MAY be provided with a PUT request to recommend the methods to be supported by the new or * modified resource. + * *

                  * The server is not required to support these methods and SHOULD include an Allow header in the response giving the * actual supported methods. + * *

                  * A proxy MUST NOT modify the Allow header field even if it does not understand all the methods specified, since the * user agent might http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/Authorization.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/Authorization.java b/juneau-core/src/main/java/org/apache/juneau/http/Authorization.java index f4fc56b..07412c8 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/Authorization.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/Authorization.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Authorization HTTP request header. + * *

                  * Authentication credentials for HTTP authentication. * @@ -26,6 +27,7 @@ package org.apache.juneau.http; * * A user agent that wishes to authenticate itself with a server--usually, but not necessarily, after receiving a 401 * response--does so by including an Authorization request-header field with the request. + * *

                  * The Authorization field value consists of credentials containing the authentication information of the user agent for * the realm of the resource being requested. @@ -33,12 +35,15 @@ package org.apache.juneau.http; *

                  * Authorization = "Authorization" ":" credentials *

                  + * *

                  * HTTP access authentication is described in "HTTP Authentication: Basic and Digest Access Authentication". + * *

                  * If a request is authenticated and a realm specified, the same credentials SHOULD be valid for all other requests * within this realm (assuming that the authentication scheme itself does not require otherwise, such as credentials * that vary according to a challenge value or using synchronized clocks). + * *

                  * When a shared cache (see section 13.7) receives a request containing an Authorization field, it MUST NOT return the * corresponding response as a reply to any other request, unless one of the following specific exceptions holds: http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/CacheControl.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/CacheControl.java b/juneau-core/src/main/java/org/apache/juneau/http/CacheControl.java index 7fee28b..8c46228 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/CacheControl.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/CacheControl.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Cache-Control HTTP request header. + * *

                  * Used to specify directives that must be obeyed by all caching mechanisms along the request-response chain. * @@ -30,9 +31,11 @@ package org.apache.juneau.http; * These directives typically override the default caching algorithms. * Cache directives are unidirectional in that the presence of a directive in a request does not imply that the same * directive is to be given in the response. + * *

                  * Note that HTTP/1.0 caches might not implement Cache-Control and might only implement Pragma: no-cache (see section * 14.32). + * *

                  * Cache directives MUST be passed through by a proxy or gateway application, regardless of their significance to that * application, since the directives might be applicable to all recipients along the request/response chain. @@ -64,11 +67,13 @@ package org.apache.juneau.http; * | cache-extension ; Section 14.9.6 * cache-extension = token [ "=" ( token | quoted-string ) ] *

                  + * *

                  * When a directive appears without any 1#field-name parameter, the directive applies to the entire request or response. * When such a directive appears with a 1#field-name parameter, it applies only to the named field or fields, and not * to the rest of the request or response. This mechanism supports extensibility; implementations of future versions * of the HTTP protocol might apply these directives to header fields not defined in HTTP/1.1. + * *

                  * The cache-control directives can be broken down into these general categories: *

                    http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/Connection.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/Connection.java b/juneau-core/src/main/java/org/apache/juneau/http/Connection.java index aed6e82..c005c25 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/Connection.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/Connection.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Connection HTTP request header. + * *

                    * Control options for the current connection and list of hop-by-hop request fields. * @@ -27,20 +28,24 @@ package org.apache.juneau.http; * * The Connection general-header field allows the sender to specify options that are desired for that particular * connection and MUST NOT be communicated by proxies over further connections. + * *

                    * The Connection header has the following grammar: *

                    * Connection = "Connection" ":" 1#(connection-token) * connection-token = token *

                    + * *

                    * HTTP/1.1 proxies MUST parse the Connection header field before a message is forwarded and, for each connection-token * in this field, remove any header field(s) from the message with the same name as the connection-token. * Connection options are signaled by the presence of a connection-token in the Connection header field, not by any * corresponding additional header field(s), since the additional header field may not be sent if there are no * parameters associated with that connection option. + * *

                    * Message headers listed in the Connection header MUST NOT include end-to-end headers, such as Cache-Control. + * *

                    * HTTP/1.1 defines the "close" connection option for the sender to signal that the connection will be closed after * completion of the response. @@ -51,9 +56,11 @@ package org.apache.juneau.http; *

                    * ...in either the request or the response header fields indicates that the connection SHOULD NOT be considered * `persistent' (section 8.1) after the current request/response is complete. + * *

                    * HTTP/1.1 applications that do not support persistent connections MUST include the "close" connection option in * every message. + * *

                    * A system receiving an HTTP/1.0 (or lower-version) message that includes a Connection header MUST, for each * connection-token in this field, remove and ignore any header field(s) from the message with the same name as the http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/ContentEncoding.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/ContentEncoding.java b/juneau-core/src/main/java/org/apache/juneau/http/ContentEncoding.java index 04ebf3e..76f9552 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/ContentEncoding.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/ContentEncoding.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Content-Encoding HTTP response header. + * *

                    * The type of encoding used on the data. * @@ -33,22 +34,27 @@ package org.apache.juneau.http; *

                    * Content-Encoding = "Content-Encoding" ":" 1#content-coding *

                    + * *

                    * Content codings are defined in section 3.5. An example of its use is... *

                    * Content-Encoding: gzip *

                    + * *

                    * The content-coding is a characteristic of the entity identified by the Request-URI. * Typically, the entity-body is stored with this encoding and is only decoded before rendering or analogous usage. * However, a non-transparent proxy MAY modify the content-coding if the new coding is known to be acceptable to the * recipient, unless the "no-transform" cache-control directive is present in the message. + * *

                    * If the content-coding of an entity is not "identity", then the response MUST include a Content-Encoding * entity-header (section 14.11) that lists the non-identity content-coding(s) used. + * *

                    * If the content-coding of an entity in a request message is not acceptable to the origin server, the server SHOULD * respond with a status code of 415 (Unsupported Media Type). + * *

                    * If multiple encodings have been applied to an entity, the content codings MUST be listed in the order in which they * were applied. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/ContentLanguage.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/ContentLanguage.java b/juneau-core/src/main/java/org/apache/juneau/http/ContentLanguage.java index 09cb94b..4e6cef5 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/ContentLanguage.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/ContentLanguage.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Content-Language HTTP response header. + * *

                    * The natural language or languages of the intended audience for the enclosed content. * @@ -30,6 +31,7 @@ package org.apache.juneau.http; *

                    * Content-Language = "Content-Language" ":" 1#language-tag *

                    + * *

                    * Language tags are defined in section 3.10. * The primary purpose of Content-Language is to allow a user to identify and differentiate entities according to the @@ -38,10 +40,12 @@ package org.apache.juneau.http; *

                    * Content-Language: da *

                    + * *

                    * If no Content-Language is specified, the default is that the content is intended for all language audiences. * This might mean that the sender does not consider it to be specific to any natural language, or that the sender * does not know for which language it is intended. + * *

                    * Multiple languages MAY be listed for content that is intended for multiple audiences. * For example, a rendition of the "Treaty of Waitangi," presented simultaneously in the original Maori and English @@ -49,12 +53,14 @@ package org.apache.juneau.http; *

                    * Content-Language: mi, en *

                    + * *

                    * However, just because multiple languages are present within an entity does not mean that it is intended for * multiple linguistic audiences. * An example would be a beginner's language primer, such as "A First Lesson in Latin," which is clearly intended to * be used by an English-literate audience. * In this case, the Content-Language would properly only include "en". + * *

                    * Content-Language MAY be applied to any media type -- it is not limited to textual documents. * http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/ContentLength.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/ContentLength.java b/juneau-core/src/main/java/org/apache/juneau/http/ContentLength.java index 94ca051..a0f3777 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/ContentLength.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/ContentLength.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Content-Length HTTP request/response header. + * *

                    * The length of the response body in octets (8-bit bytes). * @@ -30,17 +31,21 @@ package org.apache.juneau.http; *

                    * Content-Length = "Content-Length" ":" 1*DIGIT *

                    + * *

                    * An example is... *

                    * Content-Length: 3495 *

                    + * *

                    * Applications SHOULD use this field to indicate the transfer-length of the message-body, unless this is prohibited by * the rules in section 4.4. + * *

                    * Any Content-Length greater than or equal to zero is a valid value. * Section 4.4 describes how to determine the length of a message-body if a Content-Length is not given. + * *

                    * Note that the meaning of this field is significantly different from the corresponding definition in MIME, where it is * an optional field used within the "message/external-body" content-type. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/ContentLocation.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/ContentLocation.java b/juneau-core/src/main/java/org/apache/juneau/http/ContentLocation.java index cf71009..f222af0 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/ContentLocation.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/ContentLocation.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Content-Location HTTP response header. + * *

                    * An alternate location for the returned data. * @@ -34,20 +35,25 @@ package org.apache.juneau.http; * Content-Location = "Content-Location" ":" * ( absoluteURI | relativeURI ) *

                    + * *

                    * The value of Content-Location also defines the base URI for the entity. + * *

                    * The Content-Location value is not a replacement for the original requested URI; it is only a statement of the * location of the resource corresponding to this particular entity at the time of the request. * Future requests MAY specify the Content-Location URI as the request- URI if the desire is to identify the source of * that particular entity. + * *

                    * A cache cannot assume that an entity with a Content-Location different from the URI used to retrieve it can be used * to respond to later requests on that Content-Location URI. * However, the Content- Location can be used to differentiate between multiple entities retrieved from a single * requested resource, as described in section 13.6. + * *

                    * If the Content-Location is a relative URI, the relative URI is interpreted relative to the Request-URI. + * *

                    * The meaning of the Content-Location header in PUT or POST requests is undefined; servers are free to ignore it in * those cases. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/ContentRange.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/ContentRange.java b/juneau-core/src/main/java/org/apache/juneau/http/ContentRange.java index 78811e2..dc7ef18 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/ContentRange.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/ContentRange.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Content-Range HTTP response header. + * *

                    * Where in a full body message this partial message belongs. * @@ -23,6 +24,7 @@ package org.apache.juneau.http; *

                    * *
                    RFC2616 Specification
                    + * * The Content-Range entity-header is sent with a partial entity-body to specify where in the full entity-body the * partial body should be applied. * Range units are defined in section 3.12. @@ -36,23 +38,28 @@ package org.apache.juneau.http; * | "*" * instance-length = 1*DIGIT *

                    + * *

                    * The header SHOULD indicate the total length of the full entity-body, unless this length is unknown or difficult to * determine. * The asterisk "*" character means that the instance-length is unknown at the time when the response was generated. + * *

                    * Unlike byte-ranges-specifier values (see section 14.35.1), a byte- range-resp-spec MUST only specify one range, and * MUST contain absolute byte positions for both the first and last byte of the range. + * *

                    * A byte-content-range-spec with a byte-range-resp-spec whose last- byte-pos value is less than its first-byte-pos * value, or whose instance-length value is less than or equal to its last-byte-pos value, is invalid. * The recipient of an invalid byte-content-range- spec MUST ignore it and any content transferred along with it. + * *

                    * A server sending a response with status code 416 (Requested range not satisfiable) SHOULD include a Content-Range * field with a byte-range- resp-spec of "*". * The instance-length specifies the current length of the selected resource. * A response with status code 206 (Partial Content) MUST NOT include a Content-Range field with a byte-range-resp-spec * of "*". + * *

                    * Examples of byte-content-range-spec values, assuming that the entity contains a total of 1234 bytes: *

                    @@ -65,6 +72,7 @@ package org.apache.juneau.http; * The last 500 bytes: * bytes 734-1233/1234 *

                    + * *

                    * When an HTTP message includes the content of a single range (for example, a response to a request for a single range, * or to a request for a set of ranges that overlap without any holes), this content is transmitted with a Content-Range @@ -78,29 +86,35 @@ package org.apache.juneau.http; * Content-Length: 26012 * Content-Type: image/gif *

                    + * *

                    * When an HTTP message includes the content of multiple ranges (for example, a response to a request for multiple * non-overlapping ranges), these are transmitted as a multipart message. * The multipart media type used for this purpose is "multipart/byteranges" as defined in appendix 19.2. * See appendix 19.6.3 for a compatibility issue. + * *

                    * A response to a request for a single range MUST NOT be sent using the multipart/byteranges media type. * A response to a request for multiple ranges, whose result is a single range, MAY be sent as a multipart/byteranges * media type with one part. * A client that cannot decode a multipart/byteranges message MUST NOT ask for multiple byte-ranges in a single request. + * *

                    * When a client requests multiple byte-ranges in one request, the server SHOULD return them in the order that they * appeared in the request. + * *

                    * If the server ignores a byte-range-spec because it is syntactically invalid, the server SHOULD treat the request as * if the invalid Range header field did not exist. * (Normally, this means return a 200 response containing the full entity). + * *

                    * If the server receives a request (other than one including an If- Range request-header field) with an unsatisfiable * Range request- header field * (that is, all of whose byte-range-spec values have a first-byte-pos value greater than the current length of the * selected resource), * it SHOULD return a response code of 416 (Requested range not satisfiable) (section 10.4.17). + * *

                    * Note: clients cannot depend on servers to send a 416 (Requested range not satisfiable) response instead of a 200 (OK) * response for http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/ContentType.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/ContentType.java b/juneau-core/src/main/java/org/apache/juneau/http/ContentType.java index 7c1ec7d..565fe21 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/ContentType.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/ContentType.java @@ -18,6 +18,7 @@ import org.apache.juneau.internal.*; /** * Represents a parsed Content-Type HTTP request/response header. + * *

                    * The MIME type of this content. * @@ -33,6 +34,7 @@ import org.apache.juneau.internal.*; *

                    * Content-Type = "Content-Type" ":" media-type *

                    + * *

                    * Media types are defined in section 3.7. * An example of the field is... @@ -75,6 +77,7 @@ public class ContentType extends MediaType { /** * Given a list of media types, returns the best match for this Content-Type header. + * *

                    * Note that fuzzy matching is allowed on the media types where the Content-Types header may * contain additional subtype parts. http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/Date.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/Date.java b/juneau-core/src/main/java/org/apache/juneau/http/Date.java index 310836b..3b5be3e 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/Date.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/Date.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Date HTTP request/response header. + * *

                    * The date and time that the message was sent (in "HTTP-date" format as defined by RFC 7231). * @@ -30,31 +31,37 @@ package org.apache.juneau.http; *

                    * Date = "Date" ":" HTTP-date *

                    + * *

                    * An example is... *

                    * Date: Tue, 15 Nov 1994 08:12:31 GMT *

                    + * *

                    * Origin servers MUST include a Date header field in all responses, except in these cases: *

                      *
                    1. If the response status code is 100 (Continue) or 101 (Switching Protocols), the response MAY include a Date - * header field, at the server's option. + * header field, at the server's option. *
                    2. If the response status code conveys a server error, e.g. 500 (Internal Server Error) or 503 (Service - * Unavailable), and it is inconvenient or impossible to generate a valid Date. + * Unavailable), and it is inconvenient or impossible to generate a valid Date. *
                    3. If the server does not have a clock that can provide a reasonable approximation of the current time, its - * responses MUST NOT include a Date header field. + * responses MUST NOT include a Date header field. * In this case, the rules in section 14.18.1 MUST be followed. *
                    + * + *

                    * A received message that does not have a Date header field MUST be assigned one by the recipient if the message will * be cached by that recipient or gatewayed via a protocol which requires a Date. * An HTTP implementation without a clock MUST NOT cache responses without revalidating them on every use. * An HTTP cache, especially a shared cache, SHOULD use a mechanism, such as NTP, to synchronize its clock with a * reliable external standard. + * *

                    * Clients SHOULD only send a Date header field in messages that include an entity-body, as in the case of the PUT and * POST requests, and even then it is optional. * A client without a clock MUST NOT send a Date header field in a request. + * *

                    * The HTTP-date sent in a Date header SHOULD NOT represent a date and time subsequent to the generation of the message. * It SHOULD represent the best available approximation of the date and time of message generation, unless the http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/ETag.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/ETag.java b/juneau-core/src/main/java/org/apache/juneau/http/ETag.java index 0fe1d44..23a41df 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/ETag.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/ETag.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed ETag HTTP response header. + * *

                    * An identifier for a specific version of a resource, often a message digest. * @@ -27,9 +28,11 @@ package org.apache.juneau.http; * The ETag response-header field provides the current value of the entity tag for the requested variant. * The headers used with entity tags are described in sections 14.24, 14.26 and 14.44. * The entity tag MAY be used for comparison with other entities from the same resource (see section 13.3.3). + * *

                    * ETag = "ETag" ":" entity-tag *

                    + * *

                    * Examples: *

                    http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/EntityValidator.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/EntityValidator.java b/juneau-core/src/main/java/org/apache/juneau/http/EntityValidator.java index 65865c9..e4a3439 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/EntityValidator.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/EntityValidator.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a validator value. + * *

                    *

                    Example
                    *

                    http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/19c566dd/juneau-core/src/main/java/org/apache/juneau/http/Expect.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/http/Expect.java b/juneau-core/src/main/java/org/apache/juneau/http/Expect.java index 0a69862..6fa204b 100644 --- a/juneau-core/src/main/java/org/apache/juneau/http/Expect.java +++ b/juneau-core/src/main/java/org/apache/juneau/http/Expect.java @@ -14,6 +14,7 @@ package org.apache.juneau.http; /** * Represents a parsed Expect HTTP request header. + * *

                    * Indicates that particular server behaviors are required by the client. * @@ -32,24 +33,30 @@ package org.apache.juneau.http; * *expect-params ] * expect-params = ";" token [ "=" ( token | quoted-string ) ] *

                    + * *

                    * A server that does not understand or is unable to comply with any of the expectation values in the Expect field of a * request MUST respond with appropriate error status. * The server MUST respond with a 417 (Expectation Failed) status if any of the expectations cannot be met or, if there * are other problems with the request, some other 4xx status. + * *

                    * This header field is defined with extensible syntax to allow for future extensions. * If a server receives a request containing an Expect field that includes an expectation-extension that it does not * support, it MUST respond with a 417 (Expectation Failed) status. + * *

                    * Comparison of expectation values is case-insensitive for unquoted tokens (including the 100-continue token), and is * case-sensitive for quoted-string expectation-extensions. + * *

                    * The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST return a 417 (Expectation Failed) status if it * receives a request with an expectation that it cannot meet. * However, the Expect request-header itself is end-to-end; it MUST be forwarded if the request is forwarded. + * *

                    * Many older HTTP/1.0 and HTTP/1.1 applications do not understand the Expect header. + * *

                    * See section 8.2.3 for the use of the 100 (continue) status. *