http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/0d913b38/juneau-core/src/main/javadoc/overview.html ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/javadoc/overview.html b/juneau-core/src/main/javadoc/overview.html index 8537719..30be514 100644 --- a/juneau-core/src/main/javadoc/overview.html +++ b/juneau-core/src/main/javadoc/overview.html @@ -56,12 +56,18 @@ } </script> <ul class='spaced-list'> - <li>A toolkit for marshalling POJOs to a wide variety of content types using a common framework. - <li>A REST server API for creating self-documenting REST interfaces using POJOs. - <li>A REST client API for interacting with REST interfaces using POJOs. - <li>A remote proxy API built on top of REST. - <li>A sophisticated INI config file API. - <li>A REST microservice API that combines all the features above for creating lightweight stand-alone REST + <li> + A toolkit for marshalling POJOs to a wide variety of content types using a common framework. + <li> + A REST server API for creating self-documenting REST interfaces using POJOs. + <li> + A REST client API for interacting with REST interfaces using POJOs. + <li> + A remote proxy API built on top of REST. + <li> + A sophisticated INI config file API. + <li> + A REST microservice API that combines all the features above for creating lightweight stand-alone REST interfaces that start up in milliseconds. </ul> @@ -173,6 +179,7 @@ <p> In 2016, the code was donated to the Apache Foundation under the project <l>Apache Juneau</l>. </p> + <h5 class='toc'>Features</h5> <ol class='toc'> <li> @@ -246,34 +253,39 @@ Juneau requires Java 6+. The majority of the code has no other dependencies except for the following packages: </p> <ul class='doctree'> - <li class='jp'> <a class='doclink' - href='org/apache/juneau/jena/package-summary.html#TOC'>org.apache.juneau.jena</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/jena/package-summary.html#TOC'>org.apache.juneau.jena</a> - RDF support. Requires Apache Jena 2.7.1+. - <li class='jp'> <a class='doclink' - href='org/apache/juneau/rest/package-summary.html#TOC'>org.apache.juneau.rest</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/rest/package-summary.html#TOC'>org.apache.juneau.rest</a> - REST servlet support. Requires JEE 1.3+. - <li class='jp'> <a class='doclink' - href='org/apache/juneau/rest/client/package-summary.html#TOC'>org.apache.juneau.rest.client</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/rest/client/package-summary.html#TOC'>org.apache.juneau.rest.client</a> - REST client support. Requires Apache HttpClient 4.5+. </ul> <p> OSGi bundles are also provided that break down Juneau into the following components: </p> <ul class='spaced-list'> - <li><l>org.apache.juneau.core.jar</l> - Serializers, parsers, INI file support. - <li><l>org.apache.juneau.rest.jar</l> - REST servlet support. - <li><l>org.apache.juneau.rest.client.jar</l> - REST client support. - <li><l>org.apache.juneau.microservice.jar</l> - Microservice support. + <li> + <l>org.apache.juneau.core.jar</l> - Serializers, parsers, INI file support. + <li> + <l>org.apache.juneau.rest.jar</l> - REST servlet support. + <li> + <l>org.apache.juneau.rest.client.jar</l> - REST client support. + <li> + <l>org.apache.juneau.microservice.jar</l> - Microservice support. </ul> <p> The following zip files are also provided: </p> <ul class='spaced-list'> - <li><l>microservice-project.zip</l> - Contains a template Eclipse project for quickly creating REST resources + <li> + <l>microservice-project.zip</l> - Contains a template Eclipse project for quickly creating REST resources as executable jars. - <li><l>microservice-samples-project.zip</l> - Contains sample code demonstrating various aspects of Juneau. - <br> - These are discussed in detail in the <a class='doclink' href="#Samples">Samples</a> section. + <li> + <l>microservice-samples-project.zip</l> - Contains sample code demonstrating various aspects of Juneau. + <br>These are discussed in detail in the <a class='doclink' href="#Samples">Samples</a> section. </ul> <ul class='doctree'> @@ -373,15 +385,14 @@ <p> Default serialization support is provided for Java primitives, <code>Maps</code>, <code>Collections</code>, beans, and arrays. - <br> - Extensible support for other data types such as <code>Calendars</code>, <code>Dates</code>, + <br>Extensible support for other data types such as <code>Calendars</code>, <code>Dates</code>, <code>Iterators</code> is available through the use of POJO swaps (described later). </p> <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/serializer/package-summary.html#TOC'>org.apache.juneau.serializer</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/serializer/package-summary.html#TOC'>org.apache.juneau.serializer</a> - Serializer API Javadoc </ul> </div> @@ -456,19 +467,18 @@ </p> <ul class='doctree'> <li class='info'> - In the example above, we're parsing "lax" JSON (single quotes, unquoted attributes). - The JSON parser can handle any valid JSON syntax (such as quoted or unquoted attributes, single or double - quotes). - <br> - It can also handle JSON fragments and embedded Javascript comments. - Many of the JSON examples provided will use lax syntax which is easier to read since we don't have to deal - with escapes. + In the example above, we're parsing "lax" JSON (single quotes, unquoted attributes). + The JSON parser can handle any valid JSON syntax (such as quoted or unquoted attributes, single or double + quotes). + <br>It can also handle JSON fragments and embedded Javascript comments. + Many of the JSON examples provided will use lax syntax which is easier to read since we don't have to deal + with escapes. </ul> <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/parser/package-summary.html#TOC'>org.apache.juneau.parser</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/parser/package-summary.html#TOC'>org.apache.juneau.parser</a> - Parser API Javadoc </ul> </div> @@ -508,10 +518,13 @@ to provide annotated REST servlets that automatically negotiate the HTTP media types and allow the developer to work with requests and responses as POJOs. </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jc'>{@link org.apache.juneau.serializer.SerializerGroup} - <li class='jc'>{@link org.apache.juneau.parser.ParserGroup} + <li class='jc'> + {@link org.apache.juneau.serializer.SerializerGroup} + <li class='jc'> + {@link org.apache.juneau.parser.ParserGroup} </ul> </div> @@ -531,14 +544,20 @@ These classes extend directly from the following JCF classes: </p> <ul class='doctree'> - <li class='jc'> {@link java.util.LinkedHashMap java.util.LinkedHashMap} - <ul> - <li class='jc'> {@link org.apache.juneau.ObjectMap org.apache.juneau.ObjectMap} - </ul> - <li class='jc'> {@link java.util.LinkedList java.util.LinkedList} - <ul> - <li class='jc'> {@link org.apache.juneau.ObjectMap org.apache.juneau.ObjectList} - </ul> + <li class='jc'> + {@link java.util.LinkedHashMap java.util.LinkedHashMap} + <ul> + <li class='jc'> + {@link org.apache.juneau.ObjectMap org.apache.juneau.ObjectMap} + </ul> + </li> + <li class='jc'> + {@link java.util.LinkedList java.util.LinkedList} + <ul> + <li class='jc'> + {@link org.apache.juneau.ObjectMap org.apache.juneau.ObjectList} + </ul> + </li> </ul> <p> The <l>ObjectMap</l> and <l>ObjectList</l> classes are very similar to the <l>JSONObject</l> and @@ -550,9 +569,11 @@ These object can be serialized in one of two ways: </p> <ol class='spaced-list'> - <li>Using the provided {@link org.apache.juneau.ObjectMap#serializeTo(java.io.Writer)} or + <li> + Using the provided {@link org.apache.juneau.ObjectMap#serializeTo(java.io.Writer)} or {@link org.apache.juneau.ObjectList#serializeTo(java.io.Writer)} methods. - <li>Passing them to one of the {@link org.apache.juneau.serializer.Serializer} serialize methods. + <li> + Passing them to one of the {@link org.apache.juneau.serializer.Serializer} serialize methods. </ol> <p> Any valid JSON can be parsed into an unstructured model consisting of generic @@ -579,10 +600,13 @@ As a general rule, if you do not specify a target type during parsing, or if the target type cannot be determined through reflection, the parsers automatically generate <l>ObjectMaps</l> and <l>ObjectLists</l>. </ul> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jc'>{@link org.apache.juneau.ObjectMap} - <li class='jc'>{@link org.apache.juneau.ObjectList} + <li class='jc'> + {@link org.apache.juneau.ObjectMap} + <li class='jc'> + {@link org.apache.juneau.ObjectList} </ul> </div> @@ -592,30 +616,38 @@ <div class='topic'> <p> Serializers and parsers have a wide variety of configurable properties. - <br> - For example, the following code shows how to configure a JSON serializer: + <br>For example, the following code shows how to configure a JSON serializer: </p> <p class='bcode'> JsonSerializer s = <jk>new</jk> JsonSerializerBuilder().simple().ws().sq().build(); </p> <p> However, each of the serializers and parsers already contain reusable instances with common configurations. - <br> - For example, JSON has the following predefined reusable serializers and parsers: + <br>For example, JSON has the following predefined reusable serializers and parsers: </p> <ul class='doctree'> - <li class='jc'>{@link org.apache.juneau.json.JsonSerializer} - <ul> - <li class='jf'>{@link org.apache.juneau.json.JsonSerializer#DEFAULT DEFAULT} - <li class='jf'>{@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX DEFAULT_LAX} - <li class='jf'>{@link org.apache.juneau.json.JsonSerializer#DEFAULT_READABLE DEFAULT_READABLE} - <li class='jf'>{@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX_READABLE DEFAULT_LAX_READABLE} - </ul> - <li class='jc'>{@link org.apache.juneau.json.JsonParser} - <ul> - <li class='jf'>{@link org.apache.juneau.json.JsonParser#DEFAULT DEFAULT} - <li class='jf'>{@link org.apache.juneau.json.JsonParser#DEFAULT_STRICT DEFAULT_STRICT} - </ul> + <li class='jc'> + {@link org.apache.juneau.json.JsonSerializer} + <ul> + <li class='jf'> + {@link org.apache.juneau.json.JsonSerializer#DEFAULT DEFAULT} + <li class='jf'> + {@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX DEFAULT_LAX} + <li class='jf'> + {@link org.apache.juneau.json.JsonSerializer#DEFAULT_READABLE DEFAULT_READABLE} + <li class='jf'> + {@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX_READABLE DEFAULT_LAX_READABLE} + </ul> + </li> + <li class='jc'> + {@link org.apache.juneau.json.JsonParser} + <ul> + <li class='jf'> + {@link org.apache.juneau.json.JsonParser#DEFAULT DEFAULT} + <li class='jf'> + {@link org.apache.juneau.json.JsonParser#DEFAULT_STRICT DEFAULT_STRICT} + </ul> + </li> </ul> <p> These can be used directly, as follows: @@ -644,38 +676,84 @@ The following is a list of all configurable properties across all serializers and parsers. </p> <ul class='doctree'> - <li class='jc'><a class='doclink' href='org/apache/juneau/BeanContext.html#ConfigProperties'>BeanContext</a> - Properties associated with handling beans on serializers and parsers. - <ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/serializer/SerializerContext.html#ConfigProperties'>SerializerContext</a> - Configurable properties common to all serializers. - <ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/html/HtmlSerializerContext.html#ConfigProperties'>HtmlSerializerContext</a> - Configurable properties on the HTML serializer. - <ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/html/HtmlDocSerializerContext.html#ConfigProperties'>HtmlDocSerializerContext</a> - Configurable properties on the HTML document serializer. - </ul> - <li class='jic'><a class='doclink' href='org/apache/juneau/jena/RdfCommonContext.html#ConfigProperties'>RdfCommonContext</a> - Configurable properties common to the RDF serializers and parsers. - <ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/jena/RdfSerializerContext.html#ConfigProperties'>RdfSerializerContext</a> - Configurable properties on the RDF serializers. - </ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/json/JsonSerializerContext.html#ConfigProperties'>JsonSerializerContext</a> - Configurable properties on the JSON serializer. - <li class='jc'><a class='doclink' href='org/apache/juneau/msgpack/MsgPackSerializerContext.html#ConfigProperties'>MsgPackSerializerContext</a> - Configurable properties on the MessagePack serializer. - <li class='jc'><a class='doclink' href='org/apache/juneau/soap/SoapXmlSerializerContext.html#ConfigProperties'>SoapXmlSerializerContext</a> - Configurable properties on the SOAP/XML serializer. - <li class='jc'><a class='doclink' href='org/apache/juneau/urlencoding/UonSerializerContext.html#ConfigProperties'>UonSerializerContext</a> - Configurable properties on the URL-Encoding and UON serializers. - <li class='jc'><a class='doclink' href='org/apache/juneau/xml/XmlSerializerContext.html#ConfigProperties'>XmlSerializerContext</a> - Configurable properties on the XML serializer. - </ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/parser/ParserContext.html#ConfigProperties'>ParserContext</a> - Configurable properties common to all parsers. + <li class='jc'> + <a class='doclink' href='org/apache/juneau/BeanContext.html#ConfigProperties'>BeanContext</a> + - Properties associated with handling beans on serializers and parsers. <ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/html/HtmlParserContext.html#ConfigProperties'>HtmlParserContext</a> - Configurable properties on the HTML parser. - <li class='jic'><a class='doclink' href='org/apache/juneau/jena/RdfCommonContext.html#ConfigProperties'>RdfCommonContext</a> - Configurable properties common to the RDF serializers and parsers. - <ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/jena/RdfParserContext.html#ConfigProperties'>RdfParserContext</a> - Configurable properties on the RDF parsers. - </ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/json/JsonParserContext.html#ConfigProperties'>JsonParserContext</a> - Configurable properties on the JSON parser. - <li class='jc'><a class='doclink' href='org/apache/juneau/msgpack/MsgPackParserContext.html#ConfigProperties'>MsgPackParserContext</a> - Configurable properties on the MessagePack parser. - <li class='jc'><a class='doclink' href='org/apache/juneau/urlencoding/UonParserContext.html#ConfigProperties'>UonParserContext</a> - Configurable properties on the URL-Encoding and UON parsers. - <li class='jc'><a class='doclink' href='org/apache/juneau/xml/XmlParserContext.html#ConfigProperties'>XmlParserContext</a> - Configurable properties on the XML parser. + <li class='jc'> + <a class='doclink' href='org/apache/juneau/serializer/SerializerContext.html#ConfigProperties'>SerializerContext</a> + - Configurable properties common to all serializers. + <ul> + <li class='jc'> + <a class='doclink' href='org/apache/juneau/html/HtmlSerializerContext.html#ConfigProperties'>HtmlSerializerContext</a> + - Configurable properties on the HTML serializer. + <ul> + <li class='jc'> + <a class='doclink' href='org/apache/juneau/html/HtmlDocSerializerContext.html#ConfigProperties'>HtmlDocSerializerContext</a> + - Configurable properties on the HTML document serializer. + </ul> + </li> + <li class='jic'> + <a class='doclink' href='org/apache/juneau/jena/RdfCommonContext.html#ConfigProperties'>RdfCommonContext</a> + - Configurable properties common to the RDF serializers and parsers. + <ul> + <li class='jc'> + <a class='doclink' href='org/apache/juneau/jena/RdfSerializerContext.html#ConfigProperties'>RdfSerializerContext</a> + - Configurable properties on the RDF serializers. + </ul> + </li> + <li class='jc'> + <a class='doclink' href='org/apache/juneau/json/JsonSerializerContext.html#ConfigProperties'>JsonSerializerContext</a> + - Configurable properties on the JSON serializer. + <li class='jc'> + <a class='doclink' href='org/apache/juneau/msgpack/MsgPackSerializerContext.html#ConfigProperties'>MsgPackSerializerContext</a> + - Configurable properties on the MessagePack serializer. + <li class='jc'> + <a class='doclink' href='org/apache/juneau/soap/SoapXmlSerializerContext.html#ConfigProperties'>SoapXmlSerializerContext</a> + - Configurable properties on the SOAP/XML serializer. + <li class='jc'> + <a class='doclink' href='org/apache/juneau/urlencoding/UonSerializerContext.html#ConfigProperties'>UonSerializerContext</a> + - Configurable properties on the URL-Encoding and UON serializers. + <li class='jc'> + <a class='doclink' href='org/apache/juneau/xml/XmlSerializerContext.html#ConfigProperties'>XmlSerializerContext</a> + - Configurable properties on the XML serializer. + </ul> + </li> + <li class='jc'> + <a class='doclink' href='org/apache/juneau/parser/ParserContext.html#ConfigProperties'>ParserContext</a> + - Configurable properties common to all parsers. + <ul> + <li class='jc'> + <a class='doclink' href='org/apache/juneau/html/HtmlParserContext.html#ConfigProperties'>HtmlParserContext</a> + - Configurable properties on the HTML parser. + <li class='jic'> + <a class='doclink' href='org/apache/juneau/jena/RdfCommonContext.html#ConfigProperties'>RdfCommonContext</a> + - Configurable properties common to the RDF serializers and parsers. + <ul> + <li class='jc'><a class='doclink' href='org/apache/juneau/jena/RdfParserContext.html#ConfigProperties'>RdfParserContext</a> + - Configurable properties on the RDF parsers. + </ul> + </li> + <li class='jc'> + <a class='doclink' href='org/apache/juneau/json/JsonParserContext.html#ConfigProperties'>JsonParserContext</a> + - Configurable properties on the JSON parser. + <li class='jc'> + <a class='doclink' href='org/apache/juneau/msgpack/MsgPackParserContext.html#ConfigProperties'>MsgPackParserContext</a> + - Configurable properties on the MessagePack parser. + <li class='jc'> + <a class='doclink' href='org/apache/juneau/urlencoding/UonParserContext.html#ConfigProperties'>UonParserContext</a> + - Configurable properties on the URL-Encoding and UON parsers. + <li class='jc'> + <a class='doclink' href='org/apache/juneau/xml/XmlParserContext.html#ConfigProperties'>XmlParserContext</a> + - Configurable properties on the XML parser. + </ul> + </li> </ul> - </ul> - <li class='jc'><a class='doclink' href='org/apache/juneau/server/RestContext.html#ConfigProperties'>RestContext</a> - Configurable properties on the REST servlet. + </li> + <li class='jc'> + <a class='doclink' href='org/apache/juneau/server/RestContext.html#ConfigProperties'>RestContext</a> + - Configurable properties on the REST servlet. + </li> </ul> </div> @@ -689,30 +767,40 @@ These classes are: </p> <ul class='doctree'> - <li class='jc'>{@link org.apache.juneau.transform.PojoSwap} + <li class='jc'> + {@link org.apache.juneau.transform.PojoSwap} - Tailor how specific non-bean classes are handled by the framework. - <li class='jc'>{@link org.apache.juneau.transform.BeanFilter} + <li class='jc'> + {@link org.apache.juneau.transform.BeanFilter} - Tailor how specific bean classes are handled by the framework. </ul> <p> Annotations are also provided that allow you to use transformations directly on class definitions: </p> <ul class='doctree'> - <li class='ja'>{@link org.apache.juneau.annotation.Pojo @Pojo} + <li class='ja'> + {@link org.apache.juneau.annotation.Pojo @Pojo} - Used to tailor how non-bean POJOs get interpreted by the framework. - <li class='ja'>{@link org.apache.juneau.annotation.Bean @Bean} + <li class='ja'> + {@link org.apache.juneau.annotation.Bean @Bean} - Used to tailor how beans get interpreted by the framework. - <li class='ja'>{@link org.apache.juneau.annotation.BeanConstructor @BeanConstructor} + <li class='ja'> + {@link org.apache.juneau.annotation.BeanConstructor @BeanConstructor} - Maps constructor arguments to property names on beans with read-only properties. - <li class='ja'>{@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} + <li class='ja'> + {@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} - Ignore classes, fields, and methods from being interpreted as bean or bean components. - <li class='ja'>{@link org.apache.juneau.annotation.BeanProperty @BeanProperty} + <li class='ja'> + {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} - Used to tailor how bean properties get interpreted by the framework. - <li class='ja'>{@link org.apache.juneau.annotation.NameProperty @NameProperty} + <li class='ja'> + {@link org.apache.juneau.annotation.NameProperty @NameProperty} - Identifies a setter as a method for setting the name of a POJO as it's known by its parent object. - <li class='ja'>{@link org.apache.juneau.annotation.ParentProperty @ParentProperty} + <li class='ja'> + {@link org.apache.juneau.annotation.ParentProperty @ParentProperty} - Identifies a setter as a method for adding a parent reference to a child object. - <li class='ja'>{@link org.apache.juneau.annotation.URI @URI} + <li class='ja'> + {@link org.apache.juneau.annotation.URI @URI} - Used to identify a class or bean property as a URI. </ul> @@ -784,17 +872,25 @@ Several <code>PojoSwaps</code> are already provided for common Java objects: </p> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/transforms/package-summary.html#TOC'>org.apache.juneau.transforms</a> - <ul> - <li class='jc'>{@link org.apache.juneau.transforms.ByteArrayBase64Swap} - <li class='jac'>{@link org.apache.juneau.transforms.CalendarSwap} - <li class='jac'>{@link org.apache.juneau.transforms.DateSwap} - <li class='jc'>{@link org.apache.juneau.transforms.EnumerationSwap} - <li class='jc'>{@link org.apache.juneau.transforms.IteratorSwap} - <li class='jc'>{@link org.apache.juneau.transforms.ReaderSwap} - <li class='jc'>{@link org.apache.juneau.transforms.XMLGregorianCalendarSwap} - </ul> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/transforms/package-summary.html#TOC'>org.apache.juneau.transforms</a> + <ul> + <li class='jc'> + {@link org.apache.juneau.transforms.ByteArrayBase64Swap} + <li class='jac'> + {@link org.apache.juneau.transforms.CalendarSwap} + <li class='jac'> + {@link org.apache.juneau.transforms.DateSwap} + <li class='jc'> + {@link org.apache.juneau.transforms.EnumerationSwap} + <li class='jc'> + {@link org.apache.juneau.transforms.IteratorSwap} + <li class='jc'> + {@link org.apache.juneau.transforms.ReaderSwap} + <li class='jc'> + {@link org.apache.juneau.transforms.XMLGregorianCalendarSwap} + </ul> + </li> </ul> <p> In particular, the {@link org.apache.juneau.transforms.CalendarSwap} and @@ -803,8 +899,8 @@ </p> <ul class='doctree'> <li class='info'> - The 'swapped' class type must be a serializable type.<br> - See the definition for Category 4 objects in <a class='doclink' + The 'swapped' class type must be a serializable type. + <br>See the definition for Category 4 objects in <a class='doclink' href='#Core.PojoCategories'>POJO Categories</a>. </ul> </div> @@ -821,10 +917,10 @@ Objects serialized as <code>Strings</code> can be parsed back into their original objects by implementing one of the following methods on the class: </p> - <ul> - <li><code><jk>public static</jk> T fromString(String)</code> method. - <br> - Any of the following method names also work: + <ul class='spaced-list'> + <li> + <code><jk>public static</jk> T fromString(String)</code> method. + <br>Any of the following method names also work: <ul> <li><code>valueOf(String)</code> <li><code>parse(String)</code> @@ -832,7 +928,8 @@ <li><code>forName(String)</code> <li><code>forString(String)</code> </ul> - <li><code><jk>public</jk> T(String)</code> constructor. + <li> + <code><jk>public</jk> T(String)</code> constructor. </ul> <p> Note that these methods cover conversion from several built-in Java types, meaning the parsers can @@ -1030,8 +1127,8 @@ <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/transform/package-summary.html#TOC'>org.apache.juneau.transform</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/transform/package-summary.html#TOC'>org.apache.juneau.transform</a> </ul> </div> @@ -1281,9 +1378,9 @@ <tr class='light bb'> <td style='text-align:center'>2a</td> <td> - <b>With standard keys/values</b><br> - Map keys are group [1, 4a, 5a] objects.<br> - Map, Collection, and array values are group [1, 2, 3ac, 4a, 5a] objects. + <b>With standard keys/values</b> + <br>Map keys are group [1, 4a, 5a] objects. + <br>Map, Collection, and array values are group [1, 2, 3ac, 4a, 5a] objects. </td> <td> <ul class='normal'> @@ -1299,9 +1396,9 @@ <tr class='light bb'> <td style='text-align:center'>2b</td> <td> - <b>With non-standard keys/values</b><br> - Map keys are group [2, 3, 4b, 5b, 6] objects.<br> - Map, Collection, and array values are group [3b, 4b, 5b, 6] objects. + <b>With non-standard keys/values</b> + <br>Map keys are group [2, 3, 4b, 5b, 6] objects. + <br>Map, Collection, and array values are group [3b, 4b, 5b, 6] objects. </td> <td> <ul class='normal'> @@ -1322,10 +1419,10 @@ <tr class='light bb'> <td style='text-align:center'>3a</td> <td> - <b>With standard properties</b><br> - These are beans that have no-arg constructors and one or more properties defined by public getter - and setter methods or public fields.<br> - Property values are group [1, 2, 3ac, 4a, 5a] objects. + <b>With standard properties</b> + <br>These are beans that have no-arg constructors and one or more properties defined by public getter + and setter methods or public fields. + <br>Property values are group [1, 2, 3ac, 4a, 5a] objects. </td> <td> </td> <td style='background-color:lightgreen;text-align:center'><b>yes</b></td> @@ -1334,10 +1431,10 @@ <tr class='light bb'> <td style='text-align:center'>3b</td> <td> - <b>With non-standard properties or not true beans</b><br> - These include true beans that have no-arg constructors and one or more properties defined by getter - and setter methods or properties, but property types include group [3b, 4b, 5b, 6] objects.<br> - This also includes classes that look like beans but aren't true beans. + <b>With non-standard properties or not true beans</b> + <br>These include true beans that have no-arg constructors and one or more properties defined by getter + and setter methods or properties, but property types include group [3b, 4b, 5b, 6] objects. + <br>This also includes classes that look like beans but aren't true beans. For example, classes that have getters but not setters, or classes without no-arg constructors. </td> <td> </td> @@ -1347,9 +1444,9 @@ <tr class='light bb'> <td style='text-align:center'>3c</td> <td> - <b>Virtual beans</b><br> - These are unimplemented bean interfaces with properties of type [1, 2, 3ac, 4a, 5a] objects.<br> - Parsers will automatically create interface proxies on top of BeanMap instances. + <b>Virtual beans</b> + <br>These are unimplemented bean interfaces with properties of type [1, 2, 3ac, 4a, 5a] objects. + <br>Parsers will automatically create interface proxies on top of BeanMap instances. </td> <td> </td> <td style='background-color:lightgreen;text-align:center'><b>yes</b></td> @@ -1358,8 +1455,8 @@ <tr class='dark bb' style='background-color:lightyellow'> <td style='text-align:center'>4</td> <td> - <b>Swapped objects</b><br> - These are objects that are not directly serializable, but have + <b>Swapped objects</b> + <br>These are objects that are not directly serializable, but have {@link org.apache.juneau.transform.PojoSwap PojoSwaps} associated with them. The purpose of a POJO swap is to convert an object to another object that is easier to serialize and parse. @@ -1374,8 +1471,8 @@ <tr class='light bb'> <td style='text-align:center'>4a</td> <td> - <b>2-way swapped to group [1, 2a, 3ac] objects</b><br> - For example, a swap that converts a {@code Date} to a {@code String}. + <b>2-way swapped to group [1, 2a, 3ac] objects</b> + <br>For example, a swap that converts a {@code Date} to a {@code String}. </td> <td> <ul class='normal'> @@ -1389,8 +1486,8 @@ <tr class='light bb'> <td style='text-align:center'>4b</td> <td> - <b>1-way swapped to group [1, 2, 3] objects</b><br> - For example, a swap that converts an {@code Iterator} to a {@code List}. + <b>1-way swapped to group [1, 2, 3] objects</b> + <br>For example, a swap that converts an {@code Iterator} to a {@code List}. This would be one way, since you cannot reconstruct an {@code Iterator}. </td> <td> @@ -1466,8 +1563,7 @@ <td style='text-align:center'>6</td> <td> <b>All other objects</b> - <br> - Anything that doesn't fall into one of the groups above are simply converted to {@code Strings} + <br>Anything that doesn't fall into one of the groups above are simply converted to {@code Strings} using the {@code toString()} method. </td> <td> </td> @@ -1518,10 +1614,11 @@ SVL is a large topic on it's own. It is used extensively in the ConfigFile, REST and Microservice APIs. </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/svl/package-summary.html#TOC'>org.apache.juneau.svl</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/svl/package-summary.html#TOC'>org.apache.juneau.svl</a> - Simple Variable Language Javadocs. </ul> </div> @@ -1630,11 +1727,15 @@ capabilities, including: </p> <ul class='spaced-list'> - <li>The ability to use variables to reference environment variables, system properties, other config file + <li> + The ability to use variables to reference environment variables, system properties, other config file entries, and a host of other types. - <li>APIs for updating, modifying, and saving configuration files without losing comments or formatting. - <li>Extensive listener APIs. + <li> + APIs for updating, modifying, and saving configuration files without losing comments or formatting. + <li> + Extensive listener APIs. </ul> + <h6 class='topic'>Example:</h6> <p class='bcode'> <cc>#--------------------------</cc> @@ -1765,10 +1866,12 @@ ci.setBean(<jk>new</jk> MyBean()); cf.save(); </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' href='org/apache/juneau/ini/package-summary.html#TOC'> - org.apache.juneau.ini</a> - Config API Javadocs. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/ini/package-summary.html#TOC'>org.apache.juneau.ini</a> + - Config API Javadocs. </ul> </div> @@ -1780,19 +1883,42 @@ Extensive javadocs exist for individual language support. Refer to these docs for language-specific information. </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' href='org/apache/juneau/html/package-summary.html#TOC'>org.apache.juneau.html</a> - HTML support. - <li class='jp'><a class='doclink' href='org/apache/juneau/jena/package-summary.html#TOC'>org.apache.juneau.jena</a> - RDF support. - <li class='jp'><a class='doclink' href='org/apache/juneau/jso/package-summary.html#TOC'>org.apache.juneau.jso</a> - Java Serialized Object support. - <li class='jp'><a class='doclink' href='org/apache/juneau/json/package-summary.html#TOC'>org.apache.juneau.json</a> - JSON support. - <li class='jp'><a class='doclink' href='org/apache/juneau/msgpack/package-summary.html#TOC'>org.apache.juneau.msgpack</a> - MessagePack support. - <li class='jp'><a class='doclink' href='org/apache/juneau/plaintext/package-summary.html#TOC'>org.apache.juneau.plaintext</a> - Plain-text support. - <li class='jp'><a class='doclink' href='org/apache/juneau/soap/package-summary.html#TOC'>org.apache.juneau.soap</a> - SOAP support. - <li class='jp'><a class='doclink' href='org/apache/juneau/urlencoding/package-summary.html#TOC'>org.apache.juneau.urlencoding</a> - URL-Encoding and UON support. - <li class='jp'><a class='doclink' href='org/apache/juneau/xml/package-summary.html#TOC'>org.apache.juneau.xml</a> - XML support. - <li class='jp'><a class='doclink' href='org/apache/juneau/dto/atom/package-summary.html#TOC'>org.apache.juneau.dto.atom</a> - ATOM support. - <li class='jp'><a class='doclink' href='org/apache/juneau/dto/cognos/package-summary.html#TOC'>org.apache.juneau.dto.cognos</a> - Cognos support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/html/package-summary.html#TOC'>org.apache.juneau.html</a> + - HTML support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/jena/package-summary.html#TOC'>org.apache.juneau.jena</a> + - RDF support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/jso/package-summary.html#TOC'>org.apache.juneau.jso</a> + - Java Serialized Object support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/json/package-summary.html#TOC'>org.apache.juneau.json</a> + - JSON support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/msgpack/package-summary.html#TOC'>org.apache.juneau.msgpack</a> + - MessagePack support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/plaintext/package-summary.html#TOC'>org.apache.juneau.plaintext</a> + - Plain-text support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/soap/package-summary.html#TOC'>org.apache.juneau.soap</a> + - SOAP support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/urlencoding/package-summary.html#TOC'>org.apache.juneau.urlencoding</a> + - URL-Encoding and UON support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/xml/package-summary.html#TOC'>org.apache.juneau.xml</a> + - XML support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/dto/atom/package-summary.html#TOC'>org.apache.juneau.dto.atom</a> + - ATOM support. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/dto/cognos/package-summary.html#TOC'>org.apache.juneau.dto.cognos</a> + - Cognos support. </ul> </div> @@ -1808,23 +1934,33 @@ <p> The following charts describe equivalent features between the two libraries: </p> + <h6 class='topic'>Annotations</h6> <table class='styled'> <tr><th>Jackson</th><th>Juneau</th></tr> <tr> - <td><ja>@JsonGetter</ja><br><ja>@JsonSetter</ja></td> + <td> + <ja>@JsonGetter</ja> + <br><ja>@JsonSetter</ja> + </td> <td> {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} </td> </tr> <tr> - <td><ja>@JsonAnyGetter</ja><br><ja>@JsonAnySetter</ja></td> + <td> + <ja>@JsonAnyGetter</ja> + <br><ja>@JsonAnySetter</ja> + </td> <td> {@link org.apache.juneau.annotation.BeanProperty#name() @BeanProperty(name="*")} </td> </tr> <tr> - <td><ja>@JsonIgnore</ja><br><ja>@JsonIgnoreType</ja></td> + <td> + <ja>@JsonIgnore</ja> + <br><ja>@JsonIgnoreType</ja> + </td> <td> {@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} </td> @@ -1839,16 +1975,16 @@ <td><code><ja>@JsonAutoDetect</ja>(fieldVisibility=...)</code></td> <td> No equivalent annotation, but can be controlled via: - <br> - {@link org.apache.juneau.BeanContext#BEAN_beanFieldVisibility} - <br> - {@link org.apache.juneau.BeanContext#BEAN_methodVisibility} - <br> - Future annotation support planned. + <br>{@link org.apache.juneau.BeanContext#BEAN_beanFieldVisibility} + <br>{@link org.apache.juneau.BeanContext#BEAN_methodVisibility} + <br>Future annotation support planned. </td> </tr> <tr> - <td><ja>@JsonCreator</ja><br><ja>@JsonProperty</ja></td> + <td> + <ja>@JsonCreator</ja> + <br><ja>@JsonProperty</ja> + </td> <td> {@link org.apache.juneau.annotation.BeanConstructor @BeanConstructor} </td> @@ -1857,48 +1993,45 @@ <td><ja>@JacksonInject</ja></td> <td> No equivalent. - <br> - Future support planned. + <br>Future support planned. </td> </tr> <tr> - <td><ja>@JsonSerialize</ja><br><ja>@JsonDeserialize</ja></td> + <td> + <ja>@JsonSerialize</ja> + <br><ja>@JsonDeserialize</ja> + </td> <td> Juneau uses swaps to convert non-serializable object to serializable forms: - <br> - {@link org.apache.juneau.annotation.BeanProperty#swap() @BeanProperty(swap=...)} - <br> - {@link org.apache.juneau.annotation.Pojo#swap() @Pojo(swap=...)} + <br>{@link org.apache.juneau.annotation.BeanProperty#swap() @BeanProperty(swap=...)} + <br>{@link org.apache.juneau.annotation.Pojo#swap() @Pojo(swap=...)} </td> </tr> <tr> <td><ja>@JsonInclude</ja></td> <td> No equivalent annotation, but can be controlled via various settings: - <br> - {@link org.apache.juneau.BeanContext} - <br> - {@link org.apache.juneau.serializer.SerializerContext} - <br> - Future annotation support planned. + <br>{@link org.apache.juneau.BeanContext} + <br>{@link org.apache.juneau.serializer.SerializerContext} + <br>Future annotation support planned. </td> </tr> <tr> <td><ja>@JsonPropertyOrder</ja></td> <td> {@link org.apache.juneau.annotation.Bean#properties @Bean(properties="...")} - <br> - {@link org.apache.juneau.annotation.Bean#sort @Bean(sort=x)} - <br> + <br>{@link org.apache.juneau.annotation.Bean#sort @Bean(sort=x)} </td> </tr> <tr> - <td><ja>@JsonValue</ja><br><ja>@JsonRawValue</ja></td> + <td> + <ja>@JsonValue</ja> + <br><ja>@JsonRawValue</ja> + </td> <td> No equivalents. - <br> - Future support unlikely since these are JSON-centric. + <br>Future support unlikely since these are JSON-centric. </td> </tr> </table> @@ -2026,8 +2159,9 @@ <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' href='org/apache/juneau/dto/html5/package-summary.html#TOC'> - org.apache.juneau.dto.html5</a> - HTML5 beans. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/dto/html5/package-summary.html#TOC'>org.apache.juneau.dto.html5</a> + - HTML5 beans. </ul> </div> @@ -2037,8 +2171,7 @@ <div class='topic'> <p> The Juneau ATOM feed DTOs are simply beans with fluent-style setters. - <br> - The following code shows a feed being created programmatically using the + <br>The following code shows a feed being created programmatically using the {@link org.apache.juneau.dto.atom.AtomBuilder} class. </p> <p class='bcode'> @@ -2152,8 +2285,9 @@ <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/dto/atom/package-summary.html#TOC'>org.apache.juneau.dto.atom</a> - Atom DTOs. + <li class='jp'> + <a class='doclink' href='org/apache/juneau/dto/atom/package-summary.html#TOC'>org.apache.juneau.dto.atom</a> + - Atom DTOs. </ul> </div> @@ -2569,28 +2703,40 @@ The framework allows you to override header values through GET parameters, so that you can specify the <l>ACCEPT</l> header to see each type. Adding <l>&plainText=true</l> forces the response <l>Content-Type</l> to be <l>text/plain.</l> + <h6 class='figure'>HTML</h6> <img class='bordered' src="doc-files/Server.Html.png"> <p> Also, localization can be tested by passing in an <l>Accept-Language</l> header. + </p> + <h6 class='figure'>HTML/French</h6> <img class='bordered' src="doc-files/Server.Html.french.png"> + <h6 class='figure'>JSON</h6> <img class='bordered' src="doc-files/Server.Json.png"> + <h6 class='figure'>XML</h6> <img class='bordered' src="doc-files/Server.Xml.png"> + <h6 class='figure'>Simple XML</h6> <img class='bordered' src="doc-files/Server.SimpleXml.png"> + <h6 class='figure'>URL-Encoding</h6> <img class='bordered' src="doc-files/Server.UrlEncoding.png"> + <h6 class='figure'>UON</h6> <img class='bordered' src="doc-files/Server.Uon.png"> + <h6 class='figure'>RDF/XML</h6> <img class='bordered' src="doc-files/Server.RdfXml.png"> + <h6 class='figure'>RDF/N3</h6> <img class='bordered' src="doc-files/Server.N3.png"> + <h6 class='figure'>RDF/N-Tuple</h6> <img class='bordered' src="doc-files/Server.NTuple.png"> + <h6 class='figure'>RDF/Turtle</h6> <img class='bordered' src="doc-files/Server.Turtle.png"> @@ -2598,10 +2744,11 @@ The Server API is an exhaustive topic on its own. Refer to the additional information for an in-depth examination of the API. </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/server/package-summary.html#TOC'>org.apache.juneau.rest</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/server/package-summary.html#TOC'>org.apache.juneau.rest</a> - Juneau Server API Javadocs. </ul> </div> @@ -2643,10 +2790,11 @@ The Client API is also an exhaustive topic on its own. Refer to the additional information for an in-depth examination of the API. </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/client/package-summary.html#TOC'>org.apache.juneau.rest.client</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/client/package-summary.html#TOC'>org.apache.juneau.rest.client</a> - Juneau Client API Javadocs. </ul> </div> @@ -2730,8 +2878,10 @@ There are two ways to expose remoteable proxies on the server side: </p> <ol class='spaced-list'> - <li>Extending from <code>RemoteableServlet</code>. - <li>Using a <code><ja>@RestMethod</ja>(name=<js>"PROXY"</js>)</code> annotation on a Java method. + <li> + Extending from <code>RemoteableServlet</code>. + <li> + Using a <code><ja>@RestMethod</ja>(name=<js>"PROXY"</js>)</code> annotation on a Java method. </ol> <p> The <code>RemoteableServlet</code> class is a simple specialized servlet with an abstract @@ -2774,45 +2924,43 @@ </p> <p> In either case, the proxy communications layer is pure REST. - <br> - Therefore, in cases where the interface classes are not available on the client side, the same method calls can + <br>Therefore, in cases where the interface classes are not available on the client side, the same method calls can be made through pure REST calls. - <br> - This can also aid significantly in debugging, since calls to the remoteable service can be made directly from + <br>This can also aid significantly in debugging, since calls to the remoteable service can be made directly from a browser with no coding involved. </p> <p> The parameters and return types of the Java methods can be any of the supported serializable and parsable types in <a class='doclink' href='#Core.PojoCategories'>POJO Categories</a>. - <br> - This ends up being WAY more flexible than other proxy interfaces since Juneau can handle so may POJO types + <br>This ends up being WAY more flexible than other proxy interfaces since Juneau can handle so may POJO types out-of-the-box. - <br> - Most of the time you don't even need to modify your existing Java implementation code. + <br>Most of the time you don't even need to modify your existing Java implementation code. </p> <p> The RemoteableServlet class itself shows how sophisticated REST interfaces can be built on the Juneau RestServlet API using very little code. - <br> - The RemoteableServlet class itself consists of only 53 lines of code, yet is a sophisticated discoverable and + <br>The RemoteableServlet class itself consists of only 53 lines of code, yet is a sophisticated discoverable and self-documenting REST interface. - <br> - And since the remote proxy API is built on top of REST, it can be debugged using just a browser. + <br>And since the remote proxy API is built on top of REST, it can be debugged using just a browser. </p> <p> The requirements for a method to be callable through a remoteable service are: </p> <ul class='spaced-list'> - <li>The method must be public. - <li>The parameter and return types must be <a href='#Core.PojoCategories'>serializable and parsable</a>. + <li> + The method must be public. + <li> + The parameter and return types must be <a href='#Core.PojoCategories'>serializable and parsable</a>. Parameterized types are supported. - <li>Methods can throw <code>Throwables</code> with public no-arg or single-arg-string constructors which will + <li> + Methods can throw <code>Throwables</code> with public no-arg or single-arg-string constructors which will be automatically recreated on the client side. </ul> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/server/remoteable/package-summary.html#TOC'>org.apache.juneau.rest.remoteable</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/server/remoteable/package-summary.html#TOC'>org.apache.juneau.rest.remoteable</a> - Juneau Remoteable API Javadocs. </ul> @@ -2846,26 +2994,26 @@ The Java method arguments can be annotated with any of the following: </p> <ul class='spaced-list'> - <li>{@link org.apache.juneau.remoteable.Query @Query} - A URL query parameter. + <li> + {@link org.apache.juneau.remoteable.Query @Query} - A URL query parameter. <br>The argument can be any of the following types: <ul> <li>Any serializable POJO - Converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. <li><code>Map<String,Object></code> - Individual name-value pairs. - <br> - Values are converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. + <br>Values are converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. <li><code>String</code> - Treated as a query string. </ul> - <li>{@link org.apache.juneau.remoteable.QueryIfNE @QueryIfNE} + <li> + {@link org.apache.juneau.remoteable.QueryIfNE @QueryIfNE} - Same as <ja>@Query</ja> except skips the value if it's null/empty. - <li>{@link org.apache.juneau.remoteable.FormData @FormData} + <li> + {@link org.apache.juneau.remoteable.FormData @FormData} - A form-data parameter. - <br> - Note that this is only available if the HTTP method is <code>POST</code>. - <br> - The argument can be any of the following types: + <br>Note that this is only available if the HTTP method is <code>POST</code>. + <br>The argument can be any of the following types: <ul> <li>Any serializable POJO - Converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. @@ -2873,26 +3021,27 @@ - Individual name-value pairs. <li><code>Map<String,Object></code> - Individual name-value pairs. - <br> - Values are converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. + <br>Values are converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. </ul> - <li>{@link org.apache.juneau.remoteable.FormDataIfNE @FormDataIfNE} + <li> + {@link org.apache.juneau.remoteable.FormDataIfNE @FormDataIfNE} - Same as <ja>@FormData</ja> except skips the value if it's null/empty. - <li>{@link org.apache.juneau.remoteable.Header @Header} + <li> + {@link org.apache.juneau.remoteable.Header @Header} - A request header. - <br> - The argument can be any of the following types: + <br>The argument can be any of the following types: <ul> <li>Any serializable POJO - Converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. <li><code>Map<String,Object></code> - Individual name-value pairs. - <br> - Values are converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. + <br>Values are converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. </ul> - <li>{@link org.apache.juneau.remoteable.HeaderIfNE @HeaderIfNE} + <li> + {@link org.apache.juneau.remoteable.HeaderIfNE @HeaderIfNE} - Same as <ja>@Header</ja> except skips the value if it's null/empty. - <li>{@link org.apache.juneau.remoteable.Body @Body} + <li> + {@link org.apache.juneau.remoteable.Body @Body} - The HTTP request body. <br>The argument can be any of the following types: <ul> @@ -2913,28 +3062,31 @@ The return type of the Java method can be any of the following: </p> <ul class='spaced-list'> - <li><jk>void</jk> + <li> + <jk>void</jk> - Don't parse any response. - <br> - Note that the method will still throw a runtime exception if an error HTTP status is returned. - <li>Any parsable POJO + <br>Note that the method will still throw a runtime exception if an error HTTP status is returned. + <li> + Any parsable POJO - The body of the response will be converted to the POJO using the parser defined on the <code>RestClient</code>. - <li><code>HttpResponse</code> + <li> + <code>HttpResponse</code> - Returns the raw <code>HttpResponse</code> returned by the inner <code>HttpClient</code>. - <li>{@link java.io.Reader} + <li> + {@link java.io.Reader} - Returns access to the raw reader of the response. - <br> - Note that if you don't want your response parsed as a POJO, you'll want to get the response reader + <br>Note that if you don't want your response parsed as a POJO, you'll want to get the response reader directly. - <li>{@link java.io.InputStream} + <li> + {@link java.io.InputStream} - Returns access to the raw input stream of the response. </ul> <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/remoteable/package-summary.html#TOC'>org.apache.juneau.remoteable</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/remoteable/package-summary.html#TOC'>org.apache.juneau.remoteable</a> - Juneau Remoteable API Javadocs. </ul> </div> @@ -2964,10 +3116,11 @@ Microservices combine all the functionality of the core, server, and client APIs to provide truly powerful and easy-to-use REST interfaces with minimal overhead. </p> + <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jp'><a class='doclink' - href='org/apache/juneau/microservice/package-summary.html#TOC'>org.apache.juneau.microservice</a> + <li class='jp'> + <a class='doclink' href='org/apache/juneau/microservice/package-summary.html#TOC'>org.apache.juneau.microservice</a> - Juneau Microservice API Javadocs. </ul> </div> @@ -2993,16 +3146,20 @@ Follow these instructions to create the Samples project in Eclipse: </p> <ol class='spaced-list'> - <li>Download the latest microservice-samples-project .zip file (e.g. + <li> + Download the latest microservice-samples-project .zip file (e.g. <l>microservice-samples-project-5.2.zip</l>). - <li>In your Eclipse workspace, go to <b>File->Import->General->Existing Projects into Workspace</b> + <li> + In your Eclipse workspace, go to <b>File->Import->General->Existing Projects into Workspace</b> and click <b>Next</b>. <br><br> <img class='bordered' src="doc-files/Samples.Installing.1.png"> - <li>Select the .zip file and click <b>Finish</b>. + <li> + Select the .zip file and click <b>Finish</b>. <br><br> <img class='bordered' src="doc-files/Samples.Installing.2.png"> - <li>In your workspace, you can now see the following project: + <li> + In your workspace, you can now see the following project: <br><br> <img class='bordered' src="doc-files/Samples.Installing.3.png"> </ol> @@ -3010,8 +3167,9 @@ The important elements in this project are: </p> <ul class='spaced-list'> - <li><l>META-INF/MANIFEST.MF</l> - The manifest file. <br> - This defines the entry point, classpath, top-level REST resources, and location of external + <li> + <l>META-INF/MANIFEST.MF</l> - The manifest file. + <br>This defines the entry point, classpath, top-level REST resources, and location of external configuration file. <br><br> <p class='bcode'> @@ -3037,22 +3195,21 @@ lib/slf4j-api-1.6.4.jar lib/slf4j-log4j12-1.6.4.jar</mv> </p> - <li><l>RestMicroservice.java</l> + <li> + <l>RestMicroservice.java</l> - The application class. - <br> - This is a specialized microservice in Juneau for exposing REST servlets. - <br> - Allows REST servlets to be registered in the manifest or configuration file. - <li><l>RootResources.java</l> + <br>This is a specialized microservice in Juneau for exposing REST servlets. + <br>Allows REST servlets to be registered in the manifest or configuration file. + <li> + <l>RootResources.java</l> - The top-level REST resource. - <br> - This class serves as a "router" page to child resources: - <li><l>examples.cfg</l> + <br>This class serves as a "router" page to child resources: + <li> + <l>examples.cfg</l> - The external configuration file. + <br>A deceptively simple yet powerful INI-style configuration file: <br> - A deceptively simple yet powerful INI-style configuration file: - <br> - <p class='bcode'> + <p class='bcode'> <cc>#================================================================================ # Basic configuration file for SaaS microservices # Subprojects can use this as a starting point. @@ -3122,7 +3279,8 @@ </p> <img class='bordered' src='doc-files/Samples.Building.2.png'> <ul class='doctree'> - <li class='warn'>If you get an error message saying <code class='snippet'>java.net.BindException: Address + <li class='warn'> + If you get an error message saying <code class='snippet'>java.net.BindException: Address already in use</code>, this means that the microservice is already running elsewhere, so it cannot bind to port 10000. </ul> @@ -3159,28 +3317,34 @@ lib/slf4j-api-1.6.4.jar lib/slf4j-log4j12-1.6.4.jar</mv> </p> + <h6 class='topic'>Notes</h6> <ul class='spaced-list'> - <li>The <mk>Main-Class</mk> entry is just the standard manifest entry describing the entry point for the + <li> + The <mk>Main-Class</mk> entry is just the standard manifest entry describing the entry point for the executable jar. The <l>org.apache.juneau.microservice.RestMicroservice</l> class is the standard microservice class for REST microservices. Other kinds of microservices can be created by extending the {@link org.apache.juneau.microservice.Microservice} class. - <li>The <mk>Rest-Resources</mk> entry is a comma-delimited list of REST resources. + <li> + The <mk>Rest-Resources</mk> entry is a comma-delimited list of REST resources. These are classes that subclass from {@link org.apache.juneau.rest.RestServlet}. This is a specialized entry used by <l>org.apache.juneau.microservice.RestMicroservice</l>. In this case, you're pointing to a resource defined in our project, <l>org.apache.juneau.examples.rest.RootResources</l>, which serves as a "grouping" page for several other REST resources. - <li>The <mk>Main-ConfigFile</mk> entry points to the location of an external configuration file for our + <li> + The <mk>Main-ConfigFile</mk> entry points to the location of an external configuration file for our microservice. - <li>The <mk>Class-Path</mk> entry again is just the standard manifest file entry. + <li> + The <mk>Class-Path</mk> entry again is just the standard manifest file entry. However, if you need to add extra libraries to your microservice, you'll need to copy them into your <l>lib</l> directory and add them to the classpath here. </ul> <ul class='doctree'> - <li class='warn'>If you modify the manifest file and get <l>NoClassDefFoundErrors</l>, ensure that the + <li class='warn'> + If you modify the manifest file and get <l>NoClassDefFoundErrors</l>, ensure that the classpath entries contain trailing spaces. </ul> </div> @@ -3197,23 +3361,32 @@ The class hierarchy for this class is: </p> <ul class='doctree'> - <li class='jac'>{@link org.apache.juneau.rest.RestServlet org.apache.juneau.rest.RestServlet} + <li class='jac'> + {@link org.apache.juneau.rest.RestServlet org.apache.juneau.rest.RestServlet} <br>Contains all the REST servlet logic. - <ul> - <li class='jac'>{@link org.apache.juneau.rest.RestServletDefault org.apache.juneau.rest.RestServletDefault} - <br>Defines default serializers and parsers, and OPTIONs page logic. <ul> - <li class='jac'>{@link org.apache.juneau.rest.RestServletGroupDefault org.apache.juneau.rest.RestServletGroupDefault} - <br>Specialized subclass for grouping other resources - <ul> - <li class='jac'>{@link org.apache.juneau.microservice.ResourceGroup org.apache.juneau.microservice.ResourceGroup} - <br>Specialized subclass when using the Microservice API. + <li class='jac'> + {@link org.apache.juneau.rest.RestServletDefault org.apache.juneau.rest.RestServletDefault} + <br>Defines default serializers and parsers, and OPTIONs page logic. <ul> - <li class='jc'><code>org.apache.juneau.rest.samples.RootResources</code> + <li class='jac'> + {@link org.apache.juneau.rest.RestServletGroupDefault org.apache.juneau.rest.RestServletGroupDefault} + <br>Specialized subclass for grouping other resources + <ul> + <li class='jac'> + {@link org.apache.juneau.microservice.ResourceGroup org.apache.juneau.microservice.ResourceGroup} + <br>Specialized subclass when using the Microservice API. + <ul> + <li class='jc'> + <code>org.apache.juneau.rest.samples.RootResources</code> + </ul> + </li> + </ul> + </li> </ul> - </ul> + </li> </ul> - </ul> + </li> </ul> <p> Pointing a browser to the resource shows the following: @@ -3237,6 +3410,7 @@ <p> The <l>RootResources</l> class consists entirely of annotations: </p> + <h6 class='figure'>RootResources.java</h6> <p class='bcode'> <jd>/** @@ -3276,6 +3450,7 @@ <p> The resource bundle contains the localized strings for the resource: </p> + <h6 class='figure'>RootResources.properties</h6> <p class='bcode'> <cc>#-------------------------------------------------------------------------------- @@ -3299,6 +3474,7 @@ identify the subpath of the child. For example, the <l>HelloWorldResource</l> class is annotated as follows: </p> + <h6 class='figure'>HelloWorldResource.java</h6> <p class='bcode'> <ja>@RestResource</ja>(messages=<js>"nls/HelloWorldResource"</js>, path=<js>"/helloWorld"</js>) @@ -3318,8 +3494,8 @@ </p> <ul class='doctree'> <li class='info'> - Let's step back and describe what's going on here:<br> - During servlet initialization of the <l>RootResources</l> object, the toolkit looks for the + Let's step back and describe what's going on here: + <br>During servlet initialization of the <l>RootResources</l> object, the toolkit looks for the <l>@RestResource.children()</l> annotation. If it finds it, it instantiates instances of each class and recursively performs servlet initialization on them. @@ -3340,6 +3516,7 @@ <p> The <l>HelloWorldResource</l> class is a simple resource that prints a "Hello world!" message. </p> + <h6 class='figure'>HelloWorldResource.java</h6> <p class='bcode'> <jd>/** @@ -3362,6 +3539,7 @@ } } </p> + <h6 class='figure'>HelloWorldResource.properties</h6> <p class='bcode'> <cc>#-------------------------------------------------------------------------------- @@ -3375,19 +3553,25 @@ The class hierarchy for this class is: </p> <ul class='doctree'> - <li class='jac'>{@link org.apache.juneau.rest.RestServlet org.apache.juneau.rest.RestServlet} + <li class='jac'> + {@link org.apache.juneau.rest.RestServlet org.apache.juneau.rest.RestServlet} <br>Contains all the REST servlet logic. - <ul> - <li class='jac'>{@link org.apache.juneau.rest.RestServletDefault org.apache.juneau.rest.RestServletDefault} - <br>Defines default serializers and parsers, and OPTIONs page logic. <ul> - <li class='jac'>{@link org.apache.juneau.microservice.Resource org.apache.juneau.microservice.Resource} - <br>Specialized subclass when using the Microservice API. - <ul> - <li class='jc'><code>org.apache.juneau.rest.samples.HelloWorldResource</code> - </ul> + <li class='jac'> + {@link org.apache.juneau.rest.RestServletDefault org.apache.juneau.rest.RestServletDefault} + <br>Defines default serializers and parsers, and OPTIONs page logic. + <ul> + <li class='jac'> + {@link org.apache.juneau.microservice.Resource org.apache.juneau.microservice.Resource} + <br>Specialized subclass when using the Microservice API. + <ul> + <li class='jc'><code>org.apache.juneau.rest.samples.HelloWorldResource</code> + </ul> + </li> + </ul> + </li> </ul> - </ul> + </li> </ul> <p> Pointing a browser to the resource shows the following: @@ -3408,16 +3592,21 @@ The <l>MethodExampleResource</l> class provides examples of the following: </p> <ul class='spaced-list'> - <li>Using the {@link org.apache.juneau.rest.Redirect} object to perform redirections. - <li>Using the various Java method parameter annotations to retrieve request attributes, parameters, etc. - <li>Using the annotation programmatic equivalents on the {@link org.apache.juneau.rest.RestRequest} object. - <li>Setting response POJOs by either returning them or using the + <li> + Using the {@link org.apache.juneau.rest.Redirect} object to perform redirections. + <li> + Using the various Java method parameter annotations to retrieve request attributes, parameters, etc. + <li> + Using the annotation programmatic equivalents on the {@link org.apache.juneau.rest.RestRequest} object. + <li> + Setting response POJOs by either returning them or using the {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} method. </ul> <p> The resource is provided to show how various HTTP entities (e.g. parameters, headers) can be accessed - as either annotated Java parameters, or through methods on the <l>RestRequest</l> object. + as either annotated Java parameters, or through methods on the <l>RestRequest</l> object. </p> + <h6 class='figure'>MethodExampleResource.java</h6> <p class='bcode'> <jd>/** @@ -3549,13 +3738,13 @@ The class consists of 4 methods: </p> <ul class='doctree'> - <li class='jm'><l>doExample()</l> - <br> - The root page. - <br> - Performs a simple redirection to the <l>doGetExample1()</l> method using a + <li class='jm'> + <l>doExample()</l> + <br>The root page. + <br>Performs a simple redirection to the <l>doGetExample1()</l> method using a {@link org.apache.juneau.rest.Redirect} object. - <li class='jm'><l>example1()</l> + <li class='jm'> + <l>example1()</l> <br>Shows how to use the following annotations: <ul> <li class='ja'>{@link org.apache.juneau.rest.annotation.Path @Path} @@ -3565,9 +3754,9 @@ <li class='ja'>{@link org.apache.juneau.rest.annotation.PathRemainder @PathRemainder} </ul> Method returns a POJO to be serialized as the output. - <li class='jm'><l>example2()</l> - <br> - Identical to <l>doGetExample1()</l> but shows how to use the + <li class='jm'> + <l>example2()</l> + <br>Identical to <l>doGetExample1()</l> but shows how to use the {@link org.apache.juneau.rest.RestRequest} and {@link org.apache.juneau.rest.RestResponse} objects: <ul> <li class='jm'>{@link org.apache.juneau.rest.RestRequest#getPathMatch()} @@ -3578,14 +3767,12 @@ <li class='jm'>{@link org.apache.juneau.rest.RequestPathMatch#getRemainder()} </ul> Method sets the POJO to be serialized using the {@link org.apache.juneau.rest.RestResponse#setOutput(Object)} method. - <li class='jm'><l>example3()</l> - <br> - Identical to <l>doGetExample1()</l> but uses automatically resolved parameters based on class type. - <br> - Juneau automatically recognizes specific class types such as common header types and automatically + <li class='jm'> + <l>example3()</l> + <br>Identical to <l>doGetExample1()</l> but uses automatically resolved parameters based on class type. + <br>Juneau automatically recognizes specific class types such as common header types and automatically resolves them to objects for you. - <br> - See <a class='doclink' + <br>See <a class='doclink' href='org/apache/juneau/rest/package-summary.html#RestResources.MethodSignature'>Rest Resources / Method Signature</a> for the list of all automatically support parameter types, and {@link org.apache.juneau.rest.annotation.RestResource#paramResolvers() @RestResource.paramResolvers()} @@ -3610,6 +3797,7 @@ <p> Notice how the conversion to POJOs is automatically done for us, even for non-standard POJOs such as UUID. </p> + <h6 class='topic'>Self-documenting design through Swagger OPTIONS pages</h6> <p> One of the main features of Juneau is that it produces OPTIONS pages for self-documenting design (i.e. REST @@ -3619,15 +3807,16 @@ Much of the information populated on the OPTIONS page is determined through reflection. This basic information can be augmented with information defined through: </p> - <ul> - <li>Annotations - An example of this was shown in the <code>SystemPropertiesResource</code> example above. - <br> - Localized strings can be pulled from resource bundles using the <code>$L</code> localization variable. - <li>Resource bundle properties - Described in detail in this section. - <li>Swagger JSON files with the same name and location as the resource class (e.g. + <ul class='spaced-list'> + <li> + Annotations - An example of this was shown in the <code>SystemPropertiesResource</code> example above. + <br>Localized strings can be pulled from resource bundles using the <code>$L</code> localization variable. + <li> + Resource bundle properties - Described in detail in this section. + <li> + Swagger JSON files with the same name and location as the resource class (e.g. <code>MethodExampleResource.json</code>). - <br> - Localized versions are defined by appending the locale to the file name (e.g. + <br>Localized versions are defined by appending the locale to the file name (e.g. <code>MethodExampleResource_ja_JP.json</code>); </ul> <p> @@ -3639,6 +3828,7 @@ To define an OPTIONS request handler, the {@link org.apache.juneau.rest.RestServletDefault} class defines the following Java method: </p> + <h6 class='figure'>RestServletDefault.java</h6> <p class='bcode'> <jd>/** OPTIONS request handler */</jd> @@ -3669,7 +3859,8 @@ through a <code><ja>@RestResource</ja>(messages=<js>"nls/MethodExampleResources"</js>)</code> annotation. The properties file contains localized descriptions for the resource, resource methods, and method parameters. - </p> + </p> + <h6 class='figure'>MethodExampleResource.properties</h6> <p class='bcode'> <cc>#-------------------------------------------------------------------------------- @@ -3715,13 +3906,16 @@ The <l>UrlEncodedFormResource</l> class provides examples of the following: </p> <ul class='spaced-list'> - <li>How to use form entry beans to process form POSTs. - <li>How to use the {@link org.apache.juneau.rest.RestRequest#getReaderResource(String)} method to + <li> + How to use form entry beans to process form POSTs. + <li> + How to use the {@link org.apache.juneau.rest.RestRequest#getReaderResource(String)} method to serve up static files with embedded string variables. </ul> <p> The class is shown below: </p> + <h6 class='figure'>UrlEncodedFormResource.java</h6> <p class='bcode'> <jd>/** @@ -3759,6 +3953,7 @@ The {@link org.apache.juneau.rest.RestRequest#getReaderResource(String,boolean)} method pulls in the following file located in the same package as the class: </p> + <h6 class='figure'>UrlEncodedForm.html</h6> <p class='bcode'> <xt><html></xt> @@ -3810,6 +4005,7 @@ <p> The <l>$L</l> variables are string variable that pull in localized values from the resource bundle: </p> + <h6 class='figure'>UrlEncodedFormResource.properties</h6> <p class='bcode'> <cc>#-------------------------------------------------------------------------------- @@ -3888,9 +4084,11 @@ <h6 class='topic'>Additional Information</h6> <ul class='doctree'> - <li class='jm'>{@link org.apache.juneau.rest.RestConfig#addVars(Class[])} + <li class='jm'> + {@link org.apache.juneau.rest.RestConfig#addVars(Class[])} - Servlet and request variables. - <li class='jm'>{@link org.apache.juneau.rest.RestCallHandler#getSessionObjects(RestRequest)} + <li class='jm'> + {@link org.apache.juneau.rest.RestCallHandler#getSessionObjects(RestRequest)} - Var resolver session objects. </ul> </div> @@ -3908,17 +4106,21 @@ It provides examples of the following: </p> <ul class='spaced-list'> - <li>Using the {@link org.apache.juneau.rest.annotation.RestResource#properties() @RestResource.properties()} + <li> + Using the {@link org.apache.juneau.rest.annotation.RestResource#properties() @RestResource.properties()} annotation to set serializer properties. - <li>Using the {@link org.apache.juneau.rest.annotation.RestResource#beanFilters() @RestResource.beanFilters()} + <li> + Using the {@link org.apache.juneau.rest.annotation.RestResource#beanFilters() @RestResource.beanFilters()} and {@link org.apache.juneau.rest.annotation.RestResource#pojoSwaps() @RestResource.pojoSwaps()} annotations to set serializer transforms. - <li>Using the {@link org.apache.juneau.rest.annotation.Properties @Properties} annotation to set + <li> + Using the {@link org.apache.juneau.rest.annotation.Properties @Properties} annotation to set serializers properties programmatically on a request. </ul> <p> The class is shown below: </p> + <h6 class='figure'>RequestEchoResource.java</h6> <p class='bcode'> <jd>/** @@ -3974,6 +4176,7 @@ The annotations are functionally equivalent to using the {@link org.apache.juneau.rest.RestConfig} class, as follows: </p> + <h6 class='figure'>Hypothetical RequestEchoResource.createSerializers() method</h6> <p class='bcode'> <jd>/** Override the default rest serializers to add some transforms */</jd> @@ -4019,26 +4222,38 @@ It provides examples of the following: </p> <ul class='spaced-list'> - <li>How to create RESTful interfaces using only POJOs. - <li>How to use the {@link org.apache.juneau.xml.annotation.Xml @Xml} and + <li> + How to create RESTful interfaces using only POJOs. + <li> + How to use the {@link org.apache.juneau.xml.annotation.Xml @Xml} and {@link org.apache.juneau.xml.annotation.XmlSchema @XmlSchema} annotations to provide XML namespaces and alter how beans are handled by the XML serializer. - <li>How to use the {@link org.apache.juneau.jena.annotation.Rdf @Rdf} and + <li> + How to use the {@link org.apache.juneau.jena.annotation.Rdf @Rdf} and {@link org.apache.juneau.xml.annotation.XmlSchema @RdfSchema} annotations to provide XML namespaces and alter how beans are handled by the Jena serializers. - <li>How to use the {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotation + <li> + How to use the {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotation to alter how bean properties are handled by the serializers. - <li>How to use the {@link org.apache.juneau.rest.annotation.RestMethod#name() RestMethod.name()} annotation + <li> + How to use the {@link org.apache.juneau.rest.annotation.RestMethod#name() RestMethod.name()} annotation to create overloaded methods beyond the standard GET/PUT/POST/DELETE. - <li>How to augment data in the OPTIONS page. - <li>How to use the {@link org.apache.juneau.rest.client.RestClient} API to interact with the REST resource + <li> + How to augment data in the OPTIONS page. + <li> + How to use the {@link org.apache.juneau.rest.client.RestClient} API to interact with the REST resource using the same POJOs used to create the server-side API. - <li>How to interact with the REST resource using only a browser. - <li>Using the {@link org.apache.juneau.rest.converters.Traversable} converter to drill down into POJO models. - <li>Using the {@link org.apache.juneau.rest.converters.Queryable} converter to provide search/view/sort + <li> + How to interact with the REST resource using only a browser. + <li> + Using the {@link org.apache.juneau.rest.converters.Traversable} converter to drill down into POJO models. + <li> + Using the {@link org.apache.juneau.rest.converters.Queryable} converter to provide search/view/sort functionality against POJOs. - <li>Using the {@link org.apache.juneau.rest.converters.Introspectable} converter to invoke methods on POJOs. - <li>Using proxy interfaces. + <li> + Using the {@link org.apache.juneau.rest.converters.Introspectable} converter to invoke methods on POJOs. + <li> + Using proxy interfaces. </ul> <p> Pointing a browser to the resource shows the following: @@ -4053,19 +4268,25 @@ The code is straightforward, consisting of the following classes: </p> <ul class='spaced-list'> - <li><l>package-info.java</l> - Used to define XML namespaces for POJOs in this package. - <li><l>IAddressBook</l> - An interface describing the address book. - <li><l>AddressBook</l> - A data structure consisting of a list of <code>Persons</code>. - <li><l>Person, Address</l> - In-memory representations of people and addresses. - <li><l>CreatePerson, CreateAddress</l> - POJOs for creating and updating people and address through the + <li> + <l>package-info.java</l> - Used to define XML namespaces for POJOs in this package. + <li> + <l>IAddressBook</l> - An interface describing the address book. + <li> + <l>AddressBook</l> - A data structure consisting of a list of <code>Persons</code>. + <li> + <l>Person, Address</l> - In-memory representations of people and addresses. + <li> + <l>CreatePerson, CreateAddress</l> - POJOs for creating and updating people and address through the REST interface. - <li><l>AddressBookResource</l> - The REST resource class. + <li> + <l>AddressBookResource</l> - The REST resource class. </ul> <ul class='doctree'> <li class='info'> - For the sake of brevity, bean properties are defined as public fields instead of the normal - getters/setters. - Also, the examples are not the most efficient design and are not thread safe. + For the sake of brevity, bean properties are defined as public fields instead of the normal + getters/setters. + Also, the examples are not the most efficient design and are not thread safe. </ul> <p> The <l>package-info.java</l> file is used to define XML and RDF namespaces on beans and properties in @@ -4075,6 +4296,7 @@ It should be noted that these features are entirely optional, and there are often several ways of defining these namespaces. </p> + <h6 class='figure'>package-info.java</h6> <p class='bcode'> <jc>// XML and RDF namespaces used in this package</jc> @@ -4100,6 +4322,7 @@ <p> Our address book uses the following interface: </p> + <h6 class='figure'>IAddressBook.java</h6> <p class='bcode'> <jd>/** @@ -4130,15 +4353,18 @@ Person removePerson(<jk>int</jk> id); } </p> + <h6 class='topic'>Notes</h6> <ul class='spaced-list'> - <li>You interface an interface for our address book so that you can later + <li> + You interface an interface for our address book so that you can later use it to demonstrate the proxy interface support. </ul> <p> The <l>AddressBook</l> class is our address book. It maintains a list of <l>Person</l> objects with some additional convenience methods: </p> + <h6 class='figure'>AddressBook.java</h6> <p class='bcode'> <jd>/** Address book bean */</jd> @@ -4217,23 +4443,28 @@ } } </p> + <h6 class='topic'>Notes</h6> <ul class='spaced-list'> - <li>The <code><ja>@Xml</ja>(elementName=<js>"addressBook"</js>)</code> annotation tells the toolkit that + <li> + The <code><ja>@Xml</ja>(elementName=<js>"addressBook"</js>)</code> annotation tells the toolkit that when serialized as XML, the element name is <xt><addressBook></xt>. Without this annotation, the element would revert to the generalized <xt><array></xt> tag. - <li>The separate constructors are implementation specific and are needed because you're going to be + <li> + The separate constructors are implementation specific and are needed because you're going to be using this class in two ways, since you'll be demonstrating the client code as well as the server code, and it eliminates having to define separate client-side and server-side POJOs: - <ol> - <li>The normal constructor is used to programmatically create this object in the REST servlet code. - <li>The no-arg constructor is used by the Juneau parsers to construct this object in our client - side code. - </ol> + <ol> + <li>The normal constructor is used to programmatically create this object in the REST servlet code. + <li>The no-arg constructor is used by the Juneau parsers to construct this object in our client + side code. + </ol> + </li> </ul> <p> The <l>Person</l> bean is defined as follows: </p> + <h6 class='figure'>Person.java</h6> <p class='bcode'> <jd>/** Person bean */</jd> @@ -4286,15 +4517,19 @@ } } </p> + <h6 class='topic'>Notes</h6> <ul class='spaced-list'> - <li>The <l>ns="per"</l> annotations override the default <l>"ab"</l> namespace defined on the package. + <li> + The <l>ns="per"</l> annotations override the default <l>"ab"</l> namespace defined on the package. It applies to this class and all properties of this class. - <li>The <code><ja>@Rdf</ja>(beanUri=<jk>true</jk>)</code> annotation identifies the <l>uri</l> property + <li> + The <code><ja>@Rdf</ja>(beanUri=<jk>true</jk>)</code> annotation identifies the <l>uri</l> property as the resource URI for this resource. This property has special meaning for the RDF serializer. The RDF serializer uses this property for the value of the <l>rdf:resource</l> attribute. - <li>The <code><ja>@BeanProperty</ja>(swap=CalendarSwap.Medium.<jk>class</jk>)</code> annotation causes + <li> + The <code><ja>@BeanProperty</ja>(swap=CalendarSwap.Medium.<jk>class</jk>)</code> annotation causes the date field to be serialized in the format <l>"MM dd, yyyy"</l>. This could have also been specified globally on the resource level through the {@link org.apache.juneau.rest.annotation.RestResource#properties} annotation. @@ -4302,6 +4537,7 @@ <p> The <l>Address</l> bean is defined as follows: </p> + <h6 class='figure'>Address.java</h6> <p class='bcode'> <jd>/** @@ -4341,14 +4577,17 @@ } } </p> + <h6 class='topic'>Notes</h6> <ul class='spaced-list'> - <li>This class shows how the namespace can be overridden at the property level through the - <code><ja>@Xml</ja>(ns=<js>"mail"</js>)</code> annotation. + <li> + This class shows how the namespace can be overridden at the property level through the + <code><ja>@Xml</ja>(ns=<js>"mail"</js>)</code> annotation. </ul> <p> The <l>CreatePerson</l> bean is used as the input data for creating a person. </p> + <h6 class='figure'>CreatePerson.java</h6> <p class='bcode'> <jd>/** Bean for creating a new person */</jd> @@ -4372,6 +4611,7 @@ <p> The <l>CreateAddress</l> bean is used as the input data for creating an address. </p> + <h6 class='figure'>CreateAddress.java</h6> <p class='bcode'> <jd>/** Bean for creating a new address */</jd> @@ -4398,6 +4638,7 @@ <p> The <l>AddressBookResource</l> class is our REST resource class. </p> + <h6 class='figure'>AddressBookResource.java</h6> <p class='bcode'> <jd>/** @@ -4715,16 +4956,20 @@ } } </p> + <h6 class='topic'>Notes</h6> <ul class='spaced-list'> - <li>The <l>@RestResource.messages()</l> annotation identifies + <li> + The <l>@RestResource.messages()</l> annotation identifies <l>org/apache/juneau/samples/addressbook/nls/AddressBookResource.properties</l> as the resource bundle for localized message for this class. - <li>You are setting <l>XML_enableNamespaces</l> to <l>true</l> to enable XML namespaces. + <li> + You are setting <l>XML_enableNamespaces</l> to <l>true</l> to enable XML namespaces. By default, XML namespace support is disabled per {@link org.apache.juneau.xml.XmlSerializerContext#XML_enableNamespaces}, so you have to explicitly enable it on our serializers. - <li>The <l>XML_autoDetectNamespaces</l> setting is needed to get the XML serializer to add <l>xmlns</l> + <li> + The <l>XML_autoDetectNamespaces</l> setting is needed to get the XML serializer to add <l>xmlns</l> attributes to the root elements. This causes the XML serializer to scan the POJO objects for namespaces in order to populate the root element. @@ -4732,21 +4977,26 @@ setting at either the resource or method level, which might be preferred in high-performance environments. However, <l>XML_autoDetectNamespaces</l> produces the simplest code for our example. - <li>The <l>updatePerson()</l> and <l>updateAddress()</l> methods use a guard to only allow + <li> + The <l>updatePerson()</l> and <l>updateAddress()</l> methods use a guard to only allow administrators access. For the sample code, the guard does nothing. It's up to the implementer to decide how to restrict access. - <li>The <l>updatePerson()</l> and <l>updateAddress()</l> methods use the + <li> + The <l>updatePerson()</l> and <l>updateAddress()</l> methods use the {@link org.apache.juneau.utils.PojoRest} class to locate and update individual nodes in a POJO tree using the path remainder on the request. - <li>The <l>doInit()</l> method shows an example of an overloaded method using the + <li> + The <l>doInit()</l> method shows an example of an overloaded method using the <l>@RestMethod(name="INIT")</l> annotation. - <li>The <l>getOptions()</l> method shows the default OPTIONS page augmented with some additional + <li> + The <l>getOptions()</l> method shows the default OPTIONS page augmented with some additional information. </ul> <p> The OPTIONS page uses the servlet resource bundle to specify the labels so that they're globalizable. </p> + <h6 class='figure'>AddressBookResource.properties</h6> <p class='bcode'> <ck>title</ck> = <cv>AddressBook sample resource</cv> @@ -485
<TRUNCATED>
