http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/json/package.html ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/json/package.html b/juneau-core/src/main/java/org/apache/juneau/json/package.html index c32bd3c..b06dc5b 100644 --- a/juneau-core/src/main/java/org/apache/juneau/json/package.html +++ b/juneau-core/src/main/java/org/apache/juneau/json/package.html @@ -76,17 +76,6 @@ <li><p><a class='doclink' href='#ParserConfigurableProperties'>Configurable properties</a></p> <li><p><a class='doclink' href='#ParserOtherNotes'>Other notes</a></p> </ol> - <li><p><a class='doclink' href='#RestApiSupport'>REST API support</a></p> - <ol> - <li><p><a class='doclink' href='#RestServerSupport'>REST server support</a></p> - <ol> - <li><p><a class='doclink' href='#RestServletDefault'>Using RestServletDefault</a></p> - <li><p><a class='doclink' href='#RestServlet'>Using RestServlet with annotations</a></p> - <li><p><a class='doclink' href='#DefaultProvider'>Using JAX-RS DefaultProvider</a></p> - <li><p><a class='doclink' href='#BaseProvider'>Using JAX-RS BaseProvider with annotations</a></p> - </ol> - <li><p><a class='doclink' href='#RestClientSupport'>REST client support</a></p> - </ol> </ol> <!-- ======================================================================================================== --> @@ -94,23 +83,31 @@ <h2 class='topic' onclick='toggle(this)'>1 -JSON support overview</h2> <div class='topic'> <p> - Juneau supports converting arbitrary POJOs to and from JSON using ultra-efficient serializers and parsers.<br> - The JSON serializer converts POJOs directly to JSON without the need for intermediate DOM objects using a highly-efficient state machine.<br> + Juneau supports converting arbitrary POJOs to and from JSON using ultra-efficient serializers and parsers. + <br> + The JSON serializer converts POJOs directly to JSON without the need for intermediate DOM objects using a + highly-efficient state machine. + <br> Likewise, the JSON parser creates POJOs directly from JSON without the need for intermediate DOM objects. </p> <p> Juneau can serialize and parse instances of any of the following POJO types: </p> <ul class='spaced-list'> - <li>Java primitives and primitive objects (e.g. <code>String</code>, <code>Integer</code>, <code>Boolean</code>, <code>Float</code>). - <li>Java Collections Framework objects (e.g. <code>HashSet</code>, <code>TreeMap</code>) containing anything on this list. + <li>Java primitives and primitive objects (e.g. <code>String</code>, <code>Integer</code>, <code>Boolean</code>, + <code>Float</code>). + <li>Java Collections Framework objects (e.g. <code>HashSet</code>, <code>TreeMap</code>) containing anything on + this list. <li>Multi-dimensional arrays of any type on this list. <li>Java Beans with properties of any type on this list. - <li>Classes with standard transformations to and from <code>Strings</code> (e.g. classes containing <code>toString()</code>, <code>fromString()</code>, <code>valueOf()</code>, <code>constructor(String)</code>). - <li>Non-serializable classes and properties with associated <code>PojoSwaps</code> that convert them to serializable forms. + <li>Classes with standard transformations to and from <code>Strings</code> (e.g. classes containing + <code>toString()</code>, <code>fromString()</code>, <code>valueOf()</code>, <code>constructor(String)</code>). + <li>Non-serializable classes and properties with associated <code>PojoSwaps</code> that convert them to + serializable forms. </ul> <p> - Refer to <a href='../../../../overview-summary.html#Core.PojoCategories' class='doclink'>POJO Categories</a> for a complete definition of supported POJOs. + Refer to <a href='../../../../overview-summary.html#Core.PojoCategories' class='doclink'>POJO Categories</a> + for a complete definition of supported POJOs. </p> <h6 class='topic'>Prerequisites</h6> <p> @@ -123,16 +120,19 @@ <h3 class='topic' onclick='toggle(this)'>1.1 - JSON support overview - example</h3> <div class='topic'> <p> - The example shown here is from the Address Book resource located in the <code>org.apache.juneau.sample.war</code> application.<br> - The POJO model consists of a <code>List</code> of <code>Person</code> beans, with each <code>Person</code> containing - zero or more <code>Address</code> beans. + The example shown here is from the Address Book resource located in the + <code>org.apache.juneau.sample.war</code> application. + <br> + The POJO model consists of a <code>List</code> of <code>Person</code> beans, with each <code>Person</code> + containing zero or more <code>Address</code> beans. </p> <p> When you point a browser at <code>/sample/addressBook</code>, the POJO is rendered as HTML: </p> <img class='bordered' src="doc-files/Example_HTML.png"> <p> - By appending <code>?Accept=<i>mediaType</i>&plainText=true</code> to the URL, you can view the data in the various supported JSON formats: + By appending <code>?Accept=<i>mediaType</i>&plainText=true</code> to the URL, you can view the data in + the various supported JSON formats: </p> <h6 class='figure'>Normal JSON</h6> @@ -142,7 +142,8 @@ <img class='bordered' src="doc-files/Example_JSONSimple.png"> <p> - In addition to serializing POJOs to JSON, Juneau includes support for serializing POJO metamodels to JSON Schema. + In addition to serializing POJOs to JSON, Juneau includes support for serializing POJO metamodels to + JSON Schema. </p> <h6 class='figure'>JSON Schema</h6> @@ -152,9 +153,9 @@ The JSON data type produced depends on the Java object type being serialized. </p> <ul class='spaced-list'> - <li>Primitives and primitive objects are converted to JSON primitives.<br> - <li>Beans and Maps are converted to JSON objects.<br> - <li>Collections and arrays are converted to JSON arrays.<br> + <li>Primitives and primitive objects are converted to JSON primitives. + <li>Beans and Maps are converted to JSON objects. + <li>Collections and arrays are converted to JSON arrays. <li>Anything else is converted to JSON strings. </ul> @@ -203,7 +204,9 @@ </table> <p> In addition, swaps can be used to convert non-serializable POJOs into serializable forms, such as converting - <code>Calendar</code> object to ISO8601 strings, or <code><jk>byte</jk>[]</code> arrays to Base-64 encoded strings.<br> + <code>Calendar</code> object to ISO8601 strings, or <code><jk>byte</jk>[]</code> arrays to Base-64 + encoded strings. + <br> These swaps can be associated at various levels: </p> <ul class='spaced-list'> @@ -212,7 +215,8 @@ <li>On bean properties through the <code><ja>@BeanProperty</ja></code> annotations. </ul> <p> - For more information about transforms, refer to <a class='doclink' href='../transform/package-summary.html#TOC'>org.apache.juneau.transform</a>. + For more information about transforms, refer to <a class='doclink' + href='../transform/package-summary.html#TOC'>org.apache.juneau.transform</a>. </p> </div> </div> @@ -222,22 +226,27 @@ <h2 class='topic' onclick='toggle(this)'>2 - JsonSerializer class</h2> <div class='topic'> <p> - {@link org.apache.juneau.json.JsonSerializer} is the class used to convert POJOs to JSON.<br> - {@link org.apache.juneau.json.JsonSchemaSerializer} is the class used to generate JSON-Schema from POJOs.<br> + {@link org.apache.juneau.json.JsonSerializer} is the class used to convert POJOs to JSON. + <br> + {@link org.apache.juneau.json.JsonSchemaSerializer} is the class used to generate JSON-Schema from POJOs. </p> <p> - The JSON serializer includes several configurable settings.<br> + The JSON serializer includes several configurable settings. + <br> Static reusable instances of Json serializers are provided with commonly-used settings: </p> <ul class='spaced-list'> <li>{@link org.apache.juneau.json.JsonSerializer#DEFAULT} - All default settings - <li>{@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX} - Single quotes, only quote attributes when necessary. + <li>{@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX} - Single quotes, only quote attributes when + necessary. <li>{@link org.apache.juneau.json.JsonSerializer#DEFAULT_LAX_READABLE} - Readable output. </ul> <h6 class='topic'>Notes about examples</h6> <p> - The examples shown in this document will use single-quote, readable settings.<br> - For brevity, the examples will use public fields instead of getters/setters to reduce the size of the examples.<br> + The examples shown in this document will use single-quote, readable settings. + <br> + For brevity, the examples will use public fields instead of getters/setters to reduce the size of the examples. + <br> In the real world, you'll typically want to use standard bean getters and setters. </p> <p> @@ -295,21 +304,28 @@ <h3 class='topic' onclick='toggle(this)'>2.1 - @Bean and @BeanProperty annotations</h3> <div class='topic'> <p> - The {@link org.apache.juneau.annotation.Bean @Bean} and {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotations - are used to customize the behavior of beans across the entire framework.<br> + The {@link org.apache.juneau.annotation.Bean @Bean} and + {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotations are used to customize the + behavior of beans across the entire framework. + <br> They have various uses: </p> <ul class='spaced-list'> <li>Hiding bean properties. <li>Specifying the ordering of bean properties. <li>Overriding the names of bean properties. - <li>Associating swaps at both the class and property level (to convert non-serializable POJOs to serializable forms). + <li>Associating swaps at both the class and property level (to convert non-serializable POJOs to + serializable forms). </ul> <p> - For example, we now add a <code>birthDate</code> property, and associate a swap with it to transform - it to an ISO8601 date-time string in GMT time.<br> - We'll also add a couple of <code>URI</code> properties.<br> - By default, <code>Calendars</code> are treated as beans by the framework, which is usually not how you want them serialized.<br> + For example, we now add a <code>birthDate</code> property, and associate a swap with it to transform it to + an ISO8601 date-time string in GMT time. + <br> + We'll also add a couple of <code>URI</code> properties. + <br> + By default, <code>Calendars</code> are treated as beans by the framework, which is usually not how you want + them serialized. + <br> Using swaps, we can convert them to standardized string forms. </p> <p class='bcode'> @@ -342,7 +358,8 @@ </p> <p class='bcode'> <jc>// Create our bean.</jc> - Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, + <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); </p> <p> Now when we rerun the sample code, we'll get the following: @@ -357,8 +374,9 @@ } </p> <p> - Another useful feature is the {@link org.apache.juneau.annotation.Bean#propertyNamer()} annotation that allows you to plug in your own - logic for determining bean property names.<br> + Another useful feature is the {@link org.apache.juneau.annotation.Bean#propertyNamer()} annotation that + allows you to plug in your own logic for determining bean property names. + <br> The {@link org.apache.juneau.PropertyNamerDLC} is an example of an alternate property namer. It converts bean property names to lowercase-dashed format. </p> @@ -419,7 +437,8 @@ JsonSerializer s = JsonSerializer.<jsf>DEFAULT_LAX_READABLE</jsf>; <jc>// Create our bean.</jc> - Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, + <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); Address a = <jk>new</jk> Address(); a.<jf>uri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/address/1";</js>); a.<jf>personUri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/person/1";</js>); @@ -463,15 +482,17 @@ <h3 class='topic' onclick='toggle(this)'>2.3 - JSON-Schema support</h3> <div class='topic'> <p> - Juneau provides the {@link org.apache.juneau.json.JsonSchemaSerializer} class for generating JSON-Schema documents - that describe the output generated by the {@link org.apache.juneau.json.JsonSerializer} class.<br> - This class shares the same properties as <code>JsonSerializer</code>.<br> - For convenience the {@link org.apache.juneau.json.JsonSerializer#getSchemaSerializer()} method - has been added for creating instances of schema serializers from the regular serializer instance. + Juneau provides the {@link org.apache.juneau.json.JsonSchemaSerializer} class for generating JSON-Schema + documents that describe the output generated by the {@link org.apache.juneau.json.JsonSerializer} class. + <br> + This class shares the same properties as <code>JsonSerializer</code>. + <br> + For convenience the {@link org.apache.juneau.json.JsonSerializer#getSchemaSerializer()} method has been + added for creating instances of schema serializers from the regular serializer instance. </p> <p> - <i>Note:</i> As of this writing, JSON-Schema has not been standardized, so the output generated by the schema - serializer may be subject to future modifications. + <i>Note:</i> As of this writing, JSON-Schema has not been standardized, so the output generated by the + schema serializer may be subject to future modifications. </p> <p> Lets start with the classes from the previous examples: @@ -518,7 +539,8 @@ JsonSchemaSerializer s = JsonSerializer.<jsf>DEFAULT_LAX_READABLE</jsf>.getSchemaSerializer(); <jc>// Create our bean.</jc> - Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, + <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); Address a = <jk>new</jk> Address(); a.<jf>uri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/address/1";</js>); a.<jf>personUri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/person/1";</js>); @@ -612,16 +634,20 @@ <h3 class='topic' onclick='toggle(this)'>2.4 - Non-tree models and recursion detection</h3> <div class='topic'> <p> - The JSON serializer is designed to be used against POJO tree structures. <br> - It expects that there not be loops in the POJO model (e.g. children with references to parents, etc...).<br> + The JSON serializer is designed to be used against POJO tree structures. + <br> + It expects that there not be loops in the POJO model (e.g. children with references to parents, etc...). + <br> If you try to serialize models with loops, you will usually cause a <code>StackOverflowError</code> to - be thrown (if {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_maxDepth} is not reached first). + be thrown (if {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_maxDepth} is not reached + first). </p> <p> If you still want to use the JSON serializer on such models, Juneau provides the - {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_detectRecursions} setting.<br> - It tells the serializer to look for instances of an object in the current branch of the tree and - skip serialization when a duplicate is encountered. + {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_detectRecursions} setting. + <br> + It tells the serializer to look for instances of an object in the current branch of the tree and skip + serialization when a duplicate is encountered. </p> <p> For example, let's make a POJO model out of the following classes: @@ -670,7 +696,8 @@ Without recursion detection enabled, this would cause a stack-overflow error. </p> <p> - Recursion detection introduces a performance penalty of around 20%.<br> + Recursion detection introduces a performance penalty of around 20%. + <br> For this reason the setting is disabled by default. </p> </div> @@ -695,8 +722,11 @@ <h3 class='topic' onclick='toggle(this)'>2.6 - Other notes</h3> <div class='topic'> <ul class='spaced-list'> - <li>Like all other Juneau serializers, the JSON serializer is thread safe and maintains an internal cache of bean classes encountered.<br> - For performance reasons, it's recommended that serializers be reused whenever possible instead of always creating new instances. + <li>Like all other Juneau serializers, the JSON serializer is thread safe and maintains an internal cache + of bean classes encountered. + <br> + For performance reasons, it's recommended that serializers be reused whenever possible instead of + always creating new instances. </ul> </div> </div> @@ -726,7 +756,8 @@ <li>{@link org.apache.juneau.json.JsonParser#DEFAULT} </ul> <p> - Let's build upon the previous example and parse the generated JSON back into the original bean.<br> + Let's build upon the previous example and parse the generated JSON back into the original bean. + <br> We start with the JSON that was generated. </p> <p class='bcode'> @@ -734,7 +765,8 @@ JsonSerializer s = JsonSerializer.<jsf>DEFAULT_LAX_READABLE</jsf>; <jc>// Create our bean.</jc> - Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, + <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); Address a = <jk>new</jk> Address(); a.<jf>uri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/address/1";</js>); a.<jf>personUri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/person/1";</js>); @@ -814,22 +846,25 @@ <h3 class='topic' onclick='toggle(this)'>3.1 - Parsing into generic POJO models</h3> <div class='topic'> <p> - The JSON parser is not limited to parsing back into the original bean classes.<br> + The JSON parser is not limited to parsing back into the original bean classes. + <br> If the bean classes are not available on the parsing side, the parser can also be used to - parse into a generic model consisting of <code>Maps</code>, <code>Collections</code>, and primitive - objects. + parse into a generic model consisting of <code>Maps</code>, <code>Collections</code>, and primitive + objects. </p> <p> You can parse into any <code>Map</code> type (e.g. <code>HashMap</code>, <code>TreeMap</code>), but - using {@link org.apache.juneau.ObjectMap} is recommended since it has many convenience methods - for converting values to various types.<br> - The same is true when parsing collections. You can use any Collection (e.g. <code>HashSet</code>, <code>LinkedList</code>) - or array (e.g. <code>Object[]</code>, <code>String[]</code>, <code>String[][]</code>), but using - {@link org.apache.juneau.ObjectList} is recommended. + using {@link org.apache.juneau.ObjectMap} is recommended since it has many convenience methods + for converting values to various types. + <br> + The same is true when parsing collections. You can use any Collection (e.g. <code>HashSet</code>, + <code>LinkedList</code>) or array (e.g. <code>Object[]</code>, <code>String[]</code>, + <code>String[][]</code>), but using {@link org.apache.juneau.ObjectList} is recommended. </p> <p> - When the map or list type is not specified, or is the abstract <code>Map</code>, <code>Collection</code>, or <code>List</code> types, - the parser will use <code>ObjectMap</code> and <code>ObjectList</code> by default. + When the map or list type is not specified, or is the abstract <code>Map</code>, <code>Collection</code>, + or <code>List</code> types, the parser will use <code>ObjectMap</code> and <code>ObjectList</code> by + default. </p> <p> Starting back with our original JSON: @@ -866,9 +901,10 @@ String json = JsonSerializer.<jsf>DEFAULT_LAX_READABLE</jsf>.serialize(m); </p> <p> - What we end up with is the exact same output.<br> - Even the numbers and booleans are preserved because they are parsed into <code>Number</code> and <code>Boolean</code> objects - when parsing into generic models. + What we end up with is the exact same output. + <br> + Even the numbers and booleans are preserved because they are parsed into <code>Number</code> and + <code>Boolean</code> objects when parsing into generic models. </p> <p class='bcode'> { @@ -918,7 +954,8 @@ </p> <p> - As a general rule, parsing into beans is often more efficient than parsing into generic models.<br> + As a general rule, parsing into beans is often more efficient than parsing into generic models. + <br> And working with beans is often less error prone than working with generic models. </p> </div> @@ -943,415 +980,15 @@ <h3 class='topic' onclick='toggle(this)'>3.3 - Other notes</h3> <div class='topic'> <ul class='spaced-list'> - <li>Like all other Juneau parsers, the JSON parser is thread safe and maintains an internal cache of bean classes encountered.<br> - For performance reasons, it's recommended that parser be reused whenever possible instead of always creating new instances. + <li>Like all other Juneau parsers, the JSON parser is thread safe and maintains an internal cache of bean + classes encountered. + <br> + For performance reasons, it's recommended that parser be reused whenever possible instead of always + creating new instances. </ul> </div> </div> - - -<!-- ======================================================================================================== --> -<a id="RestApiSupport"></a> -<h2 class='topic' onclick='toggle(this)'>4 - REST API support</h2> -<div class='topic'> - <p> - Juneau provides fully-integrated support for JSON serialization/parsing in the REST server and client APIs.<br> - The next two sections describe these in detail. - </p> - - <!-- ======================================================================================================== --> - <a id="RestServerSupport"></a> - <h3 class='topic' onclick='toggle(this)'>4.1 - REST server support</h3> - <div class='topic'> - <p> - There are four general ways of defining REST interfaces with support for JSON. - Two using the built-in Juneau Server API, and two using the JAX-RS integration component. - </p> - <ul class='spaced-list'> - <li>Create a servlet that subclasses from {@link org.apache.juneau.rest.RestServletDefault}.<br> - This includes JSON serialization/parsing support by default, in addition to several other media types. - <li>Create a servlet that subclasses from {@link org.apache.juneau.rest.RestServlet} and specify the - a JSON serializer and/or parser using the {@link org.apache.juneau.rest.annotation.RestResource#serializers()} and - {@link org.apache.juneau.rest.annotation.RestResource#parsers()} on the entire servlet class, or - the {@link org.apache.juneau.rest.annotation.RestMethod#serializers()} and {@link org.apache.juneau.rest.annotation.RestMethod#parsers()} - annotations on individual methods within the class. - <li>Register {@link org.apache.juneau.rest.jaxrs.DefaultProvider} with JAX-RS.<br> - This includes JSON serialization/parsing support by default, in addition to several other media types. - <li>Create and register a subclass of {@link org.apache.juneau.rest.jaxrs.BaseProvider} and specify the serializers and parsers to use on JAX-RS resources. - </ul> - <p> - In general, the Juneau REST server API is much more configurable and easier to use than JAX-RS, but beware that the author may be slightly biased in this statement. - </p> - - <!-- ======================================================================================================== --> - <a id="RestServletDefault"></a> - <h4 class='topic' onclick='toggle(this)'>4.1.1 - Using RestServletDefault</h4> - <div class='topic'> - <p> - The quickest way to implement a REST resource with JSON support is to create a subclass of {@link org.apache.juneau.rest.RestServletDefault}.<br> - This class provides support for JSON, XML, HTML, URL-Encoding, and others. - </p> - <p> - The <code>AddressBookResource</code> example shown in the first chapter uses the <code>RestServletJenaDefault</code> class - which is a subclass of <code>RestServletDefault</code> with additional support for RDF languages.<br> - The start of the class definition is shown below: - </p> - <p class='bcode'> - <jc>// Proof-of-concept resource that shows off the capabilities of working with POJO resources. - // Consists of an in-memory address book repository.</jc> - <ja>@RestResource</ja>( - messages=<js>"nls/AddressBookResource"</js>, - title=<js>"$L{title}"</js>, - description=<js>"$L{description}"</js>, - htmldoc=<ja>@HtmlDoc</ja>( - links=<js>"{options:'?method=OPTIONS'}"</js> - ), - properties={ - <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>), - <ja>@Property</ja>(name=HtmlSerializerContext.<jsf>HTML_uriAnchorText</jsf>, value=<jsf>TO_STRING</jsf>) - }, - encoders=GzipEncoder.<jk>class</jk> - ) - <jk>public class</jk> AddressBookResource <jk>extends</jk> RestServletJenaDefault { - </p> - <p> - Notice how serializer and parser properties can be specified using the <code>@RestResource.properties()</code> annotation.<br> - The <jsf>SERIALIZER_quoteChar</jsf> is a property common to all serializers, including the JSON serializer. - The remaining properties are specific to the HTML serializer. - </p> - <p> - The <code>$L{...}</code> variable represent localized strings pulled from the resource bundle identified by the <code>messages</code> annotation. - These variables are replaced at runtime based on the HTTP request locale. - Several built-in runtime variable types are defined, and the API can be extended to include user-defined variables. - See {@link org.apache.juneau.rest.RestContext#getVarResolver()} for more information. - </p> - <p> - This document won't go into all the details of the Juneau <code>RestServlet</code> class.<br> - Refer to the <a class='doclink' href='../rest/package-summary.html#TOC'>org.apache.juneau.rest</a> documentation for more information on the REST servlet class in general. - </p> - <p> - The rest of the code in the resource class consists of REST methods that simply accept and return POJOs.<br> - The framework takes care of all content negotiation, serialization/parsing, and error handling.<br> - Below are 3 of those methods to give you a general idea of the concept: - </p> - <p class='bcode'> - <jc>// GET person request handler</jc> - <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/people/{id}/*"</js>, rc={200,404}) - <jk>public</jk> Person getPerson(RestRequest req, RestResponse res, <ja>@Path</ja> <jk>int</jk> id) throws Exception { - res.setPageTitle(req.getPathInfo()); - <jk>return</jk> findPerson(id); - } - - <jc>// POST person handler</jc> - <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/people"</js>, guards=AdminGuard.<jk>class</jk>, rc={307,404}) - <jk>public void</jk> createPerson(RestResponse res, <ja>@Body</ja> CreatePerson cp) <jk>throws</jk> Exception { - Person p = addressBook.createPerson(cp); - res.sendRedirect(p.<jf>uri</jf>); - } - - <jc>// DELETE person handler</jc> - <ja>@RestMethod</ja>(name=<js>"DELETE"</js>, path=<js>"/people/{id}"</js>, guards=AdminGuard.<jk>class</jk>, rc={200,404}) - <jk>public</jk> String deletePerson(RestResponse res, <ja>@Path</ja> <jk>int</jk> id) <jk>throws</jk> Exception { - Person p = findPerson(id); - addressBook.remove(p); - <jk>return</jk> <js>"DELETE successful"</js>; - } - </p> - <p> - The resource class can be registered with the web application like any other servlet, or can be - defined as a child of another resource through the {@link org.apache.juneau.rest.annotation.RestResource#children()} annotation. - </div> - - <!-- ======================================================================================================== --> - <a id="RestServlet"></a> - <h4 class='topic' onclick='toggle(this)'>4.1.2 - Using RestServlet with annotations</h4> - <div class='topic'> - <p> - For fine-tuned control of media types, the {@link org.apache.juneau.rest.RestServlet} class - can be subclassed directly.<br> - The serializers/parsers can be specified through annotations at the class and/or method levels. - </p> - <p> - An equivalent <code>AddressBookResource</code> class could be defined to only support JSON using - the following definition: - </p> - <p class='bcode'> - <ja>@RestResource</ja>( - serializers={JsonSerializer.<jk>class</jk>}, - parsers={JsonParser.<jk>class</jk>}, - properties={ - <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>) - } - ) - <jk>public class</jk> AddressBookResource <jk>extends</jk> RestServlet { - </p> - <p> - Likewise, serializers and parsers can be specified/augmented/overridden at the method level like so: - </p> - <p class='bcode'> - <jc>// GET person request handler</jc> - <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/people/{id}/*"</js>, rc={200,404}, - serializers={JsonSerializer.<jk>class</jk>}, - parsers={JsonParser.<jk>class</jk>}, - properties={ - <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>) - } - ) - <jk>public</jk> Person getPerson(RestRequest req, RestResponse res, <ja>@Path</ja> <jk>int</jk> id) throws Exception { - res.setPageTitle(req.getPathInfo()); - <jk>return</jk> findPerson(id); - } - </p> - <p> - The {@link org.apache.juneau.rest.annotation.RestMethod#serializersInherit()} and - {@link org.apache.juneau.rest.annotation.RestMethod#parsersInherit()} control how various artifacts - are inherited from the parent class.<br> - Refer to <a class='doclink' href='../rest/package-summary.html#TOC'>org.apache.juneau.rest</a> for additional information on using these annotations. - </p> - </div> - - <!-- ======================================================================================================== --> - <a id="DefaultProvider"></a> - <h4 class='topic' onclick='toggle(this)'>4.1.3 - Using JAX-RS DefaultProvider</h4> - <div class='topic'> - <p> - JSON media type support in JAX-RS can be achieved by using the {@link org.apache.juneau.rest.jaxrs.DefaultProvider} class.<br> - It implements the JAX-RS <code>MessageBodyReader</code> and <code>MessageBodyWriter</code> interfaces for all Juneau supported media types. - </p> - <p> - The <code>DefaultProvider</code> class definition is shown below: - </p> - <p class='bcode'> - <ja>@Provider</ja> - <ja>@Produces</ja>( - <js>"application/json,text/json,"</js>+ <jc>// JsonSerializer</jc> - <js>"application/json+simple,text/json+simple"</js>+ <jc>// JsonSerializer.Simple</jc> - <js>"application/json+schema,text/json+schema"</js>+ <jc>// JsonSchemaSerializer</jc> - <js>"text/xml"</js>+ <jc>// XmlDocSerializer</jc> - <js>"text/xml+simple"</js>+ <jc>// XmlDocSerializer.Simple</jc> - <js>"text/xml+schema"</js>+ <jc>// XmlSchemaDocSerializer</jc> - <js>"text/html"</js>+ <jc>// HtmlDocSerializer</jc> - <js>"application/x-www-form-urlencoded"</js>+ <jc>// UrlEncodingSerializer</jc> - <js>"text/xml+soap"</js>+ <jc>// SoapXmlSerializer</jc> - <js>"application/x-java-serialized-object"</js> <jc>// JavaSerializedObjectSerializer</jc> - ) - <ja>@Consumes</ja>( - <js>"application/json,text/json,"</js>+ <jc>// JsonParser</jc> - <js>"text/xml,"</js>+ <jc>// XmlParser</jc> - <js>"text/html,"</js>+ <jc>// HtmlParser</jc> - <js>"application/x-www-form-urlencoded,"</js>+ <jc>// UrlEncodingParser</jc> - <js>"application/x-java-serialized-object"</js> <jc>// JavaSerializedObjectParser</jc> - ) - <ja>@JuneauProvider</ja>( - serializers={ - JsonSerializer.<jk>class</jk>, - JsonSerializer.Simple.<jk>class</jk>, - JsonSchemaSerializer.<jk>class</jk>, - XmlDocSerializer.<jk>class</jk>, - XmlDocSerializer.Simple.<jk>class</jk>, - XmlSchemaDocSerializer.<jk>class</jk>, - HtmlDocSerializer.<jk>class</jk>, - UrlEncodingSerializer.<jk>class</jk>, - SoapXmlSerializer.<jk>class</jk>, - JavaSerializedObjectSerializer.<jk>class</jk> - }, - parsers={ - JsonParser.<jk>class</jk>, - XmlParser.<jk>class</jk>, - HtmlParser.<jk>class</jk>, - UrlEncodingParser.<jk>class</jk>, - JavaSerializedObjectParser.<jk>class</jk>, - } - ) - <jk>public final class</jk> DefaultProvider <jk>extends</jk> BaseProvider {} - </p> - <p> - That's the entire class. It consists of only annotations to hook up media types to Juneau serializers and parsers. - The <ja>@Provider</ja>, <ja>@Produces</ja>, and <ja>@Consumes</ja> annotations are standard JAX-RS annotations, and the <ja>@JuneauProvider</ja> annotation is from Juneau. - </p> - <p> - To enable the provider, you need to make the JAX-RS environment aware of it. - In Wink, this is accomplished by adding an entry to a config file. - </p> - <p class='bcode'> - <xt><web-app</xt> <xa>version</xa>=<xs>"2.3"</xs><xt>></xt> - <xt><servlet></xt> - <xt><servlet-name></xt>WinkService<xt></servlet-name></xt> - <xt><servlet-class></xt>org.apache.wink.server.internal.servlet.RestServlet<xt></servlet-class></xt> - <xt><init-param></xt> - <xt><param-name></xt>applicationConfigLocation<xt></param-name></xt> - <xt><param-value></xt>/WEB-INF/wink.cfg<xt></param-value></xt> - <xt></init-param></xt> - <xt></servlet></xt> - </p> - <p> - Simply include a reference to the provider in the configuration file. - <p class='bcode'> - org.apache.juneau.rest.jaxrs.DefaultProvider - </p> - <p> - Properties can be specified on providers through the {@link org.apache.juneau.rest.jaxrs.JuneauProvider#properties()} annotation.<br> - Properties can also be specified at the method level by using the {@link org.apache.juneau.rest.annotation.RestMethod#properties} annotation, like so: - </p> - <p class='bcode'> - <ja>@GET</ja> - <ja>@Produces</ja>(<js>"*/*"</js>) - <ja>@RestMethod</ja>( <jc>/* Override some properties */</jc> - properties={ - <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>) - } - ) - <jk>public</jk> Message getMessage() { - <jk>return</jk> message; - } - </p> - <h6 class='topic'>Limitations</h6> - <p> - In general, the Juneau REST API is considerably more flexible than the JAX-RS API, since you can specify and override - serializers, parsers, properties, transforms, converters, guards, etc... at both the class and method levels.<br> - Therefore, the JAX-RS API has the following limitations that the Juneau Server API does not: - </p> - <ul class='spaced-list'> - <li>The ability to specify different media type providers at the class and method levels.<br> - For example, you may want to use <code>JsonSerializer</code> with one set of properties on - one class, and another instance with different properties on another class.<br> - There is currently no way to define this at the class level.<br> - You can override properties at the method level, but this can be cumbersome since it would have to be - done for all methods in the resource. - <li>The Juneau Server API allows you to manipulate properties programatically through the {@link org.apache.juneau.rest.RestResponse#setProperty(String,Object)} - method, and through the {@link org.apache.juneau.rest.annotation.Properties} annotation.<br> - There is no equivalent in JAX-RS. - </ul> - </div> - - <!-- ======================================================================================================== --> - <a id="BaseProvider"></a> - <h4 class='topic' onclick='toggle(this)'>4.1.4 - Using JAX-RS BaseProvider with annotations</h4> - <div class='topic'> - <p> - To provide support for only JSON media types, you can define your own provider class, like so: - </p> - <p class='bcode'> - <ja>@Provider</ja> - <ja>@Produces</ja>( - <js>"application/json,text/json,"</js>+ <jc>// JsonSerializer</jc> - <js>"application/json+simple,text/json+simple,"</js>+ <jc>// JsonSerializer.Simple</jc> - <js>"application/json+schema,text/json+schema"</js> <jc>// JsonSchemaSerializer</jc> - ) - <ja>@Consumes</ja>( - <js>"application/json,text/json"</js> <jc>// JsonParser</jc> - ) - <ja>@JuneauProvider</ja>( - serializers={ - JsonSerializer.<jk>class</jk>, - JsonSerializer.Simple.<jk>class</jk>, - JsonSchemaSerializer.<jk>class</jk>, - }, - parsers={ - JsonParser.<jk>class</jk>, - } - properties={ - <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>) - } - ) - <jk>public final class</jk> MyRdfProvider <jk>extends</jk> BaseProvider {} - </p> - <p> - Then register it with Wink the same way as <code>DefaultProvider</code>. - </p> - </div> - - </div> - - <!-- ======================================================================================================== --> - <a id="RestClientSupport"></a> - <h3 class='topic' onclick='toggle(this)'>4.2 - REST client support</h3> - <div class='topic'> - <p> - The {@link org.apache.juneau.rest.client.RestClient} class provides an easy-to-use REST client interface with - pluggable media type handling using any of the Juneau serializers and parsers.<br> - Defining a client to support JSON media types on HTTP requests and responses can be done in one line of code: - </p> - <p class='bcode'> - <jc>// Create a client to handle JSON requests and responses.</jc> - RestClient client = <jk>new</jk> RestClientBuilder().build(); - </p> - <p> - The client handles all content negotiation based on the registered serializers and parsers. - </p> - <p> - The following code is pulled from the main method of the <code>ClientTest</code> class in the sample web application, and - is run against the <code>AddressBookResource</code> class running within the sample app.<br> - It shows how the client can be used to interact with the REST API while completely hiding the negotiated content type and working with nothing more than beans. - </p> - <h6 class='topic'>Example:</h6> - <p class='bcode'> - String root = <js>"http://localhost:9080/sample/addressBook";</js>; - - <jc>// Get the current contents of the address book</jc> - AddressBook ab = client.doGet(root).getResponse(AddressBook.<jk>class</jk>); - System.<jsm>out</jsm>.println(<js>"Number of entries = "</js> + ab.size()); - - <jc>// Delete the existing entries</jc> - <jk>for</jk> (Person p : ab) { - String r = client.doDelete(p.<jf>uri</jf>).getResponse(String.<jk>class</jk>); - System.<jsm>out</jsm>.println(<js>"Deleted person "</js> + p.<jf>name</jf> + <js>", response = "</js> + r); - } - - <jc>// Make sure they're gone</jc> - ab = client.doGet(root).getResponse(AddressBook.<jk>class</jk>); - System.<jsm>out</jsm>.println(<js>"Number of entries = "</js> + ab.size()); - - <jc>// Add 1st person again</jc> - CreatePerson cp = <jk>new</jk> CreatePerson( - <js>"Barack Obama"</js>, - <jsm>toCalendar</jsm>(<js>"Aug 4, 1961"</js>), - <jk>new</jk> CreateAddress(<js>"1600 Pennsylvania Ave"</js>, <js>"Washington"</js>, <js>"DC"</js>, 20500, <jk>true</jk>), - <jk>new</jk> CreateAddress(<js>"5046 S Greenwood Ave"</js>, <js>"Chicago"</js>, <js>"IL"</js>, 60615, <jk>false</jk>) - ); - Person p = client.doPost(root + <js>"/people"</js>, cp).getResponse(Person.<jk>class</jk>); - System.<jsm>out</jsm>.println(<js>"Created person "</js> + p.<jf>name</jf> + <js>", uri = "</js> + p.<jf>uri</jf>); - - <jc>// Add 2nd person again, but add addresses separately</jc> - cp = <jk>new</jk> CreatePerson( - <js>"George Walker Bush"</js>, - toCalendar(<js>"Jul 6, 1946"</js>) - ); - p = client.doPost(root + <js>"/people"</js>, cp).getResponse(Person.<jk>class</jk>); - System.<jsm>out</jsm>.println(<js>"Created person "</js> + p.<jf>name</jf> + <js>", uri = "</js> + p.<jf>uri</jf>); - - <jc>// Add addresses to 2nd person</jc> - CreateAddress ca = <jk>new</jk> CreateAddress(<js>"43 Prairie Chapel Rd"</js>, <js>"Crawford"</js>, <js>"TX"</js>, 76638, <jk>true</jk>); - Address a = client.doPost(p.<jf>uri</jf> + <js>"/addresses"</js>, ca).getResponse(Address.<jk>class</jk>); - System.<jsm>out</jsm>.println(<js>"Created address "</js> + a.<jf>uri</jf>); - - ca = <jk>new</jk> CreateAddress(<js>"1600 Pennsylvania Ave"</js>, <js>"Washington"</js>, <js>"DC"</js>, 20500, <jk>false</jk>); - a = client.doPost(p.<jf>uri</jf> + "/addresses"</js>, ca).getResponse(Address.<jk>class</jk>); - System.<jsm>out</jsm>.println(<js>"Created address "</js> + a.<jf>uri</jf>); - - <jc>// Find 1st person, and change name</jc> - Person[] pp = client.doGet(root + <js>"?q={name:\"'Barack+Obama'\"}"</js>).getResponse(Person[].<jk>class</jk>); - String r = client.doPut(pp[0].<jf>uri</jf> + <js>"/name"</js>, <js>"Barack Hussein Obama"</js>).getResponse(String.<jk>class</jk>); - System.<jsm>out</jsm>.println(<js>"Changed name, response = "</js> + r); - p = client.doGet(pp[0].<jf>uri</jf>).getResponse(Person.<jk>class</jk>); - System.<jsm>out</jsm>.println(<js>"New name = "</js> + p.<jf>name</jf>); - </p> - <h6 class='figure'>Results</h6> - <p class='bcode'> - Number of entries = 2 - Deleted person Barack Obama, response = DELETE successful - Deleted person George Walker Bush, response = DELETE successful - Number of entries = 0 - Created person Barack Obama, uri = http://localhost:9080/sample/addressBook/people/3 - Created person George Walker Bush, uri = http://localhost:9080/sample/addressBook/people/4 - Created address http://localhost:9080/sample/addressBook/addresses/7 - Created address http://localhost:9080/sample/addressBook/addresses/8 - Changed name, response = PUT successful - New name = Barack Hussein Obama - </p> - </div> -</div> <p align="center"><i><b>*** fÃn ***</b></i></p> </body>
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackInputStream.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackInputStream.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackInputStream.java index a9896dd..13e52ad 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackInputStream.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackInputStream.java @@ -56,6 +56,7 @@ public final class MsgPackInputStream extends InputStream { /** * Constructor. + * * @param is The input stream being wrapped. */ protected MsgPackInputStream(InputStream is) { @@ -171,22 +172,22 @@ public final class MsgPackInputStream extends InputStream { break; } case STRING:{ - // fixstr stores a byte array whose length is upto 31 bytes: + // fixstr stores a byte array whose length is up to 31 bytes: // +--------+========+ // |101XXXXX| data | // +--------+========+ // - // str 8 stores a byte array whose length is upto (2^8)-1 bytes: + // str 8 stores a byte array whose length is up to (2^8)-1 bytes: // +--------+--------+========+ // | 0xd9 |YYYYYYYY| data | // +--------+--------+========+ // - // str 16 stores a byte array whose length is upto (2^16)-1 bytes: + // str 16 stores a byte array whose length is up to (2^16)-1 bytes: // +--------+--------+--------+========+ // | 0xda |ZZZZZZZZ|ZZZZZZZZ| data | // +--------+--------+--------+========+ // - // str 32 stores a byte array whose length is upto (2^32)-1 bytes: + // str 32 stores a byte array whose length is up to (2^32)-1 bytes: // +--------+--------+--------+--------+--------+========+ // | 0xdb |AAAAAAAA|AAAAAAAA|AAAAAAAA|AAAAAAAA| data | // +--------+--------+--------+--------+--------+========+ @@ -208,17 +209,17 @@ public final class MsgPackInputStream extends InputStream { break; } case ARRAY: { - // fixarray stores an array whose length is upto 15 elements: + // fixarray stores an array whose length is up to 15 elements: // +--------+~~~~~~~~~~~~~~~~~+ // |1001XXXX| N objects | // +--------+~~~~~~~~~~~~~~~~~+ // - // array 16 stores an array whose length is upto (2^16)-1 elements: + // array 16 stores an array whose length is up to (2^16)-1 elements: // +--------+--------+--------+~~~~~~~~~~~~~~~~~+ // | 0xdc |YYYYYYYY|YYYYYYYY| N objects | // +--------+--------+--------+~~~~~~~~~~~~~~~~~+ // - // array 32 stores an array whose length is upto (2^32)-1 elements: + // array 32 stores an array whose length is up to (2^32)-1 elements: // +--------+--------+--------+--------+--------+~~~~~~~~~~~~~~~~~+ // | 0xdd |ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ| N objects | // +--------+--------+--------+--------+--------+~~~~~~~~~~~~~~~~~+ @@ -237,17 +238,17 @@ public final class MsgPackInputStream extends InputStream { break; } case BIN:{ - // bin 8 stores a byte array whose length is upto (2^8)-1 bytes: + // bin 8 stores a byte array whose length is up to (2^8)-1 bytes: // +--------+--------+========+ // | 0xc4 |XXXXXXXX| data | // +--------+--------+========+ // - // bin 16 stores a byte array whose length is upto (2^16)-1 bytes: + // bin 16 stores a byte array whose length is up to (2^16)-1 bytes: // +--------+--------+--------+========+ // | 0xc5 |YYYYYYYY|YYYYYYYY| data | // +--------+--------+--------+========+ // - // bin 32 stores a byte array whose length is upto (2^32)-1 bytes: + // bin 32 stores a byte array whose length is up to (2^32)-1 bytes: // +--------+--------+--------+--------+--------+========+ // | 0xc6 |ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ| data | // +--------+--------+--------+--------+--------+========+ @@ -294,17 +295,17 @@ public final class MsgPackInputStream extends InputStream { // data (cont.) | // +--------+--------+--------+--------+--------+--------+--------+--------+ // - // ext 8 stores an integer and a byte array whose length is upto (2^8)-1 bytes: + // ext 8 stores an integer and a byte array whose length is up to (2^8)-1 bytes: // +--------+--------+--------+========+ // | 0xc7 |XXXXXXXX| type | data | // +--------+--------+--------+========+ // - // ext 16 stores an integer and a byte array whose length is upto (2^16)-1 bytes: + // ext 16 stores an integer and a byte array whose length is up to (2^16)-1 bytes: // +--------+--------+--------+--------+========+ // | 0xc8 |YYYYYYYY|YYYYYYYY| type | data | // +--------+--------+--------+--------+========+ // - // ext 32 stores an integer and a byte array whose length is upto (2^32)-1 bytes: + // ext 32 stores an integer and a byte array whose length is up to (2^32)-1 bytes: // +--------+--------+--------+--------+--------+--------+========+ // | 0xc9 |ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ| type | data | // +--------+--------+--------+--------+--------+--------+========+ @@ -337,17 +338,17 @@ public final class MsgPackInputStream extends InputStream { break; } case MAP:{ - // fixmap stores a map whose length is upto 15 elements + // fixmap stores a map whose length is up to 15 elements // +--------+~~~~~~~~~~~~~~~~~+ // |1000XXXX| N*2 objects | // +--------+~~~~~~~~~~~~~~~~~+ // - // map 16 stores a map whose length is upto (2^16)-1 elements + // map 16 stores a map whose length is up to (2^16)-1 elements // +--------+--------+--------+~~~~~~~~~~~~~~~~~+ // | 0xde |YYYYYYYY|YYYYYYYY| N*2 objects | // +--------+--------+--------+~~~~~~~~~~~~~~~~~+ // - // map 32 stores a map whose length is upto (2^32)-1 elements + // map 32 stores a map whose length is up to (2^32)-1 elements // +--------+--------+--------+--------+--------+~~~~~~~~~~~~~~~~~+ // | 0xdf |ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ| N*2 objects | // +--------+--------+--------+--------+--------+~~~~~~~~~~~~~~~~~+ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackOutputStream.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackOutputStream.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackOutputStream.java index 73673dd..778a9f7 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackOutputStream.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackOutputStream.java @@ -32,6 +32,7 @@ public final class MsgPackOutputStream extends OutputStream { /** * Constructor. + * * @param os The output stream being wrapped. */ protected MsgPackOutputStream(OutputStream os) { @@ -187,22 +188,22 @@ public final class MsgPackOutputStream extends OutputStream { */ final MsgPackOutputStream appendString(CharSequence cs) throws IOException { - // fixstr stores a byte array whose length is upto 31 bytes: + // fixstr stores a byte array whose length is up to 31 bytes: // +--------+========+ // |101XXXXX| data | // +--------+========+ // - // str 8 stores a byte array whose length is upto (2^8)-1 bytes: + // str 8 stores a byte array whose length is up to (2^8)-1 bytes: // +--------+--------+========+ // | 0xd9 |YYYYYYYY| data | // +--------+--------+========+ // - // str 16 stores a byte array whose length is upto (2^16)-1 bytes: + // str 16 stores a byte array whose length is up to (2^16)-1 bytes: // +--------+--------+--------+========+ // | 0xda |ZZZZZZZZ|ZZZZZZZZ| data | // +--------+--------+--------+========+ // - // str 32 stores a byte array whose length is upto (2^32)-1 bytes: + // str 32 stores a byte array whose length is up to (2^32)-1 bytes: // +--------+--------+--------+--------+--------+========+ // | 0xdb |AAAAAAAA|AAAAAAAA|AAAAAAAA|AAAAAAAA| data | // +--------+--------+--------+--------+--------+========+ @@ -227,17 +228,17 @@ public final class MsgPackOutputStream extends OutputStream { * Appends a binary field to the stream. */ final MsgPackOutputStream appendBinary(byte[] b) throws IOException { - // bin 8 stores a byte array whose length is upto (2^8)-1 bytes: + // bin 8 stores a byte array whose length is up to (2^8)-1 bytes: // +--------+--------+========+ // | 0xc4 |XXXXXXXX| data | // +--------+--------+========+ // - // bin 16 stores a byte array whose length is upto (2^16)-1 bytes: + // bin 16 stores a byte array whose length is up to (2^16)-1 bytes: // +--------+--------+--------+========+ // | 0xc5 |YYYYYYYY|YYYYYYYY| data | // +--------+--------+--------+========+ // - // bin 32 stores a byte array whose length is upto (2^32)-1 bytes: + // bin 32 stores a byte array whose length is up to (2^32)-1 bytes: // +--------+--------+--------+--------+--------+========+ // | 0xc6 |ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ| data | // +--------+--------+--------+--------+--------+========+ @@ -259,17 +260,17 @@ public final class MsgPackOutputStream extends OutputStream { * Appends an array data type flag to the stream. */ final MsgPackOutputStream startArray(int size) throws IOException { - // fixarray stores an array whose length is upto 15 elements: + // fixarray stores an array whose length is up to 15 elements: // +--------+~~~~~~~~~~~~~~~~~+ // |1001XXXX| N objects | // +--------+~~~~~~~~~~~~~~~~~+ // - // array 16 stores an array whose length is upto (2^16)-1 elements: + // array 16 stores an array whose length is up to (2^16)-1 elements: // +--------+--------+--------+~~~~~~~~~~~~~~~~~+ // | 0xdc |YYYYYYYY|YYYYYYYY| N objects | // +--------+--------+--------+~~~~~~~~~~~~~~~~~+ // - // array 32 stores an array whose length is upto (2^32)-1 elements: + // array 32 stores an array whose length is up to (2^32)-1 elements: // +--------+--------+--------+--------+--------+~~~~~~~~~~~~~~~~~+ // | 0xdd |ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ| N objects | // +--------+--------+--------+--------+--------+~~~~~~~~~~~~~~~~~+ @@ -291,17 +292,17 @@ public final class MsgPackOutputStream extends OutputStream { * Appends a map data type flag to the stream. */ final MsgPackOutputStream startMap(int size) throws IOException { - // fixmap stores a map whose length is upto 15 elements + // fixmap stores a map whose length is up to 15 elements // +--------+~~~~~~~~~~~~~~~~~+ // |1000XXXX| N*2 objects | // +--------+~~~~~~~~~~~~~~~~~+ // - // map 16 stores a map whose length is upto (2^16)-1 elements + // map 16 stores a map whose length is up to (2^16)-1 elements // +--------+--------+--------+~~~~~~~~~~~~~~~~~+ // | 0xde |YYYYYYYY|YYYYYYYY| N*2 objects | // +--------+--------+--------+~~~~~~~~~~~~~~~~~+ // - // map 32 stores a map whose length is upto (2^32)-1 elements + // map 32 stores a map whose length is up to (2^32)-1 elements // +--------+--------+--------+--------+--------+~~~~~~~~~~~~~~~~~+ // | 0xdf |ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ|ZZZZZZZZ| N*2 objects | // +--------+--------+--------+--------+--------+~~~~~~~~~~~~~~~~~+ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParser.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParser.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParser.java index b02ee46..1eb1a92 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParser.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParser.java @@ -49,6 +49,7 @@ public class MsgPackParser extends InputStreamParser { /** * Constructor. + * * @param propertyStore The property store containing all the settings for this object. */ public MsgPackParser(PropertyStore propertyStore) { @@ -64,7 +65,8 @@ public class MsgPackParser extends InputStreamParser { /** * Workhorse method. */ - private <T> T parseAnything(MsgPackParserSession session, ClassMeta<T> eType, MsgPackInputStream is, Object outer, BeanPropertyMeta pMeta) throws Exception { + private <T> T parseAnything(MsgPackParserSession session, ClassMeta<T> eType, MsgPackInputStream is, Object outer, + BeanPropertyMeta pMeta) throws Exception { if (eType == null) eType = (ClassMeta<T>)object(); @@ -154,7 +156,11 @@ public class MsgPackParser extends InputStreamParser { m.put(parseAnything(session, string(), is, outer, pMeta), parseAnything(session, object(), is, m, pMeta)); o = session.cast(m, pMeta, eType); } else if (dt == ARRAY) { - Collection l = (sType.canCreateNewInstance(outer) ? (Collection)sType.newInstance() : new ObjectList(session)); + Collection l = ( + sType.canCreateNewInstance(outer) + ? (Collection)sType.newInstance() + : new ObjectList(session) + ); for (int i = 0; i < length; i++) l.add(parseAnything(session, sType.getElementType(), is, l, pMeta)); o = l; @@ -168,7 +174,11 @@ public class MsgPackParser extends InputStreamParser { m.put(parseAnything(session, string(), is, outer, pMeta), parseAnything(session, object(), is, m, pMeta)); o = session.cast(m, pMeta, eType); } else if (dt == ARRAY) { - Collection l = (sType.isCollection() && sType.canCreateNewInstance(outer) ? (Collection)sType.newInstance() : new ObjectList(session)); + Collection l = ( + sType.isCollection() && sType.canCreateNewInstance(outer) + ? (Collection)sType.newInstance() + : new ObjectList(session) + ); for (int i = 0; i < length; i++) l.add(parseAnything(session, sType.isArgs() ? sType.getArg(i) : sType.getElementType(), is, l, pMeta)); o = session.toArray(sType, l); @@ -182,7 +192,8 @@ public class MsgPackParser extends InputStreamParser { if (m.containsKey(session.getBeanTypePropertyName(eType))) o = session.cast(m, pMeta, eType); else - throw new ParseException(session, "Class ''{0}'' could not be instantiated. Reason: ''{1}''", sType.getInnerClass().getName(), sType.getNotABeanReason()); + throw new ParseException(session, "Class ''{0}'' could not be instantiated. Reason: ''{1}''", + sType.getInnerClass().getName(), sType.getNotABeanReason()); } else { throw new ParseException(session, "Invalid data type {0} encountered for parse type {1}", dt, sType); } @@ -203,7 +214,8 @@ public class MsgPackParser extends InputStreamParser { //-------------------------------------------------------------------------------- @Override /* Parser */ - public MsgPackParserSession createSession(Object input, ObjectMap op, Method javaMethod, Object outer, Locale locale, TimeZone timeZone, MediaType mediaType) { + public MsgPackParserSession createSession(Object input, ObjectMap op, Method javaMethod, Object outer, + Locale locale, TimeZone timeZone, MediaType mediaType) { return new MsgPackParserSession(ctx, op, input, javaMethod, outer, locale, timeZone, mediaType); } http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserBuilder.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserBuilder.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserBuilder.java index de0744c..b364222 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserBuilder.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserBuilder.java @@ -32,6 +32,7 @@ public class MsgPackParserBuilder extends ParserBuilder { /** * Constructor. + * * @param propertyStore The initial configuration settings for this builder. */ public MsgPackParserBuilder(PropertyStore propertyStore) { http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserContext.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserContext.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserContext.java index 1fdaed1..aa83954 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserContext.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserContext.java @@ -25,9 +25,11 @@ import org.apache.juneau.parser.*; * * <h6 class='topic'>Inherited configurable properties</h6> * <ul class='doctree'> - * <li class='jc'><a class="doclink" href="../BeanContext.html#ConfigProperties">BeanContext</a> - Properties associated with handling beans on serializers and parsers. + * <li class='jc'><a class="doclink" href="../BeanContext.html#ConfigProperties">BeanContext</a> + * - Properties associated with handling beans on serializers and parsers. * <ul> - * <li class='jc'><a class="doclink" href="../parser/ParserContext.html#ConfigProperties">ParserContext</a> - Configurable properties common to all parsers. + * <li class='jc'><a class="doclink" href="../parser/ParserContext.html#ConfigProperties">ParserContext</a> + * - Configurable properties common to all parsers. * </ul> * </ul> */ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserSession.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserSession.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserSession.java index 57beda3..170e165 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserSession.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackParserSession.java @@ -52,7 +52,8 @@ public final class MsgPackParserSession extends ParserSession { * If <jk>null</jk>, then the timezone defined on the context is used. * @param mediaType The session media type (e.g. <js>"application/json"</js>). */ - public MsgPackParserSession(MsgPackParserContext ctx, ObjectMap op, Object input, Method javaMethod, Object outer, Locale locale, TimeZone timeZone, MediaType mediaType) { + public MsgPackParserSession(MsgPackParserContext ctx, ObjectMap op, Object input, Method javaMethod, Object outer, + Locale locale, TimeZone timeZone, MediaType mediaType) { super(ctx, op, input, javaMethod, outer, locale, timeZone, mediaType); } http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java index 0f4949c..85f6708 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializer.java @@ -50,6 +50,7 @@ public class MsgPackSerializer extends OutputStreamSerializer { /** * Constructor. + * * @param propertyStore The property store containing all the settings for this object. */ public MsgPackSerializer(PropertyStore propertyStore) { @@ -63,11 +64,12 @@ public class MsgPackSerializer extends OutputStreamSerializer { } /** - * Workhorse method. Determines the type of object, and then calls the - * appropriate type-specific serialization method. + * Workhorse method. Determines the type of object, and then calls the appropriate type-specific serialization + * method. */ @SuppressWarnings({ "rawtypes", "unchecked" }) - MsgPackOutputStream serializeAnything(MsgPackSerializerSession session, MsgPackOutputStream out, Object o, ClassMeta<?> eType, String attrName, BeanPropertyMeta pMeta) throws Exception { + MsgPackOutputStream serializeAnything(MsgPackSerializerSession session, MsgPackOutputStream out, Object o, + ClassMeta<?> eType, String attrName, BeanPropertyMeta pMeta) throws Exception { if (o == null) return out.appendNull(); @@ -132,7 +134,8 @@ public class MsgPackSerializer extends OutputStreamSerializer { } @SuppressWarnings({ "rawtypes", "unchecked" }) - private void serializeMap(MsgPackSerializerSession session, MsgPackOutputStream out, Map m, ClassMeta<?> type) throws Exception { + private void serializeMap(MsgPackSerializerSession session, MsgPackOutputStream out, Map m, ClassMeta<?> type) + throws Exception { ClassMeta<?> keyType = type.getKeyType(), valueType = type.getValueType(); @@ -155,7 +158,8 @@ public class MsgPackSerializer extends OutputStreamSerializer { } } - private void serializeBeanMap(MsgPackSerializerSession session, MsgPackOutputStream out, final BeanMap<?> m, String typeName) throws Exception { + private void serializeBeanMap(MsgPackSerializerSession session, MsgPackOutputStream out, final BeanMap<?> m, + String typeName) throws Exception { List<BeanPropertyValue> values = m.getValues(session.isTrimNulls(), typeName != null ? session.createBeanTypeNameProperty(m, typeName) : null); @@ -191,7 +195,8 @@ public class MsgPackSerializer extends OutputStreamSerializer { } @SuppressWarnings({"rawtypes", "unchecked"}) - private void serializeCollection(MsgPackSerializerSession session, MsgPackOutputStream out, Collection c, ClassMeta<?> type) throws Exception { + private void serializeCollection(MsgPackSerializerSession session, MsgPackOutputStream out, Collection c, + ClassMeta<?> type) throws Exception { ClassMeta<?> elementType = type.getElementType(); List<Object> l = new ArrayList<Object>(c.size()); @@ -211,7 +216,8 @@ public class MsgPackSerializer extends OutputStreamSerializer { //-------------------------------------------------------------------------------- @Override /* Serializer */ - public MsgPackSerializerSession createSession(Object output, ObjectMap op, Method javaMethod, Locale locale, TimeZone timeZone, MediaType mediaType, UriContext uriContext) { + public MsgPackSerializerSession createSession(Object output, ObjectMap op, Method javaMethod, Locale locale, + TimeZone timeZone, MediaType mediaType, UriContext uriContext) { return new MsgPackSerializerSession(ctx, op, output, javaMethod, locale, timeZone, mediaType, uriContext); } http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerBuilder.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerBuilder.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerBuilder.java index 330ad04..19a33d2 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerBuilder.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerBuilder.java @@ -32,6 +32,7 @@ public class MsgPackSerializerBuilder extends SerializerBuilder { /** * Constructor. + * * @param propertyStore The initial configuration settings for this builder. */ public MsgPackSerializerBuilder(PropertyStore propertyStore) { http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerContext.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerContext.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerContext.java index 975acee..93348da 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerContext.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerContext.java @@ -25,9 +25,12 @@ import org.apache.juneau.serializer.*; * * <h6 class='topic'>Inherited configurable properties</h6> * <ul class='doctree'> - * <li class='jc'><a class="doclink" href="../BeanContext.html#ConfigProperties">BeanContext</a> - Properties associated with handling beans on serializers and parsers. + * <li class='jc'><a class="doclink" href="../BeanContext.html#ConfigProperties">BeanContext</a> + * - Properties associated with handling beans on serializers and parsers. * <ul> - * <li class='jc'><a class="doclink" href="../serializer/SerializerContext.html#ConfigProperties">SerializerContext</a> - Configurable properties common to all serializers. + * <li class='jc'><a class="doclink" + * href="../serializer/SerializerContext.html#ConfigProperties">SerializerContext</a> + * - Configurable properties common to all serializers. * </ul> * </ul> */ @@ -43,9 +46,11 @@ public final class MsgPackSerializerContext extends SerializerContext { * <li><b>Session-overridable:</b> <jk>true</jk> * </ul> * <p> - * If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred through reflection. + * If <jk>true</jk>, then <js>"_type"</js> properties will be added to beans if their type cannot be inferred + * through reflection. * This is used to recreate the correct objects during parsing if the object types cannot be inferred. - * For example, when serializing a {@code Map<String,Object>} field, where the bean class cannot be determined from the value type. + * For example, when serializing a {@code Map<String,Object>} field, where the bean class cannot be determined from + * the value type. * <p> * When present, this value overrides the {@link SerializerContext#SERIALIZER_addBeanTypeProperties} setting and is * provided to customize the behavior of specific serializers in a {@link SerializerGroup}. @@ -64,7 +69,8 @@ public final class MsgPackSerializerContext extends SerializerContext { */ public MsgPackSerializerContext(PropertyStore ps) { super(ps); - addBeanTypeProperties = ps.getProperty(MSGPACK_addBeanTypeProperties, boolean.class, ps.getProperty(SERIALIZER_addBeanTypeProperties, boolean.class, true)); + addBeanTypeProperties = ps.getProperty(MSGPACK_addBeanTypeProperties, boolean.class, + ps.getProperty(SERIALIZER_addBeanTypeProperties, boolean.class, true)); } @Override /* Context */ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerSession.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerSession.java b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerSession.java index 5cf5897..9a489d8 100644 --- a/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerSession.java +++ b/juneau-core/src/main/java/org/apache/juneau/msgpack/MsgPackSerializerSession.java @@ -36,20 +36,21 @@ public final class MsgPackSerializerSession extends SerializerSession { * Create a new session using properties specified in the context. * * @param ctx The context creating this session object. - * The context contains all the configuration settings for this object. + * The context contains all the configuration settings for this object. * @param output The output object. See {@link JsonSerializerSession#getOutputStream()} for valid class types. * @param op The override properties. - * These override any context properties defined in the context. + * These override any context properties defined in the context. * @param javaMethod The java method that called this serializer, usually the method in a REST servlet. * @param locale The session locale. - * If <jk>null</jk>, then the locale defined on the context is used. + * If <jk>null</jk>, then the locale defined on the context is used. * @param timeZone The session timezone. - * If <jk>null</jk>, then the timezone defined on the context is used. + * If <jk>null</jk>, then the timezone defined on the context is used. * @param mediaType The session media type (e.g. <js>"application/json"</js>). * @param uriContext The URI context. - * Identifies the current request URI used for resolution of URIs to absolute or root-relative form. + * Identifies the current request URI used for resolution of URIs to absolute or root-relative form. */ - protected MsgPackSerializerSession(MsgPackSerializerContext ctx, ObjectMap op, Object output, Method javaMethod, Locale locale, TimeZone timeZone, MediaType mediaType, UriContext uriContext) { + protected MsgPackSerializerSession(MsgPackSerializerContext ctx, ObjectMap op, Object output, Method javaMethod, + Locale locale, TimeZone timeZone, MediaType mediaType, UriContext uriContext) { super(ctx, op, output, javaMethod, locale, timeZone, mediaType, uriContext); if (op == null || op.isEmpty()) { addBeanTypeProperties = ctx.addBeanTypeProperties; http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/package.html ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/package.html b/juneau-core/src/main/java/org/apache/juneau/package.html index 5200d49..3c84aa1 100644 --- a/juneau-core/src/main/java/org/apache/juneau/package.html +++ b/juneau-core/src/main/java/org/apache/juneau/package.html @@ -71,12 +71,16 @@ <h2 class='topic' onclick='toggle(this)'>1 - Bean Context API</h2> <div class='topic'> <p> - The {@link org.apache.juneau.BeanContext} class is the core class in the Juneau architecture. It serves multiple functions... + The {@link org.apache.juneau.BeanContext} class is the core class in the Juneau architecture. It serves + multiple functions... </p> <ul class='normal'> <li>It provides the ability to create instances of {@link org.apache.juneau.BeanMap BeanMaps}. - <li>It serves as a repository for {@link org.apache.juneau.transform.BeanFilter BeanFilters} and {@link org.apache.juneau.transform.PojoSwap PojoSwaps}, which are used to tailor how Java objects are handled. - <li>It's used by all built-in {@link org.apache.juneau.serializer.Serializer Serializers} and {@link org.apache.juneau.parser.Parser Parsers} for working with POJOs in a consistent way. + <li>It serves as a repository for {@link org.apache.juneau.transform.BeanFilter BeanFilters} and + {@link org.apache.juneau.transform.PojoSwap PojoSwaps}, which are used to tailor how Java objects are + handled. + <li>It's used by all built-in {@link org.apache.juneau.serializer.Serializer Serializers} and + {@link org.apache.juneau.parser.Parser Parsers} for working with POJOs in a consistent way. </ul> <!-- ======================================================================================================== --> @@ -84,17 +88,24 @@ <h3 class='topic' onclick='toggle(this)'>1.1 - The BeanMap class</h3> <div class='topic'> <p> - The {@link org.apache.juneau.BeanMap} class allows you to access the properties of a bean through the familiar {@code Map} interface. - So, for example, you can use the {@code Map.get(key)} method to retrieve a property value in leu of it's getter method, and the {@code Map.put(key, value)} method to set a property value in leu of it's setter method. + The {@link org.apache.juneau.BeanMap} class allows you to access the properties of a bean through the + familiar {@code Map} interface. + So, for example, you can use the {@code Map.get(key)} method to retrieve a property value in lieu of it's + getter method, and the {@code Map.put(key, value)} method to set a property value in lieu of it's + setter method. </p> <p> - The serialization and parsing of beans in Juneau is accomplished by wrapping Java beans inside instances of the class {@code BeanMap}. + The serialization and parsing of beans in Juneau is accomplished by wrapping Java beans inside instances of + the class {@code BeanMap}. </p> <p> - <b>Note:</b> Instances of {@link org.apache.juneau.BeanMap} objects are always retrieved through the {@link org.apache.juneau.BeanContext} class. You cannot instantiate {@code BeanMaps} directly since the rules for defining what constitutes a bean depend on various settings in the bean context. + <b>Note:</b> Instances of {@link org.apache.juneau.BeanMap} objects are always retrieved through the + {@link org.apache.juneau.BeanContext} class. You cannot instantiate {@code BeanMaps} directly since the + rules for defining what constitutes a bean depend on various settings in the bean context. </p> <p> - In general, the performance on using the {@link org.apache.juneau.BeanMap} class to access properties is equivalent to using reflection directly. + In general, the performance on using the {@link org.apache.juneau.BeanMap} class to access properties is + equivalent to using reflection directly. </p> <p> See the {@link org.apache.juneau.BeanMap} javadoc for more information. @@ -106,11 +117,14 @@ <h3 class='topic' onclick='toggle(this)'>1.2 - The BeanContext and BeanSession classes</h3> <div class='topic'> <p> - The {@link org.apache.juneau.BeanContext} and {@link org.apache.juneau.BeanSession} classes are the workhorse class used to wrap Java beans inside {@link org.apache.juneau.BeanMap BeanMaps}. - There are several options provided on the {@link org.apache.juneau.BeanContext} class to tailor the definition of a bean. + The {@link org.apache.juneau.BeanContext} and {@link org.apache.juneau.BeanSession} classes are the + workhorse class used to wrap Java beans inside {@link org.apache.juneau.BeanMap BeanMaps}. + There are several options provided on the {@link org.apache.juneau.BeanContext} class to tailor the + definition of a bean. </p> <p> - The following is a very simple example of how to wrap a bean inside a {@link org.apache.juneau.BeanMap} wrapper and use the wrapper interface to get and set property values on the bean. + The following is a very simple example of how to wrap a bean inside a {@link org.apache.juneau.BeanMap} + wrapper and use the wrapper interface to get and set property values on the bean. In this case, we're using the DEFAULT bean context. </p> <p class='bcode'> @@ -168,19 +182,24 @@ <h3 class='topic' onclick='toggle(this)'>1.3 - Bean annotations</h3> <div class='topic'> <p> - Juneau provides the following annotations that can be used to fine-tune what properties are associated with beans: + Juneau provides the following annotations that can be used to fine-tune what properties are associated with + beans: </p> <ul class='normal'> <li>{@link org.apache.juneau.annotation.Bean} - Fine-tune properties associated with beans. - <li>{@link org.apache.juneau.annotation.BeanProperty} - Fine-tune bean properties (fields / getters / setters). - <li>{@link org.apache.juneau.annotation.BeanConstructor} - Define read-only bean properties that can only be set through constructor arguments. - <li>{@link org.apache.juneau.annotation.BeanIgnore} - Prevent bean classes/methods/fields from being interpreted as bean constructs. + <li>{@link org.apache.juneau.annotation.BeanProperty} - Fine-tune bean properties + (fields / getters / setters). + <li>{@link org.apache.juneau.annotation.BeanConstructor} - Define read-only bean properties that can only + be set through constructor arguments. + <li>{@link org.apache.juneau.annotation.BeanIgnore} - Prevent bean classes/methods/fields from being + interpreted as bean constructs. </ul> <p> These annotations always override the settings defined in the {@link org.apache.juneau.BeanContext} class. </p> <p> - For example, the following bean class will only have one property associated with it, <js>"name"</js>, since it's the only one listed in the list of properties. + For example, the following bean class will only have one property associated with it, <js>"name"</js>, + since it's the only one listed in the list of properties. </p> <p class='bcode'> <jc>// Bean with only one 'name' property</jc> @@ -193,17 +212,23 @@ } </p> <p> - When this bean is serialized using one of the {@link org.apache.juneau.serializer.Serializer Serializers}, the age property will be ignored. + When this bean is serialized using one of the {@link org.apache.juneau.serializer.Serializer Serializers}, + the age property will be ignored. </p> <p> - Using the <ja>@Bean</ja> and <ja>@BeanProperty</ja> annotations, it's also possible to include non-standard properties (for example, getters or setters with non-standard names), or override the names of properties (for example, {@code "Name"} or {@code "fullName"} instead of {@code "name"}). + Using the <ja>@Bean</ja> and <ja>@BeanProperty</ja> annotations, it's also possible to include non-standard + properties (for example, getters or setters with non-standard names), or override the names of properties + (for example, {@code "Name"} or {@code "fullName"} instead of {@code "name"}). </p> <p> - It should be noted that the {@link org.apache.juneau.transform.BeanFilter} class can also be used to exclude properties from beans. + It should be noted that the {@link org.apache.juneau.transform.BeanFilter} class can also be used to + exclude properties from beans. However, only the annotations can be used to include non-standard properties or override property names. </p> <p> - See the {@link org.apache.juneau.annotation.Bean}, {@link org.apache.juneau.annotation.BeanProperty}, {@link org.apache.juneau.annotation.BeanConstructor}, and {@link org.apache.juneau.annotation.BeanIgnore} javadocs for more information. + See the {@link org.apache.juneau.annotation.Bean}, {@link org.apache.juneau.annotation.BeanProperty}, + {@link org.apache.juneau.annotation.BeanConstructor}, and {@link org.apache.juneau.annotation.BeanIgnore} + javadocs for more information. </p> </div> </div> http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/5c4762ee/juneau-core/src/main/java/org/apache/juneau/parser/InputStreamParser.java ---------------------------------------------------------------------- diff --git a/juneau-core/src/main/java/org/apache/juneau/parser/InputStreamParser.java b/juneau-core/src/main/java/org/apache/juneau/parser/InputStreamParser.java index 84a9279..622dd35 100644 --- a/juneau-core/src/main/java/org/apache/juneau/parser/InputStreamParser.java +++ b/juneau-core/src/main/java/org/apache/juneau/parser/InputStreamParser.java @@ -36,6 +36,7 @@ public abstract class InputStreamParser extends Parser { /** * Constructor. + * * @param propertyStore The property store containing all the settings for this object. */ protected InputStreamParser(PropertyStore propertyStore) {
