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 <c>Context</c> classes (e.g. <c>JsonSerializerContext</c>) have been folded into
				their respective serializer or parser classes (e.g. <c>JsonSerializer</c>).
				<br>Additionally, these classes are their own bean contexts.
				<br>For example, the class hierarchy of <c>JsonSerializer</c> 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 <c>Context</c> objects are thread-safe and read-only.
			<li>
				Session objects also now have a consistent class hierarchy.
				<br>For example, the class hierarchy of <c>JsonSerializerSession</c> 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 <c>JsonSerializerBuilder</c> 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 <c>Context</c> 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 <c>PropertyStore</c> 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 <c>PropertyStore</c> objects
				that can be used as hash keys.
		</ul>
	<li>
		Improvements to the HTTP-Part APIs.
		<br>The existing <c>PartSerializer</c>/<c>PartParser</c> classes
		have been replaced with the following all located in the new <c>org.apache.juneau.httppart</c> 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'><dc>UonPartSerializer</dc>
					<li class='jc'><dc>SimpleUonPartSerializer</dc>
					<li class='jc'>{@link oaj.httppart.SimplePartSerializer}
				</ul>
				<li class='jic'>{@link oaj.httppart.HttpPartParser}
				<ul>
					<li class='jc'><dc>UonPartParser</dc>
					<li class='jc'><dc>SimplePartParser</dc>
				</ul>
			</ul>
		</ul>
		Code for marshalling of parts have been removed from the URL-Encoding serializers and parsers.
	<li>	
		<c>ContextBuilder.property(String,Object)</c> renamed to {@link oaj.ContextBuilder#set(String,Object)}.
	<li>
		<c>ResourceFinder</c> 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>
		<c>RestServletDefault</c> renamed to {@link oajr.BasicRestServlet}.
	<li>
		<c>RestServletGroupDefault</c> 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 <c>HttpServletRequest.getAttribute(String)</c>.
			<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 <c>RestConfig</c> 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><dc>REST_defaultRequestHeaders</dc>
			<li><dc>REST_defaultResponseHeaders</dc>
			<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><dc>REST_contextPath</dc>
			<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 <dc>@RestResource(staticFiles)</dc> 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 <c>RestMatcherReflecting</c> 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>
		<dc>@RestResource.allowMethodParam</dc> renamed to <dc>RestResource.allowedMethodParams</dc>.
	<li>
		<c>@RestMethod.serializersInherit</c> and <c>@RestMethod.parsersInherit</c> replaced with
		simplified <dc>@RestMethod(inherit)</dc>. 
	<li>
		Changes to {@link oajr.RequestFormData}:
		<ul>
			<li>{@link oajr.RequestFormData#addDefault(Map) addDefault(Map)} takes in a 
				<c>Map&lt;String,Object&gt;</c> instead of <c>Map&lt;String,String&gt;</c>.
		</ul>
	<li>
		Changes to {@link oajr.RequestHeaders}:
		<ul>
			<li>{@link oajr.RequestHeaders#addDefault(Map) addDefault(Map)} takes in a 
				<c>Map&lt;String,Object&gt;</c> instead of <c>Map&lt;String,String&gt;</c>.
		</ul>
	<li>
		Changes to {@link oajr.RequestQuery}:
		<ul>
			<li>{@link oajr.RequestQuery#addDefault(Map) addDefault(Map)} takes in a 
				<c>Map&lt;String,Object&gt;</c> instead of <c>Map&lt;String,String&gt;</c>.
		</ul>
	<li>
		Changes to {@link oajr.RestContext}:
		<ul>
			<li><c>getResource(String,Locale)</c> renamed to {@link oajr.RestContext#getClasspathResource(String,Locale) getClasspathResource(String,Locale)}
			<li><c>getResourceAsString(String,Locale)</c> renamed to {@link oajr.RestContext#getClasspathResourceAsString(String,Locale) getClasspathResourceAsString(String,Locale)}
			<li><c>getResource(Class,MediaType,String,Locale)</c> 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 
				<c>Map&lt;String,Object&gt;</c> instead of <c>Map&lt;String,String&gt;</c>.
			<li>{@link oajr.RestContext#getDefaultResponseHeaders() getDefaultRequestHeaders} returns a 
				<c>Map&lt;String,Object&gt;</c> instead of <c>Map&lt;String,String&gt;</c>.
		</ul>
	<li>
		Changes to {@link oajr.RestRequest}:
		<ul>	
			<li><c>getSupportedMediaTypes()</c> replaced with
				{@link oajr.RestRequest#getConsumes() getConsumes()} and
				{@link oajr.RestRequest#getProduces() getProduces()}.
			<li><c>getReaderResource(String,boolean,MediaType)</c> renamed to 
				<dc>getClasspathReaderResource(String,boolean,MediaType)</dc>
			<li><c>getReaderResource(String,boolean)</c> renamed to 
				{@link oajr.RestRequest#getClasspathReaderResource(String,boolean) getClasspathReaderResource(String,boolean)}
			<li><c>getReaderResource(String)</c> renamed to 
				{@link oajr.RestRequest#getClasspathReaderResource(String) getClasspathReaderResource(String)}
		</ul>
	<li>
		Changes to <dc>@RestResource</dc>
		<ul>
			<li>New <dc>mimeTypes()</dc> 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>
		<c>RestCallHandler</c> split up into {@link oajr.RestCallHandler} and 
		{@link oajr.BasicRestCallHandler}
	<li>
		<c>RestInfoProvider</c> split up into {@link oajr.RestInfoProvider} and 
		{@link oajr.BasicRestInfoProvider}
	<li>
		<c>RestLogger</c> split up into {@link oajr.RestLogger}, 
		{@link oajr.BasicRestLogger} and {@link oajr.NoOpRestLogger}
	<li>
		<c>RestResourceResolverSimple</c> 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 <c>@Messages</c> and <c>@Properties</c> REST java method parameter
		annotations.
		<br>These aren't needed anymore since you can just pass in <c>MessageBundle</c> and
		<c>RestRequestProperties</c> as unannotated parameters.
	<li>
		Revamped the {@link oajr.RestInfoProvider} class.
	<li>
		New builder classes:
		<ul>
			<li><dc>ReaderResourceBuilder</dc>
			<li><dc>StreamResourceBuilder</dc>
		</ul>
	<li>
		{@link oajr.RestResponse#getNegotiatedOutputStream()} now returns a 
		<dc>FinishableServletOutputStream</dc> and {@link oajr.RestResponse#getNegotiatedWriter()}
		now returns a <dc>FinishablePrintWriter</dc> that allows you to finish the output
		without closing the stream.
		<br>The {@link oajr.reshandlers.DefaultHandler} class now calls <c>finish()</c>
		instead of <c>close()</c> on the stream.
	<li>
		Added the following annotations to the {@link oajr.BasicRestServlet} class
		(which were previously defined on the <dc>Resource</dc> 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 <c>PartSerializer</c> with {@link oaj.httppart.HttpPartSerializer}.
		<br>The default value is now <dc>SimpleUonPartSerializer</dc> 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 <c>Closeable</c> interface.
</ul>

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