Package org.apache.juneau.commons.bean

Annotation Interface BeanConfig

@Documented @Target({TYPE,METHOD}) @Retention(RUNTIME) @Inherited public @interface BeanConfig
Annotation for specifying bean-modeling config properties on REST classes and methods.

The bean-modeling sibling of @MarshalledConfig. Where @MarshalledConfig (in juneau-marshall) carries the marshalling-only attributes (such as dictionary, swaps, typePropertyName, locale, mediaType, and timeZone), this annotation carries the attributes that describe how the bean MODEL is detected and introspected — visibility settings, required-properties toggles, fluent-setter detection, property naming, not-bean exclusions, etc.

Splitting the annotations lets a class/method participate in bean-modeling configuration without dragging in any marshalling concerns, and lets the bean-modeling layer live in juneau-commons independent of juneau-marshall.

Can be used in the following locations:

  • Classes and methods (typically REST classes/methods).

  • Element Details

    • beanClassVisibility

      String beanClassVisibility
      Minimum bean class visibility.

      Classes are not considered beans unless they meet the minimum visibility requirements.

      For example, if the visibility is PUBLIC and the bean class is protected, then the class will not be interpreted as a bean class and be serialized as a string.
      Use this setting to reduce the visibility requirement.

      • "PUBLIC" (default)
      • "PROTECTED"
      • "DEFAULT"
      • "PRIVATE"
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • beanConstructorVisibility

      String beanConstructorVisibility
      Minimum bean constructor visibility.

      Only look for constructors with the specified minimum visibility.

      This setting affects the logic for finding no-arg constructors for bean.
      Normally, only public no-arg constructors are used.
      Use this setting if you want to reduce the visibility requirement.

      • "PUBLIC" (default)
      • "PROTECTED"
      • "DEFAULT"
      • "PRIVATE"
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • beanFieldVisibility

      String beanFieldVisibility
      Minimum bean field visibility.

      Only look for bean fields with the specified minimum visibility.

      This affects which fields on a bean class are considered bean properties.
      Normally only public fields are considered.
      Use this setting if you want to reduce the visibility requirement.

      • "PUBLIC" (default)
      • "PROTECTED"
      • "DEFAULT"
      • "PRIVATE"
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • beanMapPutReturnsOldValue

      String beanMapPutReturnsOldValue
      BeanMap.put() returns old property value.

      If "true", then the BeanMap.put() method will return old property values.
      Otherwise, it returns null.

      • "true"
      • "false" (default because it introduces a slight performance penalty during serialization)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • beanMethodVisibility

      String beanMethodVisibility
      Minimum bean method visibility.

      Only look for bean methods with the specified minimum visibility.

      This affects which methods are detected as getters and setters on a bean class.
      Normally only public getters and setters are considered.
      Use this setting if you want to reduce the visibility requirement.

      • "PUBLIC" (default)
      • "PROTECTED"
      • "DEFAULT"
      • "PRIVATE"
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • beansRequireDefaultConstructor

      String beansRequireDefaultConstructor
      Beans require no-arg constructors.

      If "true", 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.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • beansRequireSerializable

      String beansRequireSerializable
      Beans require Serializable interface.

      If "true", 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.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • beansRequireSettersForGetters

      String beansRequireSettersForGetters
      Beans require setters for getters.

      If "true", only getters that have equivalent setters will be considered as properties on a bean.
      Otherwise, they will be ignored.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • disableBeansRequireSomeProperties

      String disableBeansRequireSomeProperties
      Beans don't require at least one property.

      If "true", then a Java class doesn't need to contain at least 1 property to be considered a bean.
      Otherwise, the bean will be serialized as a string using the Object.toString() method.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • disableIgnoreMissingSetters

      String disableIgnoreMissingSetters
      Don't silently ignore missing setters.

      If "true", trying to set a value on a bean property without a setter will throw a BeanRuntimeException.
      Otherwise it will be sliently ignored.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • disableIgnoreTransientFields

      String disableIgnoreTransientFields
      Don't ignore transient fields.

      If true, methods and fields marked as transient will not be ignored as bean properties.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • disableIgnoreUnknownNullBeanProperties

      String disableIgnoreUnknownNullBeanProperties
      Don't ignore unknown properties with null values.

      If "true", trying to set a null value on a non-existent bean property will throw a BeanRuntimeException. Otherwise it will be silently ignored.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • disableInterfaceProxies

      String disableInterfaceProxies
      Don't use interface proxies.

      Disables the feature where interfaces will be instantiated as proxy classes through the use of an InvocationHandler if there is no other way of instantiating them.
      Setting this to "true" causes this to be a BeanRuntimeException.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • findFluentSetters

      String findFluentSetters
      Find fluent setters.

      When enabled, fluent setters are detected on beans.

      Fluent setters must have the following attributes:

      • Public.
      • Not static.
      • Take in one parameter.
      • Return the bean itself.
      • "true"
      • "false" (default)
      Notes:
      See Also:
      Returns:
      The annotation value.
      Default:
      ""

    • ignoreInvocationExceptionsOnGetters

      String ignoreInvocationExceptionsOnGetters
      Ignore invocation errors on getters.

      If "true", errors thrown when calling bean getter methods will silently be ignored.
      Otherwise, a BeanRuntimeException is thrown.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • ignoreInvocationExceptionsOnSetters

      String ignoreInvocationExceptionsOnSetters
      Ignore invocation errors on setters.

      If "true", errors thrown when calling bean setter methods will silently be ignored.
      Otherwise, a BeanRuntimeException is thrown.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • ignoreUnknownBeanProperties

      String ignoreUnknownBeanProperties
      Ignore unknown properties.

      If "true", trying to set a value on a non-existent bean property will silently be ignored.
      Otherwise, a RuntimeException is thrown.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • validateSchema

      String validateSchema
      Schema validation mode.

      If "true", bean property values are validated against the constraints declared by @Schema annotations on those properties. Validation runs during both parsing (value set on the bean) and serialization (value read from the bean).

      Backed by the typed JsonSchema bean in juneau-bean-jsonschema and JSON Schema Draft 2020-12 semantics. Validation failures throw SchemaValidationException wrapped in BeanRuntimeException; the parser surfaces them as parse exceptions and the serializer surfaces them as serialize exceptions.

      If juneau-bean-jsonschema is not on the classpath, this setting becomes a silent no-op.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Since:
      10.0.0
      Default:
      ""

    • ignoreUnknownEnumValues

      String ignoreUnknownEnumValues
      Ignore unknown enum values.

      If "true", unknown enum values are set to null instead of throwing an exception.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • interfaces

      Class<?>[] interfaces
      Identifies a set of interfaces.

      When specified, only the list of properties defined on the interface class will be used during serialization of implementation classes. Additional properties on subclasses will be ignored.

      // Parent class or interface public abstract class A { public String foo = "foo"; } // Sub class public class A1 extends A { public String bar = "bar"; } // Apply it to a config @BeanConfig( interfaces={ A.class } )

      This annotation can be used on the parent class so that it filters to all child classes, or can be set individually on the child classes.

      Notes:
      Returns:
      The annotation value.
      Default:
      {}

    • notBeanClasses

      Class<?>[] notBeanClasses
      Bean class exclusions.

      List of classes that should not be treated as beans even if they appear to be bean-like.
      Not-bean classes are converted to Strings during serialization.

      Notes:
      Returns:
      The annotation value.
      Default:
      {}

    • notBeanClasses_replace

      Class<?>[] notBeanClasses_replace
      Replace classes that should not be considered beans.

      Same as notBeanClasses() but replaces any existing value.

      Returns:
      The annotation value.
      Default:
      {}

    • notBeanPackages

      String[] notBeanPackages
      Bean package exclusions.

      When specified, the current list of ignore packages are appended to.

      Any classes within these packages will be serialized to strings using Object.toString().

      Note that you can specify suffix patterns to include all subpackages.

      Notes:
      • The default value excludes the following packages:
      • Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").
      Returns:
      The annotation value.
      Default:
      {}

    • notBeanPackages_replace

      String[] notBeanPackages_replace
      Replace packages whose classes should not be considered beans.

      Same as notBeanPackages() but replaces any existing value.

      Returns:
      The annotation value.
      Default:
      {}

    • propertyNamer

      Class<? extends PropertyNamer> propertyNamer
      Bean property namer.

      The class to use for calculating bean property names.

      Predefined classes:

      Returns:
      The annotation value.
      Default:
      org.apache.juneau.commons.bean.PropertyNamer.Void.class

    • rank

      int rank
      Optional rank for this config.

      Can be used to override default ordering and application of config annotations.

      Returns:
      The annotation value.
      Default:
      0

    • unsortedProperties

      String unsortedProperties
      Disable sorted bean properties.

      When true, bean properties are serialized and accessed in declaration order instead of the default alphabetical order: record component order for records, field declaration order (superclass first) for other classes, then method-only properties alphabetically.

      • "true"
      • "false" (default — properties are sorted alphabetically)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • recordComponentOrder

      String recordComponentOrder
      Record component order.

      When true, the properties of Record beans use record component (declaration) order even when other beans are sorted alphabetically. Non-record beans are unaffected.

      Example:

      @BeanConfig(recordComponentOrder="true") public class MyRestResource { ... } public record Person(String name, int age) {} // Serialized as {"name":"Alice","age":30} instead of {"age":30,"name":"Alice"}

      • "true"
      • "false" (default: record properties are sorted alphabetically like other beans)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • useJavaBeanIntrospector

      String useJavaBeanIntrospector
      Use Java Introspector.

      Using the built-in Java bean introspector will not pick up fields or non-standard getters/setters.
      Most @BeanType annotations will be ignored.

      • "true"
      • "false" (default)
      Notes:
      Returns:
      The annotation value.
      Default:
      ""