juneau-core/src/main/java/org/apache/juneau/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>Base toolkit for serializers, parsers, and bean contexts</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='#BeanContext_Api'>Bean Context API</a></p>
 	<ol>
 		<li><p><a class='doclink' href='#BeanMap'>The BeanMap class</a></p>
 		<li><p><a class='doclink' href='#BeanContext'>The BeanContext class</a></p>
 		<li><p><a class='doclink' href='#Bean'>Bean annotations</a></p>
 	</ol>
 </ol>

 <!-- ======================================================================================================== -->
 <a id="BeanContext_Api"></a>
 <h2 class='topic' onclick='toggle(this)'>1 - Bean Context API</h2>
 <div class='topic'>
 	<p>
 		The {@link org.apache.juneau.BeanContext} class is the core class in the Juneau architecture.  It serves multiple functions...
 	</p>
 	<ul class='normal'>
 		<li>It provides the ability to create instances of {@link org.apache.juneau.BeanMap BeanMaps}.
 		<li>It serves as a repository for {@link org.apache.juneau.transform.BeanFilter BeanFilters} and {@link org.apache.juneau.transform.PojoSwap PojoSwaps}, which are used to tailor how Java objects are handled.
 		<li>It's used by all built-in {@link org.apache.juneau.serializer.Serializer Serializers} and {@link org.apache.juneau.parser.Parser Parsers} for working with POJOs in a consistent way.
 	</ul>

 	<!-- ======================================================================================================== -->
 	<a id="BeanMap"></a>
 	<h3 class='topic' onclick='toggle(this)'>1.1 - The BeanMap class</h3>
 	<div class='topic'>
 		<p>
 			The {@link org.apache.juneau.BeanMap} class allows you to access the properties of a bean through the familiar {@code Map} interface.
 			So, for example, you can use the {@code Map.get(key)} method to retrieve a property value in leu of it's getter method, and the {@code Map.put(key, value)} method to set a property value in leu of it's setter method.
 		</p>
 		<p>
 			The serialization and parsing of beans in Juneau is accomplished by wrapping Java beans inside instances of the class {@code BeanMap}.
 		</p>
 		<p>
 			<b>Note:</b> Instances of {@link org.apache.juneau.BeanMap} objects are always retrieved through the {@link org.apache.juneau.BeanContext} class. You cannot instantiate {@code BeanMaps} directly since the rules for defining what constitutes a bean depend on various settings in the bean context.
 		</p>
 		<p>
 			In general, the performance on using the {@link org.apache.juneau.BeanMap} class to access properties is equivalent to using reflection directly.
 		</p>
 		<p>
 			See the {@link org.apache.juneau.BeanMap} javadoc for more information.
 		</p>
 	</div>

 	<!-- ======================================================================================================== -->
 	<a id="BeanContext"></a>
 	<h3 class='topic' onclick='toggle(this)'>1.2 - The BeanContext and BeanSession classes</h3>
 	<div class='topic'>
 		<p>
 			The {@link org.apache.juneau.BeanContext} and {@link org.apache.juneau.BeanSession} classes are the workhorse class used to wrap Java beans inside {@link org.apache.juneau.BeanMap BeanMaps}.
 			There are several options provided on the {@link org.apache.juneau.BeanContext} class to tailor the definition of a bean.
 		</p>
 		<p>
 			The following is a very simple example of how to wrap a bean inside a {@link org.apache.juneau.BeanMap} wrapper and use the wrapper interface to get and set property values on the bean.
 			In this case, we're using the DEFAULT bean context.
 		</p>
 		<p class='bcode'>
 	<jc>// A sample pseudo bean class.</jc>
 	<jk>public class</jk> Person {
 		<jk>public</jk> String getName();
 		<jk>public void</jk> setName(String name);
 		<jk>public int</jk> getAge();
 		<jk>public void</jk> setAge(<jk>int</jk> age);
 	}

 	<jc>// Get an instance of a bean context.
 	// In this case, just use the default bean context.</jc>
 	BeanSession beanSession = BeanContext.<jsf>DEFAULT</jsf>.createSession();

 	<jc>// Create an instance of our bean and wrap it in a bean map.</jc>
 	Person p = <jk>new</jk> Person();
 	BeanMap&lt;Person&gt; m = beanSession.toBeanMap(p);

 	<jc>// Set some properties on the bean.</jc>
 	m.put(<js>"name"</js>, <js>"John Smith"</js>);
 	m.put(<js>"age"</js>, 21);

 	<jc>// Print out bean properties.</jc>
 	System.out.println(m.get(<js>"name"</js>));	<jc>// Prints "John Smith"</jc>
 	System.out.println(p.getName());	  <jc>// Prints "John Smith"</jc>
 	System.out.println(m.get(<js>"age"</js>));	 <jc>// Prints 21</jc>
 	System.out.println(p.getAge());		<jc>// Prints 21</jc>

 	<jc>// The bean context class can also create instances of bean maps.</jc>
 	m = beanContext.newBeanMap(Person.<jk>class</jk>);
 	p = m.getBean();	<jc>// Get the new wrapped bean.</jc>

 	<jc>// The bean context class can also create instances of beans.</jc>
 	p = beanContext.newBean(Person.<jk>class</jk>);
 		</p>
 		<p>
 			There are 3 ways to get an instance of a {@link org.apache.juneau.BeanContext}:
 		</p>
 		<p class='bcode'>
 	<jc>// Use one of the default bean contexts.</jc>
 	BeanContext beanContext = BeanContext.<jsf>DEFAULT</jsf>;

 	<jc>// Create a context from scratch with your own settings.</jc>
 	beanContext = <jk>new</jk> BeanContext().addPojoSwaps(DateSwap.ISO8601DT.<jk>class</jk>);

 	<jc>// Clone and modify an existing context.</jc>
 	beanContext = BeanContext.<jsf>DEFAULT</jsf>.clone().addPojoSwaps(DateSwap.ISO8601DT.<jk>class</jk>);
 		</p>
 		<p>
 			The {@link org.apache.juneau.BeanContext} class is a highly-customizable class.
 			See the {@link org.apache.juneau.BeanContext} javadoc for more information.
 		</p>
 	</div>

 	<!-- ======================================================================================================== -->
 	<a id="Bean"></a>
 	<h3 class='topic' onclick='toggle(this)'>1.3 - Bean annotations</h3>
 	<div class='topic'>
 		<p>
 			Juneau provides the following annotations that can be used to fine-tune what properties are associated with beans:
 		</p>
 		<ul class='normal'>
 			<li>{@link org.apache.juneau.annotation.Bean} - Fine-tune properties associated with beans.
 			<li>{@link org.apache.juneau.annotation.BeanProperty} - Fine-tune bean properties (fields / getters / setters).
 			<li>{@link org.apache.juneau.annotation.BeanConstructor} - Define read-only bean properties that can only be set through constructor arguments.
 			<li>{@link org.apache.juneau.annotation.BeanIgnore} - Prevent bean classes/methods/fields from being interpreted as bean constructs.
 		</ul>
 		<p>
 			These annotations always override the settings defined in the {@link org.apache.juneau.BeanContext} class.
 		</p>
 		<p>
 			For example, the following bean class will only have one property associated with it, <js>"name"</js>, since it's the only one listed in the list of properties.
 		</p>
 		<p class='bcode'>
 	<jc>// Bean with only one 'name' property</jc>
 	<ja>@Bean</ja>(properties=<js>"name"</js>)
 	<jk>public class</jk> Person {
 		<jk>public</jk> String getName();
 		<jk>public void</jk> setName(String name);
 		<jk>public int</jk> getAge();
 		<jk>public void</jk> setAge(<jk>int</jk> age);
 	}
 		</p>
 		<p>
 			When this bean is serialized using one of the {@link org.apache.juneau.serializer.Serializer Serializers}, the age property will be ignored.
 		</p>
 		<p>
 			Using the <ja>@Bean</ja> and <ja>@BeanProperty</ja> annotations, it's also possible to include non-standard properties (for example, getters or setters with non-standard names), or override the names of properties (for example, {@code "Name"} or {@code "fullName"} instead of {@code "name"}).
 		</p>
 		<p>
 			It should be noted that the {@link org.apache.juneau.transform.BeanFilter} class can also be used to exclude properties from beans.
 			However, only the annotations can be used to include non-standard properties or override property names.
 		</p>
 		<p>
 			See the {@link org.apache.juneau.annotation.Bean}, {@link org.apache.juneau.annotation.BeanProperty}, {@link org.apache.juneau.annotation.BeanConstructor}, and {@link org.apache.juneau.annotation.BeanIgnore} javadocs for more information.
 		</p>
 	</div>
 </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>Base toolkit for serializers, parsers, and bean contexts</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='#BeanContext_Api'>Bean Context API</a></p>
	<ol>
	<li><p><a class='doclink' href='#BeanMap'>The BeanMap class</a></p>
	<li><p><a class='doclink' href='#BeanContext'>The BeanContext class</a></p>
	<li><p><a class='doclink' href='#Bean'>Bean annotations</a></p>
	</ol>
	</ol>

	<!-- ======================================================================================================== -->
	<a id="BeanContext_Api"></a>
	<h2 class='topic' onclick='toggle(this)'>1 - Bean Context API</h2>
	<div class='topic'>
	<p>
	The {@link org.apache.juneau.BeanContext} class is the core class in the Juneau architecture. It serves multiple functions...
	</p>
	<ul class='normal'>
	<li>It provides the ability to create instances of {@link org.apache.juneau.BeanMap BeanMaps}.
	<li>It serves as a repository for {@link org.apache.juneau.transform.BeanFilter BeanFilters} and {@link org.apache.juneau.transform.PojoSwap PojoSwaps}, which are used to tailor how Java objects are handled.
	<li>It's used by all built-in {@link org.apache.juneau.serializer.Serializer Serializers} and {@link org.apache.juneau.parser.Parser Parsers} for working with POJOs in a consistent way.
	</ul>

	<!-- ======================================================================================================== -->
	<a id="BeanMap"></a>
	<h3 class='topic' onclick='toggle(this)'>1.1 - The BeanMap class</h3>
	<div class='topic'>
	<p>
	The {@link org.apache.juneau.BeanMap} class allows you to access the properties of a bean through the familiar {@code Map} interface.
	So, for example, you can use the {@code Map.get(key)} method to retrieve a property value in leu of it's getter method, and the {@code Map.put(key, value)} method to set a property value in leu of it's setter method.
	</p>
	<p>
	The serialization and parsing of beans in Juneau is accomplished by wrapping Java beans inside instances of the class {@code BeanMap}.
	</p>
	<p>
	<b>Note:</b> Instances of {@link org.apache.juneau.BeanMap} objects are always retrieved through the {@link org.apache.juneau.BeanContext} class. You cannot instantiate {@code BeanMaps} directly since the rules for defining what constitutes a bean depend on various settings in the bean context.
	</p>
	<p>
	In general, the performance on using the {@link org.apache.juneau.BeanMap} class to access properties is equivalent to using reflection directly.
	</p>
	<p>
	See the {@link org.apache.juneau.BeanMap} javadoc for more information.
	</p>
	</div>

	<!-- ======================================================================================================== -->
	<a id="BeanContext"></a>
	<h3 class='topic' onclick='toggle(this)'>1.2 - The BeanContext and BeanSession classes</h3>
	<div class='topic'>
	<p>
	The {@link org.apache.juneau.BeanContext} and {@link org.apache.juneau.BeanSession} classes are the workhorse class used to wrap Java beans inside {@link org.apache.juneau.BeanMap BeanMaps}.
	There are several options provided on the {@link org.apache.juneau.BeanContext} class to tailor the definition of a bean.
	</p>
	<p>
	The following is a very simple example of how to wrap a bean inside a {@link org.apache.juneau.BeanMap} wrapper and use the wrapper interface to get and set property values on the bean.
	In this case, we're using the DEFAULT bean context.
	</p>
	<p class='bcode'>
	<jc>// A sample pseudo bean class.</jc>
	<jk>public class</jk> Person {
	<jk>public</jk> String getName();
	<jk>public void</jk> setName(String name);
	<jk>public int</jk> getAge();
	<jk>public void</jk> setAge(<jk>int</jk> age);
	}

	<jc>// Get an instance of a bean context.
	// In this case, just use the default bean context.</jc>
	BeanSession beanSession = BeanContext.<jsf>DEFAULT</jsf>.createSession();

	<jc>// Create an instance of our bean and wrap it in a bean map.</jc>
	Person p = <jk>new</jk> Person();
	BeanMap<Person> m = beanSession.toBeanMap(p);

	<jc>// Set some properties on the bean.</jc>
	m.put(<js>"name"</js>, <js>"John Smith"</js>);
	m.put(<js>"age"</js>, 21);

	<jc>// Print out bean properties.</jc>
	System.out.println(m.get(<js>"name"</js>)); <jc>// Prints "John Smith"</jc>
	System.out.println(p.getName()); <jc>// Prints "John Smith"</jc>
	System.out.println(m.get(<js>"age"</js>)); <jc>// Prints 21</jc>
	System.out.println(p.getAge()); <jc>// Prints 21</jc>

	<jc>// The bean context class can also create instances of bean maps.</jc>
	m = beanContext.newBeanMap(Person.<jk>class</jk>);
	p = m.getBean(); <jc>// Get the new wrapped bean.</jc>

	<jc>// The bean context class can also create instances of beans.</jc>
	p = beanContext.newBean(Person.<jk>class</jk>);
	</p>
	<p>
	There are 3 ways to get an instance of a {@link org.apache.juneau.BeanContext}:
	</p>
	<p class='bcode'>
	<jc>// Use one of the default bean contexts.</jc>
	BeanContext beanContext = BeanContext.<jsf>DEFAULT</jsf>;

	<jc>// Create a context from scratch with your own settings.</jc>
	beanContext = <jk>new</jk> BeanContext().addPojoSwaps(DateSwap.ISO8601DT.<jk>class</jk>);

	<jc>// Clone and modify an existing context.</jc>
	beanContext = BeanContext.<jsf>DEFAULT</jsf>.clone().addPojoSwaps(DateSwap.ISO8601DT.<jk>class</jk>);
	</p>
	<p>
	The {@link org.apache.juneau.BeanContext} class is a highly-customizable class.
	See the {@link org.apache.juneau.BeanContext} javadoc for more information.
	</p>
	</div>

	<!-- ======================================================================================================== -->
	<a id="Bean"></a>
	<h3 class='topic' onclick='toggle(this)'>1.3 - Bean annotations</h3>
	<div class='topic'>
	<p>
	Juneau provides the following annotations that can be used to fine-tune what properties are associated with beans:
	</p>
	<ul class='normal'>
	<li>{@link org.apache.juneau.annotation.Bean} - Fine-tune properties associated with beans.
	<li>{@link org.apache.juneau.annotation.BeanProperty} - Fine-tune bean properties (fields / getters / setters).
	<li>{@link org.apache.juneau.annotation.BeanConstructor} - Define read-only bean properties that can only be set through constructor arguments.
	<li>{@link org.apache.juneau.annotation.BeanIgnore} - Prevent bean classes/methods/fields from being interpreted as bean constructs.
	</ul>
	<p>
	These annotations always override the settings defined in the {@link org.apache.juneau.BeanContext} class.
	</p>
	<p>
	For example, the following bean class will only have one property associated with it, <js>"name"</js>, since it's the only one listed in the list of properties.
	</p>
	<p class='bcode'>
	<jc>// Bean with only one 'name' property</jc>
	<ja>@Bean</ja>(properties=<js>"name"</js>)
	<jk>public class</jk> Person {
	<jk>public</jk> String getName();
	<jk>public void</jk> setName(String name);
	<jk>public int</jk> getAge();
	<jk>public void</jk> setAge(<jk>int</jk> age);
	}
	</p>
	<p>
	When this bean is serialized using one of the {@link org.apache.juneau.serializer.Serializer Serializers}, the age property will be ignored.
	</p>
	<p>
	Using the <ja>@Bean</ja> and <ja>@BeanProperty</ja> annotations, it's also possible to include non-standard properties (for example, getters or setters with non-standard names), or override the names of properties (for example, {@code "Name"} or {@code "fullName"} instead of {@code "name"}).
	</p>
	<p>
	It should be noted that the {@link org.apache.juneau.transform.BeanFilter} class can also be used to exclude properties from beans.
	However, only the annotations can be used to include non-standard properties or override property names.
	</p>
	<p>
	See the {@link org.apache.juneau.annotation.Bean}, {@link org.apache.juneau.annotation.BeanProperty}, {@link org.apache.juneau.annotation.BeanConstructor}, and {@link org.apache.juneau.annotation.BeanIgnore} javadocs for more information.
	</p>
	</div>
	</div>

	</body>
	</html>