juneau-doc/docs/ReleaseNotes/8.1.0.html

<!--
/***************************************************************************************************************************
 * 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.
 ***************************************************************************************************************************/
 -->

8.1.0 (Aug 21, 2019)

<p>
	8.1.0 introduces some significant new features including:
</p>
<ul class='spaced-list'>
	<li>
		<a href='#juneau-marshall.ConfigurableAnnotations'>Configurable Annotations</a>
	<li>
		<a href='#juneau-marshall.Transforms.DefaultPojoSwaps'>Default PojoSwaps</a>
	<li>
		<a href='#juneau-config.Imports'>Config Imports</a>
	<li>
		<a href='#juneau-rest-server.Instantiation.BasicRest'>BasicRest</a>, <a href='#juneau-rest-server.Instantiation.BasicRestGroup'>BasicRestGroup</a> classes
	<li>
		<a href='#juneau-rest-server.Rest.RestPath'>Path variables on resource paths</a>
	<li>
		<a href='#juneau-rest-server.RestMethod.RequestAttributes'>Request Attributes API</a>
	<li>
		<a href='#juneau-rest-server.RoleGuards'>Role Guards</a>
	<li>
		<a href='#juneau-rest-server.LoggingAndDebugging'>Improved REST logging/debugging</a>
	<li>
		<a href='#juneau-rest-mock'>New MockRest API</a>
</ul>

