• Home
• org.apache.juneau
• juneau-all
• 9.0.1
• source code
• BeanContext.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.apache.juneau.BeanContext Maven / Gradle / Ivy

// ***************************************************************************************************************************
// * 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.                                              *
// ***************************************************************************************************************************
package org.apache.juneau;

import static org.apache.juneau.Visibility.*;
import static org.apache.juneau.collections.JsonMap.*;
import static org.apache.juneau.common.internal.StringUtils.*;
import static org.apache.juneau.common.internal.ThrowableUtils.*;
import static org.apache.juneau.internal.ClassUtils.*;
import static org.apache.juneau.internal.CollectionUtils.*;

import java.beans.*;
import java.io.*;
import java.lang.annotation.*;
import java.lang.reflect.*;
import java.util.*;
import java.util.concurrent.*;
import java.util.stream.*;

import org.apache.juneau.annotation.*;
import org.apache.juneau.collections.*;
import org.apache.juneau.cp.*;
import org.apache.juneau.internal.*;
import org.apache.juneau.json.*;
import org.apache.juneau.marshaller.*;
import org.apache.juneau.reflect.*;
import org.apache.juneau.serializer.*;
import org.apache.juneau.swap.*;
import org.apache.juneau.utils.*;

/**
 * Bean context.
 *
 * 

 * This class servers multiple purposes:
 * 

 * 	

 * 		Provides the ability to wrap beans inside {@link Map} interfaces.
 * 	

 * 		Serves as a repository for metadata on POJOs, such as associated {@link Bean @Bean} annotations,
 * 		{@link PropertyNamer PropertyNamers}, etc...  which are used to tailor how POJOs are serialized and parsed.
 * 
 *
 * 

 * All serializers and parsers use this context so that they can handle POJOs using a common framework.
 *
 * 
Bean Contexts
 *
 * 

 * Bean contexts are created through the {@link BeanContext#create() BeanContext.create()} and {@link Builder#build()} methods.
 * 
These context objects are read-only, reusable, and thread-safe.
 *
 * 

 * Each bean context maintains a cache of {@link ClassMeta} objects that describe information about classes encountered.
 * These ClassMeta objects are time-consuming to construct.
 * Therefore, instances of {@link BeanContext} that share the same "BeanContext.*" property values share
 * the same cache.  This allows for efficient reuse of ClassMeta objects so that the information about
 * classes only needs to be calculated once.
 * Because of this, many of the properties defined on the {@link BeanContext} class cannot be overridden on the session.
 *
 * 
Bean Sessions
 *
 * 

 * Whereas BeanContext objects are permanent, unchangeable, cached, and thread-safe,
 * {@link BeanSession} objects are ephemeral and not thread-safe.
 * They are meant to be used as quickly-constructed scratchpads for creating bean maps.
 * {@link BeanMap} objects can only be created through the session.
 *
 * 
BeanContext configuration properties
 *
 * 

 * BeanContexts have several configuration properties that can be used to tweak behavior on how beans are
 * handled.  These are denoted as the static BEAN_* fields on this class.
 *
 * 

 * Some settings (e.g. {@link Builder#beansRequireDefaultConstructor()}) are used to differentiate between bean
 * and non-bean classes.
 * Attempting to create a bean map around one of these objects will throw a {@link BeanRuntimeException}.
 * The purpose for this behavior is so that the serializers can identify these non-bean classes and convert them to
 * plain strings using the {@link Object#toString()} method.
 *
 * 

 * Some settings (e.g. {@link Builder#beanFieldVisibility(Visibility)}) are used to determine what kinds of properties are
 * detected on beans.
 *
 * 

 * Some settings (e.g. {@link Builder#beanMapPutReturnsOldValue()}) change the runtime behavior of bean maps.
 *
 * 
Example:
 *
 * 

 * 	// Construct a context from scratch.
 * 	BeanContext beanContext = BeanContext
 * 		.create()
 * 		.beansRequireDefaultConstructor()
 * 		.notBeanClasses(Foo.class)
 * 		.build();
 * 
 *
 * 
Bean Maps
 *
 * 

 * {@link BeanMap BeanMaps} are wrappers around Java beans that allow properties to be retrieved and
 * set using the common {@link Map#put(Object,Object)} and {@link Map#get(Object)} methods.
 *
 * 

 * Bean maps are created in two ways...
 * 

 * 	
{@link BeanSession#toBeanMap(Object) BeanSession.toBeanMap()} - Wraps an existing bean inside a {@code Map}
 * 		wrapper.
 * 	
{@link BeanSession#newBeanMap(Class) BeanSession.newBeanMap()} - Create a new bean instance wrapped in a
 * 		{@code Map} wrapper.
 * 
 *
 * 
Example:
 *
 * 

 * 	// A sample bean class
 * 	public class Person {
 * 		public String getName();
 * 		public void setName(String name);
 * 		public int getAge();
 * 		public void setAge(int age);
 * 	}
 *
 * 	// Create a new bean session
 * 	BeanSession session = BeanContext.DEFAULT.createSession();
 *
 * 	// Wrap an existing bean in a new bean map
 * 	BeanMap<Person> map1 = session.toBeanMap(new Person());
 * 	map1.put("name", "John Smith");
 * 	map1.put("age", 45);
 *
 * 	// Create a new bean instance wrapped in a new bean map
 * 	BeanMap<Person> map2 = session.newBeanMap(Person.class);
 * 	map2.put("name", "John Smith");
 * 	map2.put("age", 45);
 * 	Person person = map2.getBean();  // Get the bean instance that was created.
 * 
 *
 * 
Notes:

 * 	
This class is thread safe and reusable.
 * 
 *
 * 
See Also:

 * 	
Bean Contexts
 * 
 */
