http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/990b5d22/juneau-doc/src/main/javadoc/overview.html ---------------------------------------------------------------------- diff --git a/juneau-doc/src/main/javadoc/overview.html b/juneau-doc/src/main/javadoc/overview.html index 41225be..17bf8d9 100644 --- a/juneau-doc/src/main/javadoc/overview.html +++ b/juneau-doc/src/main/javadoc/overview.html @@ -56,259 +56,437 @@ } </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 - interfaces that start up in milliseconds. + <li>A universal toolkit for marshalling POJOs to a wide variety of content types using a common framework. + <li>A universal REST server API for creating Swagger-based self-documenting REST interfaces using POJOs, simply deployed as + one or more top-level servlets in any Servlet 3.1.0+ container. + <li>A universal REST client API for interacting with Juneau or 3rd-party REST interfaces using POJOs and proxy interfaces. + <li>A sophisticated configuration file API. + <li>A REST microservice API that combines all the features above with a simple configurable Jetty server for + creating lightweight stand-alone REST interfaces that start up in milliseconds. + <li>Built on top of Servlet and Apache HttpClient APIs that allow you to use the newest HTTP/2 features + such as request/response multiplexing and server push. </ul> <a id='TOC'></a><h5 class='toc'>Table of Contents</h5> <ol class='toc'> - <li><p><a class='doclink' href='#Intro'>Juneau - What is it?</a></p> - <li><p><a class='doclink' href='#Core'>Juneau Core (org.apache.juneau)</a></p> + <li><p><a class='doclink' href='#Intro'>Introduction</a></p> <ol> - <li><p><a class='doclink' href='#Core.Serializers'>Serializers</a></p> - <li><p><a class='doclink' href='#Core.Parsers'>Parsers</a></p> - <li><p><a class='doclink' href='#Core.SerializerAndParserGroups'>SerializerGroups and ParserGroups</a></p> - <li><p><a class='doclink' href='#Core.ObjectMap'>ObjectMap and ObjectList</a></p> - <li><p><a class='doclink' href='#Core.ConfigurableProperties'>Configurable Properties</a></p> - <li><p><a class='doclink' href='#Core.Transforms'>Transforms</a></p> + <li><p><a class='doclink' href='#Intro.Features'>Features</a></p> + <li><p><a class='doclink' href='#Intro.Components'>Components</a></p> + </ol> + <li><p><a class='doclink' href='#juneau-core'><i>juneau-core</i></a></p> + <ol> + <li><p><a class='doclink' href='#juneau-marshall'><i>juneau-marshall</i></a></p> <ol> - <li><p><a class='doclink' href='#Core.PojoSwaps'>PojoSwaps</a></p> - <li><p><a class='doclink' href='#Core.SwapAnnotation'>@Swap annotation</a></p> - <li><p><a class='doclink' href='#Core.SwapMethods'>Swap methods</a></p> - <li><p><a class='doclink' href='#Core.BeanFilters'>BeanFilters and @Bean annotations</a></p> - <li><p><a class='doclink' href='#Core.SerializingReadersAndInputStreams'>Serializing Readers and InputStreams</a></p> + <li><p><a class='doclink' href='#juneau-marshall.Serializers'>Serializers</a></p> + <li><p><a class='doclink' href='#juneau-marshall.Parsers'>Parsers</a></p> + <li><p><a class='doclink' href='#juneau-marshall.SerializerAndParserGroups'>SerializerGroups and ParserGroups</a></p> + <li><p><a class='doclink' href='#juneau-marshall.ObjectMap'>ObjectMap and ObjectList</a></p> + <li><p><a class='doclink' href='#juneau-marshall.ConfigurableProperties'>Configurable Properties</a></p> + <li><p><a class='doclink' href='#juneau-marshall.Transforms'>Transforms</a></p> + <ol> + <li><p><a class='doclink' href='#juneau-marshall.PojoSwaps'>PojoSwaps</a></p> + <li><p><a class='doclink' href='#juneau-marshall.SwapAnnotation'>@Swap annotation</a></p> + <li><p><a class='doclink' href='#juneau-marshall.SwapMethods'>Swap methods</a></p> + <li><p><a class='doclink' href='#juneau-marshall.BeanFilters'>BeanFilters and @Bean annotations</a></p> + <li><p><a class='doclink' href='#juneau-marshall.SerializingReadersAndInputStreams'>Serializing Readers and InputStreams</a></p> + </ol> + <li><p><a class='doclink' href='#juneau-marshall.BeanDictionaries'>Bean Name and Dictionaries</a></p> + <ol> + <li><p><a class='doclink' href='#juneau-marshall.BeanSubTypes'>Bean Subtypes</a></p> + </ol> + <li><p><a class='doclink' href='#juneau-marshall.VirtualBeans'>Virtual Beans</a></p> + <li><p><a class='doclink' href='#juneau-marshall.JacksonComparison'>Comparison with Jackson</a></p> + <li><p><a class='doclink' href='#juneau-marshall.PojoCategories'>POJO Categories</a></p> + <li><p><a class='doclink' href='#juneau-marshall.BestPractices'>Best Practices</a></p> + <li><p><a class='doclink' href='#juneau-marshall.AdditionalInfo'>Additional Information</a></p> </ol> - <li><p><a class='doclink' href='#Core.BeanDictionaries'>Bean Name and Dictionaries</a></p> + <li><p><a class='doclink' href='#juneau-marshall-rdf'><i>juneau-marshall-rdf</i></a></p> + <li><p><a class='doclink' href='#juneau-dto'><i>juneau-dto</i></a></p> <ol> - <li><p><a class='doclink' href='#Core.BeanSubTypes'>Bean Subtypes</a></p> + <li><p><a class='doclink' href='#juneau-dto.HTML5'>HTML5</a></p> + <li><p><a class='doclink' href='#juneau-dto.Atom'>Atom</a></p> + <li><p><a class='doclink' href='#juneau-dto.Swagger'>Swagger</a></p> + <li><p><a class='doclink' href='#juneau-dto.JsonSchema'>JSON-Schema</a></p> </ol> - <li><p><a class='doclink' href='#Core.VirtualBeans'>Virtual Beans</a></p> - <li><p><a class='doclink' href='#Core.PojoCategories'>POJO Categories</a></p> - <li><p><a class='doclink' href='#Core.SimpleVarLanguage'>Simple Variable Language</a></p> - <li><p><a class='doclink' href='#Core.ConfigFile'>Configuration Files</a></p> - <li><p><a class='doclink' href='#Core.SupportedLanguages'>Supported Languages</a></p> - <li><p><a class='doclink' href='#Core.JacksonComparison'>Comparison with Jackson</a></p> + <li><p><a class='doclink' href='#juneau-svl'><i>juneau-svl</i></a></p> + <li><p><a class='doclink' href='#juneau-config'><i>juneau-config</i></a></p> </ol> - <li><p><a class='doclink' href='#DTOs'>Juneau Data Transfer Objects (org.apache.juneau.dto)</a></p> + <li><p><a class='doclink' href='#juneau-rest'><i>juneau-rest</i></a></p> <ol> - <li><p><a class='doclink' href='#DTOs.HTML5'>HTML5</a></p> - <li><p><a class='doclink' href='#DTOs.Atom'>Atom</a></p> - <li><p><a class='doclink' href='#DTOs.Swagger'>Swagger</a></p> - <li><p><a class='doclink' href='#DTOs.JsonSchema'>JSON-Schema</a></p> + <li><p><a class='doclink' href='#juneau-rest-server'><i>juneau-rest-server</i></a></p> + <ol> + <li><p><a class='doclink' href='#juneau-rest-server.Remoteable'>Remoteable Proxies</a></p> + <li><p><a class='doclink' href='#juneau-rest-server.Injection'>Using with Spring or other Injection frameworks</a></p> + <li><p><a class='doclink' href='#juneau-rest-server.HTTP2'>Using HTTP/2 features</a></p> + </ol> + <li><p><a class='doclink' href='#juneau-rest-server-jaxrs'><i>juneau-rest-server-jaxrs</i></a></p> + <li><p><a class='doclink' href='#juneau-rest-client'><i>juneau-rest-client</i></a></p> + <ol> + <li><p><a class='doclink' href='#juneau-rest-client.3rdPartyProxies'>Interface proxies against 3rd-party REST interfaces</a></p> + </ol> </ol> - <li><p><a class='doclink' href='#Server'>Juneau Server (org.apache.juneau.rest)</a></p> - <li><p><a class='doclink' href='#Client'>Juneau Client (org.apache.juneau.rest.client)</a></p> - <li><p><a class='doclink' href='#Remoteable'>Remoteable services (org.apache.juneau.rest.remoteable)</a></p> + <li><p><a class='doclink' href='#juneau-microservice'><i>juneau-microservice</i></a></p> <ol> - <li><p><a class='doclink' href='#Remoteable.3rdParty'>Interface proxies against 3rd-party REST interfaces</a></p> + <li><p><a class='doclink' href='#juneau-microservice-server'><i>juneau-microservice-server</i></a></p> + <li><p><a class='doclink' href='#juneau-microservice-template'><i>juneau-microservice-template</i></a></p> </ol> - <li><p><a class='doclink' href='#Microservices'>Juneau Microservices (org.apache.juneau.microservice)</a></p> - <li><p><a class='doclink' href='#Samples'>Samples</a></p> + <li><p><a class='doclink' href='#juneau-examples'><i>juneau-examples</i></a></p> <ol> - <li><p><a class='doclink' href='#Samples.Installing'>Installing in Eclipse</a></p> - <li><p><a class='doclink' href='#Samples.Running'>Running in Eclipse</a></p> - <li><p><a class='doclink' href='#Samples.Building'>Building and Running from Command-Line</a></p> - <li><p><a class='doclink' href='#Samples.RestResource'>MANIFEST.MF</a></p> - <li><p><a class='doclink' href='#Samples.RootResources'>RootResources</a></p> - <li><p><a class='doclink' href='#Samples.HelloWorldResource'>HelloWorldResource</a></p> - <li><p><a class='doclink' href='#Samples.MethodExampleResource'>MethodExampleResource</a></p> - <li><p><a class='doclink' href='#Samples.UrlEncodedFormResource'>UrlEncodedFormResource</a></p> - <li><p><a class='doclink' href='#Samples.RequestEchoResource'>RequestEchoResource</a></p> - <li><p><a class='doclink' href='#Samples.AddressBookResource'>AddressBookResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-core'><i>juneau-examples-core</i></a></p> + <li><p><a class='doclink' href='#juneau-examples-rest'><i>juneau-examples-rest</i></a></p> <ol> - <li><p><a class='doclink' href='#Samples.AddressBookResource.Classes'>Classes</a></p> - <li><p><a class='doclink' href='#Samples.AddressBookResource.Demo'>Demo</a></p> - <li><p><a class='doclink' href='#Samples.AddressBookResource.Traversable'>Traversable</a></p> - <li><p><a class='doclink' href='#Samples.AddressBookResource.Queryable'>Queryable</a></p> - <li><p><a class='doclink' href='#Samples.AddressBookResource.Introspectable'>Introspectable</a></p> - <li><p><a class='doclink' href='#Samples.AddressBookResource.RestClient'>ClientTest</a></p> - <li><p><a class='doclink' href='#Samples.AddressBookResource.Browser'>Browser Tips</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.RootResources'>RootResources</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.HelloWorldResource'>HelloWorldResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.MethodExampleResource'>MethodExampleResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.UrlEncodedFormResource'>UrlEncodedFormResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.RequestEchoResource'>RequestEchoResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.AddressBookResource'>AddressBookResource</a></p> + <ol> + <li><p><a class='doclink' href='#juneau-examples-rest.AddressBookResource.Classes'>Classes</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.AddressBookResource.Demo'>Demo</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.AddressBookResource.Traversable'>Traversable</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.AddressBookResource.Queryable'>Queryable</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.AddressBookResource.Introspectable'>Introspectable</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.AddressBookResource.RestClient'>ClientTest</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.AddressBookResource.Browser'>Browser Tips</a></p> + </ol> + <li><p><a class='doclink' href='#juneau-examples-rest.SampleRemoteableServlet'>SampleRemoteableServlet</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.TempDirResource'>TempDirResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.AtomFeedResource'>AtomFeedResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.DockerRegistryResource'>DockerRegistryResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.TumblrParserResource'>TumblrParserResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.PhotosResource'>PhotosResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.JsonSchemaResource'>JsonSchemaResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.SqlQueryResource'>SqlQueryResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.ConfigResource'>ConfigResource</a></p> + <li><p><a class='doclink' href='#juneau-examples-rest.LogsResource'>LogsResource</a></p> </ol> - <li><p><a class='doclink' href='#Samples.SampleRemoteableServlet'>SampleRemoteableServlet</a></p> - <li><p><a class='doclink' href='#Samples.TempDirResource'>TempDirResource</a></p> - <li><p><a class='doclink' href='#Samples.AtomFeedResource'>AtomFeedResource</a></p> - <li><p><a class='doclink' href='#Samples.DockerRegistryResource'>DockerRegistryResource</a></p> - <li><p><a class='doclink' href='#Samples.TumblrParserResource'>TumblrParserResource</a></p> - <li><p><a class='doclink' href='#Samples.PhotosResource'>PhotosResource</a></p> - <li><p><a class='doclink' href='#Samples.JsonSchemaResource'>JsonSchemaResource</a></p> - <li><p><a class='doclink' href='#Samples.SqlQueryResource'>SqlQueryResource</a></p> - <li><p><a class='doclink' href='#Samples.ConfigResource'>ConfigResource</a></p> - <li><p><a class='doclink' href='#Samples.LogsResource'>LogsResource</a></p> </ol> - <li><p><a class='doclink' href='#BestPractices'>Best Practices</a></p> - <li><p><a class='doclink' href='#ImportantLinks'>Important Documentation Links</a></p> <li><p><a class='doclink' href='#ReleaseNotes'>Release Notes</a></p> </ol> -<!-- ======================================================================================================== --> +<!-- =============================================================================================================== --> <a id="Intro"></a> -<h2 class='topic' onclick='toggle(this)'>1 - Juneau - What is it?</h2> +<h2 class='topic' onclick='toggle(this)'>1 - Introduction</h2> <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. - It's use grew to more than 50 projects and was one of the most popular community source projects within IBM. + Juneau is a single cohesive framework consisting of the following parts: </p> + <ul class='spaced-list'> + <li>A universal toolkit for marshalling POJOs to a wide variety of content types using a common framework. + <li>A universal REST server API for creating Swagger-based self-documenting REST interfaces using POJOs, simply + deployed as one or more top-level servlets in any Servlet 3.1.0+ container. + <li>A universal REST client API for interacting with Juneau or 3rd-party REST interfaces using POJOs and proxy + interfaces. + <li>A sophisticated configuration file API. + <li>A REST microservice API that combines all the features above with a simple configurable Jetty server for + creating lightweight stand-alone REST interfaces that start up in milliseconds. + <li>Built on top of Servlet and Apache HttpClient APIs that allow you to use the newest HTTP/2 features + such as request/response multiplexing and server push. + </ul> <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> - <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> - <li>JSON (including variants) - <li>XML - <li>HTML - <li>URL-Encoding - <li>UON (URL-Encoded Object Notation) - <li>MessagePack - <li>RDF/XML - <li>RDF/XML-Abbrev - <li>N-Triple - <li>Turtle - <li>N3 - <li>SOAP/XML - </ul> - <li> - <p>Parsing support:</p> - <ul> - <li>JSON (including lax syntax, comments, concatenated strings) - <li>XML - <li>HTML - <li>URL-Encoding - <li>UON (URL-Encoded Object Notation) - <li>MessagePack - <li>RDF/XML - <li>RDF/XML-Abbrev - <li>N-Triple - <li>Turtle - <li>N3 - </ul> - <li> - <p>Data Transfer Objects:</p> - <ul> - <li>HTML5 - <li>ATOM - <li>Swagger - <li>Cognos - <li>JSON-Schema - </ul> - <p>DTOs can be used with any serializers and parsers (e.g. ATOM as JSON). - <li> - <p>Serialization of POJO meta-models (e.g. the POJO class structure itself) to:</p> - <ul> - <li>JSON-Schema - <li>XML-Schema - <li>HTML-Schema - </ul> - <li> - <p> - Serializers/parsers require only Java 6+. - (RDF support requires Jena 2.7.1+) - </p> - <li> - <p> - REST APIs require only Java 6+ and JEE 1.3+. - (JAX/RS integration component requires JAX/RS provider) - </p> - </ol> - - <h5 class='topic'>Components</h5> - <p> - Juneau ships as a single Java library called <l>juneau.jar</l>. + Questions via email to <a class='doclink' href='mailto:d...@juneau.apache.org?Subject=Apache%20Juneau%20question'>d...@juneau.apache.org</a> are always welcome. </p> <p> - Juneau requires Java 6+. The majority of the code has no other dependencies except for the following packages: + Juneau is packed with features that may not be obvious at first. + Users are encouraged to ask for code reviews by providing links to specific source files such as through GitHub. + Not only can we help you with feedback, but it helps us understand usage patterns to further improve the product. </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+. - </ul> + + <h6 class='topic'>History</h6> <p> - OSGi bundles are also provided that break down Juneau into the following components: + 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. + It's use grew to more than 50 projects and was one of the most popular community source projects within IBM. </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. - </ul> <p> - The following zip files are also provided: + In June of 2016, the code was donated to the Apache Foundation under the project <l>Apache Juneau</l> where it + has continued to evolve to where it is today. </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>These are discussed in detail in the <a class='doclink' href="#Samples">Samples</a> section. - </ul> - <ul class='doctree'> - <li class='info'> - Many of the examples below use beans with public field properties instead of standard getters/setters. - This is to simplify the examples. - </ul> + <!-- =========================================================================================================== --> + <a id="Intro.Features"></a> + <h3 class='topic' onclick='toggle(this)'>1.1 - Features</h3> + <div class='topic'> + <ul class='spaced-list'> + <li> + KISS is our mantra! No auto-wiring. No code generation. No dependency injection (but still compatible with). + Just add it to your classpath and use it. Extremely simple unit testing! + <li> + Extensive and extensible support for a large variety of POJOs, including structured data (beans) and + unstructured data (<code>Maps</code> and <code>Collections</code>). + <li> + Sophisticated configurable serializers and parsers. + <br>For example, the JSON serializers and parsers can handle strict or lax syntax, comments, + concatenated strings, etc... + <li>Tiny - ~1MB + <li>Exhaustively tested + </ul> + </div> + + <!-- =========================================================================================================== --> + <a id="Intro.Components"></a> + <h3 class='topic' onclick='toggle(this)'>1.2 - Components</h3> + <div class='topic'> + <p> + We've strived to keep prerequisites to an absolute minimum in order to make adoption as easy as possible. + </p> + <p> + The library consists of the following artifacts found in the Maven group <code>"org.apache.juneau"</code>: + </p> + <table class='styled' style='min-width:800px;'> + <tr> + <th>Category</th><th>Maven Artifacts</th><th>Description</th><th>Prerequisites</th> + </tr> + <tr class='dark bb'> + <td rowspan="5" style='text-align:center;font-weight:bold;padding:20px;' class='code'><a class='doclink' href='#juneau-core'>juneau-core</a></td> + <td class='code'><a class='doclink' href='#juneau-marshall'>juneau-marshall</a></td> + <td>Serializers and parsers for: + <ul style='margin:0px 10px;'> + <li>JSON + <li>XML + <li>HTML + <li>UON + <li>URL-Encoding + <li>MessagePack + <li>SOAP/XML + <li>CSV + <li>BSON (coming soon) + <li>YAML (coming soon) + <li>Protobuf (coming soon) + </ul> + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + </ul> + </td> + </tr> + <tr class='dark bb'> + <td class='code'><a class='doclink' href='#juneau-marshall-rdf'>juneau-marshall-rdf</a></td> + <td> + Serializers and parsers for: + <ul style='margin:0px 10px;'> + <li>RDF/XML + <li>RDF/XML-Abbrev + <li>N-Triple + <li>Turtle + <li>N3 + </ul> + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>Apache Jena 2.7.1 + </ul> + </td> + </tr> + <tr class='dark bb'> + <td class='code'><a class='doclink' href='#juneau-dto'>juneau-dto</a></td> + <td> + Data Transfer Objects for: + <ul style='margin:0px 10px;'> + <li>HTML5 + <li>Atom + <li>Cognos + <li>JSON-Schema + <li>Swagger 2.0 + </ul> + </td> + <td><ul style='margin:0px 10px;'><li>Java 6</li></ul></td> + </tr> + <tr class='dark bb'> + <td class='code'><a class='doclink' href='#juneau-svl'>juneau-svl</a></td> + <td> + Simple Variable Language API + </td> + <td><ul style='margin:0px 10px;'><li>Java 6</li></ul></td> + </tr> + <tr class='dark bb'> + <td class='code'><a class='doclink' href='#juneau-config'>juneau-config</a></td> + <td> + Configuration file API + </td> + <td><ul style='margin:0px 10px;'><li>Java 6</li></ul></td> + </tr> + <tr class='light bb'> + <td rowspan="3" style='text-align:center;font-weight:bold;padding:20px;' class='code'><a class='doclink' href='#juneau-rest'>juneau-rest</a></td> + <td class='code'><a class='doclink' href='#juneau-rest-server'>juneau-rest-server</a></td> + <td> + REST Servlet API + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>Servlet 3.1 + </ul> + </td> + </tr> + <tr class='light bb'> + <td class='code'><a class='doclink' href='#juneau-rest-server-jaxrs'>juneau-rest-server-jaxrs</a></td> + <td> + Optional JAX-RS support + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>JAX-RS 2.0 + </ul> + </td> + </tr> + <tr class='light bb'> + <td class='code'><a class='doclink' href='#juneau-rest-client'>juneau-rest-client</a></td> + <td> + REST Client API + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>Apache HttpClient 4.5 + </ul> + </td> + </tr> + <tr class='dark bb'> + <td rowspan="2" style='text-align:center;font-weight:bold;padding:20px;' class='code'><a class='doclink' href='#juneau-microservice'>juneau-microservice</a></td> + <td class='code'><a class='doclink' href='#juneau-microservice-server'>juneau-microservice-server</a></td> + <td> + REST Microservice Server API + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 8 + <li>Eclipse Jetty 9.4.3 + </ul> + </td> + </tr> + <tr class='dark bb'> + <td class='code'><a class='doclink' href='#juneau-microservice-template'>juneau-microservice-template</a></td> + <td> + Developer template project + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 8 + <li>Eclipse Jetty 9.4.3 + </ul> + </td> + </tr> + <tr class='light bb'> + <td rowspan="2" style='text-align:center;font-weight:bold;padding:20px;' class='code'><a class='doclink' href='#juneau-examples'>juneau-examples</a></td> + <td class='code'><a class='doclink' href='#juneau-examples-core'>juneau-examples-core</a></td> + <td> + Core code examples + </td> + <td></td> + </tr> + <tr class='light bb'> + <td class='code'><a class='doclink' href='#juneau-examples-rest'>juneau-examples-rest</a></td> + <td> + REST code examples + </td> + <td></td> + </tr> + <tr class='dark bb'> + <td rowspan="1" style='text-align:center;font-weight:bold;padding:20px;' class='code'>juneau-all</td> + <td class='code'><code>juneau-all</code></td> + <td> + Combination of the following: + <ul style='margin:0px 10px;'> + <li>juneau-marshall + <li>juneau-dto + <li>juneau-svl + <li>juneau-config + <li>juneau-rest-server + <li>juneau-rest-client + </ul> + </td> + <td> + <ul style='margin:0px 10px;'> + <li>Java 6 + <li>Servlet 3.1 + <li>Apache HttpClient 4.5.3 + </ul> + </td> + </tr> + </table> + + <p> + Each component are also packaged as stand-alone OSGi modules. + </p> + </div> + </div> -<!-- ======================================================================================================== --> -<a id="Core"></a> -<h2 class='topic' onclick='toggle(this)'>2 - Juneau Core (org.apache.juneau)</h2> +<!-- =============================================================================================================== --> +<a id="juneau-core"></a> +<h2 class='topic' onclick='toggle(this)'>2 - juneau-core</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. - 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. + The core Maven artifacts of Juneau consist of the following: </p> - - <!-- ======================================================================================================== --> - <a id="Core.Serializers"></a> - <h3 class='topic' onclick='toggle(this)'>2.1 - Serializers</h3> + <ul class='spaced-list'> + <li><a class='doclink' href='#juneau-marshall'>juneau-marshall</a> + - Serializers and parsers for converting POJOs to and from a wide variety of content types using a + universal API. + <li><a class='doclink' href='#juneau-marshall-rdf'>juneau-marshall-rdf</a> + - RDF serializers and parsers that use Apache Jena for marshalling. + <li><a class='doclink' href='#juneau-dto'>juneau-dto</a> + - Data transfer objects for a variety of languages. + <li><a class='doclink' href='#juneau-svl'>juneau-svl</a> + - A sophisticated yet simple variable language. + <li><a class='doclink' href='#juneau-config'>juneau-config</a> + - A sophisticated configuration file API. + </ul> + + <!-- =========================================================================================================== --> + <a id="juneau-marshall"></a> + <h3 class='topic' onclick='toggle(this)'>2.1 - juneau-marshall</h3> <div class='topic'> + + <h6 class='figure'>Maven Dependency</h6> + <p class='bcode'> + <<xt>dependency</xt>> + <<xt>groupId</xt>>org.apache.juneau<<xt>/groupId</xt>> + <<xt>artifactId</xt>>juneau-marshall<<xt>/artifactId</xt>> + <<xt>version</xt>>6.4.0-incubating<<xt>/version</xt>> + <<xt>/dependency</xt>> + </p> + + <h6 class='figure'>OSGi Module</h6> + <p class='bcode'> + juneau-marshall-6.4.0-incubating.jar + </p> + <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. + The <code>juneau-marshall</code> artifact contains the API for defining serializers and parsers, and + marshalling support for JSON, XML, HTML, URL-Encoding, UON and others. </p> <p> - In most cases, you can serialize objects in one line of code by using one of the default serializers: + It also defines many convenience utility classes used throughout the framework. </p> - <p class='bcode'> + + <!-- ======================================================================================================= --> + <a id="juneau-marshall.Serializers"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.1 - Serializers</h4> + <div class='topic'> + <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. + </p> + <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. + </p> + <p> + In most cases, you can serialize objects in one line of code by using one of the default serializers: + </p> + <p class='bcode'> <jc>// A simple bean</jc> <jk>public class</jk> Person { <jk>public</jk> String <jf>name</jf> = <js>"John Smith"</js>; @@ -348,13 +526,13 @@ <jc>// Produces: // 82 A4 6E 61 6D 65 AA 4A 6F 68 6E 20 53 6D 69 74 68 A3 61 67 65 15 </jc> <jk>byte</jk>[] b = MsgPackSerializer.<jsf>DEFAULT</jsf>.serialize(p); - </p> - - <p> - In addition to the default serializers, customized serializers can be created using various built-in options: - </p> - - <p class='bcode'> + </p> + + <p> + In addition to the default serializers, customized serializers can be created using various built-in options: + </p> + + <p class='bcode'> <jc>// Use one of the default serializers to serialize a POJO</jc> String json = JsonSerializer.<jsf>DEFAULT</jsf>.serialize(someObject); @@ -366,35 +544,35 @@ <jc>// Serialize a POJO to JSON</jc> 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). - </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 - </ul> - </div> + </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). + </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 + </ul> + </div> - <!-- ======================================================================================================== --> - <a id="Core.Parsers"></a> - <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. - This allows them to parse input with minimal object creation. - </p> - <p> - Like the serializers, you can often parse objects in one line of code by using one of the default parsers: - </p> - <p class='bcode'> + <!-- ======================================================================================================= --> + <a id="juneau-marshall.Parsers"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.2 - Parsers</h4> + <div class='topic'> + <p> + 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> + Like the serializers, you can often parse objects in one line of code by using one of the default parsers: + </p> + <p class='bcode'> <jc>// Use one of the predefined parsers.</jc> Parser parser = JsonParser.<jsf>DEFAULT</jsf>; @@ -427,11 +605,11 @@ json = <js>"[1,2,3]"</js>; List<Integer> l6 = parser.parse(json, LinkedList.<jk>class</jk>, Integer.<jk>class</jk>); <jk>int</jk>[] i7 = parser.parse(json, <jk>int</jk>[].<jk>class</jk>); - </p> - <p> - The parsers can also be used to populating existing bean and collection objects: - </p> - <p class='bcode'> + </p> + <p> + The parsers can also be used to populating existing bean and collection objects: + </p> + <p class='bcode'> <jc>// Use one of the predefined parsers.</jc> Parser parser = JsonParser.<jsf>DEFAULT</jsf>; @@ -449,36 +627,36 @@ json = <js>"{a:{name:'John Smith',age:21},b:{name:'Joe Smith',age:42}}"</js>; Map<String,Person> m3 = <jk>new</jk> TreeMap<String,Person>(); parser.parseIntoMap(json, m3, String.<jk>class</jk>, Person.<jk>class</jk>); - </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. - </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 - </ul> - </div> + </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. + </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 + </ul> + </div> - <!-- ======================================================================================================== --> - <a id="Core.SerializerAndParserGroups"></a> - <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... - </p> - <p class='bcode'> + <!-- ======================================================================================================= --> + <a id="juneau-marshall.Groups"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.3 - SerializerGroups and ParserGroups</h4> + <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... + </p> + <p class='bcode'> <jc>// Construct a new serializer group with configuration parameters that get applied to all serializers.</jc> SerializerGroup sg = <jk>new</jk> SerializerGroupBuilder() .append(JsonSerializer.<jk>class</jk>, UrlEncodingSerializer.<jk>class</jk>); @@ -497,80 +675,80 @@ .build(); Person p = pg.getParser(<js>"text/json"</js>).parse(myReader, Person.<jk>class</jk>); - </p> - <p> - The REST servlet API builds upon the <code>SerializerGroup</code> and <code>ParserGroup</code> classes - 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} - </ul> - </div> + </p> + <p> + The REST servlet API builds upon the <code>SerializerGroup</code> and <code>ParserGroup</code> classes + 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} + </ul> + </div> - <!-- ======================================================================================================== --> - <a id="Core.ObjectMap"></a> - <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. - </p> - <p> - 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> - <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 - <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> - Passing them to one of the {@link org.apache.juneau.serializer.Serializer} serialize methods. - <li> - Simply calling the {@link org.apache.juneau.ObjectMap#toString()} or {@link org.apache.juneau.ObjectList#toString()} - methods which will serialize it as Simplified JSON. - </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. - <br> - (In theory, any valid XML can also be parsed into an unstructured model, although this has not been - officially 'tested') - </p> - <p class='bcode'> + <!-- ======================================================================================================= --> + <a id="juneau-marshall.ObjectMap"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.4 - ObjectMap and ObjectList</h4> + <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. + </p> + <p> + 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> + <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 + <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> + Passing them to one of the {@link org.apache.juneau.serializer.Serializer} serialize methods. + <li> + Simply calling the {@link org.apache.juneau.ObjectMap#toString()} or {@link org.apache.juneau.ObjectList#toString()} + methods which will serialize it as Simplified JSON. + </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. + <br> + (In theory, any valid XML can also be parsed into an unstructured model, although this has not been + officially 'tested') + </p> + <p class='bcode'> <jc>// Parse an arbitrary JSON document into an unstructered data model // consisting of ObjectMaps, ObjectLists, and java primitive objects.</jc> Parser parser = JsonParser.<jsf>DEFAULT</jsf>; @@ -588,250 +766,279 @@ <jc>// Or just use toString().</jc> json = m.toString(); - </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>. - </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} - </ul> - </div> - - <!-- ======================================================================================================== --> - <a id="Core.ConfigurableProperties"></a> - <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>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: - </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> - <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: - </p> - <p class='bcode'> - <jc>// Serialize a POJO to LAX JSON.</jc> - String json = JsonSerializer.<jsf>DEFAULT_LAX</jsf>.serialize(myPojo); - </p> - <p> - Serializers and parsers can be locked to prevent further modification to the properties. - They can also be cloned to copy the configuration of other serializers and parsers. - </p> - <p class='bcode'> - <jc>// Clone and customize an existing serializer.</jc> - JsonSerializer s = JsonSerializer.<jsf>DEFAULT_LAX</jsf> - .builder() - .quoteChar(<js>'"'</js>) - .build(); - - <jc>// Lock it so that the configuration cannot be changed.</jc> - s.lock(); - </p> - - <h6 class='topic'>Additional Information</h6> - <p> - 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> - <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> - </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> - - <!-- ======================================================================================================== --> - <a id="Core.Transforms"></a> - <h3 class='topic' onclick='toggle(this)'>2.6 - Transforms</h3> - <div class='topic'> - <p> - By default, the Juneau framework can serialize and parse a wide variety of POJOs out-of-the-box. - However, two special classes are provided tailor how certain Java objects are handled by the framework. - 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. - </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.Swap @Swap} - - 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> + </p> + <p> + The <code>ObjectMap</code> and <code>ObjectList</code> classes have many convenience features: + </p> + <p class='bcode'> + <jc>// Convert the map to a bean.</jc> + MyBean m = objectMap.cast(MyBean.<jk>class</jk>); + + <jc>// Find entries by multiple keys.</jc> + MyBean m = objectMap.find(MyBean.<jk>class</jk>, <js>"key1"</js>, <js>"key2"</js>); + + <jc>// Fluent-style appenders.</jc> + objectMap.append(<js>"key1"</js>, <js>"val1"</js>).append(<js>"key2"</js>, <js>"val2"</js>); + + <jc>// REST-like functions for manipulating nodes in the data structure using URL-like notation.</jc> + objectMap.getAt(<js>"foo/bar/myBean"</js>, MyBean.<jk>class</jk>); + objectMap.putAt(<js>"foo/bar/myBean"</js>, MyBean.<jk>class</jk>); + objectMap.postAt(<js>"foo/bar/myListOfBeans"</js>, MyBean.<jk>class</jk>); + objectMap.deleteAt(<js>"foo/bar/myBean"</js>); + + <jc>// Copy with inclusion or exclusion.</jc> + ObjectMap m2 = objectMap.include(<js>"key1"</js>, <js>"key2"</js>, <js>"key3"</js>); + ObjectMap m3 = objectMap.exclude(<js>"key1"</js>, <js>"key2"</js>, <js>"key3"</js>); - <!-- ======================================================================================================== --> - <a id="Core.PojoSwaps"></a> - <h4 class='topic' onclick='toggle(this)'>2.6.1 - PojoSwaps</h4> + <jc>// Serialize using another serializer.</jc> + String xml = objectMap.serializeTo(XmlSerializer.<jsf>DEFAULT</jsf>); + + <jc>// Nested maps.</jc> + objectMap.setInner(objectMapInner); + </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>. + </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} + </ul> + </div> + + <!-- ======================================================================================================= --> + <a id="juneau-marshall-ConfigurableProperties"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.5 - Configurable Properties</h4> <div class='topic'> <p> - {@link org.apache.juneau.transform.PojoSwap PojoSwaps} are a critical component of Juneau. - They allow the serializers and parsers to handle Java objects that wouldn't normally be serializable. + 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> - 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. + 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'> + <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} + <li class='jf'> + {@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX_READABLE_SAFE DEFAULT_LAX_READABLE_SAFE} + </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> - 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. + These can be used directly, as follows: + </p> + <p class='bcode'> + <jc>// Serialize a POJO to LAX JSON.</jc> + String json = JsonSerializer.<jsf>DEFAULT_LAX</jsf>.serialize(myPojo); </p> <p> - In the following example, we introduce a <code>PojoSwap</code> that will swap in ISO8601 strings for - <code>Date</code> objects: + For performance reasons, serializers and parsers are immutable. + However, they can be 'copied' and modified using the <code>builder()</code> method. </p> <p class='bcode'> - <jc>// Sample swap for converting Dates to ISO8601 strings.</jc> - <jk>public class</jk> MyDateSwap <jk>extends</jk> PojoSwap<Date,String> { - - <jc>// ISO8601 formatter.</jc> - <jk>private</jk> DateFormat <jf>format</jf> = <jk>new</jk> SimpleDateFormat(<js>"yyyy-MM-dd'T'HH:mm:ssZ"</js>); - - <jd>/** Converts a Date object to an ISO8601 string. */</jd> - <ja>@Override</ja> - <jk>public</jk> String swap(BeanSession session, Date o) { - <jk>return</jk> <jf>format</jf>.format(o); - } + <jc>// Clone and customize an existing serializer.</jc> + JsonSerializer s = JsonSerializer.<jsf>DEFAULT_LAX</jsf> + .builder() + .quoteChar(<js>'"'</js>) <jc>// Use a different quote character.</jc> + .build(); + </p> + + <h6 class='topic'>Additional Information</h6> + <p> + 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> + <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> + </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> + + <!-- ======================================================================================================= --> + <a id="juneau-marshall-Transforms"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.6 - Transforms</h4> + <div class='topic'> + <p> + By default, the Juneau framework can serialize and parse a wide variety of POJOs out-of-the-box. + However, two special classes are provided tailor how certain Java objects are handled by the framework. + 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. + </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.Swap @Swap} + - 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> + + <!-- =================================================================================================== --> + <a id="juneau-marshall.PojoSwaps"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.6.1 - PojoSwaps</h4> + <div class='topic'> + <p> + {@link org.apache.juneau.transform.PojoSwap PojoSwaps} are a critical component of Juneau. + They allow the serializers and parsers to handle Java objects that wouldn't normally be serializable. + </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. + </p> + <p> + 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: + </p> + <p class='bcode'> + <jc>// Sample swap for converting Dates to ISO8601 strings.</jc> + <jk>public class</jk> MyDateSwap <jk>extends</jk> PojoSwap<Date,String> { + + <jc>// ISO8601 formatter.</jc> + <jk>private</jk> DateFormat <jf>format</jf> = <jk>new</jk> SimpleDateFormat(<js>"yyyy-MM-dd'T'HH:mm:ssZ"</js>); + + <jd>/** Converts a Date object to an ISO8601 string. */</jd> + <ja>@Override</ja> + <jk>public</jk> String swap(BeanSession session, Date o) { + <jk>return</jk> <jf>format</jf>.format(o); + } <jd>/** Converts an ISO8601 string to a Date object. */</jd> <ja>@Override</ja> @@ -843,11 +1050,11 @@ } } } - </p> - <p> - The swap can then be associated with serializers and parsers like so: - </p> - <p class='bcode'> + </p> + <p> + The swap can then be associated with serializers and parsers like so: + </p> + <p class='bcode'> <jc>// Sample bean with a Date field.</jc> <jk>public class</jk> MyBean { <jk>public</jk> Date <jf>date</jf> = <jk>new</jk> Date(112, 2, 3, 4, 5, 6); @@ -861,55 +1068,129 @@ ReaderParser parser = <jk>new</jk> JsonParserBuilder().pojoSwaps(MyDateSwap.<jk>class</jk>).build(); MyBean bean = parser.parse(json, MyBean.<jk>class</jk>); <jk>int</jk> day = bean.<jf>date</jf>.getDay(); <jc>// == 3</jc> - </p> - <p> - 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> - </ul> - <p> - 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>. - </ul> - </div> + </p> + <p> + 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> + </ul> + <p> + 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> - <!-- ======================================================================================================== --> - <a id="Core.SwapAnnotation"></a> - <h4 class='topic' onclick='toggle(this)'>2.6.2 - @Swap annotation</h4> - <div class='topic'> - <p> - {@link org.apache.juneau.annotation.Swap @Swap} can be used to associate a swap class using an - annotation. - This is often cleaner than using the builder <code>pojoSwaps()</code> method since you can keep - your swap class near your POJO class. - </p> - <p class='bcode'> + <p> + Swaps can also be defined per-media-type. + The {@link org.apache.juneau.transform.PojoSwap#forMediaTypes()} method can be overridden to + provide a set of media types that the swap is invoked on. + It's also possible to define multiple swaps against the same POJO as long as they're differentiated + by media type. + When multiple swaps are defined, the best-match media type is used. + </p> + <p> + In the following example, we define 3 swaps against the same POJO. + One for JSON, one for XML, and one for all other types. + </p> + <p class='bcode'> + <jk>public class</jk> PojoSwapTest { + + <jk>public static class</jk> MyPojo {} + + <jk>public static class</jk> MyJsonSwap <jk>extends</jk> PojoSwap<MyPojo,String> { + + <jk>public</jk> MediaType[] forMediaTypes() { + <jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"*/json"</js>); + } + + <jk>public</jk> String swap(BeanSession session, MyPojo o) <jk>throws</jk> Exception { + <jk>return</jk> <js>"It's JSON!"</js>; + } + } + + <jk>public static class</jk> MyXmlSwap <jk>extends</jk> PojoSwap<MyPojo,String> { + + <jk>public</jk> MediaType[] forMediaTypes() { + <jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"*/xml"</js>); + } + + <jk>public</jk> String swap(BeanSession session, MyPojo o) <jk>throws</jk> Exception { + <jk>return</jk> <js>"It's XML!"</js>; + } + } + + <jk>public static class</jk> MyOtherSwap <jk>extends</jk> PojoSwap<MyPojo,String> { + + <jk>public</jk> MediaType[] forMediaTypes() { + <jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"*/*"</js>); + } + + <jk>public</jk> String swap(BeanSession session, MyPojo o) <jk>throws</jk> Exception { + <jk>return</jk> <js>"It's something else!"</js>; + } + } + + <ja>@Test</ja> + <jk>public void</jk> doTest() <jk>throws</jk> Exception { + + SerializerGroup g = <jk>new</jk> SerializerGroupBuilder() + .append(JsonSerializer.<jk>class</jk>, XmlSerializer.<jk>class</jk>, HtmlSerializer.<jk>class</jk>) + .sq() + .pojoSwaps(MyJsonSwap.<jk>class</jk>, MyXmlSwap.<jk>class</jk>, MyOtherSwap.<jk>class</jk>) + .build(); + + MyPojo myPojo = <jk>new</jk> MyPojo(); + + String json = g.getWriterSerializer(<js>"text/json"</js>).serialize(myPojo); + <jsm>assertEquals</jsm>(<js>"'It\\'s JSON!'"</js>, json); + + String xml = g.getWriterSerializer(<js>"text/xml"</js>).serialize(myPojo); + <jsm>assertEquals</jsm>(<js>"<string>It's XML!</string>"</js>, xml); + + String html = g.getWriterSerializer(<js>"text/html"</js>).serialize(myPojo); + <jsm>assertEquals</jsm>(<js>"<string>It's something else!</string>"</js>, html); + } + } + </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='#juneau-marshall.PojoCategories'>POJO Categories</a>. + </ul> + </div> + + <!-- =================================================================================================== --> + <a id="juneau-marshall.SwapAnnotation"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.6.2 - @Swap annotation</h4> + <div class='topic'> + <p> + {@link org.apache.juneau.annotation.Swap @Swap} can be used to associate a swap class using an + annotation. + This is often cleaner than using the builder <code>pojoSwaps()</code> method since you can keep + your swap class near your POJO class. + </p> + <p class='bcode'> <ja>@Swap</ja>(MyPojoSwap.<jk>class</jk>) <jk>public class</jk> MyPojo { ... @@ -923,74 +1204,105 @@ <jk>return</jk> o.toSomeSerializableForm(); } } - </p> - </div> + </p> + + <p> + Multiple swaps can be associated with a POJO by using the {@link org.apache.juneau.annotation.Swaps @Swaps} annotation: + </p> + <p class='bcode'> + <ja>@Swaps</ja>( + { + <ja>@Swap</ja>(MyJsonSwap.<jk>class</jk>), + <ja>@Swap</ja>(MyXmlSwap.<jk>class</jk>), + <ja>@Swap</ja>(MyOtherSwap.<jk>class</jk>) + } + ) + <jk>public class</jk> MyPojo {} + </p> + <p> + <code>Readers</code> get serialized directly to the output of a serializer. + Therefore it's possible to implement a swap that provides fully-customized output. + </p> + <p class='bcode'> + <jk>public class</jk> MyJsonSwap <jk>extends</jk> PojoSwap<MyPojo,Reader> { - <!-- ======================================================================================================== --> - <a id="Core.SwapMethods"></a> - <h4 class='topic' onclick='toggle(this)'>2.6.3 - Swap methods</h4> - <div class='topic'> - <p> - Various methods can be defined on a class directly to affect how it gets serialized. - 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: - </p> - <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> - <li><code>parseString(String)</code> - <li><code>forName(String)</code> - <li><code>forString(String)</code> - </ul> - <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: - </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>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. - </p> - <p> - 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. - </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()}). - </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. - </p> - <p class='bcode'> + <jk>public</jk> MediaType[] forMediaTypes() { + <jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"*/json"</js>); + } + + <jk>public</jk> Reader swap(BeanSession session, MyPojo o) <jk>throws</jk> Exception { + <jk>return new</jk> StringReader(<js>"{message:'Custom JSON!'}"</js>); + } + } + </p> + + </div> + + <!-- ======================================================================================================= --> + <a id="juneau-marshall.SwapMethods"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.6.3 - Swap methods</h4> + <div class='topic'> + <p> + Various methods can be defined on a class directly to affect how it gets serialized. + 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: + </p> + <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> + <li><code>parseString(String)</code> + <li><code>forName(String)</code> + <li><code>forString(String)</code> + </ul> + <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: + </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>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. + </p> + <p> + 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. + </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()}). + </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. + </p> + <p class='bcode'> <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; <jd>/** @@ -1017,21 +1329,21 @@ ); } } - </p> - <p> - 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</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: - </p> - <p class='bcode'> + </p> + <p> + 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</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: + </p> + <p class='bcode'> <jk>import static</jk> org.apache.juneau.dto.html5.HtmlBuilder.*; <jd>/** @@ -1067,40 +1379,40 @@ ); } } - </div> - - <!-- ======================================================================================================== --> - <a id="Core.BeanFilters"></a> - <h4 class='topic' onclick='toggle(this)'>2.6.4 - 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. - They allow you to control various aspects of beans, such as... - </p> - <ul> - <li>Which properties to include or exclude. - <li>Property order. - <li>Property naming conventions. - <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. - The annotations are functionally equivalent to the bean filter class. - </p> - <p class='bcode'> + </div> + + <!-- ======================================================================================================= --> + <a id="juneau-marshall.BeanFilters"></a> + <h4 class='topic' onclick='toggle(this)'>2.1.6.4 - 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. + They allow you to control various aspects of beans, such as... + </p> + <ul> + <li>Which properties to include or exclude. + <li>Property order. + <li>Property naming conventions. + <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. + The annotations are functionally equivalent to the bean filter class. + </p> + <p class='bcode'> <jc>// Address class with only street/city/state properties (in that order).</jc> <jc>// All other properties are ignored.</jc> <ja>@Bean</ja>(properties=<js>"street,city,state"</js>) <jk>public class</jk> Address { ... - </p> - <p> - Bean filters are defined through {@link org.apache.juneau.transform.BeanFilterBuilder BeanFilterBuilders}. - The programmatic equivalent to the the annotation above would be: - </p> - <p class='bcode'> + </p> + <p> + Bean filters are defined through {@link org.apache.juneau.transform.BeanFilterBuilder BeanFilterBuilders}. + The programmatic equivalent to the the annotation above would be: + </p> + <p class='bcode'> <jk>public class</jk> MyAddressBeanFilter <jk>extends</jk> BeanFilterBuilder { <jc>// Must provide a no-arg constructor!</jc> @@ -1109,27 +1421,27 @@ setIncludeProperties(<js>"street,city,state"</js>); <jc>// The properties we want exposed.</jc> } } - </p> - <p> - Bean filters are added to serializers and parsers using the <code>*BeanFilters(Class...)</code> methods. - For example: - </p> - <p class='bcode'> + </p> + <p> + Bean filters are added to serializers and parsers using the <code>*Be
<TRUNCATED>
