juneau-doc/docs/Topics/16.juneau-examples-rest/03.DtoExamples.html - juneau - Git at Google

 <!--
 /***************************************************************************************************************************
  * 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>
	<!--
	/***************************************************************************************************************************
	* 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&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&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 <em>lot</em> 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>"<div><p>[Update: Juneau supports ATOM.]</p></div>"</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&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>"<div style='min-width:200px' class='text'>"</js>,
	<js>" <p>Shows how to produce JSON-Schema documents in a variety of languages using the JSON-Schema DTOs.</p>"</js>,
	<js>"</div>"</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>