blob: 1fcc51a8780f83a1594328470ff10ef4cf62a6e6 [file] [log] [blame]
<!--
/***************************************************************************************************************************
* Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
* specific language governing permissions and limitations under the License.
***************************************************************************************************************************/
-->
{updated} Configurable Properties
<p>
Serializers and parsers have a wide variety of configurable properties. They all extend from the
{@link oaj.BeanContextBuilder} class that allows you to easily construct new instances from scratch or build upon existing instances.
For example, the following code shows how to configure a JSON serializer:
</p>
<p class='bpcode w800'>
WriterSerializer s = JsonSerializer
.<jsm>create</jsm>() <jc>// Create a JsonSerializerBuilder</jc>
.simple() <jc>// Simple mode</jc>
.ws() <jc>// Use whitespace</jc>
.sq() <jc>// Use single quotes </jc>
.build(); <jc>// Create a JsonSerializer</jc>
</p>
<p>
Configurable settings can also be set declaratively.
The following produces the same serializer.
</p>
<p class='bpcode w800'>
WriterSerializer s = JsonSerializer
.<jsm>create</jsm>()
.set(<jsf>JSON_simpleMode</jsf>, <jk>true</jk>)
.set(<jsf>WSERIALIZER_useWhitespace</jsf>, <jk>true</jk>)
.set(<jsf>WSERIALIZER_quoteChar</jsf>, <js>"'"</js>)
.build();
</p>
<p>
However, each of the serializers and parsers already contain reusable instances with common configurations.
For example, JSON has the following predefined reusable serializers and parsers:
</p>
<ul class='javatree'>
<li class='jc'>{@link oaj.json.JsonSerializer}
<ul>
<li class='jf'>{@link oaj.json.JsonSerializer#DEFAULT DEFAULT}
<li class='jf'>{@link oaj.json.JsonSerializer#DEFAULT_READABLE DEFAULT_READABLE}
</ul>
</li>
<li class='jc'>{@link oaj.json.SimpleJsonSerializer}
<ul>
<li class='jf'>{@link oaj.json.SimpleJsonSerializer#DEFAULT DEFAULT}
<li class='jf'>{@link oaj.json.SimpleJsonSerializer#DEFAULT_READABLE DEFAULT_READABLE}
</ul>
</li>
<li class='jc'>{@link oaj.json.JsonParser}
<ul>
<li class='jf'>{@link oaj.json.JsonParser#DEFAULT DEFAULT}
<li class='jf'>{@link oaj.json.JsonParser#DEFAULT_STRICT DEFAULT_STRICT}
</ul>
</li>
</ul>
<p>
These can be used directly, as follows:
</p>
<p class='bpcode w800'>
<jc>// Serialize a POJO to LAX JSON.</jc>
String json = SimpleJsonSerializer.<jsf>DEFAULT</jsf>.serialize(myPojo);
</p>
<p>
For performance reasons, serializers and parsers are immutable.
However, they can be 'copied' and modified using the <c>builder()</c> method.
</p>
<p class='bpcode w800'>
<jc>// Clone and customize an existing serializer.</jc>
WriterSerializer s = SimpleJsonSerializer.<jsf>DEFAULT</jsf>
.builder() <jc>// Create a new builder with copied settings.</jc>
.quoteChar(<js>'"'</js>) <jc>// Use a different quote character.</jc>
.build();
</p>
<p>
Configurable properties can be set globally using either system properties or environment variables.
<br>For example, the <jsf>WSERIALIZER_useWhitespace</jsf> variable resolves to the string <js>"WriterSerializer.useWhitespace.b"</js>.
This setting can be enabled by setting the system property <js>"WriterSerializer.useWhitespace"</js> or environment
variables <js>"WriterSerializer_useWhitespace"</js> or <js>"WRITERSERIALIZER_USEWHITESPACE"</js> to <js>"true"</js>.
</p>