juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/cognos/package.html - juneau - Git at Google

 <!DOCTYPE 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.
  *
  ***************************************************************************************************************************/
  -->
 <html>
 <head>
 	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 	<style type="text/css">
 		/* For viewing in Page Designer */
 		@IMPORT url("../../../../../../javadoc.css");

 		/* For viewing in REST interface */
 		@IMPORT url("../htdocs/javadoc.css");
 		body {
 			margin: 20px;
 		}
 	</style>
 	<script>
 		/* Replace all @code and @link tags. */
 		window.onload = function() {
 			document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>');
 			document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>');
 		}
 	</script>
 </head>
 <body>
 <p>Cognos Data Transfer Objects</p>
 <script>
 	function toggle(x) {
 		var div = x.nextSibling;
 		while (div != null && div.nodeType != 1)
 			div = div.nextSibling;
 		if (div != null) {
 			var d = div.style.display;
 			if (d == 'block' || d == '') {
 				div.style.display = 'none';
 				x.className += " closed";
 			} else {
 				div.style.display = 'block';
 				x.className = x.className.replace(/(?:^|\s)closed(?!\S)/g , '' );
 			}
 		}
 	}
 </script>
 <a id='TOC'></a><h5 class='toc'>Table of Contents</h5>
 <ol class='toc'>
 	<li><p><a class='doclink' href='#CognosSerializer'>Cognos serialization support</a></p>
 	<li><p><a class='doclink' href='#CognosParser'>Cognos parsing support</a></p>
 </ol>

 <!-- ======================================================================================================== -->
 <a id="CognosSerializer"></a>
 <h2 class='topic' onclick='toggle(this)'>1 - Cognos serialization support</h2>
 <div class='topic'>
 	<p>
 		The {@link org.apache.juneau.dto.cognos.DataSet} class is a DTO used to convert POJO models directly to Cognos-XML.
 	</p>
 	<p>
 		Because of the nature of the Cognos XML syntax, only <i>2-dimensional</i> POJO data structures can be serialized to Cognos-XML.
 	</p>
 	<p>
 		For example...
 	</p>
 	<ul class='normal'>
 		<li><code>Collection&lt;Bean&gt;</code>
 		<li><code>Collection&lt;Map&gt;</code>
 		<li>{@code MyBean[]}
 		<li>{@code HashMap[]}
 	</ul>

 	<h6 class='topic'>Example:</h6>
 	<p>
 		The following example shows how to generate Cognos-XML from a POJO.
 		The example uses the <a class='doclink' href='../../doc-files/AddressBook.html'>AddressBook</a> sample POJO.
 		It should be noted that since the {@code AddressBook} class is a subclass of {@code LinkedList}, it fulfills
 			the requirement of being a tabular data structure.
 	</p>
 	<p class='bcode'>
 	<jc>// Create our POJO with some entries.</jc>
 	AddressBook addressBook = <jk>new</jk> AddressBook();
 	addressBook.add(
 		<jk>new</jk> Person(<js>"Barack Obama"</js>, <js>"Aug 4, 1961"</js>,
 			<jk>new</jk> Address(<js>"1600 Pennsylvania Ave"</js>, <js>"Washington"</js>, <js>"DC"</js>, 20500, <jk>true</jk>),
 			<jk>new</jk> Address(<js>"5046 S Greenwood Ave"</js>, <js>"Chicago"</js>, <js>"IL"</js>, 60615, <jk>false</jk>)
 		)
 	);
 	addressBook.add(
 		<jk>new</jk> Person(<js>"George Walker Bush"</js>, <js>"Jul 6, 1946"</js>,
 			<jk>new</jk> Address(<js>"43 Prairie Chapel Rd"</js>, <js>"Crawford"</js>, <js>"TX"</js>, 76638, <jk>true</jk>),
 			<jk>new</jk> Address(<js>"1600 Pennsylvania Ave"</js>, <js>"Washington"</js>, <js>"DC"</js>, 20500, <jk>false</jk>)
 		)
 	);

 	<jc>// Define the Cognos metadata</jc>
 	Column[] items = {
 		<jk>new</jk> Column(<js>"name"</js>, <js>"xs:String"</js>, 255),
 		<jk>new</jk> Column(<js>"age"</js>, <js>"xs:int"</js>),
 		<jk>new</jk> Column(<js>"numAddresses"</js>, <js>"xs:int"</js>)
 			.addPojoSwap(
 				<jk>new</jk> PojoSwap&lt;Person,Integer&gt;() {
 					<ja>@Override</ja>
 					<jk>public</jk> Integer swap(BeanSession session, Person p) {
 						<jk>return</jk> p.<jf>addresses</jf>.size();
 					}
 				}
 			)
 	};

 	<jc>// Create the Cognos DataSet object</jc>
 	DataSet ds = <jk>new</jk> DataSet(items, <jsf>addressBook</jsf>, BeanContext.<jsf>DEFAULT</jsf>);

 	<jc>// Serialize it to XML</jc>
 	String xml = XmlSerializer.<jsf>DEFAULT_SQ</jsf>.serialize(ds);
 	</p>
 	<p>
 		When run, this code produces the following XML...
 	</p>
 	<p class='bcode'>
 	<xt>&lt;?xml</xt> <xa>version</xa>=<xs>'1.0'</xs> <xa>encoding</xa>=<xs>'UTF-8'</xs><xt>?&gt;</xt>
 	<xt>&lt;c:dataset <xa>xmlns:c</xa>=<xs>'http://developer.cognos.com/schemas/xmldata/1/'</xs>&gt;</xt>
 		<xt>&lt;c:metadata&gt;</xt>
 			<xt>&lt;c:item</xt> <xa>name</xa>=<xs>'name'</xs> <xa>type</xa>=<xs>'xs:String'</xs> <xa>length</xa>=<xs>'255'</xs><xt>/&gt;</xt>
 			<xt>&lt;c:item</xt> <xa>name</xa>=<xs>'age'</xs> <xa>type</xa>=<xs>'xs:int'</xs><xt>/&gt;</xt>
 			<xt>&lt;c:item</xt> <xa>name</xa>=<xs>'numAddresses'</xs> <xa>type</xa>=<xs>'xs:int'</xs><xt>/&gt;</xt>
 		<xt>&lt;/c:metadata&gt;</xt>
 		<xt>&lt;c:data&gt;</xt>
 			<xt>&lt;c:row&gt;</xt>
 				<xt>&lt;c:value&gt;</xt>Barack Obama<xt>&lt;/c:value&gt;</xt>
 				<xt>&lt;c:value&gt;</xt>52<xt>&lt;/c:value&gt;</xt>
 				<xt>&lt;c:value&gt;</xt>2<xt>&lt;/c:value&gt;</xt>
 			<xt>&lt;/c:row&gt;</xt>
 			<xt>&lt;c:row&gt;</xt>
 				<xt>&lt;c:value&gt;</xt>George Walker Bush<xt>&lt;/c:value&gt;</xt>
 				<xt>&lt;c:value&gt;</xt>67<xt>&lt;/c:value&gt;</xt>
 				<xt>&lt;c:value&gt;</xt>2<xt>&lt;/c:value&gt;</xt>
 			<xt>&lt;/c:row&gt;</xt>
 		<xt>&lt;/c:data&gt;</xt>
 	<xt>&lt;/c:dataset&gt;</xt>
 	</p>

 	<h6 class='topic'>Other data formats</h6>
 	<p>
 		The following shows examples of what this data structure looks like when serialized to other formats:
 	</p>

 	<h6 class='figure'>HTML</h6>
 	<img class='bordered' src='doc-files/HTML.png'>

 	<h6 class='figure'>JSON</h6>
 	<img class='bordered' src='doc-files/JSON.png'>

 	<h6 class='figure'>RDF/XML</h6>
 	<img class='bordered' src='doc-files/RDFXML.png'>
 </div>

 <!-- ======================================================================================================== -->
 <a id="CognosParser"></a>
 <h2 class='topic' onclick='toggle(this)'>2 - Cognos parsing support</h2>
 <div class='topic'>
 	<p>
 		The {@link org.apache.juneau.dto.cognos.DataSet} class can be reconstructed from Cognos/XML using one of the standard XML parsers.
 	</p>

 	<h6 class='topic'>Example:</h6>
 	<p class='bcode'>
 	<jc>// Parse XML back into original DataSet</jc>
 	DataSet ds = XmlParser.<jsf>DEFAULT</jsf>.parse(xml, DataSet.<jk>class</jk>);
 	</p>
 </div>
 </body>
 </html>
	<!DOCTYPE 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.
	*
	***************************************************************************************************************************/
	-->
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<style type="text/css">
	/* For viewing in Page Designer */
	@IMPORT url("../../../../../../javadoc.css");

	/* For viewing in REST interface */
	@IMPORT url("../htdocs/javadoc.css");
	body {
	margin: 20px;
	}
	</style>
	<script>
	/* Replace all @code and @link tags. */
	window.onload = function() {
	document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>');
	document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>');
	}
	</script>
	</head>
	<body>
	<p>Cognos Data Transfer Objects</p>
	<script>
	function toggle(x) {
	var div = x.nextSibling;
	while (div != null && div.nodeType != 1)
	div = div.nextSibling;
	if (div != null) {
	var d = div.style.display;
	if (d == 'block' \|\| d == '') {
	div.style.display = 'none';
	x.className += " closed";
	} else {
	div.style.display = 'block';
	x.className = x.className.replace(/(?:^\|\s)closed(?!\S)/g , '' );
	}
	}
	}
	</script>
	<a id='TOC'></a><h5 class='toc'>Table of Contents</h5>
	<ol class='toc'>
	<li><p><a class='doclink' href='#CognosSerializer'>Cognos serialization support</a></p>
	<li><p><a class='doclink' href='#CognosParser'>Cognos parsing support</a></p>
	</ol>

	<!-- ======================================================================================================== -->
	<a id="CognosSerializer"></a>
	<h2 class='topic' onclick='toggle(this)'>1 - Cognos serialization support</h2>
	<div class='topic'>
	<p>
	The {@link org.apache.juneau.dto.cognos.DataSet} class is a DTO used to convert POJO models directly to Cognos-XML.
	</p>
	<p>
	Because of the nature of the Cognos XML syntax, only <i>2-dimensional</i> POJO data structures can be serialized to Cognos-XML.
	</p>
	<p>
	For example...
	</p>
	<ul class='normal'>
	<li><code>Collection<Bean></code>
	<li><code>Collection<Map></code>
	<li>{@code MyBean[]}
	<li>{@code HashMap[]}
	</ul>

	<h6 class='topic'>Example:</h6>
	<p>
	The following example shows how to generate Cognos-XML from a POJO.
	The example uses the <a class='doclink' href='../../doc-files/AddressBook.html'>AddressBook</a> sample POJO.
	It should be noted that since the {@code AddressBook} class is a subclass of {@code LinkedList}, it fulfills
	the requirement of being a tabular data structure.
	</p>
	<p class='bcode'>
	<jc>// Create our POJO with some entries.</jc>
	AddressBook addressBook = <jk>new</jk> AddressBook();
	addressBook.add(
	<jk>new</jk> Person(<js>"Barack Obama"</js>, <js>"Aug 4, 1961"</js>,
	<jk>new</jk> Address(<js>"1600 Pennsylvania Ave"</js>, <js>"Washington"</js>, <js>"DC"</js>, 20500, <jk>true</jk>),
	<jk>new</jk> Address(<js>"5046 S Greenwood Ave"</js>, <js>"Chicago"</js>, <js>"IL"</js>, 60615, <jk>false</jk>)
	)
	);
	addressBook.add(
	<jk>new</jk> Person(<js>"George Walker Bush"</js>, <js>"Jul 6, 1946"</js>,
	<jk>new</jk> Address(<js>"43 Prairie Chapel Rd"</js>, <js>"Crawford"</js>, <js>"TX"</js>, 76638, <jk>true</jk>),
	<jk>new</jk> Address(<js>"1600 Pennsylvania Ave"</js>, <js>"Washington"</js>, <js>"DC"</js>, 20500, <jk>false</jk>)
	)
	);

	<jc>// Define the Cognos metadata</jc>
	Column[] items = {
	<jk>new</jk> Column(<js>"name"</js>, <js>"xs:String"</js>, 255),
	<jk>new</jk> Column(<js>"age"</js>, <js>"xs:int"</js>),
	<jk>new</jk> Column(<js>"numAddresses"</js>, <js>"xs:int"</js>)
	.addPojoSwap(
	<jk>new</jk> PojoSwap<Person,Integer>() {
	<ja>@Override</ja>
	<jk>public</jk> Integer swap(BeanSession session, Person p) {
	<jk>return</jk> p.<jf>addresses</jf>.size();
	}
	}
	)
	};

	<jc>// Create the Cognos DataSet object</jc>
	DataSet ds = <jk>new</jk> DataSet(items, <jsf>addressBook</jsf>, BeanContext.<jsf>DEFAULT</jsf>);

	<jc>// Serialize it to XML</jc>
	String xml = XmlSerializer.<jsf>DEFAULT_SQ</jsf>.serialize(ds);
	</p>
	<p>
	When run, this code produces the following XML...
	</p>
	<p class='bcode'>
	<xt><?xml</xt> <xa>version</xa>=<xs>'1.0'</xs> <xa>encoding</xa>=<xs>'UTF-8'</xs><xt>?></xt>
	<xt><c:dataset <xa>xmlns:c</xa>=<xs>'http://developer.cognos.com/schemas/xmldata/1/'</xs>></xt>
	<xt><c:metadata></xt>
	<xt><c:item</xt> <xa>name</xa>=<xs>'name'</xs> <xa>type</xa>=<xs>'xs:String'</xs> <xa>length</xa>=<xs>'255'</xs><xt>/></xt>
	<xt><c:item</xt> <xa>name</xa>=<xs>'age'</xs> <xa>type</xa>=<xs>'xs:int'</xs><xt>/></xt>
	<xt><c:item</xt> <xa>name</xa>=<xs>'numAddresses'</xs> <xa>type</xa>=<xs>'xs:int'</xs><xt>/></xt>
	<xt></c:metadata></xt>
	<xt><c:data></xt>
	<xt><c:row></xt>
	<xt><c:value></xt>Barack Obama<xt></c:value></xt>
	<xt><c:value></xt>52<xt></c:value></xt>
	<xt><c:value></xt>2<xt></c:value></xt>
	<xt></c:row></xt>
	<xt><c:row></xt>
	<xt><c:value></xt>George Walker Bush<xt></c:value></xt>
	<xt><c:value></xt>67<xt></c:value></xt>
	<xt><c:value></xt>2<xt></c:value></xt>
	<xt></c:row></xt>
	<xt></c:data></xt>
	<xt></c:dataset></xt>
	</p>

	<h6 class='topic'>Other data formats</h6>
	<p>
	The following shows examples of what this data structure looks like when serialized to other formats:
	</p>

	<h6 class='figure'>HTML</h6>
	<img class='bordered' src='doc-files/HTML.png'>

	<h6 class='figure'>JSON</h6>
	<img class='bordered' src='doc-files/JSON.png'>

	<h6 class='figure'>RDF/XML</h6>
	<img class='bordered' src='doc-files/RDFXML.png'>
	</div>

	<!-- ======================================================================================================== -->
	<a id="CognosParser"></a>
	<h2 class='topic' onclick='toggle(this)'>2 - Cognos parsing support</h2>
	<div class='topic'>
	<p>
	The {@link org.apache.juneau.dto.cognos.DataSet} class can be reconstructed from Cognos/XML using one of the standard XML parsers.
	</p>

	<h6 class='topic'>Example:</h6>
	<p class='bcode'>
	<jc>// Parse XML back into original DataSet</jc>
	DataSet ds = XmlParser.<jsf>DEFAULT</jsf>.parse(xml, DataSet.<jk>class</jk>);
	</p>
	</div>
	</body>
	</html>