juneau-doc/docs/Topics/02.juneau-marshall/16.ReadingContinuousStreams.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.
 ***************************************************************************************************************************/
 -->

Reading Continuous Streams

<p>
	The following parsers can be configured to read continuous streams of objects from the same input stream:
</p>
<ul class='javatree'>
	<li class='jc'>{@link oaj.json.JsonParser}
	<li class='jc'>{@link oaj.uon.UonParser}
	<li class='jc'>{@link oaj.msgpack.MsgPackParser}
</ul>
<p>
	The {@link oaj.json.JsonParser} and {@link oaj.uon.UonParser}
	classes can read continuous streams by using the {@link oaj.parser.Parser#PARSER_unbuffered PARSER_unbuffered}
	setting.
	This prevents the parsers from using an internal buffer that would read past the end of the currently
	parsed POJO.
</p>
<h5 class='figure'>Examples:</h5>
<p class='bpcode w800'>
	<jc>// If you're calling parse on the same input multiple times, use a session instead of the parser directly.</jc>
	ReaderParserSession p = JsonParser.<jsm>create</jsm>().unbuffered().build().createSession();
	Object x;
	Reader r;

	r = new StringReader(<js>"{foo:'bar'}{baz:'qux'}"</js>);
	x = p.parse(r, ObjectMap.<jk>class</jk>);  <jc>// {foo:'bar'}</jc>
	x = p.parse(r, ObjectMap.<jk>class</jk>);  <jc>// {baz:'qux'}</jc>

	r = reader(<js>"[123][456]"</js>);
	x = p.parse(r, <jk>int</jk>[].<jk>class</jk>);  <jc>// [123]</jc>
	x = p.parse(r, <jk>int</jk>[].<jk>class</jk>);  <jc>// [456]</jc>
</p>
<p>
	Note that this isn't perfect in all cases since you can't combine two JSON numbers into a single
	reader (e.g. <c>"123" + "456" = "123456"</c>).
</p>
<p>
	For obvious reasons, do not use the following properties when reading continuous streams:
</p>
<ul class='javatree'>
	<li class='jf'>{@link oaj.json.JsonParser#JSON_validateEnd}
	<li class='jf'>{@link oaj.uon.UonParser#UON_validateEnd}
	<li class='jf'>{@link oaj.parser.Parser#PARSER_autoCloseStreams}
</ul>
<p>
	The {@link oaj.msgpack.MsgPackParser} class doesn't use any internal buffering to begin with, so it can be used with
	continuous streams without any special properties.
</p>