juneau-doc/docs/ReleaseNotes/7.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.
 ***************************************************************************************************************************/
 -->

7.1.0 (Mar 08, 2018)

<p>
	Version 7.1.0 is a major update with major implementation refactoring across all aspects of the product.
</p>

<h5 class='topic w800'>juneau-marshall</h5>
<ul class='spaced-list'>
	<li>
		Significant improvements made to the internals of the Serializer and Parser classes.
		<ul>
			<li>
				Caching improvements on serializers and parsers have reduced execution time of the core
				JUnits by approximately 1/3.
				<br>The 17000+ JUnit tests now execute in less than 10 seconds and have a cache-reuse hit rate
				of 98% (164104 serializers/parsers/bean-contexts retrieved, but only 1801 created from scratch).
			<li>
				All the various separate <code>Context</code> classes (e.g. <code>JsonSerializerContext</code>) have been folded into
				their respective serializer or parser classes (e.g. <code>JsonSerializer</code>).
				<br>Additionally, these classes are their own bean contexts.
				<br>For example, the class hierarchy of <code>JsonSerializer</code> is now:
				<ul class='doctree'>
					<li class='jac'>{@link oaj.Context}
					<ul>
						<li class='jc'>{@link oaj.BeanContext}
						<ul>
							<li class='jac'>{@link oaj.serializer.Serializer}
							<ul>
								<li class='jac'>{@link oaj.serializer.WriterSerializer}
								<ul>
									<li class='jc'>{@link oaj.json.JsonSerializer}
								</ul>
							</ul>
						</ul>
					</ul>
				</ul>
				All <code>Context</code> objects are thread-safe and read-only.
			<li>
				Session objects also now have a consistent class hierarchy.
				<br>For example, the class hierarchy of <code>JsonSerializerSession</code> is now:
				<ul class='doctree'>
					<li class='jac'>{@link oaj.Session}
					<ul>
						<li class='jc'>{@link oaj.BeanSession}
						<ul>
							<li class='jac'>{@link oaj.serializer.SerializerSession}
							<ul>
								<li class='jac'>{@link oaj.serializer.WriterSerializerSession}
								<ul>
									<li class='jc'>{@link oaj.json.JsonSerializerSession}
								</ul>
							</ul>
						</ul>
					</ul>
				</ul>
				Session objects are transient objects that live for the duration of a single parse.
			<li>
				Builder objects also now have a consistent class hierarchy.
				<br>For example, the class hierarchy of <code>JsonSerializerBuilder</code> is now:
				<ul class='doctree'>
					<li class='jac'>{@link oaj.ContextBuilder}
					<ul>
						<li class='jc'>{@link oaj.BeanContextBuilder}
						<ul>
							<li class='jac'>{@link oaj.serializer.SerializerBuilder}
							<ul>
								<li class='jc'>{@link oaj.json.JsonSerializerBuilder}
							</ul>
						</ul>
					</ul>
				</ul>
				Builder objects are used for building up and creating <code>Context</code> objects.
			<li>
				The {@link oaj.PropertyStore} class has been completely rewritten.
				It is now a read-only configuration store build using the {@link oaj.PropertyStoreBuilder}
				class.
				<br>The previous <code>PropertyStore</code> class was overly-complicated with many read/write
				locks to ensure thread-safety. 
				<br>The new design shifts to a builder-based model with read-only <code>PropertyStore</code> objects
				that can be used as hash keys.
		</ul>
	<li>
		Improvements to the HTTP-Part APIs.
		<br>The existing <code>PartSerializer</code>/<code>PartParser</code> classes
		have been replaced with the following all located in the new <code>org.apache.juneau.httppart</code> package:
		<ul class='doctree'>
			<li class='jp'>{@link oaj.httppart}
			<ul>
				<li class='jc'>{@link oaj.httppart.HttpPartType}
				<li class='jic'>{@link oaj.httppart.HttpPartSerializer}
				<ul>
					<li class='jc'><code><del>UonPartSerializer</del></code>
					<li class='jc'><code><del>SimpleUonPartSerializer</del></code>
					<li class='jc'>{@link oaj.httppart.SimplePartSerializer}
				</ul>
				<li class='jic'>{@link oaj.httppart.HttpPartParser}
				<ul>
					<li class='jc'><code><del>UonPartParser</del></code>
					<li class='jc'><code><del>SimplePartParser</del></code>
				</ul>
			</ul>
		</ul>
		Code for marshalling of parts have been removed from the URL-Encoding serializers and parsers.
	<li>	
		<code>ContextBuilder.property(String,Object)</code> renamed to {@link oaj.ContextBuilder#set(String,Object)}.
	<li>
		<code>ResourceFinder</code> class has been replaced with the following:
		<ul>
			<li>{@link oaj.utils.ClasspathResourceFinder}
			<li>{@link oaj.utils.ClasspathResourceFinderSimple}
			<li>{@link oaj.utils.ClasspathResourceFinderBasic}
			<li>{@link oaj.utils.ClasspathResourceFinderRecursive}
			<li>{@link oaj.utils.ClasspathResourceManager}
		</ul>
	<li>
		New methods on {@link oaj.serializer.SerializerSession}:
		<ul>
			<li>{@link oaj.serializer.SerializerSession#getListener() getListener()}
			<li>{@link oaj.serializer.SerializerSession#getListener(Class) getListener(Class)}
		</ul>
	<li>
		New methods on {@link oaj.parser.ParserSession}:
		<ul>
			<li>{@link oaj.parser.ParserSession#getListener() getListener()}
			<li>{@link oaj.parser.ParserSession#getListener(Class) getListener(Class)}
		</ul>
	<li>
		New {@link oaj.parser.Parser#PARSER_unbuffered} setting allows you to disable internal
		buffering on the JSON and UON parsers so that they can be used to read continous streams of objects.
	<li>
		New {@link oaj.json.JsonParser#JSON_validateEnd} and {@link oaj.uon.UonParser#UON_validateEnd} 
		settings allow you to control whether we validate that there is no garbage at the end of the parsed input.
	<li>
		New {@link oaj.parser.Parser#PARSER_autoCloseStreams} setting allows input streams and
		readers passed into parsers to be automatically closed after parsing.
	<li>
		Syntax changed on unswap method on {@link oaj.transform.Surrogate} classes.
		<br>It's now a regular method instead of a static method.
	<li>
		{@link oaj.annotation.Swap @Swap} annotation can now be used with 
		{@link oaj.transform.Surrogate} classes.
	<li>
		New support for {@doc juneau-marshall.Transforms.PojoBuilders POJO Builders}.	
</ul>

<h5 class='topic w800'>juneau-svl</h5>
<ul class='spaced-list'>
	<li>
		New variables:
		<ul>
			<li>{@link oaj.svl.vars.CoalesceVar}
			<li>{@link oaj.svl.vars.PatternMatchVar}
			<li>{@link oaj.svl.vars.NotEmptyVar}
			<li>{@link oaj.svl.vars.UpperCaseVar}
			<li>{@link oaj.svl.vars.LowerCaseVar}
		</ul>
	<li>
		Variables moved from <l>juneau-microservice</l>:
		<ul>
			<li>{@link oaj.svl.vars.ArgsVar}
			<li>{@link oaj.svl.vars.ManifestFileVar}
		</ul>
</ul>

<h5 class='topic w800'>juneau-config</h5>
<ul class='spaced-list'>
	<li>
		The Config API has been completely revamped.
		<br>New features include:
		<ul>
			<li>Support for pluggable storage.
			<li>File-system watcher integration support.
				<br>Changes made to file system files now automatically reflected in configurations
				and interface proxies.
			<li>New builder-based design.
		</ul>
</ul>

<h5 class='topic w800'>juneau-dto</h5>
<ul class='spaced-list'>
	<li>
		Enhancements to Swagger DTO:
		<ul>
			<li>New methods for setting and retrieving properties via name:
				<ul>
					<li>{@link oaj.dto.swagger.SwaggerElement#get(String,Class)}
					<li>{@link oaj.dto.swagger.SwaggerElement#set(String,Object)}
				</ul>
			<li>
				Support for setting non-standard fields such as <js>"$ref"</js> via getter and setter
				above.
			<li>
				Setter methods that take in beans and collections of beans can now take in 
				JSON strings.
		</ul>
</ul>

<h5 class='topic w800'>juneau-rest-server</h5>
<ul class='spaced-list'>
	<li>
		<code>RestServletDefault</code> renamed to {@link oajr.BasicRestServlet}.
	<li>
		<code>RestServletGroupDefault</code> renamed to {@link oajr.BasicRestServletGroup}.
	<li>
		The <js>"$R{...}"</js> variable has been split into the following:
		<ul>
			<li><js>"$RA{key1[,key2...]}"</js> - {@link oajr.vars.RequestAttributeVar}, first non-null value returned by <code>HttpServletRequest.getAttribute(String)</code>.
			<li><js>"$RF{key1[,key2...]}"</js> - {@link oajr.vars.RequestFormDataVar}, first non-null value returned by {@link oajr.RestRequest#getFormData(String)}.
			<li><js>"$RH{key1[,key2...]}"</js> - {@link oajr.vars.RequestHeaderVar}, first non-null value returned by {@link oajr.RestRequest#getHeader(String)}.
			<li><js>"$RI{key1[,key2...]}"</js> - {@link oajr.vars.RestInfoVar}, first non-null value returned by {@link oajr.RestRequest#getInfoProvider()}.
				<br>The possible values are:
				<ul>
					<li><js>"contact"</js> - Value returned by {@link oaj.dto.swagger.Info#getContact()}
					<li><js>"description"</js> - Value returned by {@link oajr.RestInfoProvider#getDescription(RestRequest)}
					<li><js>"externalDocs"</js> - Value returned by {@link oaj.dto.swagger.Swagger#getExternalDocs()}
					<li><js>"license"</js> - Value returned by {@link oaj.dto.swagger.Info#getLicense()}
					<li><js>"methodDescription"</js> - Value returned by {@link oajr.RestInfoProvider#getMethodDescription(Method,RestRequest)}
					<li><js>"methodSummary"</js> - Value returned by {@link oajr.RestInfoProvider#getMethodSummary(Method,RestRequest)}
					<li><js>"siteName"</js> - Value returned by {@link oajr.RestInfoProvider#getSiteName(RestRequest)}
					<li><js>"tags"</js> - Value returned by {@link oaj.dto.swagger.Swagger#getTags()}
					<li><js>"termsOfService"</js> - Value returned by {@link oaj.dto.swagger.Info#getTermsOfService()}
					<li><js>"title"</js> - See {@link oajr.RestInfoProvider#getTitle(RestRequest)}
					<li><js>"version"</js> - See {@link oaj.dto.swagger.Info#getVersion()}
				</ul>					
			<li><js>"$RP{key1[,key2...]}"</js> - {@link oajr.vars.RequestPathVar}, first non-null value returned by {@link oajr.RestRequest#getPath(String)}.
			<li><js>"$RQ{key1[,key2...]}"</js> - {@link oajr.vars.RequestQueryVar}, first non-null value returned by {@link oajr.RestRequest#getQuery(String)}
			<li><js>"$R{key1[,key2...]}"</js> - {@link oajr.vars.RequestVar}, first non-null other request variable.
				<br>The possible values are:
				<ul>
					<li><js>"contextPath"</js> - Value returned by {@link oajr.RestRequest#getContextPath()}
					<li><js>"method"</js> - Value returned by {@link oajr.RestRequest#getMethod()}
					<li><js>"methodDescription"</js> - Value returned by {@link oajr.RestRequest#getMethodDescription()}
					<li><js>"methodSummary"</js> - Value returned by {@link oajr.RestRequest#getMethodSummary()}
					<li><js>"pathInfo"</js> - Value returned by {@link oajr.RestRequest#getPathInfo()}
					<li><js>"requestParentURI"</js> - Value returned by {@link oaj.UriContext#getRootRelativePathInfoParent()}
					<li><js>"requestURI"</js> - Value returned by {@link oajr.RestRequest#getRequestURI()}
					<li><js>"resourceDescription"</js> - Value returned by {@link oajr.RestRequest#getResourceDescription()}
					<li><js>"resourceTitle"</js> - See {@link oajr.RestRequest#getResourceTitle()}
					<li><js>"servletParentURI"</js> - Value returned by {@link oaj.UriContext#getRootRelativeServletPathParent()}
					<li><js>"servletPath"</js> - See {@link oajr.RestRequest#getServletPath()}
					<li><js>"servletURI"</js> - See {@link oaj.UriContext#getRootRelativeServletPath()}
					<li><js>"siteName"</js> - See {@link oajr.RestRequest#getSiteName()}
				</ul>
		</ul>
	<li>
		Refactored the <code>RestConfig</code> class into {@link oajr.RestContextBuilder}.
		<br>Settings on {@link oajr.RestContext} objects can now be set declaratively through the 
			following new properties:
		<ul>
			<li>{@link oajr.RestContext#REST_allowHeaderParams REST_allowHeaderParams}
			<li>{@link oajr.RestContext#REST_allowBodyParam REST_allowBodyParam}
			<li>{@link oajr.RestContext#REST_allowedMethodParams REST_allowedMethodParams}
			<li>{@link oajr.RestContext#REST_renderResponseStackTraces REST_renderResponseStackTraces}
			<li>{@link oajr.RestContext#REST_useStackTraceHashes REST_useStackTraceHashes}
			<li>{@link oajr.RestContext#REST_defaultCharset REST_defaultCharset}
			<li>{@link oajr.RestContext#REST_maxInput REST_maxInput}
			<li>{@link oajr.RestContext#REST_paramResolvers REST_paramResolvers}
			<li>{@link oajr.RestContext#REST_converters REST_converters}
			<li>{@link oajr.RestContext#REST_guards REST_guards}
			<li>{@link oajr.RestContext#REST_responseHandlers REST_responseHandlers}
			<li>{@link oajr.RestContext#REST_defaultRequestHeaders REST_defaultRequestHeaders}
			<li>{@link oajr.RestContext#REST_defaultResponseHeaders REST_defaultResponseHeaders}
			<li>{@link oajr.RestContext#REST_produces REST_produces}
			<li>{@link oajr.RestContext#REST_consumes REST_consumes}
			<li>{@link oajr.RestContext#REST_clientVersionHeader REST_clientVersionHeader}
			<li>{@link oajr.RestContext#REST_resourceResolver REST_resourceResolver}
			<li>{@link oajr.RestContext#REST_logger REST_logger}
			<li>{@link oajr.RestContext#REST_callHandler REST_callHandler}
			<li>{@link oajr.RestContext#REST_infoProvider REST_infoProvider}
			<li>{@link oajr.RestContext#REST_path REST_path}
			<li><code><del>REST_contextPath</del></code>
			<li>{@link oajr.RestContext#REST_staticFiles REST_staticFiles}
			<li>{@link oajr.RestContext#REST_staticFileResponseHeaders REST_staticFileResponseHeaders}
			<li>{@link oajr.RestContext#REST_classpathResourceFinder REST_classpathResourceFinder}
			<li>{@link oajr.RestContext#REST_useClasspathResourceCaching REST_useClasspathResourceCaching}
			<li>{@link oajr.RestContext#REST_widgets REST_widgets}
			<li>{@link oajr.RestContext#REST_mimeTypes REST_mimeTypes}
		</ul>
	<li>
		Support for static files has been simplified and improved.
		<ul>
			<li>Syntax on {@link oajr.annotation.RestResource#staticFiles() @RestResource(staticFiles)} has been simplified, and
				now allows you to specify response headers in the strings.
			<li>Response headers for static files can also be configured through 
				{@link oajr.RestContext#REST_staticFileResponseHeaders REST_staticFileResponseHeaders}.
			<li>Static file in-memory caching now configurable through 
				{@link oajr.RestContext#REST_useClasspathResourceCaching REST_useClasspathResourceCaching}.
			<li>Static file retrieval can be customized through 
				{@link oajr.RestContext#REST_classpathResourceFinder REST_classpathResourceFinder}
		</ul>
	<li>
		Eliminated the <code>RestMatcherReflecting</code> class.
		<br>You can now simply create a {@link oajr.RestMatcher} that has a public constructor that 
		takes in the server and method arguments.
	<li>
		<code>@RestResource.allowMethodParam</code> renamed to {@link oajr.annotation.RestResource#allowedMethodParams}.
	<li>
		<code>@RestMethod.serializersInherit</code> and <code>@RestMethod.parsersInherit</code> replaced with
		simplified <code><del>@RestMethod(inherit)</del></code>. 
	<li>
		Changes to {@link oajr.RequestFormData}:
		<ul>
			<li>{@link oajr.RequestFormData#addDefault(Map) addDefault(Map)} takes in a 
				<code>Map&lt;String,Object&gt;</code> instead of <code>Map&lt;String,String&gt;</code>.
		</ul>
	<li>
		Changes to {@link oajr.RequestHeaders}:
		<ul>
			<li>{@link oajr.RequestHeaders#addDefault(Map) addDefault(Map)} takes in a 
				<code>Map&lt;String,Object&gt;</code> instead of <code>Map&lt;String,String&gt;</code>.
		</ul>
	<li>
		Changes to {@link oajr.RequestQuery}:
		<ul>
			<li>{@link oajr.RequestQuery#addDefault(Map) addDefault(Map)} takes in a 
				<code>Map&lt;String,Object&gt;</code> instead of <code>Map&lt;String,String&gt;</code>.
		</ul>
	<li>
		Changes to {@link oajr.RestContext}:
		<ul>
			<li><code>getResource(String,Locale)</code> renamed to {@link oajr.RestContext#getClasspathResource(String,Locale) getClasspathResource(String,Locale)}
			<li><code>getResourceAsString(String,Locale)</code> renamed to {@link oajr.RestContext#getClasspathResourceAsString(String,Locale) getClasspathResourceAsString(String,Locale)}
			<li><code>getResource(Class,MediaType,String,Locale)</code> renamed to {@link oajr.RestContext#getClasspathResource(Class,MediaType,String,Locale) getClasspathResourceAsString(Class,MediaType,String,Locale)}
			<li>New method {@link oajr.RestContext#getClasspathResource(Class,String,Locale) getClasspathResource(Class,String,Locale)}.
			<li>New method {@link oajr.RestContext#getClasspathResourceAsString(Class,String,Locale) getClasspathResourceAsString(Class,String,Locale)}.
			<li>New method {@link oajr.RestContext#getClasspathResource(Class,Class,MediaType,String,Locale) getClasspathResource(Class,Class,MediaType,String,Locale)}.
			<li>{@link oajr.RestContext#getDefaultRequestHeaders() getDefaultRequestHeaders} returns a 
				<code>Map&lt;String,Object&gt;</code> instead of <code>Map&lt;String,String&gt;</code>.
			<li>{@link oajr.RestContext#getDefaultResponseHeaders() getDefaultRequestHeaders} returns a 
				<code>Map&lt;String,Object&gt;</code> instead of <code>Map&lt;String,String&gt;</code>.
		</ul>
	<li>
		Changes to {@link oajr.RestRequest}:
		<ul>	
			<li><code>getSupportedMediaTypes()</code> replaced with
				{@link oajr.RestRequest#getConsumes() getConsumes()} and
				{@link oajr.RestRequest#getProduces() getProduces()}.
			<li><code>getReaderResource(String,boolean,MediaType)</code> renamed to 
				<code><del>getClasspathReaderResource(String,boolean,MediaType)</del></code>
			<li><code>getReaderResource(String,boolean)</code> renamed to 
				{@link oajr.RestRequest#getClasspathReaderResource(String,boolean) getClasspathReaderResource(String,boolean)}
			<li><code>getReaderResource(String)</code> renamed to 
				{@link oajr.RestRequest#getClasspathReaderResource(String) getClasspathReaderResource(String)}
		</ul>
	<li>
		Changes to {@link oajr.annotation.RestResource @RestResource}:
		<ul>
			<li>New {@link oajr.annotation.RestResource#mimeTypes() mimeTypes()} annotation.
		</ul>
	<li>
		Changes to {@link oajr.annotation.RestMethod @RestMethod}:
		<ul>
			<li>New {@link oajr.annotation.RestMethod#consumes() consumes()} and
				{@link oajr.annotation.RestMethod#produces() produces()}
				for overriding the supported media types inferred from the serializers and parsers.
		</ul>
	<li>
		<code>RestCallHandler</code> split up into {@link oajr.RestCallHandler} and 
		{@link oajr.BasicRestCallHandler}
	<li>
		<code>RestInfoProvider</code> split up into {@link oajr.RestInfoProvider} and 
		{@link oajr.BasicRestInfoProvider}
	<li>
		<code>RestLogger</code> split up into {@link oajr.RestLogger}, 
		{@link oajr.BasicRestLogger} and {@link oajr.NoOpRestLogger}
	<li>
		<code>RestResourceResolverSimple</code> renamed to {@link oajr.BasicRestResourceResolver}
	<li>
		Introduced the following classes that helps make the code more understandable:
		<ul>
			<li>{@link oajr.RestContextProperties}
			<li>{@link oajr.RestMethodProperties}
			<li>{@link oajr.RequestProperties}
		</ul>
	<li>
		Eliminated the <code>@Messages</code> and <code>@Properties</code> REST java method parameter
		annotations.
		<br>These aren't needed anymore since you can just pass in <code>MessageBundle</code> and
		<code>RestRequestProperties</code> as unannotated parameters.
	<li>
		Revamped the {@link oajr.RestInfoProvider} class.
	<li>
		New builder classes:
		<ul>
			<li><code><del>ReaderResourceBuilder</del></code>
			<li><code><del>StreamResourceBuilder</del></code>
		</ul>
	<li>
		{@link oajr.RestResponse#getNegotiatedOutputStream()} now returns a 
		<code><del>FinishableServletOutputStream</del></code> and {@link oajr.RestResponse#getNegotiatedWriter()}
		now returns a <code><del>FinishablePrintWriter</del></code> that allows you to finish the output
		without closing the stream.
		<br>The {@link oajr.reshandlers.DefaultHandler} class now calls <code>finish()</code>
		instead of <code>close()</code> on the stream.
	<li>
		Added the following annotations to the {@link oajr.BasicRestServlet} class
		(which were previously defined on the <code><del>Resource</del></code> class):
		<p class='bcode w800'>
	<ja>@RestResource</ja>(
		htmldoc=<ja>@HtmlDoc</ja>(
			navlinks={
				<js>"up: request:/.."</js>,
				<js>"options: servlet:/?method=OPTIONS"</js>
			},
			stylesheet=<js>"$C{REST/stylesheet,servlet:/styles/devops.css}"</js>
		),
		
		<jc>// Optional external configuration file.</jc>
		config=<js>"$S{juneau.configFile}"</js>
	)
		</p>
</ul>

<h5 class='topic w800'>juneau-rest-client</h5>
<ul class='spaced-list'>
	<li>
		New configuration property {@link oajrc.RestClient#RESTCLIENT_query} and
		builder method {@link oajrc.RestClientBuilder#query(String,Object)}.
	<li>
		API changes to replace <code>PartSerializer</code> with {@link oaj.httppart.HttpPartSerializer}.
		<br>The default value is now <code><del>SimpleUonPartSerializer</del></code> which will
		serialize strings as plain-text and collections/arrays as comma-delimited lists.
		<br>We decided to change the default behavior in favor of practicality over purity.
	<li>
		New methods on {@link oajrc.RestCall} class:
		<ul>
			<li>{@link oajrc.RestCall#getResponseHeader(String) getResponseHeader(String)}
			<li>{@link oajrc.RestCall#getResponseCode() getResponseCode()}
		</ul>
	<li>
		{@link oajrc.RestCall} and {@link oajrc.RestClient}
		now implement the <code>Closeable</code> interface.
</ul>

<h5 class='topic w800'>juneau-microservice</h5>
<ul class='spaced-list'>
	<li>
		<code>Resource</code> and <code>ResourceGroup</code> classes removed.
		<br>{@link oajr.BasicRestServlet} and {@link oajr.BasicRestServletGroup} can be used instead.
	<li>
		<code>ResourceJena</code> and <code>ResourceJenaGroup</code> classes renamed to
		<code><del>BasicRestServletJena</del></code> and <code><del>BasicRestServletJenaGroup</del></code>.
</ul>