Package org.apache.juneau

Class BeanSession

java.lang.Object
org.apache.juneau.ContextSession
org.apache.juneau.BeanSession
Direct Known Subclasses:
BeanTraverseSession, ParserSession, RestRequest
public class BeanSession extends ContextSession
Session object that lives for the duration of a single use of BeanContext.
  • Typically session objects are not thread safe nor reusable. However, bean sessions do not maintain any state and thus can be safely cached and reused.
See Also:

  • Constructor Details

  • Method Details

    • create

      public static BeanSession.Builder create(BeanContext ctx)
      Creates a builder of this object.
      Parameters:
      ctx - The context creating this builder.
      Returns:
      A new builder.

    • convertToType

      public final <T> T convertToType(Object value, Class<T> type) throws InvalidDataConversionException
      Converts the specified value to the specified class type.

      See convertToType(Object, ClassMeta) for the list of valid conversions.

      Type Parameters:
      T - The class type to convert the value to.
      Parameters:
      value - The value to convert.
      type - The class type to convert the value to.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If the specified value cannot be converted to the specified type.

    • convertToMemberType

      public final <T> T convertToMemberType(Object outer, Object value, Class<T> type) throws InvalidDataConversionException
      Same as convertToType(Object, Class), except used for instantiating inner member classes that must be instantiated within another class instance.
      Type Parameters:
      T - The class type to convert the value to.
      Parameters:
      outer - If class is a member class, this is the instance of the containing class. Should be null if not a member class.
      value - The value to convert.
      type - The class type to convert the value to.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If the specified value cannot be converted to the specified type.

    • convertToType

      public final <T> T convertToType(Object value, ClassMeta<T> type) throws InvalidDataConversionException
      Casts the specified value into the specified type.

      If the value isn't an instance of the specified type, then converts the value if possible.

      The following conversions are valid:

      Convert to typeValid input value typesNotes
      A class that is the normal type of a registered ObjectSwap. A value whose class matches the transformed type of that registered ObjectSwap.  
      A class that is the transformed type of a registered ObjectSwap. A value whose class matches the normal type of that registered ObjectSwap.  
      Number (e.g. Integer, Short, Float,...)
      Number.TYPE (e.g. Integer.TYPE, Short.TYPE, Float.TYPE,...)       		Number, String, null For primitive TYPES, null returns the JVM default value for that type.
      Map (e.g. Map, HashMap, TreeMap, JsonMap) Map If Map is not constructible, an JsonMap is created.
      Collection (e.g. List, LinkedList, HashSet, JsonList) Collection<Object>
      Object[]       		If Collection is not constructible, an JsonList is created.
      X[] (array of any type X) List<X>  
      X[][] (multi-dimensional arrays) List<List<X>>
      List<X[]>
      List[]<X>       		 
      Enum String  
      Bean Map  
      String Anything Arrays are converted to JSON arrays
      Anything with one of the following methods:
      public static T fromString(String)
      public static T valueOf(String)
      public T(String)       		String
      Type Parameters:
      T - The class type to convert the value to.
      Parameters:
      value - The value to be converted.
      type - The target object type.
      Returns:
      The converted type.
      Throws:
      InvalidDataConversionException - If the specified value cannot be converted to the specified type.

    • convertToType

      public final <T> T convertToType(Object value, Type type, Type... args) throws InvalidDataConversionException
      Same as convertToType(Object, Class), but allows for complex data types consisting of collections or maps.
      Type Parameters:
      T - The class type to convert the value to.
      Parameters:
      value - The value to be converted.
      type - The target object type.
      args - The target object parameter types.
      Returns:
      The converted type.
      Throws:
      InvalidDataConversionException - If the specified value cannot be converted to the specified type.

    • convertToMemberType

      protected final <T> T convertToMemberType(Object outer, Object value, ClassMeta<T> to) throws InvalidDataConversionException
      Same as convertToType(Object, ClassMeta), except used for instantiating inner member classes that must be instantiated within another class instance.
      Type Parameters:
      T - The class type to convert the value to.
      Parameters:
      outer - If class is a member class, this is the instance of the containing class. Should be null if not a member class.
      value - The value to convert.
      to - The class type to convert the value to.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If the specified value cannot be converted to the specified type.

    • toArray

      protected final Object toArray(ClassMeta<?> type, Collection<?> list)
      Converts the contents of the specified list into an array.

      Works on both object and primitive arrays.

      In the case of multi-dimensional arrays, the incoming list must contain elements of type n-1 dimension. i.e. if type is int[][] then list must have entries of type int[].

      Parameters:
      type - The type to convert to. Must be an array type.
      list - The contents to populate the array with.
      Returns:
      A new object or primitive array.

    • toBeanMap

      public final <T> BeanMap<T> toBeanMap(T o)
      Wraps an object inside a BeanMap object (a modifiable Map).

      If object is not a true bean, then throws a BeanRuntimeException with an explanation of why it's not a bean.

      If object is already a BeanMap, simply returns the same object.

      Example:

      // Construct a bean map around a bean instance BeanMap<Person> beanMap = BeanContext.DEFAULT.toBeanMap(new Person());

      Type Parameters:
      T - The class of the object being wrapped.
      Parameters:
      o - The object to wrap in a map interface. Must not be null.
      Returns:
      The wrapped object.

    • toBeanMap

      public final <T> BeanMap<T> toBeanMap(T o, PropertyNamer propertyNamer)
      Wraps an object inside a BeanMap object (a modifiable Map).

      Same as toBeanMap(Object) but allows you to specify a property namer instance.

      Example:

      // Construct a bean map around a bean instance BeanMap<Person> beanMap = BeanContext.DEFAULT.toBeanMap(new Person(), PropertyNamerDLC.INSTANCE);

      Type Parameters:
      T - The class of the object being wrapped.
      Parameters:
      o - The object to wrap in a map interface. Must not be null.
      propertyNamer - The property namer to use.
      Returns:
      The wrapped object.

    • isBean

      public final boolean isBean(Object o)
      Determines whether the specified object matches the requirements on this context of being a bean.
      Parameters:
      o - The object being tested.
      Returns:
      true if the specified object is considered a bean.

    • isBean

      public final boolean isBean(Class<?> c)
      Determines whether the specified class matches the requirements on this context of being a bean.
      Parameters:
      c - The class being tested.
      Returns:
      true if the specified class is considered a bean.

    • toBeanMap

      public final <T> BeanMap<T> toBeanMap(T o, Class<? super T> c) throws BeanRuntimeException
      Wraps an object inside a BeanMap object (i.e.: a modifiable Map) defined as a bean for one of its class, a super class, or an implemented interface.

      If object is not a true bean, throws a BeanRuntimeException with an explanation of why it's not a bean.

      Example:

      // Construct a bean map for new bean using only properties defined in a superclass BeanMap<MySubBean> beanMap = BeanContext.DEFAULT.toBeanMap(new MySubBean(), MySuperBean.class); // Construct a bean map for new bean using only properties defined in an interface BeanMap<MySubBean> beanMap = BeanContext.DEFAULT.toBeanMap(new MySubBean(), MySuperInterface.class);

      Type Parameters:
      T - The class of the object being wrapped.
      Parameters:
      o - The object to wrap in a bean interface. Must not be null.
      c - The superclass to narrow the bean properties to. Must not be null.
      Returns:
      The bean representation, or null if the object is not a true bean.
      Throws:
      NullPointerException - If either parameter is null.
      IllegalArgumentException - If the specified object is not an an instance of the specified class.
      BeanRuntimeException - If specified object is not a bean according to the bean rules specified in this context class.

    • newBeanMap

      public final <T> BeanMap<T> newBeanMap(Class<T> c)
      Creates a new BeanMap object (a modifiable Map) of the given class with uninitialized property values.

      If object is not a true bean, then throws a BeanRuntimeException with an explanation of why it's not a bean.

      Example:

      // Construct a new bean map wrapped around a new Person object BeanMap<Person> beanMap = BeanContext.DEFAULT.newBeanMap(Person.class);

      Type Parameters:
      T - The class of the object being wrapped.
      Parameters:
      c - The name of the class to create a new instance of.
      Returns:
      A new instance of the class.

    • newBeanMap

      public final <T> BeanMap<T> newBeanMap(Object outer, Class<T> c)
      Same as newBeanMap(Class), except used for instantiating inner member classes that must be instantiated within another class instance.
      Type Parameters:
      T - The class of the object being wrapped.
      Parameters:
      c - The name of the class to create a new instance of.
      outer - If class is a member class, this is the instance of the containing class. Should be null if not a member class.
      Returns:
      A new instance of the class.

    • newBean

      public final <T> T newBean(Class<T> c) throws BeanRuntimeException
      Creates a new empty bean of the specified type, except used for instantiating inner member classes that must be instantiated within another class instance.
      Example:

      // Construct a new instance of the specified bean class Person person = BeanContext.DEFAULT.newBean(Person.class);

      Type Parameters:
      T - The class type of the bean being created.
      Parameters:
      c - The class type of the bean being created.
      Returns:
      A new bean object.
      Throws:
      BeanRuntimeException - If the specified class is not a valid bean.

    • newBean

      public final <T> T newBean(Object outer, Class<T> c) throws BeanRuntimeException
      Same as newBean(Class), except used for instantiating inner member classes that must be instantiated within another class instance.
      Type Parameters:
      T - The class type of the bean being created.
      Parameters:
      c - The class type of the bean being created.
      outer - If class is a member class, this is the instance of the containing class. Should be null if not a member class.
      Returns:
      A new bean object.
      Throws:
      BeanRuntimeException - If the specified class is not a valid bean.

    • getBeanMeta

      public final <T> BeanMeta<T> getBeanMeta(Class<T> c)
      Returns the BeanMeta class for the specified class.
      Type Parameters:
      T - The class type to get the meta-data on.
      Parameters:
      c - The class to get the meta-data on.
      Returns:
      The BeanMeta for the specified class, or null if the class is not a bean per the settings on this context.

    • getClassMeta

      public final <T> ClassMeta<T> getClassMeta(Class<T> c)
      Returns a ClassMeta wrapper around a Class object.
      Type Parameters:
      T - The class type being wrapped.
      Parameters:
      c - The class being wrapped.
      Returns:
      The class meta object containing information about the class.

    • getClassMeta

      public final <T> ClassMeta<T> getClassMeta(Type type, Type... args)
      Used to resolve ClassMetas of type Collection and Map that have ClassMeta values that themselves could be collections or maps.

      Collection meta objects are assumed to be followed by zero or one meta objects indicating the element type.

      Map meta objects are assumed to be followed by zero or two meta objects indicating the key and value types.

      The array can be arbitrarily long to indicate arbitrarily complex data structures.

      Examples:
      • getClassMeta(String.class); - A normal type.
      • getClassMeta(List.class); - A list containing objects.
      • getClassMeta(List.class, String.class); - A list containing strings.
      • getClassMeta(LinkedList.class, String.class); - A linked-list containing strings.
      • getClassMeta(LinkedList.class, LinkedList.class, String.class); - A linked-list containing linked-lists of strings.
      • getClassMeta(Map.class); - A map containing object keys/values.
      • getClassMeta(Map.class, String.class, String.class); - A map containing string keys/values.
      • getClassMeta(Map.class, String.class, List.class, MyBean.class); - A map containing string keys and values of lists containing beans.
      Type Parameters:
      T - The class to resolve.
      Parameters:
      type - The class to resolve.
      Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
      args - The type arguments of the class if it's a collection or map.
      Can be any of the following: ClassMeta, Class, ParameterizedType, GenericArrayType
      Ignored if the main type is not a map or collection.
      Returns:
      The class meta.

    • getArgsClassMeta

      protected final ClassMeta<Object[]> getArgsClassMeta(Type[] classes)
      Given an array of Type objects, returns a ClassMeta representing those arguments.

      Constructs a new meta on each call.

      Parameters:
      classes - The array of classes to get class metas for.
      Returns:
      The args ClassMeta object corresponding to the classes. Never null.

    • getClassMetaForObject

      public final <T> ClassMeta<T> getClassMetaForObject(T o)
      Shortcut for calling getClassMeta(o.getClass()).
      Type Parameters:
      T - The class of the object being passed in.
      Parameters:
      o - The class to find the class type for.
      Returns:
      The ClassMeta object, or null if o is null.

    • getClassMetaForObject

      protected final ClassMeta<?> getClassMetaForObject(Object o, ClassMeta<?> def)
      Shortcut for calling getClassMeta(o.getClass()) but returns a default value if object is null.
      Parameters:
      o - The class to find the class type for.
      def - The default ClassMeta if the object is null.
      Returns:
      The ClassMeta object, or the default value if o is null.

    • getLocale

      public Locale getLocale()
      Locale.

      The locale is determined in the following order:

      1. locale parameter passed in through constructor.
      2. BeanContext.Builder.locale(Locale) setting on bean context.
      3. Locale returned by Locale.getDefault().
      Returns:
      The session locale.
      See Also:

    • getMediaType

      public final MediaType getMediaType()
      Media type.

      For example, "application/json".

      Returns:
      The media type for this session, or null if not specified.
      See Also:

    • getBeanTypePropertyName

      public final String getBeanTypePropertyName(ClassMeta cm)
      Returns the type property name as defined by BeanContext.Builder.typePropertyName(String).
      Parameters:
      cm - The class meta of the type we're trying to resolve the type name for. Can be null.
      Returns:
      The type property name. Never null.

    • getNamePropertyName

      public final String getNamePropertyName()
      Returns the name property name.

      Currently this always returns "_name".

      Returns:
      The name property name. Never null.

    • getBeanRegistry

      public final BeanRegistry getBeanRegistry()
      Returns the bean registry defined in this bean context defined by BeanContext.Builder.beanDictionary(Class...).
      Returns:
      The bean registry defined in this bean context. Never null.

    • object

      public final ClassMeta<Object> object()
      Returns a reusable ClassMeta representation for the class Object.

      This ClassMeta is often used to represent "any object type" when an object type is not known.

      This method is identical to calling getClassMeta(Object.class) but uses a cached copy to avoid a hashmap lookup.

      Returns:
      The ClassMeta object associated with the Object class.

    • string

      public final ClassMeta<String> string()
      Returns a reusable ClassMeta representation for the class String.

      This ClassMeta is often used to represent key types in maps.

      This method is identical to calling getClassMeta(String.class) but uses a cached copy to avoid a hashmap lookup.

      Returns:
      The ClassMeta object associated with the String class.

    • _class

      public final ClassMeta<Class> _class()
      Returns a reusable ClassMeta representation for the class Class.

      This ClassMeta is often used to represent key types in maps.

      This method is identical to calling getClassMeta(Class.class) but uses a cached copy to avoid a hashmap lookup.

      Returns:
      The ClassMeta object associated with the String class.

    • newGenericMap

      protected Map newGenericMap(ClassMeta mapMeta)
      Creates either an JsonMap or LinkedHashMap depending on whether the key type is String or something else.
      Parameters:
      mapMeta - The metadata of the map to create.
      Returns:
      A new map.

    • addWarning

      public void addWarning(String msg, Object... args)
      Logs a warning message.
      Overrides:
      addWarning in class ContextSession
      Parameters:
      msg - The warning message.
      args - Optional MessageFormat-style arguments.

    • getBeanClassVisibility

      public final Visibility getBeanClassVisibility()
      Minimum bean class visibility.
      Returns:
      Classes are not considered beans unless they meet the minimum visibility requirements.
      See Also:

    • getBeanConstructorVisibility

      public final Visibility getBeanConstructorVisibility()
      Minimum bean constructor visibility.
      Returns:
      Only look for constructors with this specified minimum visibility.
      See Also:

    • getBeanDictionary

      public final List<Class<?>> getBeanDictionary()
      Bean dictionary.
      Returns:
      The list of classes that make up the bean dictionary in this bean context.
      See Also:

    • getBeanFieldVisibility

      public final Visibility getBeanFieldVisibility()
      Minimum bean field visibility.
      Returns:
      Only look for bean fields with this specified minimum visibility.
      See Also:

    • isBeanMapPutReturnsOldValue

      public final boolean isBeanMapPutReturnsOldValue()
      BeanMap.put() returns old property value.
      Returns:
      true if the BeanMap.put() method will return old property values.
      Otherwise, it returns null.
      See Also:

    • getBeanMethodVisibility

      public final Visibility getBeanMethodVisibility()
      Minimum bean method visibility.
      Returns:
      Only look for bean methods with this specified minimum visibility.
      See Also:

    • isBeansRequireDefaultConstructor

      public final boolean isBeansRequireDefaultConstructor()
      Beans require no-arg constructors.
      Returns:
      true if a Java class must implement a default no-arg constructor to be considered a bean.
      Otherwise, the bean will be serialized as a string using the Object.toString() method.
      See Also:

    • isBeansRequireSerializable

      public final boolean isBeansRequireSerializable()
      Beans require Serializable interface.
      Returns:
      true if a Java class must implement the Serializable interface to be considered a bean.
      Otherwise, the bean will be serialized as a string using the Object.toString() method.
      See Also:

    • isBeansRequireSettersForGetters

      public final boolean isBeansRequireSettersForGetters()
      Beans require setters for getters.
      Returns:
      true if only getters that have equivalent setters will be considered as properties on a bean.
      Otherwise, they are ignored.
      See Also:

    • isBeansRequireSomeProperties

      public final boolean isBeansRequireSomeProperties()
      Beans require at least one property.
      Returns:
      true if a Java class doesn't need to contain at least 1 property to be considered a bean.
      Otherwise, the bean is serialized as a string using the Object.toString() method.
      See Also:

    • getBeanTypePropertyName

      public final String getBeanTypePropertyName()
      Bean type property name.
      Returns:
      The name of the bean property used to store the dictionary name of a bean type so that the parser knows the data type to reconstruct.
      See Also:

    • isFindFluentSetters

      public final boolean isFindFluentSetters()
      Find fluent setters.
      Description:

      Returns:
      true if fluent setters are detected on beans.
      See Also:

    • isIgnoreInvocationExceptionsOnGetters

      public final boolean isIgnoreInvocationExceptionsOnGetters()
      Ignore invocation errors on getters.
      Returns:
      true if errors thrown when calling bean getter methods are silently ignored.
      See Also:

    • isIgnoreInvocationExceptionsOnSetters

      public final boolean isIgnoreInvocationExceptionsOnSetters()
      Ignore invocation errors on setters.
      Returns:
      true if errors thrown when calling bean setter methods are silently ignored.
      See Also:

    • isIgnoreMissingSetters

      public final boolean isIgnoreMissingSetters()
      Silently ignore missing setters.
      Returns:
      true if trying to set a value on a bean property without a setter should throw a BeanRuntimeException.
      See Also:

    • isIgnoreUnknownBeanProperties

      public final boolean isIgnoreUnknownBeanProperties()
      Ignore unknown properties.
      Returns:
      true if trying to set a value on a non-existent bean property is silently ignored.
      Otherwise, a RuntimeException is thrown.
      See Also:

    • isIgnoreUnknownNullBeanProperties

      public final boolean isIgnoreUnknownNullBeanProperties()
      Ignore unknown properties with null values.
      Returns:
      true if trying to set a null value on a non-existent bean property should not throw a BeanRuntimeException.
      See Also:

    • getNotBeanClasses

      public final Class<?>[] getNotBeanClasses()
      Bean class exclusions.
      Returns:
      The list of classes that are explicitly not beans.
      See Also:

    • getNotBeanPackagesNames

      public final String[] getNotBeanPackagesNames()
      Bean package exclusions.
      Returns:
      The list of fully-qualified package names to exclude from being classified as beans.
      See Also:

    • getNotBeanPackagesPrefixes

      protected final String[] getNotBeanPackagesPrefixes()
      Bean package exclusions.
      Returns:
      The list of package name prefixes to exclude from being classified as beans.
      See Also:

    • getPropertyNamer

      public final PropertyNamer getPropertyNamer()
      Bean property namer.
      Returns:
      The interface used to calculate bean property names.
      See Also:

    • isSortProperties

      public final boolean isSortProperties()
      Sort bean properties.
      Returns:
      true if all bean properties will be serialized and access in alphabetical order.
      See Also:

    • getSwaps

      public final ObjectSwap<?,?>[] getSwaps()
      Java object swaps.
      Returns:
      The list POJO swaps defined.
      See Also:

    • getTimeZone

      public final TimeZone getTimeZone()
      Time zone.

      The timezone is determined in the following order:

      1. timeZone parameter passed in through constructor.
      2. BeanContext.Builder.timeZone(TimeZone) setting on bean context.
      Returns:
      The session timezone, or null if timezone not specified.
      See Also:

    • getTimeZoneId

      public final ZoneId getTimeZoneId()
      Time zone.

      The timezone is determined in the following order:

      1. timeZone parameter passed in through constructor.
      2. BeanContext.Builder.timeZone(TimeZone) setting on bean context.
      Returns:
      The session timezone, or the system timezone if not specified. Never null.
      See Also:

    • isUseEnumNames

      public final boolean isUseEnumNames()
      Use enum names.
      Returns:
      true if enums are always serialized by name, not using Object.toString().
      See Also:

    • isUseInterfaceProxies

      public final boolean isUseInterfaceProxies()
      Use interface proxies.
      Returns:
      true if interfaces will be instantiated as proxy classes through the use of an InvocationHandler if there is no other way of instantiating them.
      See Also:

    • isUseJavaBeanIntrospector

      public final boolean isUseJavaBeanIntrospector()
      Use Java Introspector.
      Returns:
      true if the built-in Java bean introspector should be used for bean introspection.
      See Also: