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

DtoExamples

<p>
	The <l>DtoExamples</l> resource is a resource group for demonstrating various DTO examples.
</p>
<p>	
	The <l>AtomFeedResource</l> class shows examples of the following:
</p>
<ul class='spaced-list'>
	<li>
		Using the {@doc org.apache.juneau.dto.atom#TOC ATOM Feed DTO} API.
</ul>
<p>
	Pointing a browser to the resource shows the following:
</p>
<p class='bpcode w800'>
	http://localhost:10000/atom
</p>			
<img class='bordered w800' src='doc-files/juneau-examples-rest.AtomFeedResource.1.png'>
<p>
	True ATOM feeds require using an <l>Accept:text/xml</l> header:
</p>
<p class='bpcode w800'>
	http://localhost:10000/atom?Accept=text/xml&amp;plainText=true
</p>			
<img class='bordered w800' src='doc-files/juneau-examples-rest.AtomFeedResource.2.png'>
<p>
	Other languages, such as JSON are also supported:
</p>
<p class='bpcode w800'>
	http://localhost:10000/atom?Accept=text/json&amp;plainText=true
</p>			
<img class='bordered w800' src='doc-files/juneau-examples-rest.AtomFeedResource.3.png'>

<h5 class='figure'>AtomFeedResource.java</h5>
<p class='bpcode w800'>
	<jd>/** 
	* Sample resource that shows how to generate ATOM feeds. 
	*/</jd> 
	<ja>@Rest</ja>( 
		path=<js>"/atom"</js>,
		title=<js>"Sample ATOM feed resource"</js>,
		description=<js>"Sample resource that shows how to render ATOM feeds"</js>,
		htmldoc=<ja>@HtmlDoc</ja>(
			widgets={
				ContentTypeMenuItem.<jk>class</jk>,
				StyleMenuItem.<jk>class</jk>
			},
			navlinks={
				<js>"up: request:/.."</js>,
				<js>"options: servlet:/?method=OPTIONS"</js>,
				<js>"$W{ContentTypeMenuItem}"</js>,
				<js>"$W{StyleMenuItem}"</js>,
				<js>"source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
			}
		),
		encoders=GzipEncoder.<jk>class</jk> 
	) 
	<ja>@SerializerConfig</ja>(quoteChar=<js>"'"</js>)
	<ja>@RdfConfig</ja>(rdfxml_tab=<js>"5"</js>, addRootProperty=<js>"true"</js>)
	<jk>public class</jk> AtomFeedResource <jk>extends</jk> BasicRestServletJena { 
	
		<jk>private</jk> Feed <jf>feed</jf>; <jc>// The root resource object</jc> 
		
		<ja>@Override</ja> <jc>/* Servlet */</jc> 
		<jk>public void</jk> init() { 
			<jk>try</jk> {
				<jf>feed</jf> =
					<jsm>feed</jsm>(<js>"tag:juneau.sample.com,2013:1"</js>, <js>"Juneau ATOM specification"</js>, <js>"2013-05-08T12:29:29Z"</js>)
					.subtitle(<jsm>text</jsm>(<js>"html"</js>).text(<js>"A &lt;em&gt;lot&lt;/em&gt; of effort went into making this effortless"</js>))
					.links(
						<jsm>link</jsm>(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/"</js>).hreflang(<js>"en"</js>),
						<jsm>link</jsm>(<js>"self"</js>, <js>"application/atom+xml"</js>, <js>"http://www.sample.com/feed.atom"</js>)
					)
					.generator(
						<jsm>generator</jsm>(<js>"Juneau"</js>).uri(<js>"http://juneau.apache.org/"</js>).version(<js>"1.0"</js>)
					)
					.entries(
						<jsm>entry</jsm>(<js>"tag:juneau.sample.com,2013:1.2345"</js>, <js>"Juneau ATOM specification snapshot"</js>, <js>"2013-05-08T12:29:29Z"</js>)
						.links(
							<jsm>link</jsm>(<js>"alternate"</js>, <js>"text/html"</js>, <js>"http://www.sample.com/2012/05/08/juneau.atom"</js>),
							<jsm>link</jsm>(<js>"enclosure"</js>, <js>"audio/mpeg"</js>, <js>"http://www.sample.com/audio/juneau_podcast.mp3"</js>).length(1337)
						)
						.published(<js>"2013-05-08T12:29:29Z"</js>)
						.authors(
							<jsm>person</jsm>(<js>"James Bognar"</js>).uri(<jk>new</jk> URI(<js>"http://www.sample.com/"</js>)).email(<js>"jamesbognar@apache.org"</js>)
						)
						.contributors(
							<jsm>person</jsm>(<js>"Barry M. Caceres"</js>)
						)
						.content(
							<jsm>content</jsm>(<js>"xhtml"</js>)
							.lang(<js>"en"</js>)
							.base(<js>"http://www.apache.org/"</js>)
							.text(<js>"&lt;div&gt;&lt;p&gt;[Update: Juneau supports ATOM.]&lt;/p&gt;&lt;/div&gt;"</js>)
						)
					);
			} <jk>catch</jk> (Exception e) {
				<jk>throw new</jk> RuntimeException(e);
			}
		} 
		
		<jd>/** 
		* GET request handler 
		*/</jd> 
		<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>) 
		<jk>public</jk> Feed getFeed() <jk>throws</jk> Exception { 
			<jk>return</jk> <jf>feed</jf>; 
		} 
		
		<jd>/** 
		* PUT request handler. 
		* Replaces the feed with the specified content, and then mirrors it as the response. 
		*/</jd> 
		<ja>@RestMethod</ja>(name=<jsf>PUT</jsf>, path=<js>"/"</js>) 
		<jk>public</jk> Feed setFeed(<ja>@Body</ja> Feed feed) <jk>throws</jk> Exception { 
			<jk>this</jk>.<jf>feed</jf> = feed; 
			<jk>return</jk> feed; 
		} 
	} 		
</p>
<p>	
	The <l>JsonSchemaResource</l> class shows examples of the following:
</p>
<ul class='spaced-list'>
	<li>
		Using the {@link oaj.dto.jsonschema JSON Schema DTO} API.
</ul>
<p>
	The resource consists of a pre-initialized {@link oaj.dto.jsonschema.JsonSchema} object.
	Pointing a browser to the resource shows the following:
</p>
<p class='bpcode w800'>
	http://localhost:10000/jsonSchema
</p>			
<img class='bordered w800' src='doc-files/juneau-examples-rest.JsonSchemaResource.1.png'>
<p>
	For true JSON-Schema, you need to specify the header <l>Accept: text/json</l>:
</p>
<p class='bpcode w800'>
	http://localhost:10000/jsonSchema?Accept=text/json&amp;plainText=true
</p>			
<img class='bordered w800' src='doc-files/juneau-examples-rest.JsonSchemaResource.2.png'>

<h5 class='figure'>JsonSchemaResource.java</h5>
<p class='bpcode w800'>
	<jd>/** 
	* Sample resource that shows how to serialize JSON-Schema documents. 
	*/</jd> 
	<ja>@Rest</ja>( 
		path=<js>"/jsonSchema"</js>,
		messages=<js>"nls/JsonSchemaResource"</js>,
		title=<js>"Sample JSON-Schema document"</js>,
		description=<js>"Sample resource that shows how to generate JSON-Schema documents"</js>,
		htmldoc=<ja>@HtmlDoc</ja>(
			widgets={
				ContentTypeMenuItem.<jk>class</jk>,
				StyleMenuItem.<jk>class</jk>
			},
			navlinks={
				<js>"up: request:/.."</js>,
				<js>"options: servlet:/?method=OPTIONS"</js>,
				<js>"$W{ContentTypeMenuItem}"</js>,
				<js>"$W{StyleMenuItem}"</js>,
				<js>"source: $C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
			},
			aside={
				<js>"&lt;div style='min-width:200px' class='text'&gt;"</js>,
				<js>"	&lt;p&gt;Shows how to produce JSON-Schema documents in a variety of languages using the JSON-Schema DTOs.&lt;/p&gt;"</js>,
				<js>"&lt;/div&gt;"</js>
			}
		)
	) 
	<jk>public class</jk> JsonSchemaResource <jk>extends</jk> BasicRestServletJena { 
		<jk>private static final long</jk> <jsf>serialVersionUID</jsf> = 1L; 
		
		<jk>private</jk> JsonSchema schema; <jc>// The schema document</jc> 
		
		<ja>@Override</ja> /* Servlet */ 
		<jk>public void</jk> init() { 
			
			<jk>try</jk> { 
				<jf>schema</jf> = <jk>new</jk> JsonSchema() 
					.setId(<js>"http://example.com/sample-schema#"</js>) 
					.setSchemaVersionUri(<js>"http://json-schema.org/draft-04/schema#"</js>) 
					.setTitle(<js>"Example Schema"</js>) 
					.setType(JsonType.<jsf>OBJECT</jsf>) 
					.addProperties( 
						<jk>new</jk> JsonSchemaProperty(<js>"firstName"</js>, JsonType.<jsf>STRING</jsf>), 
						<jk>new</jk> JsonSchemaProperty(<js>"lastName"</js>, JsonType.<jsf>STRING</jsf>), 
						<jk>new</jk> JsonSchemaProperty(<js>"age"</js>, JsonType.<jsf>INTEGER</jsf>) 
							.setDescription(<js>"Age in years"</js>) 
							.setMinimum(0) 
				) 
				.addRequired(<js>"firstName"</js>, <js>"lastName"</js>); 
			} <jk>catch</jk> (Exception e) { 
				<jk>throw new</jk> RuntimeException(e); 
			} 
		} 
		
		<jd>/** GET request handler */</jd> 
		<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>) 
		<jk>public</jk> JsonSchema getSchema() <jk>throws</jk> Exception { 
			<jk>return</jk> <jf>schema</jf>; 
		} 
		
		<jd>/** 
		* PUT request handler. 
		* Replaces the schema document with the specified content, and then mirrors it as the response. 
		*/</jd> 
		<ja>@RestMethod</ja>(name=<jsf>PUT</jsf>, path=<js>"/"</js>) 
		<jk>public</jk> JsonSchema setSchema(<ja>@Body</ja> JsonSchema schema) <jk>throws</jk> Exception { 
			<jk>this</jk>.<jf>schema</jf> = schema; 
			<jk>return</jk> schema; 
		} 
	} 		
</p>