@SuppressWarnings({"unchecked","rawtypes"})
public class BeanContext extends Context {

	//-----------------------------------------------------------------------------------------------------------------
	// Static
	//-----------------------------------------------------------------------------------------------------------------

	/*
	 * The default package pattern exclusion list.
	 * Any beans in packages in this list will not be considered beans.
	 */
	private static final String[] DEFAULT_NOTBEAN_PACKAGES = {
		"java.lang",
		"java.lang.annotation",
		"java.lang.ref",
		"java.lang.reflect",
		"java.io",
		"java.net",
		"java.nio.*",
		"java.util.*"
	};

	/*
	 * The default bean class exclusion list.
	 * Anything in this list will not be considered beans.
	 */
	private static final Class[] DEFAULT_NOTBEAN_CLASSES = {
		Map.class,
		Collection.class,
		Reader.class,
		Writer.class,
		InputStream.class,
		OutputStream.class,
		Throwable.class
	};


	/** Default config.  All default settings. */
	public static final BeanContext DEFAULT = create().build();

	/** Default config.  All default settings except sort bean properties. */
	public static final BeanContext DEFAULT_SORTED = create().sortProperties().build();

	/** Default reusable unmodifiable session.  Can be used to avoid overhead of creating a session (for creating BeanMaps for example).*/
	public  static final BeanSession DEFAULT_SESSION = DEFAULT.createSession().unmodifiable().build();

	/**
	 * Creates a new builder for this object.
	 *
	 * @return A new builder.
	 */
	public static Builder create() {
		return new Builder();
	}

	//-----------------------------------------------------------------------------------------------------------------
	// Builder
	//-----------------------------------------------------------------------------------------------------------------

	/**
	 * Builder class.
	 */
	@FluentSetters
	public static class Builder extends Context.Builder {

		private static final Cache CACHE = Cache.of(HashKey.class, BeanContext.class).build();

		Visibility beanClassVisibility, beanConstructorVisibility, beanMethodVisibility, beanFieldVisibility;
		boolean disableBeansRequireSomeProperties, beanMapPutReturnsOldValue, beansRequireDefaultConstructor, beansRequireSerializable,
			beansRequireSettersForGetters, disableIgnoreTransientFields, disableIgnoreUnknownNullBeanProperties, disableIgnoreMissingSetters,
			disableInterfaceProxies, findFluentSetters, ignoreInvocationExceptionsOnGetters, ignoreInvocationExceptionsOnSetters,
			ignoreUnknownBeanProperties, ignoreUnknownEnumValues, sortProperties, useEnumNames, useJavaBeanIntrospector;
		String typePropertyName;
		MediaType mediaType;
		Locale locale;
		TimeZone timeZone;
		Class propertyNamer;
		List> beanDictionary;
		List