<h5 class='topic w800'>juneau-marshall</h5>
<ul class='spaced-list'>
	<li>
		New utility class for diffing beans: 
		<ul class='javatree'>
			<li class='jc'>{@link oaj.utils.BeanDiff}
		</ul>
	<li>
		New annotation for defining bean property names: 
		<ul class='javatree'>
			<li class='ja'>{@link oaj.annotation.Name}
		</ul>
	<li>
		New serializer properties:
		<ul class='javatree'>
			<li class='jc'>{@link oaj.serializer.WriterSerializer}
			<ul>
				<li class='jf'>{@link oaj.serializer.WriterSerializer#WSERIALIZER_fileCharset WSERIALIZER_fileCharset}
				<li class='jf'>{@link oaj.serializer.WriterSerializer#WSERIALIZER_streamCharset WSERIALIZER_streamCharset}
			</ul>
		</ul>
	<li>
		The following POJO methods can be used to convert a POJO to/from a Map before serialization and after parsing.
		<br>It's a convenient way of defining a POJO transform.
		<ul class='javatree'>
			<li class='jm'><c><jk>public</jk> Map toMap()</c> -  Can be any type of map with string keys and object vals. 
			<li class='jm'><c><jk>public</jk> ObjectMap toMap()</c>
			<li class='jm'><c><jk>public</jk> Map toMap(BeanSession bs)</c> -  Can be any type of map with string keys and object vals. 
			<li class='jm'><c><jk>public</jk> ObjectMap toMap(BeanSession bs)</c>
			<li class='jm'><c><jk>public static</jk> T fromMap(Map m)</c> -  Can be any type of map with string keys and object vals. 
			<li class='jm'><c><jk>public static</jk> T fromMap(ObjectMap m)</c>
			<li class='jm'><c><jk>public static</jk> T fromMap(BeanSession bs, Map m)</c> -  Can be any type of map with string keys and object vals. 
			<li class='jm'><c><jk>public static</jk> T fromMap(BeanSession bs, ObjectMap m)</c>
		</ul>
	<li>
		New convenience debugging methods on Marshall API:
		<ul class='javatree'>
			<li class='jc'>{@link oaj.marshall.Marshall}
			<ul>
				<li class='jm'>{@link oaj.marshall.Marshall#format(String,Object...) format(String,Object...)} - <c>MessageFormat</c>-style formatter.
				<li class='jm'>{@link oaj.marshall.Marshall#out(String,Object...) out(String,Object...)} - Prints <c>MessageFormat</c>-style messages to STDOUT.
				<li class='jm'>{@link oaj.marshall.Marshall#err(String,Object...) err(String,Object...)} - Prints <c>MessageFormat</c>-style messages to STDERR.
			</ul>
		</ul>
	<li>
		Serializer and parser APIs now throw <c>IOExceptions</c> in addition to <c>SerializeException</c> and <c>ParseException</c> to make it
		easier to determine if problems are stream based or syntax based.
	<li>
		New Java 8 date-time transforms:
		<ul class='javatree'>
			<li class='jc'>{@link oaj.transforms.TemporalSwap} - For all Java 8 temporal types (e.g. {@link java.time.ZonedDateTime})
			<li class='jc'>{@link oaj.transforms.TemporalDateSwap} - For {@link java.util.Date}
			<li class='jc'>{@link oaj.transforms.TemporalCalendarSwap} - For {@link java.util.Calendar}
		</ul>
	<li>
		All serializers and parsers now have built-in default swaps for common class types:
		<ul class='javatree'>
			<li class='jc'>{@link java.util.Enumeration}
			<li class='jc'>{@link java.util.Iterator}
			<li class='jc'>{@link java.util.Locale}
			<li class='jc'>{@link java.util.Calendar} - ISO offset date-time.
			<li class='jc'>{@link java.util.Date} - Local date-time
			<li class='jc'>{@link java.time.Instant} - ISO instant.
			<li class='jc'>{@link java.time.ZonedDateTime} - ISO offset date-time.
			<li class='jc'>{@link java.time.LocalDate} - ISO local date.
			<li class='jc'>{@link java.time.LocalDateTime} - ISO local date-time.
			<li class='jc'>{@link java.time.LocalTime} - ISO local time.
			<li class='jc'>{@link java.time.OffsetDateTime} - ISO offset date-time.
			<li class='jc'>{@link java.time.OffsetTime} - ISO offset time.
			<li class='jc'>{@link java.time.Year} - ISO year.
			<li class='jc'>{@link java.time.YearMonth} - ISO year-month.
			<li class='jc'>{@link java.time.Temporal} - ISO instant.
			<li class='jc'>{@link java.util.TimeZone}
			<li class='jc'>{@link javax.xml.datatype.XMLGregorianCalendar}
			<li class='jc'>{@link java.time.ZoneId}
		</ul>
</ul>

<h5 class='topic w800'>juneau-config</h5>
<ul class='spaced-list'>
	<li>
		Support for import statements:
		<p class='bcode'>
	<cc># Import values from another configuration:</cc>
	<ci>&lt;ParentConfig1&gt;</ci>
	
	<cs>[Foo]</cs>
	<ck>bar</ck> = <cv>baz</cv>
		</p>
	<li>
		The {@link oaj.config.store.ConfigFileStore} now automatically resolves file extensions.
		<br>New configuration property for specifying search paths for file extensions:
		<ul class='javatree'>
			<li class='jf'>{@link oaj.config.store.ConfigFileStore#FILESTORE_extensions}
		</ul>
	<li>
		Fixed a bug where instances of {@link oaj.config.store.ConfigMemoryStore} ended up resolving to the same object.
	<li>
		Uses <js>"application.properties"</js> file as a system default if present.
		<br>Useful when being used in a Spring Boot application.
	<li>
		New {@link oaj.config.Config#setSystemProperties} method for quickly moving configuration settings into the 
		system properties.
	<li>
		Entries in the system config are automatically set as system properties.
		<br>This mean you can set any of the various serializer and parser settings (e.g. <js>"JsonSerializer.simpleMode.b"</js>)
		in the default configuration area or <c>application.properties</c>.
</ul>

<h5 class='topic w800'>juneau-rest-server</h5>
<ul class='spaced-list'>
	<li>
		New annotations that can be applied to REST classes and methods to configure serializers and parsers.
		<p class='bcode w800'>
	<jc>// Old way using generic properties.</jc>
	<ja>@RestResource</ja>(
		path=<js>"/atom"</js>,
		title=<js>"Sample ATOM feed resource"</js>,
		properties={
			<ja>@Property</ja>(name=<jsf>WSERIALIZER_quoteChar</jsf>, value=<js>"'"</js>),
			<ja>@Property</ja>(name=<jsf>RDF_rdfxml_tab</jsf>, value=<js>"5"</js>),
			<ja>@Property</ja>(name<jsf>RDF_addRootProperty</jsf>, value=<js>"true"</js>),
			<ja>@Property</ja>(name=<jsf>BEAN_examples</jsf>, value=<js>"{'org.apache.juneau.dto.atom.Feed': $F{AtomFeedResource_example.json}}"</js>)
		}
		...
	)
	<jk>public class</jk> AtomFeedResource <jk>extends</jk> BasicRestServletJena {
		...
	}
		</p>
		<p class='bcode w800'>
	<jc>// New way using specific annotations.</jc>
	<ja>@RestResource</ja>(
		path=<js>"/atom"</js>,
		title=<js>"Sample ATOM feed resource"</js>
		...
	)
	<ja>@SerializerConfig</ja>(quoteChar=<js>"'"</js>)
	<ja>@RdfConfig</ja>(rdfxml_tab=<js>"5"</js>, addRootProperty=<js>"true"</js>)
	<ja>@BeanConfig</ja>(examples=<js>"Feed: $F{AtomFeedResource_example.json}"</js>)
	<jk>public class</jk> AtomFeedResource <jk>extends</jk> BasicRestServletJena {
		...
	}
		</p>
		<p>
			Config annotations are provided for all serializers and parsers:
		</p>
		<ul class='javatree'>
			<li class='ja'>{@link oaj.annotation.BeanConfig BeanConfig}
			<li class='ja'>{@link oaj.csv.annotation.CsvConfig CsvConfig}
			<li class='ja'>{@link oaj.html.annotation.HtmlConfig HtmlConfig}
			<li class='ja'>{@link oaj.html.annotation.HtmlDocConfig HtmlDocConfig}
			<li class='ja'>{@link oaj.jso.annotation.JsoConfig JsoConfig}
			<li class='ja'>{@link oaj.json.annotation.JsonConfig JsonConfig}
			<li class='ja'>{@link oaj.jsonschema.annotation.JsonSchemaConfig JsonSchemaConfig}
			<li class='ja'>{@link oaj.msgpack.annotation.MsgPackConfig MsgPackConfig}
			<li class='ja'>{@link oaj.oapi.annotation.OpenApiConfig OpenApiConfig}
			<li class='ja'>{@link oaj.parser.annotation.ParserConfig ParserConfig}
			<li class='ja'>{@link oaj.plaintext.annotation.PlainTextConfig PlainTextConfig}
			<li class='ja'>{@link oaj.jena.annotation.RdfConfig RdfConfig}
			<li class='ja'>{@link oaj.serializer.annotation.SerializerConfig SerializerConfig}
			<li class='ja'>{@link oaj.soap.annotation.SoapXmlConfig SoapXmlConfig}
			<li class='ja'>{@link oaj.uon.annotation.UonConfig UonConfig}
			<li class='ja'>{@link oaj.urlencoding.annotation.UrlEncodingConfig UrlEncodingConfig}
			<li class='ja'>{@link oaj.xml.annotation.XmlConfig XmlConfig}
		</ul>
	<li>
		New support for using Servlet request attributes.  
		<ul class='javatree'>
			<li class='jc'>{@link oajr.RequestAttributes}
			<li class='jc'>{@link oajr.RestContext}
			<ul>
				<li class='jf'><dc>REST_attrs</dc>
			</ul>
			<li class='jc'>{@link oajr.RestContextBuilder}
			<ul>
				<li class='jm'><dc>attrs(String...)</dc>
				<li class='jm'><dc>attr(String,Object)</dc>
			</ul>
			<li class='jc'>{@link oajr.RestMethodContext}
			<ul>
				<li class='jf'>{@link oajr.RestMethodContext#RESTMETHOD_attrs RESTMETHOD_attrs}
			</ul>
			<li class='jc'>{@link oajr.RestRequest}
			<ul>
				<li class='jm'>{@link oajr.RestRequest#getAttributes() getAttributes()}
			</ul>
			<li class='jc'>{@link oajr.RestResponse}
			<ul>
				<li class='jm'>{@link oajr.RestResponse#getAttributes() getAttributes()}
				<li class='jm'>{@link oajr.RestResponse#attr(String,Object) attr(String,Object)}
			</ul>
			<li class='ja'>{@link oajr.annotation.Attr}
			<li class='ja'><dc>RestMethod#attrs()</dc>
			<li class='ja'><dc>RestResource.attrs()</dc>
		</ul>
		<br>This deprecates the following APIs:
		<ul class='javatree'>
			<li class='jc'>{@link oajr.RequestProperties}
			<li class='jc'>{@link oajr.RestMethodProperties}
			<li class='jc'>{@link oajr.RestRequest}
			<ul>
				<li class='jm'>{@link oajr.RestRequest#getProperties() getProperties()}
				<li class='jm'>{@link oajr.RestRequest#prop(String,Object) prop(String,Object)}
			</ul>
		</ul>
	<li>
		Added the following classes that provide the same support as the servlet classes but doesn't extend from <c>HttpServlet</c>.
		<br>This fixes an issue where instances of {@link oajr.BasicRestServlet} are registered as top-level servlets even though
		you don't want them to be.  
		<ul class='javatree'>
			<li class='jac'>{@link oajr.BasicRest} - Non-servlet equivalent to {@link oajr.BasicRestServlet}
			<li class='jac'>{@link oajr.BasicRestGroup} - Non-servlet equivalent to {@link oajr.BasicRestServletGroup}
			<li class='jac'>{@link oajr.BasicRestJena} - Non-servlet equivalent to {@link oajr.BasicRestServletJena}
			<li class='jac'>{@link oajr.BasicRestJenaGroup} - Non-servlet equivalent to {@link oajr.BasicRestServletJenaGroup}
		</ul>
	<li>
		HTML widgets now have access to the <c>RestResponse</c> object if they need access to the output bean.
	<li>
		New annotations for simplified role-based guards on classes and methods:
		<ul class='javatree'>
			<li class='ja'><dc>RestResource</dc> 
			<ul>
				<li class='jm'><dc>roleGuard()</dc>
				<li class='jm'><dc>rolesDeclared()</dc>
			</ul>
			<li class='ja'>{@link oajr.annotation.RestMethod} 
			<ul>
				<li class='jm'>{@link oajr.annotation.RestMethod#roleGuard roleGuard()}
				<li class='jm'>{@link oajr.annotation.RestMethod#rolesDeclared rolesDeclared()}
			</ul>
		</ul>
	<li>
		New annotations for fine-tuned handling of http-methods/http-headers as query parameters and others:
		<ul class='javatree'>
			<li class='ja'><dc>RestResource</dc> 
			<ul>
				<li class='jm'><dc>allowedHeaderParams()</dc>
				<li class='jm'><dc>allowedMethodHeaders()}</dc>
				<li class='jm'><dc>allowedMethodParams()</dc>
			</ul>
		</ul>
	<li>
		The <dc>@RestResource(path)</dc> annotation can now use variables:
		<p class='bcode'>
	<ja>@RestResource</ja>(
		path=<js>"/myResource/{foo}/{bar}"</js>
	)
	<jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {...}
		</p>		
	<li>
		New methods:
		<ul class='javatree'>
			<li class='jc'>{@link oajr.RestRequest}
			<ul>
				<li class='jm'>{@link oajr.RestRequest#getCharset() getCharset()}
			</ul>
			<li class='jc'>{@link oajr.RestResponse}
			<ul>
				<li class='jm'>{@link oajr.RestResponse#getCharset() getCharset()}
			</ul>
		</ul>
	<li>
		New interface method for catching arbitrary thrown objects and converting them to other throwables.
		<ul class='javatree'>
			<li class='jc'>{@link oajr.RestCallHandler}
			<ul>
				<li class='jm'>{@link oajr.RestCallHandler#convertThrowable(Throwable) convertThrowable(Throwable)}
			</ul>
			<li class='jc'>{@link oajr.BasicRestCallHandler}
			<ul>
				<li class='jm'>{@link oajr.BasicRestCallHandler#convertThrowable(Throwable) convertThrowable(Throwable)}
			</ul>
		</ul>
	<li>
		Support for fine-tuned logging of HTTP requests and responses. 
		<p class='bcode'>
	<ja>@RestResource</ja>(
		debug=<js>"per-request"</js>,
		logging=<ja>@Logging</ja>(
			level=<js>"info"</js>,
			rules={
				<ja>@LoggingRule</ja>(codes<js>"400-499"</js>, level=<js>"warning"</js>, req=<js>"short"</js>, res=<js>"short"</js>)
				<ja>@LoggingRule</ja>(codes<js>"500-"</js>, level=<js>"severe"</js>, req=<js>"long"</js>, res=<js>"long"</js>)
			}
		)
	)
	<jk>public class</jk> MyRest {

		<ja>@RestMethod</ja>(
			method=<js>"POST"</js>, 
			path=<js>"foo"</js>
			logging=<ja>@Logging</ja>(
				level=<js>"info"</js>,
				rules={
					<ja>@LoggingRule</ja>(exceptions<js>"NotFound*"</js>, level=<js>"info"</js>)
					<ja>@LoggingRule</ja>(codes<js>"200"</js>, disabled=<js>"true"</js>)
				}
			)
		)
		<jk>public</jk> String myMethod() <jk>throws</jk> Exception {...}
		</p>		
		See {@doc juneau-rest-server.LoggingAndDebugging} for details.
	<li>
		Fixed a bug where the HTTP response was returning 405 (method not found) but should really be 404 (not found)
		when no path patterns match on any of the Java methods.
</ul>

<h5 class='topic w800'>juneau-rest-client</h5>
<ul class='spaced-list'>
	<li>
		PATCH support added.
</ul>