Package org.apache.juneau

Class BeanContextable.Builder

java.lang.Object
org.apache.juneau.Context.Builder
org.apache.juneau.BeanContextable.Builder
Direct Known Subclasses:
BaseHttpPartParser.Builder, BaseHttpPartSerializer.Builder, BeanTraverseContext.Builder, Parser.Builder, RestClient.Builder
Enclosing class:
BeanContextable
public abstract static class BeanContextable.Builder extends Context.Builder
Builder class.

  • Constructor Details

    • Builder

      protected Builder()
      Constructor. All default settings.

    • Builder

      protected Builder(BeanContextable copyFrom)
      Copy constructor.
      Parameters:
      copyFrom - The bean to copy from.

    • Builder

      protected Builder(BeanContextable.Builder copyFrom)
      Copy constructor.
      Parameters:
      copyFrom - The builder to copy from.

  • Method Details

    • copy

      public abstract BeanContextable.Builder copy()
      Description copied from class: Context.Builder
      Copy creator.
      Specified by:
      copy in class Context.Builder
      Returns:
      A new mutable copy of this builder.

    • hashKey

      public HashKey hashKey()
      Description copied from class: Context.Builder
      Returns the hashkey of this builder.

      Used to return previously instantiated context beans that have matching hashkeys. The HashKey object is suitable for use as a hashmap key of a map of context beans. A context bean is considered equivalent if the HashKey.equals(Object) method is the same.

      Overrides:
      hashKey in class Context.Builder
      Returns:
      The hashkey of this builder.

    • beanContext

      public BeanContext.Builder beanContext()
      Returns the inner bean context builder.
      Returns:
      The inner bean context builder.

    • beanContext

      public final BeanContextable.Builder beanContext(Consumer<BeanContext.Builder> operation)
      Applies an operation to the inner bean context builder.
      Parameters:
      operation - The operation to apply.
      Returns:
      This object.

    • beanContext

      public BeanContextable.Builder beanContext(BeanContext.Builder value)
      Overrides the bean context builder.

      Used when sharing bean context builders across multiple context objects. For example, JsonSchemaGenerator.Builder uses this to apply common bean settings with the JSON serializer and parser.

      Parameters:
      value - The new value for this setting.
      Returns:
      This object.

    • beanContext

      public BeanContextable.Builder beanContext(BeanContext value)
      Specifies an already-instantiated bean context to use.

      Provides an optimization for cases where serializers and parsers can use an existing bean context without having to go through beanContext.copy().build(). An example is BeanContext.getBeanToStringSerializer().

      Parameters:
      value - The bean context to use.
      Returns:
      This object.

    • beanClassVisibility

      public BeanContextable.Builder beanClassVisibility(Visibility value)
      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.

      Example:

      // A bean with a protected class and one field. protected class MyBean { public String foo = "bar"; } // Create a serializer that's capable of serializing the class. WriterSerializer serializer = JsonSerializer .create() .beanClassVisibility(PROTECTED) .build(); // Produces: {"foo","bar"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean annotation can be used on a non-public bean class to override this setting.
      • The @BeanIgnore annotation can also be used on a public bean class to ignore it as a bean.
      See Also:
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC.
      Returns:
      This object.

    • beanConstructorVisibility

      public BeanContextable.Builder beanConstructorVisibility(Visibility value)
      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.

      Example:

      // A bean with a protected constructor and one field. public class MyBean { public String foo; protected MyBean() {} } // Create a parser capable of calling the protected constructor. ReaderParser parser = ReaderParser .create() .beanConstructorVisibility(PROTECTED) .build(); // Use it. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      Notes:
      • The @Beanc annotation can also be used to expose a non-public constructor.
      • The @BeanIgnore annotation can also be used on a public bean constructor to ignore it.
      See Also:
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC.
      Returns:
      This object.

    • beanFieldVisibility

      public BeanContextable.Builder beanFieldVisibility(Visibility value)
      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.

      Example:

      // A bean with a protected field. public class MyBean { protected String foo = "bar"; } // Create a serializer that recognizes the protected field. WriterSerializer serializer = JsonSerializer .create() .beanFieldVisibility(PROTECTED) .build(); // Produces: {"foo":"bar"} String json = serializer.serialize(new MyBean());

      Bean fields can be ignored as properties entirely by setting the value to Visibility.NONE

      // Disable using fields as properties entirely. WriterSerializer serializer = JsonSerializer .create() .beanFieldVisibility(NONE) .build();

      Notes:
      • The @Beanp annotation can also be used to expose a non-public field.
      • The @BeanIgnore annotation can also be used on a public bean field to ignore it as a bean property.
      See Also:
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC.
      Returns:
      This object.

    • beanInterceptor

      public BeanContextable.Builder beanInterceptor(Class<?> on, Class<? extends BeanInterceptor<?>> value)
      Bean interceptor.

      Bean interceptors can be used to intercept calls to getters and setters and alter their values in transit.

      Example:

      // Interceptor that strips out sensitive information. public class AddressInterceptor extends BeanInterceptor<Address> { public Object readProperty(Address bean, String name, Object value) { if ("taxInfo".equals(name)) return "redacted"; return value; } public Object writeProperty(Address bean, String name, Object value) { if ("taxInfo".equals(name) && "redacted".equals(value)) return TaxInfoUtils.lookup(bean.getStreet(), bean.getCity(), bean.getState()); return value; } } // Our bean class. public class Address { public String getTaxInfo() {...} public void setTaxInfo(String value) {...} } // Register filter on serializer or parser. WriterSerializer serializer = JsonSerializer .create() .beanInterceptor(Address.class, AddressInterceptor.class) .build(); // Produces: {"taxInfo":"redacted"} String json = serializer.serialize(new Address());

      See Also:
      Parameters:
      on - The bean that the filter applies to.
      value - The new value for this setting.
      Returns:
      This object.

    • beanMapPutReturnsOldValue

      public BeanContextable.Builder beanMapPutReturnsOldValue()
      BeanMap.put() returns old property value.

      When enabled, then the BeanMap.put() method will return old property values. Otherwise, it returns null.

      Disabled by default because it introduces a slight performance penalty during serialization.

      Example:

      // Create a context that creates BeanMaps with normal put() behavior. BeanContext context = BeanContext .create() .beanMapPutReturnsOldValue() .build(); BeanMap<MyBean> beanMap = context.createSession().toBeanMap(new MyBean()); beanMap.put("foo", "bar"); Object oldValue = beanMap.put("foo", "baz"); // oldValue == "bar"

      See Also:
      Returns:
      This object.

    • beanMethodVisibility

      public BeanContextable.Builder beanMethodVisibility(Visibility value)
      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.

      Example:

      // A bean with a protected getter. public class MyBean { public String getFoo() { return "foo"; } protected String getBar() { return "bar"; } } // Create a serializer that looks for protected getters and setters. WriterSerializer serializer = JsonSerializer .create() .beanMethodVisibility(PROTECTED) .build(); // Produces: {"foo":"foo","bar":"bar"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Beanp annotation can also be used to expose a non-public method.
      • The @BeanIgnore annotation can also be used on a public bean getter/setter to ignore it as a bean property.
      See Also:
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC
      Returns:
      This object.

    • beansRequireDefaultConstructor

      public BeanContextable.Builder beansRequireDefaultConstructor()
      Beans require no-arg constructors.

      When enabled, 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.

      Example:

      // A bean without a no-arg constructor. public class MyBean { // A property method. public String foo = "bar"; // A no-arg constructor public MyBean(String foo) { this.foo = foo; } @Override public String toString() { return "bar"; } } // Create a serializer that ignores beans without default constructors. WriterSerializer serializer = JsonSerializer .create() .beansRequireDefaultConstructor() .build(); // Produces: "bar" String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean annotation can be used on a bean class to override this setting.
      • The @BeanIgnore annotation can also be used on a class to ignore it as a bean.
      See Also:
      Returns:
      This object.

    • beansRequireSerializable

      public BeanContextable.Builder beansRequireSerializable()
      Beans require Serializable interface.

      When enabled, 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.

      Example:

      // A bean without a Serializable interface. public class MyBean { // A property method. public String foo = "bar"; @Override public String toString() { return "bar"; } } // Create a serializer that ignores beans not implementing Serializable. WriterSerializer serializer = JsonSerializer .create() .beansRequireSerializable() .build(); // Produces: "bar" String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean annotation can be used on a bean class to override this setting.
      • The @BeanIgnore annotation can also be used on a class to ignore it as a bean.
      See Also:
      Returns:
      This object.

    • beansRequireSettersForGetters

      public BeanContextable.Builder beansRequireSettersForGetters()
      Beans require setters for getters.

      When enabled, ignore read-only properties (properties with getters but not setters).

      Example:

      // A bean without a Serializable interface. public class MyBean { // A read/write property. public String getFoo() { return "foo"; } public void setFoo(String foo) { ... } // A read-only property. public String getBar() { return "bar"; } } // Create a serializer that ignores bean properties without setters. WriterSerializer serializer = JsonSerializer .create() .beansRequireSettersForGetters() .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Beanp annotation can be used on the getter to override this setting.
      • The @BeanIgnore annotation can also be used on getters to ignore them as bean properties.
      See Also:
      Returns:
      This object.

    • disableBeansRequireSomeProperties

      public BeanContextable.Builder disableBeansRequireSomeProperties()
      Beans don't require at least one property.

      When enabled, 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.

      The @Bean annotation can be used on a class to override this setting when true.

      Example:

      // A bean with no properties. public class MyBean { } // Create a serializer that serializes beans even if they have zero properties. WriterSerializer serializer = JsonSerializer .create() .disableBeansRequireSomeProperties() .build(); // Produces: {} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean annotation can be used on the class to force it to be recognized as a bean class even if it has no properties.
      See Also:
      Returns:
      This object.

    • beanProperties

      public BeanContextable.Builder beanProperties(Class<?> beanClass, String properties)
      Bean property includes.

      Specifies the set and order of names of properties associated with the bean class.

      For example, beanProperties(MyBean.class, "foo,bar") means only serialize the foo and bar properties on the specified bean. Likewise, parsing will ignore any bean properties not specified and either throw an exception or silently ignore them depending on whether ignoreUnknownBeanProperties() has been called.

      This value is entirely optional if you simply want to expose all the getters and public fields on a class as bean properties. However, it's useful if you want certain getters to be ignored or you want the properties to be serialized in a particular order. Note that on IBM JREs, the property order is the same as the order in the source code, whereas on Oracle JREs, the order is entirely random.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that includes only the 'foo' and 'bar' properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanProperties(MyBean.class, "foo,bar") .build(); // Produces: {"foo":"foo","bar":"bar"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClass).properties(properties).build());

      See Also:
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanProperties

      public BeanContextable.Builder beanProperties(Map<String,Object> values)
      Bean property includes.

      Specifies the set and order of names of properties associated with bean classes.

      For example, beanProperties(AMap.of("MyBean", "foo,bar")) means only serialize the foo and bar properties on the specified bean. Likewise, parsing will ignore any bean properties not specified and either throw an exception or silently ignore them depending on whether ignoreUnknownBeanProperties() has been called.

      This value is entirely optional if you simply want to expose all the getters and public fields on a class as bean properties. However, it's useful if you want certain getters to be ignored or you want the properties to be serialized in a particular order. Note that on IBM JREs, the property order is the same as the order in the source code, whereas on Oracle JREs, the order is entirely random.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that includes only the 'foo' and 'bar' properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanProperties(AMap.of("MyBean", "foo,bar")) .build(); // Produces: {"foo":"foo","bar":"bar"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code for each entry:

      builder.annotations(BeanAnnotation.create(key).properties(value.toString()).build());

      See Also:
      Parameters:
      values - The values to add to this builder.
      Keys are bean class names which can be a simple name, fully-qualified name, or "*" for all beans.
      Values are comma-delimited lists of property names. Non-String objects are first converted to Strings.
      Returns:
      This object.

    • beanProperties

      public BeanContextable.Builder beanProperties(String beanClassName, String properties)
      Bean property includes.

      Specifies the set and order of names of properties associated with the bean class.

      For example, beanProperties("MyBean", "foo,bar") means only serialize the foo and bar properties on the specified bean. Likewise, parsing will ignore any bean properties not specified and either throw an exception or silently ignore them depending on whether ignoreUnknownBeanProperties() has been called.

      This value is entirely optional if you simply want to expose all the getters and public fields on a class as bean properties. However, it's useful if you want certain getters to be ignored or you want the properties to be serialized in a particular order. Note that on IBM JREs, the property order is the same as the order in the source code, whereas on Oracle JREs, the order is entirely random.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that includes only the 'foo' and 'bar' properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanProperties("MyBean", "foo,bar") .build(); // Produces: {"foo":"foo","bar":"bar"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClassName).properties(properties).build());

      See Also:
      Parameters:
      beanClassName - The bean class name.
      Can be a simple name, fully-qualified name, or "*" for all beans.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanPropertiesExcludes

      public BeanContextable.Builder beanPropertiesExcludes(Class<?> beanClass, String properties)
      Bean property excludes.

      Specifies to exclude the specified list of properties for the specified bean class.

      Same as beanProperties(Class, String) except you specify a list of bean property names that you want to exclude from serialization.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that excludes the "bar" and "baz" properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesExcludes(MyBean.class, "bar,baz") .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClass).excludeProperties(properties).build());

      See Also:
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanPropertiesExcludes

      public BeanContextable.Builder beanPropertiesExcludes(Map<String,Object> values)
      Bean property excludes.

      Specifies to exclude the specified list of properties for the specified bean classes.

      Same as beanProperties(Map) except you specify a list of bean property names that you want to exclude from serialization.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that excludes the "bar" and "baz" properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesExcludes(AMap.of("MyBean", "bar,baz")) .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code for each entry:

      builder.annotations(BeanAnnotation.create(key).excludeProperties(value.toString()).build());

      See Also:
      Parameters:
      values - The values to add to this builder.
      Keys are bean class names which can be a simple name, fully-qualified name, or "*" for all beans.
      Values are comma-delimited lists of property names. Non-String objects are first converted to Strings.
      Returns:
      This object.

    • beanPropertiesExcludes

      public BeanContextable.Builder beanPropertiesExcludes(String beanClassName, String properties)
      Bean property excludes.

      Specifies to exclude the specified list of properties for the specified bean class.

      Same as beanPropertiesExcludes(String, String) except you specify a list of bean property names that you want to exclude from serialization.

      Setting applies to specified class and all subclasses.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo = "foo", bar = "bar", baz = "baz"; } // Create a serializer that excludes the "bar" and "baz" properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesExcludes("MyBean", "bar,baz") .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClassName).excludeProperties(properties).build());

      See Also:
      Parameters:
      beanClassName - The bean class name.
      Can be a simple name, fully-qualified name, or "*" for all bean classes.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanPropertiesReadOnly

      public BeanContextable.Builder beanPropertiesReadOnly(Class<?> beanClass, String properties)
      Read-only bean properties.

      Specifies one or more properties on a bean that are read-only despite having valid getters. Serializers will serialize such properties as usual, but parsers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with read-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesReadOnly(MyBean.class, "bar,baz") .build(); // All 3 properties will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with read-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesReadOnly(MyBean.class, "bar,baz") .ignoreUnknownBeanProperties() .build(); // Parser ignores bar and baz properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClass).readOnlyProperties(properties).build());

      See Also:
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanPropertiesReadOnly

      public BeanContextable.Builder beanPropertiesReadOnly(Map<String,Object> values)
      Read-only bean properties.

      Specifies one or more properties on beans that are read-only despite having valid getters. Serializers will serialize such properties as usual, but parsers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with read-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesReadOnly(AMap.of("MyBean", "bar,baz")) .build(); // All 3 properties will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with read-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesReadOnly(AMap.of("MyBean", "bar,baz")) .ignoreUnknownBeanProperties() .build(); // Parser ignores bar and baz properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code for each entry:

      builder.annotations(BeanAnnotation.create(key).readOnlyProperties(value.toString()).build());

      See Also:
      Parameters:
      values - The values to add to this builder.
      Keys are bean class names which can be a simple name, fully-qualified name, or "*" for all beans.
      Values are comma-delimited lists of property names. Non-String objects are first converted to Strings.
      Returns:
      This object.

    • beanPropertiesReadOnly

      public BeanContextable.Builder beanPropertiesReadOnly(String beanClassName, String properties)
      Read-only bean properties.

      Specifies one or more properties on a bean that are read-only despite having valid getters. Serializers will serialize such properties as usual, but parsers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with read-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesReadOnly("MyBean", "bar,baz") .build(); // All 3 properties will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with read-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesReadOnly("MyBean", "bar,baz") .ignoreUnknownBeanProperties() .build(); // Parser ignores bar and baz properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClassName).readOnlyProperties(properties).build());

      See Also:
      Parameters:
      beanClassName - The bean class name.
      Can be a simple name, fully-qualified name, or "*" for all bean classes.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanPropertiesWriteOnly

      public BeanContextable.Builder beanPropertiesWriteOnly(Class<?> beanClass, String properties)
      Write-only bean properties.

      Specifies one or more properties on a bean that are write-only despite having valid setters. Parsers will parse such properties as usual, but serializers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with write-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesWriteOnly(MyBean.class, "bar,baz") .build(); // Only foo will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with write-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesWriteOnly(MyBean.class, "bar,baz") .build(); // Parser parses all 3 properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClass).writeOnlyProperties(properties).build());

      See Also:
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanPropertiesWriteOnly

      public BeanContextable.Builder beanPropertiesWriteOnly(Map<String,Object> values)
      Write-only bean properties.

      Specifies one or more properties on a bean that are write-only despite having valid setters. Parsers will parse such properties as usual, but serializers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with write-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesWriteOnly(AMap.of("MyBean", "bar,baz")) .build(); // Only foo will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with write-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesWriteOnly(AMap.of("MyBean", "bar,baz")) .build(); // Parser parses all 3 properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code for each entry:

      builder.annotations(BeanAnnotation.create(key).writeOnlyProperties(value.toString()).build());

      See Also:
      Parameters:
      values - The values to add to this builder.
      Keys are bean class names which can be a simple name, fully-qualified name, or "*" for all beans.
      Values are comma-delimited lists of property names. Non-String objects are first converted to Strings.
      Returns:
      This object.

    • beanPropertiesWriteOnly

      public BeanContextable.Builder beanPropertiesWriteOnly(String beanClassName, String properties)
      Write-only bean properties.

      Specifies one or more properties on a bean that are write-only despite having valid setters. Parsers will parse such properties as usual, but serializers will silently ignore them. Note that this is different from the beanProperties/beanPropertiesExcludes settings which include or exclude properties for both serializers and parsers.

      Example:

      // A bean with 3 properties. public class MyBean { public String foo, bar, baz; } // Create a serializer with write-only property settings. WriterSerializer serializer = JsonSerializer .create() .beanPropertiesWriteOnly("MyBean", "bar,baz") .build(); // Only foo will be serialized. String json = serializer.serialize(new MyBean()); // Create a parser with write-only property settings. ReaderParser parser = JsonParser .create() .beanPropertiesWriteOnly("MyBean", "bar,baz") .build(); // Parser parses all 3 properties. MyBean bean = parser.parse("{foo:'foo',bar:'bar',baz:'baz'}", MyBean.class);

      This method is functionally equivalent to the following code:

      builder.annotations(BeanAnnotation.create(beanClassName).writeOnlyProperties(properties).build());

      See Also:
      Parameters:
      beanClassName - The bean class name.
      Can be a simple name, fully-qualified name, or "*" for all bean classes.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanDictionary

      public BeanContextable.Builder beanDictionary(Class<?>... values)
      Bean dictionary.

      The list of classes that make up the bean dictionary in this bean context.

      Values are prepended to the list so that later calls can override classes of earlier calls.

      A dictionary is a name/class mapping used to find class types during parsing when they cannot be inferred through reflection. The names are defined through the @Bean(typeName) annotation defined on the bean class. For example, if a class Foo has a type-name of "myfoo", then it would end up serialized as "{_type:'myfoo',...}" in JSON or "<myfoo>...</myfoo>" in XML.

      This setting tells the parsers which classes to look for when resolving "_type" attributes.

      Values can consist of any of the following types:

      • Any bean class that specifies a value for @Bean(typeName).
      • Any subclass of BeanDictionaryList containing a collection of bean classes with type name annotations.
      • Any subclass of BeanDictionaryMap containing a mapping of type names to classes without type name annotations.
      • Any array or collection of the objects above.
      Example:

      // POJOs with @Bean(name) annotations. @Bean(typeName="foo") public class Foo {...} @Bean(typeName="bar") public class Bar {...} // Create a parser and tell it which classes to try to resolve. ReaderParser parser = JsonParser .create() .dictionary(Foo.class, Bar.class) .addBeanTypes() .build(); // A bean with a field with an indeterminate type. public class MyBean { public Object mySimpleField; } // Parse bean. MyBean bean = parser.parse("{mySimpleField:{_type:'foo',...}}", MyBean.class);

      Another option is to use the Bean.dictionary() annotation on the POJO class itself:

      // Instead of by parser, define a bean dictionary on a class through an annotation. // This applies to all properties on this class and all subclasses. @Bean(dictionary={Foo.class,Bar.class}) public class MyBean { public Object mySimpleField; // May contain Foo or Bar object. public Map<String,Object> myMapField; // May contain Foo or Bar objects. }

      A typical usage is to allow for HTML documents to be parsed back into HTML beans:

      // Use the predefined HTML5 bean dictionary which is a BeanDictionaryList. ReaderParser parser = HtmlParser .create() .dictionary(HtmlBeanDictionary.class) .build(); // Parse an HTML body into HTML beans. Body body = parser.parse("<body><ul><li>foo</li><li>bar</li></ul>", Body.class);

      See Also:
      Parameters:
      values - The values to add to this setting.
      Returns:
      This object.

    • dictionaryOn

      public BeanContextable.Builder dictionaryOn(Class<?> on, Class<?>... values)
      Bean dictionary.

      This is identical to beanDictionary(Class...), but specifies a dictionary within the context of a single class as opposed to globally.

      Example:

      // POJOs with @Bean(name) annotations. @Bean(typeName="foo") public class Foo {...} @Bean(typeName="bar") public class Bar {...} // A bean with a field with an indeterminate type. public class MyBean { public Object mySimpleField; } // Create a parser and tell it which classes to try to resolve. ReaderParser parser = JsonParser .create() .dictionaryOn(MyBean.class, Foo.class, Bar.class) .build(); // Parse bean. MyBean bean = parser.parse("{mySimpleField:{_type:'foo',...}}", MyBean.class);

      This is functionally equivalent to the Bean.dictionary() annotation.

      See Also:
      Parameters:
      on - The class that the dictionary values apply to.
      values - The new values for this setting.
      Returns:
      This object.

    • example

      public <T> BeanContextable.Builder example(Class<T> pojoClass, T o)
      POJO example.

      Specifies an example of the specified class.

      Examples are used in cases such as POJO examples in Swagger documents.

      Example:

      // Create a serializer that excludes the 'foo' and 'bar' properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .example(MyBean.class, new MyBean().setFoo("foo").setBar(123)) .build();

      This is a shorthand method for the following code:

      builder.annotations(MarshalledAnnotation.create(pojoClass).example(Json5.DEFAULT.toString(object)).build())

      Notes:
      • Using this method assumes the serialized form of the object is the same as that produced by the default serializer. This may not be true based on settings or swaps on the constructed serializer.

      POJO examples can also be defined on classes via the following:

      Type Parameters:
      T - The POJO class.
      Parameters:
      pojoClass - The POJO class.
      o - An instance of the POJO class used for examples.
      Returns:
      This object.

    • example

      public <T> BeanContextable.Builder example(Class<T> pojoClass, String json)
      POJO example.

      Specifies an example in JSON of the specified class.

      Examples are used in cases such as POJO examples in Swagger documents.

      Setting applies to specified class and all subclasses.

      Example:

      // Create a serializer that excludes the 'foo' and 'bar' properties on the MyBean class. WriterSerializer serializer = JsonSerializer .create() .example(MyBean.class, "{foo:'bar'}") .build();

      This is a shorthand method for the following code:

      builder.annotations(MarshalledAnnotation.create(pojoClass).example(json).build())

      POJO examples can also be defined on classes via the following:

      • A static field annotated with @Example.
      • A static method annotated with @Example with zero arguments or one BeanSession argument.
      • A static method with name example with no arguments or one BeanSession argument.
      See Also:
      Type Parameters:
      T - The POJO class type.
      Parameters:
      pojoClass - The POJO class.
      json - The JSON 5 representation of the example.
      Returns:
      This object.

    • findFluentSetters

      public BeanContextable.Builder findFluentSetters()
      Find fluent setters.

      When enabled, fluent setters are detected on beans during parsing.

      Fluent setters must have the following attributes:

      • Public.
      • Not static.
      • Take in one parameter.
      • Return the bean itself.
      Example:

      // A bean with a fluent setter. public class MyBean { public MyBean foo(String value) {...} } // Create a parser that finds fluent setters. ReaderParser parser = JsonParser .create() .findFluentSetters() .build(); // Parse into bean using fluent setter. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      Notes:
      • The @Beanp annotation can also be used on methods to individually identify them as fluent setters.
      • The @Bean.fluentSetters() annotation can also be used on classes to specify to look for fluent setters.
      See Also:
      Returns:
      This object.

    • findFluentSetters

      public BeanContextable.Builder findFluentSetters(Class<?> on)
      Find fluent setters.

      Identical to findFluentSetters() but enables it on a specific class only.

      Example:

      // A bean with a fluent setter. public class MyBean { public MyBean foo(String value) {...} } // Create a parser that finds fluent setters. ReaderParser parser = JsonParser .create() .findFluentSetters(MyBean.class) .build(); // Parse into bean using fluent setter. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      Notes:
      See Also:
      Parameters:
      on - The class that this applies to.
      Returns:
      This object.

    • ignoreInvocationExceptionsOnGetters

      public BeanContextable.Builder ignoreInvocationExceptionsOnGetters()
      Ignore invocation errors on getters.

      When enabled, errors thrown when calling bean getter methods will silently be ignored. Otherwise, a BeanRuntimeException is thrown.

      Example:

      // A bean with a property that throws an exception. public class MyBean { public String getFoo() { throw new RuntimeException("foo"); } } // Create a serializer that ignores bean getter exceptions. WriterSerializer serializer = JsonSerializer .create() .ingoreInvocationExceptionsOnGetters() .build(); // Exception is ignored. String json = serializer.serialize(new MyBean());

      See Also:
      Returns:
      This object.

    • ignoreInvocationExceptionsOnSetters

      public BeanContextable.Builder ignoreInvocationExceptionsOnSetters()
      Ignore invocation errors on setters.

      When enabled, errors thrown when calling bean setter methods will silently be ignored. Otherwise, a BeanRuntimeException is thrown.

      Example:

      // A bean with a property that throws an exception. public class MyBean { public void setFoo(String foo) { throw new RuntimeException("foo"); } } // Create a parser that ignores bean setter exceptions. ReaderParser parser = JsonParser .create() .ignoreInvocationExceptionsOnSetters() .build(); // Exception is ignored. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      See Also:
      Returns:
      This object.

    • disableIgnoreMissingSetters

      public BeanContextable.Builder disableIgnoreMissingSetters()
      Don't silently ignore missing setters.

      When enabled, trying to set a value on a bean property without a setter will throw a BeanRuntimeException. Otherwise, it will be silently ignored.

      Example:

      // A bean with a property with a getter but not a setter. public class MyBean { public void getFoo() { return "foo"; } } // Create a parser that throws an exception if a setter is not found but a getter is. ReaderParser parser = JsonParser .create() .disableIgnoreMissingSetters() .build(); // Throws a ParseException. MyBean bean = parser.parse("{foo:'bar'}", MyBean.class);

      Notes:
      • The @BeanIgnore annotation can also be used on getters and fields to ignore them.
      See Also:
      Returns:
      This object.

    • disableIgnoreTransientFields

      public BeanContextable.Builder disableIgnoreTransientFields()
      Don't ignore transient fields.

      When enabled, methods and fields marked as transient will not be ignored as bean properties.

      Example:

      // A bean with a transient field. public class MyBean { public transient String foo = "foo"; } // Create a serializer that doesn't ignore transient fields. WriterSerializer serializer = JsonSerializer .create() .disableIgnoreTransientFields() .build(); // Produces: {"foo":"foo"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Beanp annotation can also be used on transient fields to keep them from being ignored.
      See Also:
      Returns:
      This object.

    • ignoreUnknownBeanProperties

      public BeanContextable.Builder ignoreUnknownBeanProperties()
      Ignore unknown properties.

      When enabled, trying to set a value on a non-existent bean property will silently be ignored. Otherwise, a BeanRuntimeException is thrown.

      Example:

      // A bean with a single property. public class MyBean { public String foo; } // Create a parser that ignores missing bean properties. ReaderParser parser = JsonParser .create() .ignoreUnknownBeanProperties() .build(); // Doesn't throw an exception on unknown 'bar' property. MyBean bean = parser.parse("{foo:'foo',bar:'bar'}", MyBean.class);

      See Also:
      Returns:
      This object.

    • ignoreUnknownEnumValues

      public BeanContextable.Builder ignoreUnknownEnumValues()
      Ignore unknown enum values.

      When enabled, unknown enum values are set to null instead of throwing a parse exception.

      See Also:
      Returns:
      This object.

    • disableIgnoreUnknownNullBeanProperties

      public BeanContextable.Builder disableIgnoreUnknownNullBeanProperties()
      Don't ignore unknown properties with null values.

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

      Example:

      // A bean with a single property. public class MyBean { public String foo; } // Create a parser that throws an exception on an unknown property even if the value being set is null. ReaderParser parser = JsonParser .create() .disableIgnoreUnknownNullBeanProperties() .build(); // Throws a BeanRuntimeException wrapped in a ParseException on the unknown 'bar' property. MyBean bean = parser.parse("{foo:'foo',bar:null}", MyBean.class);

      See Also:
      Returns:
      This object.

    • implClass

      public BeanContextable.Builder implClass(Class<?> interfaceClass, Class<?> implClass)
      Implementation classes.

      For interfaces and abstract classes this method can be used to specify an implementation class for the interface/abstract class so that instances of the implementation class are used when instantiated (e.g. during a parse).

      Example:

      // A bean interface. public interface MyBean { ... } // A bean implementation. public class MyBeanImpl implements MyBean { ... } // Create a parser that instantiates MyBeanImpls when parsing MyBeans. ReaderParser parser = JsonParser .create() .implClass(MyBean.class, MyBeanImpl.class) .build(); // Instantiates a MyBeanImpl, MyBean bean = parser.parse("...", MyBean.class);

      Parameters:
      interfaceClass - The interface class.
      implClass - The implementation class.
      Returns:
      This object.

    • implClasses

      public BeanContextable.Builder implClasses(Map<Class<?>,Class<?>> values)
      Implementation classes.

      For interfaces and abstract classes this method can be used to specify an implementation class for the interface/abstract class so that instances of the implementation class are used when instantiated (e.g. during a parse).

      Example:

      // A bean with a single property. public interface MyBean { ... } // A bean with a single property. public class MyBeanImpl implements MyBean { ... } // Create a parser that instantiates MyBeanImpls when parsing MyBeans. ReaderParser parser = JsonParser .create() .implClasses(AMap.of(MyBean.class, MyBeanImpl.class)) .build(); // Instantiates a MyBeanImpl, MyBean bean = parser.parse("...", MyBean.class);

      Parameters:
      values - The new value for this setting.
      Returns:
      This object.

    • interfaceClass

      public BeanContextable.Builder interfaceClass(Class<?> on, Class<?> value)
      Identifies a class to be used as the interface class for the specified class and all subclasses.

      When specified, only the list of properties defined on the interface class will be used during serialization. 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"; } // Create a serializer and define our interface class mapping. WriterSerializer serializer = JsonSerializer .create() .interfaceClass(A1.class, A.class) .build(); // Produces "{"foo":"foo"}" String json = serializer.serialize(new A1());

      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:
      Parameters:
      on - The class that the interface class applies to.
      value - The new value for this setting.
      Returns:
      This object.

    • interfaces

      public BeanContextable.Builder interfaces(Class<?>... value)
      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"; } // Create a serializer and define our interface class mapping. WriterSerializer serializer = JsonSerializer .create() .interfaces(A.class) .build(); // Produces "{"foo":"foo"}" String json = serializer.serialize(new A1());

      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:
      Parameters:
      value - The new value for this setting.
      Returns:
      This object.

    • locale

      public BeanContextable.Builder locale(Locale value)
      Context configuration property:  Locale.

      Specifies the default locale for serializer and parser sessions when not specified via BeanSession.Builder.locale(Locale). Typically used for POJO swaps that need to deal with locales such as swaps that convert Date and Calendar objects to strings by accessing it via the session passed into the ObjectSwap.swap(BeanSession, Object) and ObjectSwap.unswap(BeanSession, Object, ClassMeta, String) methods.

      Example:

      // Define a POJO swap that skips serializing beans if we're in the UK. public class MyBeanSwap extends StringSwap<MyBean> { @Override public String swap(BeanSession session, MyBean bean) throws Exception { if (session.getLocale().equals(Locale.UK)) return null; return bean.toString(); } } // Create a serializer that uses the specified locale if it's not passed in through session args. WriterSerializer serializer = JsonSerializer .create() .locale(Locale.UK) .swaps(MyBeanSwap.class) .build();

      See Also:
      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • mediaType

      public BeanContextable.Builder mediaType(MediaType value)
      Context configuration property:  Media type.

      Specifies the default media type for serializer and parser sessions when not specified via BeanSession.Builder.mediaType(MediaType). Typically used for POJO swaps that need to serialize the same POJO classes differently depending on the specific requested media type. For example, a swap could handle a request for media types "application/json" and "application/json+foo" slightly differently even though they're both being handled by the same JSON serializer or parser.

      Example:

      // Define a POJO swap that skips serializing beans if the media type is application/json. public class MyBeanSwap extends StringSwap<MyBean> { @Override public String swap(BeanSession session, MyBean bean) throws Exception { if (session.getMediaType().equals("application/json")) return null; return bean.toString(); } } // Create a serializer that uses the specified media type if it's not passed in through session args. WriterSerializer serializer = JsonSerializer .create() .mediaType(MediaType.JSON) .build();

      See Also:
      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • notBeanClasses

      public BeanContextable.Builder notBeanClasses(Class<?>... values)
      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.

      Values can consist of any of the following types:

      • Classes.
      • Arrays and collections of classes.
      Example:

      // A bean with a single property. public class MyBean { public String foo = "bar"; public String toString() { return "baz"; } } // Create a serializer that doesn't treat MyBean as a bean class. WriterSerializer serializer = JsonSerializer .create() .notBeanClasses(MyBean.class) .build(); // Produces "baz" instead of {"foo":"bar"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @BeanIgnore annotation can also be used on classes to prevent them from being recognized as beans.
      See Also:
      Parameters:
      values - The values to add to this setting.
      Values can consist of any of the following types:
      • Classes.
      • Arrays and collections of classes.
      Returns:
      This object.

    • notBeanPackages

      public BeanContextable.Builder notBeanPackages(String... values)
      Bean package exclusions.

      Used as a convenient way of defining the BeanContext.Builder.notBeanClasses(Class...) property for entire packages. Any classes within these packages will be serialized to strings using Object.toString().

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

      Values can consist of any of the following types:

      • Strings.
      • Arrays and collections of strings.
      Example:

      // Create a serializer that ignores beans in the specified packages. WriterSerializer serializer = JsonSerializer .create() .notBeanPackages("org.apache.foo", "org.apache.bar.*") .build();

      See Also:
      Parameters:
      values - The values to add to this setting.
      Values can consist of any of the following types:
      • Package objects.
      • Strings.
      • Arrays and collections of anything in this list.
      Returns:
      This object.

    • propertyNamer

      public BeanContextable.Builder propertyNamer(Class<? extends PropertyNamer> value)
      Bean property namer

      The class to use for calculating bean property names.

      Predefined classes:

      Example:

      // A bean with a single property. public class MyBean { public String fooBarBaz = "fooBarBaz"; } // Create a serializer that uses Dashed-Lower-Case property names. // (e.g. "foo-bar-baz" instead of "fooBarBaz") WriterSerializer serializer = JsonSerializer .create() .propertyNamer(PropertyNamerDLC.class) .build(); // Produces: {"foo-bar-baz":"fooBarBaz"} String json = serializer.serialize(new MyBean());

      See Also:
      Parameters:
      value - The new value for this setting.
      The default is BasicPropertyNamer.
      Returns:
      This object.

    • propertyNamer

      public BeanContextable.Builder propertyNamer(Class<?> on, Class<? extends PropertyNamer> value)
      Bean property namer

      Same as propertyNamer(Class) but allows you to specify a namer for a specific class.

      Example:

      // A bean with a single property. public class MyBean { public String fooBarBaz = "fooBarBaz"; } // Create a serializer that uses Dashed-Lower-Case property names for the MyBean class only. // (e.g. "foo-bar-baz" instead of "fooBarBaz") WriterSerializer serializer = JsonSerializer .create() .propertyNamer(MyBean.class, PropertyNamerDLC.class) .build(); // Produces: {"foo-bar-baz":"fooBarBaz"} String json = serializer.serialize(new MyBean());

      See Also:
      Parameters:
      on - The class that the namer applies to.
      value - The new value for this setting.
      The default is BasicPropertyNamer.
      Returns:
      This object.

    • sortProperties

      public BeanContextable.Builder sortProperties()
      Sort bean properties.

      When enabled, all bean properties will be serialized and access in alphabetical order. Otherwise, the natural order of the bean properties is used which is dependent on the JVM vendor. On IBM JVMs, the bean properties are ordered based on their ordering in the Java file. On Oracle JVMs, the bean properties are not ordered (which follows the official JVM specs).

      this setting is disabled by default so that IBM JVM users don't have to use @Bean annotations to force bean properties to be in a particular order and can just alter the order of the fields/methods in the Java file.

      Example:

      // A bean with 3 properties. public class MyBean { public String c = "1"; public String b = "2"; public String a = "3"; } // Create a serializer that sorts bean properties. WriterSerializer serializer = JsonSerializer .create() .sortProperties() .build(); // Produces: {"a":"3","b":"2","c":"1"} String json = serializer.serialize(new MyBean());

      Notes:
      • The @Bean.sort() annotation can also be used to sort properties on just a single class.
      See Also:
      Returns:
      This object.

    • sortProperties

      public BeanContextable.Builder sortProperties(Class<?>... on)
      Sort bean properties.

      Same as sortProperties() but allows you to specify individual bean classes instead of globally.

      Example:

      // A bean with 3 properties. public class MyBean { public String c = "1"; public String b = "2"; public String a = "3"; } // Create a serializer that sorts properties on MyBean. WriterSerializer serializer = JsonSerializer .create() .sortProperties(MyBean.class) .build(); // Produces: {"a":"3","b":"2","c":"1"} String json = serializer.serialize(new MyBean());

      See Also:
      Parameters:
      on - The bean classes to sort properties on.
      Returns:
      This object.

    • stopClass

      public BeanContextable.Builder stopClass(Class<?> on, Class<?> value)
      Identifies a stop class for the annotated class.

      Identical in purpose to the stop class specified by Introspector.getBeanInfo(Class, Class). Any properties in the stop class or in its base classes will be ignored during analysis.

      For example, in the following class hierarchy, instances of C3 will include property p3, but not p1 or p2.

      Example:

      public class C1 { public int getP1(); } public class C2 extends C1 { public int getP2(); } public class C3 extends C2 { public int getP3(); } // Create a serializer specifies a stop class for C3. WriterSerializer serializer = JsonSerializer .create() .stopClass(C3.class, C2.class) .build(); // Produces: {"p3":"..."} String json = serializer.serialize(new C3());

      Parameters:
      on - The class on which the stop class is being applied.
      value - The new value for this setting.
      Returns:
      This object.

    • swaps

      public BeanContextable.Builder swaps(Class<?>... values)
      Java object swaps.

      Swaps are used to "swap out" non-serializable classes with serializable equivalents during serialization, and "swap in" the non-serializable class during parsing.

      An example of a swap would be a Calendar object that gets swapped out for an ISO8601 string.

      Multiple swaps can be associated with a single class. When multiple swaps are applicable to the same class, the media type pattern defined by ObjectSwap.forMediaTypes() or @Swap(mediaTypes) are used to come up with the best match.

      Values can consist of any of the following types:

      • Any subclass of ObjectSwap.
      • Any instance of ObjectSwap.
      • Any surrogate class. A shortcut for defining a SurrogateSwap.
      • Any array or collection of the objects above.
      Example:

      // Sample swap for converting Dates to ISO8601 strings. public class MyDateSwap extends StringSwap<Date> { // ISO8601 formatter. private DateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ"); @Override public String swap(BeanSession session, Date date) { return format.format(date); } @Override public Date unswap(BeanSession session, String string, ClassMeta hint) throws Exception { return format.parse(string); } } // Sample bean with a Date field. public class MyBean { public Date date = new Date(112, 2, 3, 4, 5, 6); } // Create a serializer that uses our date swap. WriterSerializer serializer = JsonSerializer .create() .swaps(MyDateSwap.class) .build(); // Produces: {"date":"2012-03-03T04:05:06-0500"} String json = serializer.serialize(new MyBean()); // Create a serializer that uses our date swap. ReaderParser parser = JsonParser .create() .swaps(MyDateSwap.class) .build(); // Use our parser to parse a bean. MyBean bean = parser.parse(json, MyBean.class);

      Notes:
      • The @Swap annotation can also be used on classes to identify swaps for the class.
      • The @Swap annotation can also be used on bean methods and fields to identify swaps for values of those bean properties.
      See Also:
      Parameters:
      values - The values to add to this setting.
      Values can consist of any of the following types:
      • Any subclass of ObjectSwap.
      • Any surrogate class. A shortcut for defining a SurrogateSwap.
      • Any array or collection of the objects above.
      Returns:
      This object.

    • swap

      public <T, S> BeanContextable.Builder swap(Class<T> normalClass, Class<S> swappedClass, ThrowingFunction<T,S> swapFunction)
      A shortcut for defining a FunctionalSwap.
      Example:

      // Create a serializer that performs a custom format for Date objects. WriterSerializer serializer = JsonSerializer .create() .swap(Date.class, String.class, x -> format(x)) .build();

      Type Parameters:
      T - The object type being swapped out.
      S - The object type being swapped in.
      Parameters:
      normalClass - The object type being swapped out.
      swappedClass - The object type being swapped in.
      swapFunction - The function to convert the object.
      Returns:
      This object.

    • swap

      public <T, S> BeanContextable.Builder swap(Class<T> normalClass, Class<S> swappedClass, ThrowingFunction<T,S> swapFunction, ThrowingFunction<S,T> unswapFunction)
      A shortcut for defining a FunctionalSwap.
      Example:

      // Create a serializer that performs a custom format for Date objects. WriterSerializer serializer = JsonSerializer .create() .swap(Date.class, String.class, x -> format(x), x -> parse(x)) .build();

      Type Parameters:
      T - The object type being swapped out.
      S - The object type being swapped in.
      Parameters:
      normalClass - The object type being swapped out.
      swappedClass - The object type being swapped in.
      swapFunction - The function to convert the object during serialization.
      unswapFunction - The function to convert the object during parsing.
      Returns:
      This object.

    • timeZone

      public BeanContextable.Builder timeZone(TimeZone value)
      Context configuration property:  TimeZone.

      Specifies the default time zone for serializer and parser sessions when not specified via BeanSession.Builder.timeZone(TimeZone). Typically used for POJO swaps that need to deal with timezones such as swaps that convert Date and Calendar objects to strings by accessing it via the session passed into the ObjectSwap.swap(BeanSession, Object) and ObjectSwap.unswap(BeanSession, Object, ClassMeta, String) methods.

      Example:

      // Define a POJO swap that skips serializing beans if the time zone is GMT. public class MyBeanSwap extends StringSwap<MyBean> { @Override public String swap(BeanSession session, MyBean bean) throws Exception { if (session.getTimeZone().equals(TimeZone.GMT)) return null; return bean.toString(); } } // Create a serializer that uses GMT if the timezone is not specified in the session args. WriterSerializer serializer = JsonSerializer .create() .timeZone(TimeZone.GMT) .build();

      See Also:
      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • typeName

      public BeanContextable.Builder typeName(Class<?> on, String value)
      An identifying name for this class.

      The name is used to identify the class type during parsing when it cannot be inferred through reflection. For example, if a bean property is of type Object, then the serializer will add the name to the output so that the class can be determined during parsing.

      It is also used to specify element names in XML.

      Example:

      // Use _type='mybean' to identify this bean. public class MyBean {...} // Create a serializer and specify the type name.. WriterSerializer serializer = JsonSerializer .create() .typeName(MyBean.class, "mybean") .build(); // Produces: {"_type":"mybean",...} String json = serializer.serialize(new MyBean());

      Notes:
      See Also:
      Parameters:
      on - The class the type name is being defined on.
      value - The new value for this setting.
      Returns:
      This object.

    • typePropertyName

      public BeanContextable.Builder typePropertyName(String value)
      Bean type property name.

      This specifies 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.

      Example:

      // POJOs with @Bean(name) annotations. @Bean(typeName="foo") public class Foo {...} @Bean(typeName="bar") public class Bar {...} // Create a serializer that uses 't' instead of '_type' for dictionary names. WriterSerializer serializer = JsonSerializer .create() .typePropertyName("t") .dictionary(Foo.class, Bar.class) .build(); // Create a serializer that uses 't' instead of '_type' for dictionary names. ReaderParser parser = JsonParser .create() .typePropertyName("t") .dictionary(Foo.class, Bar.class) .build(); // A bean with a field with an indeterminate type. public class MyBean { public Object mySimpleField; } // Produces "{mySimpleField:{t:'foo',...}}". String json = serializer.serialize(new MyBean()); // Parse bean. MyBean bean = parser.parse(json, MyBean.class);

      See Also:
      Parameters:
      value - The new value for this setting.
      The default is "_type".
      Returns:
      This object.

    • typePropertyName

      public BeanContextable.Builder typePropertyName(Class<?> on, String value)
      Bean type property name.

      Same as typePropertyName(String) except targets a specific bean class instead of globally.

      Example:

      // POJOs with @Bean(name) annotations. @Bean(typeName="foo") public class Foo {...} @Bean(typeName="bar") public class Bar {...} // A bean with a field with an indeterminate type. public class MyBean { public Object mySimpleField; } // Create a serializer that uses 't' instead of '_type' for dictionary names. WriterSerializer serializer = JsonSerializer .create() .typePropertyName(MyBean.class, "t") .dictionary(Foo.class, Bar.class) .build(); // Produces "{mySimpleField:{t:'foo',...}}". String json = serializer.serialize(new MyBean());

      See Also:
      Parameters:
      on - The class the type property name applies to.
      value - The new value for this setting.
      The default is "_type".
      Returns:
      This object.

    • useEnumNames

      public BeanContextable.Builder useEnumNames()
      Use enum names.

      When enabled, enums are always serialized by name, not using Object.toString().

      Example:

      // Create a serializer with debug enabled. WriterSerializer serializer = JsonSerializer .create() .useEnumNames() .build(); // Enum with overridden toString(). // Will be serialized as ONE/TWO/THREE even though there's a toString() method. public enum Option { ONE(1), TWO(2), THREE(3); private int value; Option(int value) { this.value = value; } @Override public String toString() { return String.valueOf(value); } }

      See Also:
      Returns:
      This object.

    • disableInterfaceProxies

      public BeanContextable.Builder disableInterfaceProxies()
      Don't use interface proxies.

      When enabled, interfaces will be instantiated as proxy classes through the use of an InvocationHandler if there is no other way of instantiating them. Otherwise, throws a BeanRuntimeException.

      See Also:
      Returns:
      This object.

    • useJavaBeanIntrospector

      public BeanContextable.Builder useJavaBeanIntrospector()
      Use Java Introspector.

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

      Example:

      // Create a serializer that only uses the built-in java bean introspector for finding properties. WriterSerializer serializer = JsonSerializer .create() .useJavaBeanIntrospector() .build();

      See Also:
      Returns:
      This object.

    • annotations

      public BeanContextable.Builder annotations(Annotation... value)
      Description copied from class: Context.Builder
      Defines annotations to apply to specific classes and methods.

      Allows you to dynamically apply Juneau annotations typically applied directly to classes and methods. Useful in cases where you want to use the functionality of the annotation on beans and bean properties but do not have access to the code to do so.

      As a rule, any Juneau annotation with an on() method can be used with this setting.

      The following example shows the equivalent methods for applying the @Bean annotation:

      // Class with explicit annotation. @Bean(properties="street,city,state") public class A {...} // Class with annotation applied via @BeanConfig public class B {...} // Java REST method with @BeanConfig annotation. @RestGet(...) @Bean(on="B", properties="street,city,state") public void doFoo() {...}

      In general, the underlying framework uses this method when it finds dynamically applied annotations on config annotations. However, concrete implementations of annotations are also provided that can be passed directly into builder classes like so:

      // Create a concrete @Bean annotation. Bean annotation = BeanAnnotation.create(B.class).properties("street,city,state").build(); // Apply it to a serializer. WriterSerializer serializer = JsonSerializer.create().annotations(annotation).build(); // Serialize a bean with the dynamically applied annotation. String json = serializer.serialize(new B());

      The following is the list of annotations builders provided that can be constructed and passed into the builder class:

      The syntax for the on() pattern match parameter depends on whether it applies to a class, method, field, or constructor. The valid pattern matches are:

      • Classes:
        • Fully qualified:
          • "com.foo.MyClass"
        • Fully qualified inner class:
          • "com.foo.MyClass$Inner1$Inner2"
        • Simple:
          • "MyClass"
        • Simple inner:
          • "MyClass$Inner1$Inner2"
          • "Inner1$Inner2"
          • "Inner2"
      • Methods:
        • Fully qualified with args:
          • "com.foo.MyClass.myMethod(String,int)"
          • "com.foo.MyClass.myMethod(java.lang.String,int)"
          • "com.foo.MyClass.myMethod()"
        • Fully qualified:
          • "com.foo.MyClass.myMethod"
        • Simple with args:
          • "MyClass.myMethod(String,int)"
          • "MyClass.myMethod(java.lang.String,int)"
          • "MyClass.myMethod()"
        • Simple:
          • "MyClass.myMethod"
        • Simple inner class:
          • "MyClass$Inner1$Inner2.myMethod"
          • "Inner1$Inner2.myMethod"
          • "Inner2.myMethod"
      • Fields:
        • Fully qualified:
          • "com.foo.MyClass.myField"
        • Simple:
          • "MyClass.myField"
        • Simple inner class:
          • "MyClass$Inner1$Inner2.myField"
          • "Inner1$Inner2.myField"
          • "Inner2.myField"
      • Constructors:
        • Fully qualified with args:
          • "com.foo.MyClass(String,int)"
          • "com.foo.MyClass(java.lang.String,int)"
          • "com.foo.MyClass()"
        • Simple with args:
          • "MyClass(String,int)"
          • "MyClass(java.lang.String,int)"
          • "MyClass()"
        • Simple inner class:
          • "MyClass$Inner1$Inner2()"
          • "Inner1$Inner2()"
          • "Inner2()"
      • A comma-delimited list of anything on this list.
      See Also:
      Overrides:
      annotations in class Context.Builder
      Parameters:
      value - The annotations to register with the context.
      Returns:
      This object.

    • debug

      public BeanContextable.Builder debug()
      Description copied from class: Context.Builder
      Context configuration property:  Debug mode.

      Enables the following additional information during serialization:

      Enables the following additional information during parsing:

      • When bean setters throws exceptions, the exception includes the object stack information in order to determine how that method was invoked.
      Example:

      // Create a serializer with debug enabled. WriterSerializer serializer = JsonSerializer .create() .debug() .build(); // Create a POJO model with a recursive loop. public class MyBean { public Object f; } MyBean bean = new MyBean(); bean.f = bean; // Throws a SerializeException and not a StackOverflowError String json = serializer.serialize(bean);

      See Also:
      Overrides:
      debug in class Context.Builder
      Returns:
      This object.

    • apply

      public BeanContextable.Builder apply(AnnotationWorkList work)
      Description copied from class: Context.Builder
      Applies a set of applied to this builder.

      An AnnotationWork consists of a single pair of AnnotationInfo that represents an annotation instance, and AnnotationApplier which represents the code used to apply the values in that annotation to a specific builder.

      Example:

      // A class annotated with a config annotation. @BeanConfig(sortProperties="$S{sortProperties,false}") public class MyClass {...} // Find all annotations that themselves are annotated with @ContextPropertiesApply. AnnotationList annotations = ClassInfo.of(MyClass.class).getAnnotationList(CONTEXT_APPLY_FILTER); VarResolverSession vrs = VarResolver.DEFAULT.createSession(); AnnotationWorkList work = AnnotationWorkList.of(vrs, annotations); // Apply any settings found on the annotations. WriterSerializer serializer = JsonSerializer .create() .apply(work) .build();

      Overrides:
      apply in class Context.Builder
      Parameters:
      work - The list of annotations and appliers to apply to this builder.
      Returns:
      This object.

    • applyAnnotations

      public BeanContextable.Builder applyAnnotations(Class<?>... fromClasses)
      Description copied from class: Context.Builder
      Applies any of the various @XConfig annotations on the specified class to this context.

      Any annotations found that themselves are annotated with ContextApply will be resolved and applied as properties to this builder. These annotations include:

      Annotations on classes are appended in the following order:

      1. On the package of this class.
      2. On interfaces ordered parent-to-child.
      3. On parent classes ordered parent-to-child.
      4. On this class.

      The default var resolver VarResolver.DEFAULT is used to resolve any variables in annotation field values.

      Example:

      // A class annotated with a config annotation. @BeanConfig(sortProperties="$S{sortProperties,false}") public class MyClass {...} // Apply any settings found on the annotations. WriterSerializer serializer = JsonSerializer .create() .applyAnnotations(MyClass.class) .build();

      Overrides:
      applyAnnotations in class Context.Builder
      Parameters:
      fromClasses - The classes on which the annotations are defined.
      Returns:
      This object.

    • applyAnnotations

      public BeanContextable.Builder applyAnnotations(Method... fromMethods)
      Description copied from class: Context.Builder
      Applies any of the various @XConfig annotations on the specified method to this context.

      Any annotations found that themselves are annotated with ContextApply will be resolved and applied as properties to this builder. These annotations include:

      Annotations on methods are appended in the following order:

      1. On the package of the method class.
      2. On interfaces ordered parent-to-child.
      3. On parent classes ordered parent-to-child.
      4. On the method class.
      5. On this method and matching methods ordered parent-to-child.

      The default var resolver VarResolver.DEFAULT is used to resolve any variables in annotation field values.

      Example:

      // A method annotated with a config annotation. public class MyClass { @BeanConfig(sortProperties="$S{sortProperties,false}") public void myMethod() {...} } // Apply any settings found on the annotations. WriterSerializer serializer = JsonSerializer .create() .applyAnnotations(MyClass.class.getMethod("myMethod")) .build();

      Overrides:
      applyAnnotations in class Context.Builder
      Parameters:
      fromMethods - The methods on which the annotations are defined.
      Returns:
      This object.

    • cache

      public BeanContextable.Builder cache(Cache<HashKey,? extends Context> value)
      Description copied from class: Context.Builder
      Specifies a cache to use for hashkey-based caching.
      Overrides:
      cache in class Context.Builder
      Parameters:
      value - The cache.
      Returns:
      This object.

    • impl

      public BeanContextable.Builder impl(Context value)
      Description copied from class: Context.Builder
      Specifies a pre-instantiated bean for the Context.Builder.build() method to return.
      Overrides:
      impl in class Context.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • type

      public BeanContextable.Builder type(Class<? extends Context> value)
      Description copied from class: Context.Builder
      Associates a context class with this builder.

      This is the type of object that this builder creates when the Context.Builder.build() method is called.

      By default, it's the outer class of where the builder class is defined.

      Overrides:
      type in class Context.Builder
      Parameters:
      value - The context class that this builder should create.
      Returns:
      This object.