http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/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 310cd26..8537719 100644 --- a/juneau-core/src/main/javadoc/overview.html +++ b/juneau-core/src/main/javadoc/overview.html @@ -61,7 +61,8 @@ <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 standalone REST interfaces that start up in milliseconds. + <li>A REST microservice API that combines all the features above for creating lightweight stand-alone REST + interfaces that start up in milliseconds. </ul> <a id='TOC'></a><h5 class='toc'>Table of Contents</h5> @@ -142,8 +143,10 @@ <li><p><a class='doclink' href='#Cookbook.Core'>Core API</a></p> <li><p><a class='doclink' href='#Cookbook.Server'>Server API</a></p> <ol> - <li><p><a class='doclink' href='#Cookbook.Server.applyDoubletransform'>Apply a transform that changes the format of doubles</a></p> - <li><p><a class='doclink' href='#Cookbook.Server.applyTransformsSubset'>Apply transforms to a subset of serializers or parsers</a></p> + <li><p><a class='doclink' href='#Cookbook.Server.applyDoubletransform'>Apply a transform that changes the + format of doubles</a></p> + <li><p><a class='doclink' href='#Cookbook.Server.applyTransformsSubset'>Apply transforms to a subset of + serializers or parsers</a></p> </ol> <li><p><a class='doclink' href='#Cookbook.Client'>Client API</a></p> <ol> @@ -163,7 +166,8 @@ <div class='topic'> <p> Juneau started off as a popular internal IBM toolkit called Juno. - Originally used for serializing POJOs to and from JSON, it later expanded in scope to include a variety of content types, and then later REST servlet, client, and microservice APIs. + Originally used for serializing POJOs to and from JSON, it later expanded in scope to include a variety of + content types, and then later REST servlet, client, and microservice APIs. It's use grew to more than 50 projects and was one of the most popular community source projects within IBM. </p> <p> @@ -172,7 +176,8 @@ <h5 class='toc'>Features</h5> <ol class='toc'> <li> - <p>Extensive and extensible support for a large variety of POJOs, including structured data (beans) and unstructured data (<code>Maps</code> and <code>Collections</code>).</p> + <p>Extensive and extensible support for a large variety of POJOs, including structured data (beans) and + unstructured data (<code>Maps</code> and <code>Collections</code>).</p> <li> <p>Serialization support:</p> <ul> @@ -241,25 +246,33 @@ 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> - 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> - 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> - REST client support. Requires Apache HttpClient 4.5+. + <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> + - 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> + - 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.<br> - <li><l>org.apache.juneau.rest.jar</l> - REST servlet support.<br> - <li><l>org.apache.juneau.rest.client.jar</l> - REST client support.<br> - <li><l>org.apache.juneau.microservice.jar</l> - Microservice support.<br> + <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 as executable jars. - <li><l>microservice-samples-project.zip</l> - Contains sample code demonstrating various aspects of Juneau.<br> + <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. </ul> @@ -275,13 +288,15 @@ <h2 class='topic' onclick='toggle(this)'>2 - Juneau Core (org.apache.juneau)</h2> <div class='topic'> <p> - The core packages of Juneau contains serializers and parsers for converting POJOs to and from a wide variety of content types. + The core packages of Juneau contains serializers and parsers for converting POJOs to and from a wide variety of + content types. It uses a common API for defining serializers and parsers. </p> <p> One of the goals of Juneau was to make serialization as simple as possible. In a single line of code, you should be able to serialize and parse most POJOs. - Despite this simplicity, Juneau provides lots of extensibility and configuration properties for tailoring how POJOs are serialized and parsed. + Despite this simplicity, Juneau provides lots of extensibility and configuration properties for tailoring how + POJOs are serialized and parsed. </p> <!-- ======================================================================================================== --> @@ -290,7 +305,8 @@ <div class='topic'> <p> The built-in serializers in Juneau are fast, efficient, and highly configurable. - They work by serializing POJOs directly to streams instead of using intermediate Document Object Model objects. + They work by serializing POJOs directly to streams instead of using intermediate Document Object Model + objects. </p> <p> In most cases, you can serialize objects in one line of code by using one of the default serializers: @@ -355,13 +371,18 @@ String json = serializer.serialize(someObject); </p> <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>, <code>Iterators</code> is available through the use of POJO swaps (described later). + 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>, + <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> - Serializer API Javadoc + <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> @@ -370,7 +391,8 @@ <h3 class='topic' onclick='toggle(this)'>2.2 - Parsers</h3> <div class='topic'> <p> - Parsers work by parsing input directly into POJOs instead of having to create intermediate Document Object Models. + Parsers work by parsing input directly into POJOs instead of having to create intermediate Document Object + Models. This allows them to parse input with minimal object creation. </p> <p> @@ -402,7 +424,8 @@ <jc>// Parse a JSON object as a HashMap<String,LinkedList<Person>>.</jc> json = <js>"{a:[{name:'John Smith',age:21},{name:'Joe Smith',age:42}]}"</js>; - Map<String,List<Person>> m5 = parser.parse(json, HashMap.<jk>class</jk>, String.<jk>class</jk>, LinkedList.<jk>class</jk>, Person.<jk>class</jk>) + Map<String,List<Person>> m5 = parser.parse(json, HashMap.<jk>class</jk>, String.<jk>class</jk>, + LinkedList.<jk>class</jk>, Person.<jk>class</jk>) <jc>// Parse a JSON array of integers as a Collection of Integers or int[] array.</jc> json = <js>"[1,2,3]"</js>; @@ -434,14 +457,19 @@ <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 fragements 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. + 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> - Parser API Javadoc + <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> @@ -450,8 +478,10 @@ <h3 class='topic' onclick='toggle(this)'>2.3 - SerializerGroups and ParserGroups</h3> <div class='topic'> <p> - Above the serializers and parsers are the {@link org.apache.juneau.serializer.SerializerGroup} and {@link org.apache.juneau.parser.ParserGroup} classes. - These classes allow serializers and parsers to be retrieved by W3C-compliant HTTP <code>Accept</code> and <code>Content-Type</code> values... + Above the serializers and parsers are the {@link org.apache.juneau.serializer.SerializerGroup} and + {@link org.apache.juneau.parser.ParserGroup} classes. + These classes allow serializers and parsers to be retrieved by W3C-compliant HTTP <code>Accept</code> + and <code>Content-Type</code> values... </p> <p class='bcode'> <jc>// Construct a new serializer group with configuration parameters that get applied to all serializers.</jc> @@ -490,9 +520,12 @@ <h3 class='topic' onclick='toggle(this)'>2.4 - ObjectMap and ObjectList</h3> <div class='topic'> <p> - The {@link org.apache.juneau.ObjectMap} and {@link org.apache.juneau.ObjectList} classes are generic Java representations of JSON objects and arrays. - These classes can be used to create "unstructured" models for serialization (as opposed to "structured" models consisting of beans). - If you want to quickly generate JSON/XML/HTML from generic maps/collections, or parse JSON/XML/HTML into generic maps/collections, these classes work well. + The {@link org.apache.juneau.ObjectMap} and {@link org.apache.juneau.ObjectList} classes are generic Java + representations of JSON objects and arrays. + These classes can be used to create "unstructured" models for serialization (as opposed to "structured" + models consisting of beans). + If you want to quickly generate JSON/XML/HTML from generic maps/collections, or parse JSON/XML/HTML into + generic maps/collections, these classes work well. </p> <p> These classes extend directly from the following JCF classes: @@ -508,20 +541,22 @@ </ul> </ul> <p> - The <l>ObjectMap</l> and <l>ObjectList</l> classes are very similar to the <l>JSONObject</l> and <l>JSONArray</l> - classes found in other libraries. However, the names were chosen - because the concepts of <l>Maps</l> and <l>Lists</l> are already familiar to - Java programmers, and these classes can be used with any of the serializers or parsers. + The <l>ObjectMap</l> and <l>ObjectList</l> classes are very similar to the <l>JSONObject</l> and + <l>JSONArray</l> classes found in other libraries. + However, the names were chosen because the concepts of <l>Maps</l> and <l>Lists</l> are already familiar to + Java programmers, and these classes can be used with any of the serializers or parsers. </p> <p> 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 {@link org.apache.juneau.ObjectList#serializeTo(java.io.Writer)} methods. + <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. </ol> <p> - Any valid JSON can be parsed into an unstructured model consisting of generic {@link org.apache.juneau.ObjectMap} and {@link org.apache.juneau.ObjectList} objects. + Any valid JSON can be parsed into an unstructured model consisting of generic + {@link org.apache.juneau.ObjectMap} and {@link org.apache.juneau.ObjectList} objects. </p> <p class='bcode'> <jc>// Parse an arbitrary JSON document into an unstructered data model @@ -541,8 +576,8 @@ </p> <ul class='doctree'> <li class='info'> - 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>. + 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'> @@ -556,14 +591,16 @@ <h3 class='topic' onclick='toggle(this)'>2.5 - Configurable Properties</h3> <div class='topic'> <p> - Serializers and parsers have a wide variety of configurable properties.<br> + Serializers and parsers have a wide variety of configurable properties. + <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> + 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: </p> <ul class='doctree'> @@ -652,21 +689,31 @@ These classes are: </p> <ul class='doctree'> - <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} - Tailor how specific bean classes are handled by the framework. + <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} + - 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} - Used to tailor how non-bean POJOs get interpreted by the framework. - <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} - Maps constructor arguments to property names on beans with read-only properties. - <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} - Used to tailor how bean properties get interpreted by the framework. - <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} - 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} - Used to identify a class or bean property as a URI. + <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} + - Used to tailor how beans get interpreted by the framework. + <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} + - Ignore classes, fields, and methods from being interpreted as bean or bean components. + <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} + - 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} + - 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} + - Used to identify a class or bean property as a URI. </ul> <!-- ======================================================================================================== --> @@ -679,14 +726,17 @@ </p> <p> Swaps are very easy to understand. - Simply put, they can be thought of as 'object swappers' that swap in serializable objects for non-serializable ones during serialization, and vis-versa during parsing. + Simply put, they can be thought of as 'object swappers' that swap in serializable objects for + non-serializable ones during serialization, and vis-versa during parsing. </p> <p> - Some examples of non-serializable POJOs are <code>File</code>, <code>Reader</code>, <code>Iterable</code>, etc... + Some examples of non-serializable POJOs are <code>File</code>, <code>Reader</code>, + <code>Iterable</code>, etc... These are classes that aren't beans and cannot be represented as simple maps, collections, or primitives. </p> <p> - In the following example, we introduce a <code>PojoSwap</code> that will swap in ISO8601 strings for <code>Date</code> objects: + In the following example, we introduce a <code>PojoSwap</code> that will swap in ISO8601 strings for + <code>Date</code> objects: </p> <p class='bcode'> <jc>// Sample swap for converting Dates to ISO8601 strings.</jc> @@ -734,7 +784,8 @@ 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> + <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} @@ -746,13 +797,15 @@ </ul> </ul> <p> - In particular, the {@link org.apache.juneau.transforms.CalendarSwap} and {@link org.apache.juneau.transforms.DateSwap} tramsforms - provide a large number of customized swaps to ISO, RFC, or localized strings. + In particular, the {@link org.apache.juneau.transforms.CalendarSwap} and + {@link org.apache.juneau.transforms.DateSwap} transforms provide a large number of customized swaps to + ISO, RFC, or localized strings. </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' href='#Core.PojoCategories'>POJO Categories</a>. + See the definition for Category 4 objects in <a class='doclink' + href='#Core.PojoCategories'>POJO Categories</a>. </ul> </div> @@ -765,11 +818,12 @@ This can often be simpler than using <code>PojoSwaps</code>. </p> <p> - Objects serialized as <code>Strings</code> can be parsed back into their original objects by implementing - one of the following methods on the class: + 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> + <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> @@ -781,32 +835,42 @@ <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 automatically construct these objects from strings: + Note that these methods cover conversion from several built-in Java types, meaning the parsers can + automatically construct these objects from strings: </p> <ul> <li><code>fromString(String)</code> - {@link java.util.UUID} - <li><code>valueOf(String)</code> - {@link java.lang.Boolean}, {@link java.lang.Byte}, {@link java.lang.Double}, {@link java.lang.Float}, - {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Short}, {@link java.sql.Date}, {@link java.sql.Time}, {@link java.sql.Timestamp} - <li><code>parse(String)</code> - {@link java.text.DateFormat}, {@link java.text.MessageFormat}, {@link java.text.NumberFormat}, {@link java.util.Date}, {@link java.util.logging.Level} + <li><code>valueOf(String)</code> - {@link java.lang.Boolean}, {@link java.lang.Byte}, + {@link java.lang.Double}, {@link java.lang.Float}, + {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Short}, {@link java.sql.Date}, + {@link java.sql.Time}, {@link java.sql.Timestamp} + <li><code>parse(String)</code> - {@link java.text.DateFormat}, {@link java.text.MessageFormat}, + {@link java.text.NumberFormat}, {@link java.util.Date}, {@link java.util.logging.Level} <li><code>parseString(String)</code> - {@link javax.xml.bind.DatatypeConverter} <li><code>forName(String)</code> - {@link java.lang.Class} </ul> <p> - If you want to force a bean-like class to be serialized as a string, you can use the {@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} - annotation on the class to force it to be serialized to a string using the <code>toString()</code> method. + If you want to force a bean-like class to be serialized as a string, you can use the + {@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} annotation on the class to force it to be + serialized to a string using the <code>toString()</code> method. </p> <p> - Serializing to other intermediate objects can be accomplished by defining a swap method directly on the class: + Serializing to other intermediate objects can be accomplished by defining a swap method directly on the + class: </p> <ul> - <li><code><jk>public</jk> X swap(BeanSession)</code> method, where <code>X</code> is any serializable object. + <li><code><jk>public</jk> X swap(BeanSession)</code> method, where <code>X</code> is any serializable + object. </ul> <p> - The <code>BeanSession</code> parameter allows you access to various information about the current serialization session. - For example, you could provide customized results based on the media type being produced ({@link org.apache.juneau.BeanSession#getMediaType()}). + The <code>BeanSession</code> parameter allows you access to various information about the current + serialization session. + For example, you could provide customized results based on the media type being produced + ({@link org.apache.juneau.BeanSession#getMediaType()}). </p> <p> - The following example shows how an HTML5 form template object can be created that gets serialized as a populated HTML5 {@link org.apache.juneau.dto.html5.Form} bean. + The following example shows how an HTML5 form template object can be created that gets serialized as a + populated HTML5 {@link org.apache.juneau.dto.html5.Form} bean. </p> <p class='bcode'> <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; @@ -837,14 +901,17 @@ } </p> <p> - Swapped objects can be converted back into their original form by the parsers by specifying one of the following methods: + Swapped objects can be converted back into their original form by the parsers by specifying one of the + following methods: </p> <ul> - <li><code><jk>public static</jk> T unswap(BeanSession, X)</code> method where <code>X</code> is the swap class type. + <li><code><jk>public static</jk> T unswap(BeanSession, X)</code> method where <code>X</code> is the + swap class type. <li><code><jk>public</jk> T(X)</code> constructor where <code>X</code> is the swap class type. </ul> <p> - The following shows how our form template class can be modified to allow the parsers to reconstruct our original object: + The following shows how our form template class can be modified to allow the parsers to reconstruct our + original object: </p> <p class='bcode'> <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; @@ -863,8 +930,10 @@ <jc>// Our 'unswap' constructor</jc> <jk>public</jk> FormTemplate(Form f) { <jk>this</jk>.<jf>action</jf> = f.getAttr(<js>"action"</js>); - <jk>this</jk>.<jf>value1</jf> = f.getChild(Input.<jk>class</jk>, 0).getAttr(<jk>int</jk>.<jk>class</jk>, <js>"value"</js>); - <jk>this</jk>.<jf>value2</jf> = f.getChild(Input.<jk>class</jk>, 1).getAttr(<jk>boolean</jk>.<jk>class</jk>, <js>"value"</js>); + <jk>this</jk>.<jf>value1</jf> = f.getChild(Input.<jk>class</jk>, 0) + .getAttr(<jk>int</jk>.<jk>class</jk>, <js>"value"</js>); + <jk>this</jk>.<jf>value2</jf> = f.getChild(Input.<jk>class</jk>, 1) + .getAttr(<jk>boolean</jk>.<jk>class</jk>, <js>"value"</js>); } <jk>public</jk> FormTemplate(String action, <jk>int</jk> value1, <jk>boolean</jk> value2) { @@ -887,7 +956,8 @@ <h4 class='topic' onclick='toggle(this)'>2.6.3 - BeanFilters and @Bean annotations</h4> <div class='topic'> <p> - {@link org.apache.juneau.transform.BeanFilter BeanFilters} are used to control aspects of how beans are handled during serialization and parsing. + {@link org.apache.juneau.transform.BeanFilter BeanFilters} are used to control aspects of how beans are + handled during serialization and parsing. They allow you to control various aspects of beans, such as... </p> <ul> @@ -897,8 +967,8 @@ <li>Overriding reading and writing of properties. </ul> <p> - In practice, however, it's simpler to use the {@link org.apache.juneau.annotation.Bean @Bean} and {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} - annotations on your bean classes. + In practice, however, it's simpler to use the {@link org.apache.juneau.annotation.Bean @Bean} and + {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotations on your bean classes. The annotations are functionally equivalent to the bean filter class. </p> <p class='bcode'> @@ -938,7 +1008,8 @@ The <code>addBeanFilter(Class...)</code> method also allows you to pass in interfaces. Any class that's not a subclass of {@link org.apache.juneau.transform.BeanFilterBuilder} get interpreted as bean interface classes. - These cause bean implementations of those interfaces to only expose the properties defined on the interface. + These cause bean implementations of those interfaces to only expose the properties defined on the + interface. </p> <p class='bcode'> <jc>// An interface with the 3 properties we want serialized.</jc> @@ -959,7 +1030,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> @@ -970,22 +1042,28 @@ <h3 class='topic' onclick='toggle(this)'>2.7 - Bean Names and Dictionaries</h3> <div class='topic'> <p> - While parsing into beans, Juneau attempts to determine the class types of bean properties through reflection on the bean property getter or setter. - Often this is insufficient if the property type is an interface or abstract class that cannot be instantiated. + While parsing into beans, Juneau attempts to determine the class types of bean properties through + reflection on the bean property getter or setter. + Often this is insufficient if the property type is an interface or abstract class that cannot be + instantiated. This is where bean names and dictionaries come into play. </p> <p> - Bean names and dictionary are used for identifying class types when they cannot be inferred through reflection. + Bean names and dictionary are used for identifying class types when they cannot be inferred through + reflection. </p> <p> - Bean classes are given names through the {@link org.apache.juneau.annotation.Bean#typeName() @Bean.typeName()} annotation. - These names are then added to the serialized output as virtual <js>"_type"</js> properties (or element names in XML). + Bean classes are given names through the {@link org.apache.juneau.annotation.Bean#typeName() @Bean.typeName()} + annotation. + These names are then added to the serialized output as virtual <js>"_type"</js> properties (or element + names in XML). </p> <p> On the parsing side, these type names are resolved to classes through the use of bean dictionaries. </p> <p> - For example, if a bean property is of type <code>Object</code>, then the serializer will add <js>"_type"</js> attributes so that the class can be determined during parsing. + For example, if a bean property is of type <code>Object</code>, then the serializer will add + <js>"_type"</js> attributes so that the class can be determined during parsing. </p> <p class='bcode'> <ja>@Bean</ja>(typeName=<js>"foo"</js>) @@ -1002,7 +1080,8 @@ <jk>public class</jk> Baz {} </p> <p> - When serialized as JSON, <js>"_type"</js> attributes would be added when needed to infer the type during parsing: + When serialized as JSON, <js>"_type"</js> attributes would be added when needed to infer the type during + parsing: </p> <p class='bcode'> { @@ -1015,7 +1094,8 @@ <p> Type names can be represented slightly differently in different languages. For example, the dictionary name is used as element names when serialized to XML. - This allows the <code>typeName</code> annotation to be used as a shortcut for defining element names for beans. + This allows the <code>typeName</code> annotation to be used as a shortcut for defining element names for + beans. </p> <p> When serialized as XML, the bean is rendered as: @@ -1032,20 +1112,27 @@ Bean dictionaries are defined at two levels: </p> <ul> - <li>On individual bean properties through the {@link org.apache.juneau.annotation.BeanProperty#beanDictionary() @BeanProperty.beanDictionary()} annotation. - <li>Globally for a parser using the {@link org.apache.juneau.parser.ParserBuilder#beanDictionary(Class...)} method. + <li>On individual bean properties through the + {@link org.apache.juneau.annotation.BeanProperty#beanDictionary() @BeanProperty.beanDictionary()} + annotation. + <li>Globally for a parser using the {@link org.apache.juneau.parser.ParserBuilder#beanDictionary(Class...)} + method. </ul> <ul class='doctree'> <li class='info'> Type names do not need to be universally unique. However, they must be unique within a dictionary. <li class='info'> - The following reserved words cannot be used as type names: <code>object, array, number, boolean, null</code>. + The following reserved words cannot be used as type names: + <code>object, array, number, boolean, null</code>. <li class='info'> Serialized type names are DISABLED by default. - They must be enabled on the serializer using the {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_addBeanTypeProperties} configuration property. + They must be enabled on the serializer using the + {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_addBeanTypeProperties} + configuration property. <li class='info'> - The <js>"_type"</js> property name can be overridden using the {@link org.apache.juneau.BeanContext#BEAN_beanTypePropertyName} configuration property. + The <js>"_type"</js> property name can be overridden using the + {@link org.apache.juneau.BeanContext#BEAN_beanTypePropertyName} configuration property. </ul> <!-- ======================================================================================================== --> @@ -1236,7 +1323,8 @@ <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> + 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> @@ -1247,8 +1335,8 @@ <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> + 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> @@ -1271,10 +1359,13 @@ <td style='text-align:center'>4</td> <td> <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. - For example, the {@link org.apache.juneau.transforms.DateSwap.ISO8601DT} class can be used to serialize {@link java.util.Date} objects - to ISO8601 strings, and parse them back into {@link java.util.Date} objects. + 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. + For example, the {@link org.apache.juneau.transforms.DateSwap.ISO8601DT} class can be used to + serialize {@link java.util.Date} objects to ISO8601 strings, and parse them back into + {@link java.util.Date} objects. </td> <td> </td> <td> </td> @@ -1324,7 +1415,8 @@ <td> Classes with a method that converts it to a serializable form: <ul> - <li><code><jk>public</jk> X swap(BeanSession);</code> where <code>X</code> is in groups [1, 2a, 3ac]. + <li><code><jk>public</jk> X swap(BeanSession);</code> where <code>X</code> is in groups + [1, 2a, 3ac]. <li><code><jk>public</jk> String toString();</code> where the string is any meaningful data. </ul> And a method that converts it back into the original object: @@ -1336,7 +1428,8 @@ <li><code><jk>public static</jk> T forName(String);</code> <li><code><jk>public static</jk> T forString(String);</code> <li><code><jk>public</jk> T(X);</code> where <code>X</code> is in groups [1, 2a, 3ac]. - <li><code><jk>public static</jk> T unswap(BeanSession,X);</code> where <code>X</code> is in groups [1, 2a, 3ac]. + <li><code><jk>public static</jk> T unswap(BeanSession,X);</code> where <code>X</code> is in + groups [1, 2a, 3ac]. </ul> </td> <td> @@ -1360,7 +1453,8 @@ <td> Classes that only have a method to convert to a serializable form: <ul> - <li><code><jk>public</jk> X swap(BeanSession);</code> where <code>X</code> is in groups [1, 2, 3]. + <li><code><jk>public</jk> X swap(BeanSession);</code> where <code>X</code> is in groups + [1, 2, 3]. <li><code><jk>public</jk> String toString();</code> where the string is any meaningful data. </ul> </td> @@ -1371,8 +1465,10 @@ <tr class='dark' style='background-color:lightyellow'> <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} using the {@code toString()} method. + <b>All other objects</b> + <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> <td style='background-color:lightgreen;text-align:center'><b>yes</b></td> @@ -1382,9 +1478,11 @@ <ul class='doctree'> <li class='info'> Serializers are designed to work on tree-shaped POJO models. - These are models where there are no referential loops (e.g. leaves with references to nodes, or nodes in one branch referencing nodes in another branch). - There is a serializer setting {@code detectRecursions} to look for and handle these kinds of loops (by setting these references to <jk>null</jk>), - but it is not enabled by default since it introduces a moderate performance penalty. + These are models where there are no referential loops (e.g. leaves with references to nodes, or nodes + in one branch referencing nodes in another branch). + There is a serializer setting {@code detectRecursions} to look for and handle these kinds of loops + (by setting these references to <jk>null</jk>), but it is not enabled by default since it introduces + a moderate performance penalty. </ul> </div> @@ -1393,8 +1491,10 @@ <h4 class='topic' onclick='toggle(this)'>2.10 - Simple Variable Language</h4> <div class='topic'> <p> - The <a class='doclink' href='org/apache/juneau/svl/package-summary.html#TOC'>org.apache.juneau.svl</a> package defines an API for a language called "Simple Variable Language". - In a nutshell, Simple Variable Language (or SVL) is text that contains variables of the form <js>"$varName{varKey}"</js>. + The <a class='doclink' href='org/apache/juneau/svl/package-summary.html#TOC'>org.apache.juneau.svl</a> + package defines an API for a language called "Simple Variable Language". + In a nutshell, Simple Variable Language (or SVL) is text that contains variables of the form + <js>"$varName{varKey}"</js>. </p> <p> Variables can be recursively nested within the varKey (e.g. <js>"$FOO{$BAR{xxx},$BAZ{xxx}}"</js>). @@ -1420,7 +1520,9 @@ </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> - Simple Variable Language Javadocs. + <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> @@ -1429,7 +1531,9 @@ <h3 class='topic' onclick='toggle(this)'>2.11 - Configuration Files</h3> <div class='topic'> <p> - The <a class='doclink' href='org/apache/juneau/ini/package-summary.html#TOC'>org.apache.juneau.ini</a> package contains a powerful API for creating and using INI-style config files. + The <a class='doclink' + href='org/apache/juneau/ini/package-summary.html#TOC'>org.apache.juneau.ini</a> package contains a powerful + API for creating and using INI-style config files. </p> <p> An example of an INI file: @@ -1495,7 +1599,8 @@ .save(); </p> <p> - The following is equivalent, except that it uses {@link org.apache.juneau.ini.ConfigFile#put(String, Object)} to set values: + The following is equivalent, except that it uses {@link org.apache.juneau.ini.ConfigFile#put(String, Object)} + to set values: </p> <p class='bcode'> <jc>// Construct the sample INI file programmatically</jc> @@ -1515,14 +1620,18 @@ cf.save(); </p> <p> - Values are LAX JSON (i.e. unquoted attributes, single quotes) except for top-level strings which are left unquoted. - Any parsable object types are supported as values (e.g. arrays, collections, beans, swappable objects, enums, etc...). + Values are LAX JSON (i.e. unquoted attributes, single quotes) except for top-level strings which are left + unquoted. + Any parsable object types are supported as values (e.g. arrays, collections, beans, swappable objects, + enums, etc...). </p> <p> - The config file looks deceptively simple, the config file API is a very powerful feature with many capabilities, including: + The config file looks deceptively simple, the config file API is a very powerful feature with many + capabilities, including: </p> <ul class='spaced-list'> - <li>The ability to use variables to reference environment variables, system properties, other config file entries, and a host of other types. + <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. </ul> @@ -1590,7 +1699,8 @@ String firstArg = cf.getString(<js>"MySection/firstArg"</js>); </p> <p> - Config files can also be used to directly populate beans using the {@link org.apache.juneau.ini.ConfigFile#getSectionAsBean(String,Class,boolean)}: + Config files can also be used to directly populate beans using the + {@link org.apache.juneau.ini.ConfigFile#getSectionAsBean(String,Class,boolean)}: </p> <p class='bcode'> <jc>// Example config file</jc> @@ -1613,7 +1723,8 @@ Address myAddress = cf.getSectionAsBean(<js>"MySection"</js>, Address.<jk>class</jk>); </p> <p> - Config file sections can also be accessed via interface proxies using {@link org.apache.juneau.ini.ConfigFile#getSectionAsInterface(String,Class)}: + Config file sections can also be accessed via interface proxies using + {@link org.apache.juneau.ini.ConfigFile#getSectionAsInterface(String,Class)}: </p> <p class='bcode'> <jc>// Example config file</jc> @@ -1656,7 +1767,8 @@ </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> @@ -1690,7 +1802,7 @@ <div class='topic'> <p> Juneau was developed independently from Jackson, but shares many of the same features and capabilities. - Whereas Jackson was created to work primariliy with JSON, Juneau was created to work for multiple languages. + Whereas Jackson was created to work primarily with JSON, Juneau was created to work for multiple languages. Therefore, the terminology and annotations in Juneau are similar, but language-agnostic. </p> <p> @@ -1726,9 +1838,12 @@ <tr> <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> + 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. </td> </tr> @@ -1741,7 +1856,8 @@ <tr> <td><ja>@JacksonInject</ja></td> <td> - No equivalent.<br> + No equivalent. + <br> Future support planned. </td> @@ -1749,31 +1865,39 @@ <tr> <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> + 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=...)} </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> + 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. </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> + {@link org.apache.juneau.annotation.Bean#properties @Bean(properties="...")} + <br> + {@link org.apache.juneau.annotation.Bean#sort @Bean(sort=x)} + <br> </td> </tr> <tr> <td><ja>@JsonValue</ja><br><ja>@JsonRawValue</ja></td> <td> - No equivalents.<br> + No equivalents. + <br> Future support unlikely since these are JSON-centric. </td> </tr> @@ -1796,8 +1920,8 @@ <div class='topic'> <p> The Juneau HTML5 DTOs are simply beans with fluent-style setters that allow you to quickly construct HTML - fragments as Java objects. These object can then be serialized to HTML using one of the existing HTML serializers, - or to other languages such as JSON using the JSON serializers. + fragments as Java objects. These object can then be serialized to HTML using one of the existing HTML + serializers, or to other languages such as JSON using the JSON serializers. </p> <p> The {@link org.apache.juneau.dto.html5.HtmlBuilder} class is a utility class with predefined static methods @@ -1877,8 +2001,10 @@ </td> <td class='code'><xt> <form <xa>action</xa>=<xs>'/submit'</xs> <xa>method</xa>=<xs>'POST'</xs>> - <xv>Position (1-10000):</xv> <input <xa>name</xa>=<xs>'pos'</xs> <xa>type</xa>=<xs>'number'</xs> <xa>value</xa>=<xs>'1'</xs>/><br/> - <xv>Limit (1-10000):</xv> <input <xa>name</xa>=<xs>'pos'</xs> <xa>type</xa>=<xs>'number'</xs> <xa>value</xa>=<xs>'100'</xs>/><br/> + <xv>Position (1-10000):</xv> <input <xa>name</xa>=<xs>'pos'</xs> <xa>type</xa>=<xs>'number'</xs> + <xa>value</xa>=<xs>'1'</xs>/><br/> + <xv>Limit (1-10000):</xv> <input <xa>name</xa>=<xs>'pos'</xs> <xa>type</xa>=<xs>'number'</xs> + <xa>value</xa>=<xs>'100'</xs>/><br/> <button <xa>type</xa>=<xs>'submit'</xs>><xv>Submit</xv></button> <button <xa>type</xa>=<xs>'reset'</xs>><xv>Reset</xv></button> </form> @@ -1887,7 +2013,7 @@ </table> <p> Using the HTML5 DTOs, you should be able to construct any valid HTML5 from full document bodies - to any possible fragements. + to any possible fragments. </p> <p> The {@link org.apache.juneau.html.HtmlParser} class can be used convert these HTML documents back @@ -1900,7 +2026,8 @@ <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> @@ -1909,8 +2036,10 @@ <h3 class='topic' onclick='toggle(this)'>3.2 - Atom</h3> <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 {@link org.apache.juneau.dto.atom.AtomBuilder} class. + The Juneau ATOM feed DTOs are simply beans with fluent-style setters. + <br> + The following code shows a feed being created programmatically using the + {@link org.apache.juneau.dto.atom.AtomBuilder} class. </p> <p class='bcode'> @@ -1967,8 +2096,10 @@ <xt><id></xt> tag:juneau.apache.org <xt></id></xt> - <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/'</xs> <xa>rel</xa>=<xs>'alternate'</xs> <xa>type</xa>=<xs>'text/html'</xs> <xa>hreflang</xa>=<xs>'en'</xs>/<xt>></xt> - <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/feed.atom'</xs> <xa>rel</xa>=<xs>'self'</xs> <xa>type</xa>=<xs>'application/atom+xml'</xs>/<xt>></xt> + <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/'</xs> <xa>rel</xa>=<xs>'alternate'</xs> + <xa>type</xa>=<xs>'text/html'</xs> <xa>hreflang</xa>=<xs>'en'</xs>/<xt>></xt> + <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/feed.atom'</xs> <xa>rel</xa>=<xs>'self'</xs> + <xa>type</xa>=<xs>'application/atom+xml'</xs>/<xt>></xt> <xt><rights></xt> Copyright (c) 2016, Apache Foundation <xt></rights></xt> @@ -1994,22 +2125,25 @@ <xt><id></xt> tag:juneau.apache.org <xt></id></xt> - <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/juneau.atom'</xs> <xa>rel</xa>=<xs>'alternate'</xs> <xa>type</xa>=<xs>'text/html'</xs>/<xt>></xt> - <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/audio/juneau_podcast.mp3'</xs> <xa>rel</xa>=<xs>'enclosure'</xs> <xa>type</xa>=<xs>'audio/mpeg'</xs> <xa>length</xa>=<xs>'12345'</xs>/<xt>></xt> + <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/juneau.atom'</xs> + <xa>rel</xa>=<xs>'alternate'</xs> <xa>type</xa>=<xs>'text/html'</xs>/<xt>></xt> + <xt><link</xt> <xa>href</xa>=<xs>'http://juneau.apache.org/audio/juneau_podcast.mp3'</xs> + <xa>rel</xa>=<xs>'enclosure'</xs> <xa>type</xa>=<xs>'audio/mpeg'</xs> <xa>length</xa>=<xs>'12345'</xs>/<xt>></xt> <xt><title></xt> Juneau ATOM specification snapshot <xt></title></xt> <xt><updated></xt>2016-01-02T03:04:05Z<xt></updated></xt> - <xt><content</xt> <xa>base</xa>=<xs>'http://www.apache.org/'</xs> <xa>lang</xa>=<xs>'en'</xs> <xa>type</xa>=<xs>'xhtml'</xs><xt>></xt> - <xt><div</xt> <xa>xmlns</xa>=<xs>"http://www.w3.org/1999/xhtml";</xs><xt>><p><i></xt>[Update: Juneau supports ATOM.]<xt></i></p></div></xt> + <xt><content</xt> <xa>base</xa>=<xs>'http://www.apache.org/'</xs> <xa>lang</xa>=<xs>'en'</xs> + <xa>type</xa>=<xs>'xhtml'</xs><xt>></xt> + <xt><div</xt> <xa>xmlns</xa>=<xs>"http://www.w3.org/1999/xhtml";</xs> + <xt>><p><i></xt>[Update: Juneau supports ATOM.]<xt></i></p></div></xt> <xt></content></xt> <xt><published></xt>2016-01-02T03:04:05Z<xt></published></xt> <xt></entry></xt> <xt></feed></xt> </p> <p> - The {@link org.apache.juneau.xml.XmlParser} class can be used convert these Atom documents back - into POJOs. + The {@link org.apache.juneau.xml.XmlParser} class can be used convert these Atom documents back into POJOs. </p> <p> Other serializers and parsers (e.g. {@link org.apache.juneau.json.JsonSerializer}) can be used to @@ -2018,7 +2152,8 @@ <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> @@ -2027,16 +2162,18 @@ <h3 class='topic' onclick='toggle(this)'>3.3 - Swagger</h3> <div class='topic'> <p> - The Juneau Swagger DTOs are simply beans with fluent-style setters that allow you to quickly construct Swagger - documents as Java objects. These object can then be serialized to JSON using one of the existing JSON serializers, - or to other languages such as XML or HTML using the other serializers. + The Juneau Swagger DTOs are simply beans with fluent-style setters that allow you to quickly construct + Swagger documents as Java objects. + These object can then be serialized to JSON using one of the existing JSON serializers, or to other + languages such as XML or HTML using the other serializers. </p> <p> - The {@link org.apache.juneau.dto.swagger.SwaggerBuilder} class is a utility class with predefined static methods - that allow you to easily construct DTO instances in a minimal amount of code. + The {@link org.apache.juneau.dto.swagger.SwaggerBuilder} class is a utility class with predefined static + methods that allow you to easily construct DTO instances in a minimal amount of code. </p> <p> - The following is an example Swagger document from the <a href="http://petstore.swagger.io/";>Swagger website</a>. + The following is an example Swagger document from the + <a href="http://petstore.swagger.io/";>Swagger website</a>. </p> <p class='bcode'> { @@ -2175,11 +2312,12 @@ The Juneau REST Server API provides servlet-based REST resources on top of existing POJOs. </p> <p> - The API automatically detects <l>Accept</l> header of requests and converts POJOs to any of the supported languages. + The API automatically detects <l>Accept</l> header of requests and converts POJOs to any of the supported + languages. The toolkit is extensible and also allows for support of user-defined content types. </p> <p> - Automatic built-in support is provided for negotiation of response charsets and gzip encoding. + Automatic built-in support is provided for negotiation of response character sets and gzip encoding. </p> <p> The following is an example of a REST API used to view and set JVM system properties. @@ -2218,7 +2356,8 @@ license=<js>"{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>, version=<js>"2.0"</js>, termsOfService=<js>"You're on your own."</js>, - tags=<js>"[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]"</js>, + tags=<js>"[{name:'Java',description:'Java utility', + externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]"</js>, externalDocs=<js>"{description:'Home page',url:'http://juneau.apache.org'}"</js> ) ) @@ -2229,13 +2368,15 @@ summary=<js>"Show all system properties"</js>, description=<js>"Returns all system properties defined in the JVM."</js>, parameters={ - <ja>@Parameter</ja>(in=<js>"query"</js>, name=<js>"sort"</js>, description=<js>"Sort results alphabetically."</js>, _default=<js>"false"</js>) + <ja>@Parameter</ja>(in=<js>"query"</js>, name=<js>"sort"</js>, + description=<js>"Sort results alphabetically."</js>, _default=<js>"false"</js>) }, responses={ <ja>@Response</ja>(value=200, description=<js>"Returns a map of key/value pairs."</js>) } ) - <jk>public</jk> Map getSystemProperties(<ja>@Query</ja>(<js>"sort"</js>) <jk>boolean</jk> sort) <jk>throws</jk> Throwable { + <jk>public</jk> Map getSystemProperties(<ja>@Query</ja>(<js>"sort"</js>) <jk>boolean</jk> sort) + <jk>throws</jk> Throwable { <jk>if</jk> (sort) <jk>return new</jk> TreeMap(System.<jsm>getProperties</jsm>()); <jk>return</jk> System.<jsm>getProperties</jsm>(); @@ -2246,7 +2387,8 @@ summary=<js>"Get system property"</js>, description=<js>"Returns the value of the specified system property."</js>, parameters={ - <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, description=<js>"The system property name."</js>) + <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, + description=<js>"The system property name."</js>) }, responses={ <ja>@Response</ja>(value=200, description=<js>"The system property value, or null if not found."</js>) @@ -2262,13 +2404,15 @@ description=<js>"Sets a new value for the specified system property."</js>, guards=AdminGuard.<jk>class</jk>, parameters={ - <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, description=<js>"The system property name."</js>), + <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, + description=<js>"The system property name."</js>), <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"The new system property value."</js>), }, responses={ <ja>@Response</ja>(value=302, headers={ - <ja>@Parameter</ja>(name=<js>"Location"</js>, description=<js>"The root URL of this resource."</js>) + <ja>@Parameter</ja>(name=<js>"Location"</js>, + description=<js>"The root URL of this resource."</js>) } ), <ja>@Response</ja>(value=403, description=<js>"User is not an admin."</js>) @@ -2285,13 +2429,16 @@ description=<js>"Takes in a map of key/value pairs and creates a set of new system properties."</js>, guards=AdminGuard.<jk>class</jk>, parameters={ - <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, description=<js>"The system property key."</js>), - <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"The new system property values.", schema="{example:{key1:'val1',key2:123}}"</js>), + <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, + description=<js>"The system property key."</js>), + <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"The new system property values.", + schema="{example:{key1:'val1',key2:123}}"</js>), }, responses={ <ja>@Response</ja>(value=302, headers={ - <ja>@Parameter</ja>(name=<js>"Location"</js>, description=<js>"The root URL of this resource."</js>) + <ja>@Parameter</ja>(name=<js>"Location"</js>, + description=<js>"The root URL of this resource."</js>) } ), <ja>@Response</ja>(value=403, description=<js>"Unauthorized: User is not an admin."</js>) @@ -2308,12 +2455,14 @@ description=<js>"Deletes the specified system property."</js>, guards=AdminGuard.<jk>class</jk>, parameters={ - <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, description=<js>"The system property name."</js>), + <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"propertyName"</js>, + description=<js>"The system property name."</js>), }, responses={ <ja>@Response</ja>(value=302, headers={ - <ja>@Parameter</ja>(name=<js>"Location"</js>, description=<js>"The root URL of this resource."</js>) + <ja>@Parameter</ja>(name=<js>"Location"</js>, + description=<js>"The root URL of this resource."</js>) } ), <ja>@Response</ja>(value=403, description=<js>"Unauthorized: User is not an admin"</js>) @@ -2351,21 +2500,26 @@ <xt></web-app></xt> </p> <p> - Pointing your browser to the resource renders the POJOs as HTML (since that's what the browser specifies in the <code>Accept</code> header). + Pointing your browser to the resource renders the POJOs as HTML (since that's what the browser specifies in the + <code>Accept</code> header). </p> <img class='bordered' src="doc-files/Server.SystemPropertiesResource.png"> <p> One of the most useful aspects of using this API is the self-discovering, self-documenting OPTIONS pages. - These are constructed automatically using reflection, augmented with information pulled from annotations (as shown above), resource bundles, or Swagger JSON files: + These are constructed automatically using reflection, augmented with information pulled from annotations + (as shown above), resource bundles, or Swagger JSON files: </p> <img class='bordered' src="doc-files/Server.Options.png"> <p> - Arbitrarily complex POJO models can be serialized using any of the supported serializers, and content can be parsed using any of the supported parsers. + Arbitrarily complex POJO models can be serialized using any of the supported serializers, and content can be + parsed using any of the supported parsers. </p> <p> - The <l>juneau-examples-rest</l> project contains various REST resource examples in an easy-to-use REST microservice. - One of these is <l>AddressBookResource</l> which serializes <l>AddressBook</l> objects defined below (some code omitted): + The <l>juneau-examples-rest</l> project contains various REST resource examples in an easy-to-use REST + microservice. + One of these is <l>AddressBookResource</l> which serializes <l>AddressBook</l> objects defined below + (some code omitted): </p> <p class='bcode'> <jd>/** package-info.java */</jd> @@ -2412,13 +2566,14 @@ } </p> <p> - 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. + 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. - <h6 class='figure'>HTML/french</h6> + <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"> @@ -2445,7 +2600,9 @@ </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> - Juneau Server API Javadocs. + <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> @@ -2454,12 +2611,12 @@ <h2 class='topic' onclick='toggle(this)'>5 - Juneau Client (org.apache.juneau.rest.client)</h2> <div class='topic'> <p> - The REST client API provides the ability to access remote REST interfaces and transparently convert the input and output to and from POJOs using any - of the provided serializers and parsers. + The REST client API provides the ability to access remote REST interfaces and transparently convert the input + and output to and from POJOs using any of the provided serializers and parsers. </p> <p> - Built upon the Apache HttpClient libraries, it extends that API and provides specialized APIs for working with REST interfaces while - maintaining all the functionality available in the HttpClient API. + Built upon the Apache HttpClient libraries, it extends that API and provides specialized APIs for working with + REST interfaces while maintaining all the functionality available in the HttpClient API. </p> <p class='bcode'> <jc>// Create a reusable JSON client.</jc> @@ -2488,7 +2645,9 @@ </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> - Juneau Client API Javadocs. + <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> @@ -2502,7 +2661,8 @@ define and use, and allowing much more flexibility in the types of objects serialized. </p> <p> - The remote proxy interface API allows you to invoke server-side POJO methods on the client side using REST as the communications protocol: + The remote proxy interface API allows you to invoke server-side POJO methods on the client side using REST as + the communications protocol: </p> <p class='bcode'> @@ -2550,8 +2710,8 @@ The object returned by the method is then serialized as the body of the response. </p> <p> - To define a remoteable interface, simply add the {@link org.apache.juneau.remoteable.Remoteable @Remoteable} annotation - to your interface class. + To define a remoteable interface, simply add the {@link org.apache.juneau.remoteable.Remoteable @Remoteable} + annotation to your interface class. </p> <p class='bcode'> <ja>@Remoteable</ja> @@ -2559,11 +2719,12 @@ </p> <p> This annotation tells the framework that all methods defined on this interface can be executed remotely. - It can be applied to super-interfaces, super-classes, etc..., and exposes the methods at whatever level it is defined. + It can be applied to super-interfaces, super-classes, etc..., and exposes the methods at whatever level it is + defined. </p> <p> - The {@link org.apache.juneau.remoteable.RemoteMethod @RemoteMethod} annotation can also be used on individual methods - to tailor which methods are exposed or their paths. + The {@link org.apache.juneau.remoteable.RemoteMethod @RemoteMethod} annotation can also be used on individual + methods to tailor which methods are exposed or their paths. </p> <p> There are two ways to expose remoteable proxies on the server side: @@ -2573,8 +2734,8 @@ <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 <code>getServiceMap()</code> - method to define the server-side POJOs: + The <code>RemoteableServlet</code> class is a simple specialized servlet with an abstract + <code>getServiceMap()</code> method to define the server-side POJOs: </p> <p class='bcode'> <ja>@RestResource</ja>( @@ -2599,8 +2760,10 @@ } </p> <p> - The <code><ja>@RestMethod</ja>(name=<js>"PROXY"</js>)</code> approach is easier if you only have a single interface you want to expose. - You simply define a Java method whose return type is an interface, and return the implementation of that interface: + The <code><ja>@RestMethod</ja>(name=<js>"PROXY"</js>)</code> approach is easier if you only have a single + interface you want to expose. + You simply define a Java method whose return type is an interface, and return the implementation of that + interface: </p> <p class='bcode'> <jc>// Our exposed proxy object.</jc> @@ -2611,20 +2774,30 @@ </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 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 a browser with no coding involved. + <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 + 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 out-of-the-box. - <br>Most of the time you don't even need to modify your existing Java implementation code. + 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 + out-of-the-box. + <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 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. + 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 + 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. </p> <p> The requirements for a method to be callable through a remoteable service are: @@ -2633,12 +2806,14 @@ <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 be automatically - recreated on the client side. + <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> - Juneau Remoteable API Javadocs. + <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> <!-- ======================================================================================================== --> @@ -2647,11 +2822,13 @@ <div class='topic'> <p> Remoteable proxies can also be used to define interface proxies against 3rd-party REST interfaces. - This is an extremely powerful feature that allows you to quickly define easy-to-use interfaces against virtually any REST interface. + This is an extremely powerful feature that allows you to quickly define easy-to-use interfaces against + virtually any REST interface. </p> <p> Similar in concept to remoteable services defined above, but in this case we simply define our interface with - special annotations that tell us how to convert input and output to HTTP headers, query paramters, form post parameters, or request/response bodies. + special annotations that tell us how to convert input and output to HTTP headers, query parameters, form + post parameters, or request/response bodies. </p> <p class='bcode'> <ja>@Remoteable</ja> @@ -2666,62 +2843,99 @@ String response = p.doMethod(UUID.<jsm>generate</jsm>(), <jk>true</jk>, <jk>new</jk> MyPojo()); </p> <p> - The Java method arguements can be annotated with any of the following: + 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. <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)}. - <li><code>String</code> - Treated as a query string. - </ul> - <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} - 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: - <ul> - <li>Any serializable POJO - Converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. - <li>{@link org.apache.juneau.rest.client.NameValuePairs} - 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)}. + <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)}. + <li><code>String</code> + - Treated as a query string. + </ul> + <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} + - 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: + <ul> + <li>Any serializable POJO + - Converted to text using {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#serializePart(Object, Boolean, Boolean)}. + <li>{@link org.apache.juneau.rest.client.NameValuePairs} + - 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)}. </ul> - <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} - A request header. - <br>The argument can be any of the following types: + <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} + - A request header. + <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)}. + <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)}. </ul> - <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} - The HTTP request body. + <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} + - The HTTP request body. <br>The argument can be any of the following types: <ul> - <li>Any serializable POJO - Converted to text/bytes using the {@link org.apache.juneau.serializer.Serializer} registered with the <code>RestClient</code>. - <li>{@link java.io.Reader} - Raw contents of reader will be serialized to remote resource. - <li>{@link java.io.InputStream} - Raw contents of input stream will be serialized to remote resource. - <li>{@link org.apache.http.HttpEntity} - Bypass Juneau serialization and pass HttpEntity directly to HttpClient. - <li>{@link org.apache.juneau.rest.client.NameValuePairs} - Converted to a URL-encoded FORM post. + <li>Any serializable POJO + - Converted to text/bytes using the {@link org.apache.juneau.serializer.Serializer} registered + with the <code>RestClient</code>. + <li>{@link java.io.Reader} + - Raw contents of reader will be serialized to remote resource. + <li>{@link java.io.InputStream} + - Raw contents of input stream will be serialized to remote resource. + <li>{@link org.apache.http.HttpEntity} + - Bypass Juneau serialization and pass HttpEntity directly to HttpClient. + <li>{@link org.apache.juneau.rest.client.NameValuePairs} + - Converted to a URL-encoded FORM post. </ul> </ul> <p> The return type of the Java method can be any of the following: </p> <ul class='spaced-list'> - <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 - The body of the response will be converted to the POJO using the parser defined on the <code>RestClient</code>. - <li><code>HttpResponse</code> - Returns the raw <code>HttpResponse</code> returned by the inner <code>HttpClient</code>. - <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 directly. - <li>{@link java.io.InputStream} - Returns access to the raw input stream of the response. + <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 + - The body of the response will be converted to the POJO using the parser defined on the + <code>RestClient</code>. + <li><code>HttpResponse</code> + - Returns the raw <code>HttpResponse</code> returned by the inner <code>HttpClient</code>. + <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 + directly. + <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> - Juneau Remoteable API Javadocs. + <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> </div> @@ -2734,15 +2948,16 @@ <b>WARNING - The microservice API is still in beta. It may be replaced with an OSGi-based architecture.</b> </p> <p> - The <l>microservice-project.zip</l> file contains a standalone Eclipse project that can be used - to quickly create REST microservices as standalone executable jars without the need of an application server. + The <l>microservice-project.zip</l> file contains a stand-alone Eclipse project that can be used + to quickly create REST microservices as stand-alone executable jars without the need of an application server. They start almost instantly and are started through a simple java command: </p> <p> <code class='snippet'>java -jar microservice.jar</code> </p> <p> - When you execute this command, you can point your browser to <l>http://localhost:10000</l> to bring up the REST interface: + When you execute this command, you can point your browser to <l>http://localhost:10000</l> to bring up the + REST interface: </p> <img class='bordered' src="doc-files/Microservices.1.png"> <p> @@ -2751,7 +2966,9 @@ </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> - Juneau Microservice API Javadocs. + <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> @@ -2761,11 +2978,11 @@ <div class='topic'> <p> The <l>microservice-samples-project.zip</l> file is a zipped eclipse project that includes everything you - need to start the Samples REST microservice in an Eclipse workspace. + need to start the Samples REST microservice in an Eclipse workspace. </p> <p> This project is packaged as a Juneau Microservice project that allows REST resources to be started - using embedded Jetty. + using embedded Jetty. </p> <!-- ======================================================================================================== --> @@ -2776,12 +2993,17 @@ 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. <l>microservice-samples-project-5.2.zip</l>). - <li>In your Eclipse workspace, go to <b>File->Import->General->Existing Projects into Workspace</b> and click <b>Next</b>.<br><br> + <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> + 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>.<br><br> + <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:<br><br> + <li>In your workspace, you can now see the following project: + <br><br> <img class='bordered' src="doc-files/Samples.Installing.3.png"> </ol> <p> @@ -2789,7 +3011,9 @@ </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 configuration file. <br><br> + This defines the entry point, classpath, top-level REST resources, and location of external + configuration file. + <br><br> <p class='bcode'> <mk>Manifest-Version</mk>: <mv>1.0</mv> <mk>Main-Class</mk>: <mv>org.apache.juneau.microservice.RestMicroservice</mv> @@ -2813,14 +3037,21 @@ lib/slf4j-api-1.6.4.jar lib/slf4j-log4j12-1.6.4.jar</mv> </p> - <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> - The top-level REST resource. - <br>This class serves as a "router" page to child resources:<br> - <li><l>examples.cfg</l> - The external configuration file. - <br>A deceptively simple yet powerful INI-style configuration file: - <br><br> + <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> + - The top-level REST resource. + <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 IN
<TRUNCATED>
