Package org.apache.juneau.serializer

Class OutputStreamSerializer.Builder

java.lang.Object
org.apache.juneau.Context.Builder
org.apache.juneau.BeanContextable.Builder
org.apache.juneau.BeanTraverseContext.Builder
org.apache.juneau.serializer.Serializer.Builder
org.apache.juneau.serializer.OutputStreamSerializer.Builder
Direct Known Subclasses:
MsgPackSerializer.Builder
Enclosing class:
OutputStreamSerializer
public static class OutputStreamSerializer.Builder extends Serializer.Builder
Builder class.

  • Constructor Details

  • Method Details

    • copy

      public OutputStreamSerializer.Builder copy()
      Description copied from class: Context.Builder
      Copy creator.
      Overrides:
      copy in class Serializer.Builder
      Returns:
      A new mutable copy of this builder.

    • build

      public OutputStreamSerializer build()
      Description copied from class: Context.Builder
      Build the object.
      Overrides:
      build in class Serializer.Builder
      Returns:
      The built object.

    • 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 Serializer.Builder
      Returns:
      The hashkey of this builder.

    • binaryFormat

      public OutputStreamSerializer.Builder binaryFormat(BinaryFormat value)
      Binary output format.

      When using the Serializer.serializeToString(Object) method on stream-based serializers, this defines the format to use when converting the resulting byte array to a string.

      Example:

      // Create a serializer that serializes to BASE64. OutputStreamSerializer serializer = MsgPackSerializer .create() .binaryFormat(BASE64) .build(); // The bean we want to serialize. public class MyBean {...} // MessagePack will generate BASE64-encoded string. String msgPack = serializer.serializeToString(new MyBean());

      Parameters:
      value - The new value for this property.
      The default is BinaryFormat.HEX.
      Returns:
      This object.

    • annotations

      public OutputStreamSerializer.Builder annotations(Annotation... values)
      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 Serializer.Builder
      Parameters:
      values - The annotations to register with the context.
      Returns:
      This object.

    • apply

      public OutputStreamSerializer.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 Serializer.Builder
      Parameters:
      work - The list of annotations and appliers to apply to this builder.
      Returns:
      This object.

    • applyAnnotations

      public OutputStreamSerializer.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 Serializer.Builder
      Parameters:
      fromClasses - The classes on which the annotations are defined.
      Returns:
      This object.

    • applyAnnotations

      public OutputStreamSerializer.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 Serializer.Builder
      Parameters:
      fromMethods - The methods on which the annotations are defined.
      Returns:
      This object.

    • cache

      public OutputStreamSerializer.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 Serializer.Builder
      Parameters:
      value - The cache.
      Returns:
      This object.

    • debug

      public OutputStreamSerializer.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 Serializer.Builder
      Returns:
      This object.

    • debug

      public OutputStreamSerializer.Builder debug(boolean value)
      Description copied from class: Context.Builder
      Same as Context.Builder.debug() but allows you to explicitly specify the value.
      Overrides:
      debug in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • impl

      public OutputStreamSerializer.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 Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • type

      public OutputStreamSerializer.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 Serializer.Builder
      Parameters:
      value - The context class that this builder should create.
      Returns:
      This object.

    • beanClassVisibility

      public OutputStreamSerializer.Builder beanClassVisibility(Visibility value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanClassVisibility in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC.
      Returns:
      This object.

    • beanConstructorVisibility

      public OutputStreamSerializer.Builder beanConstructorVisibility(Visibility value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanConstructorVisibility in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC.
      Returns:
      This object.

    • beanContext

      public OutputStreamSerializer.Builder beanContext(BeanContext value)
      Description copied from class: BeanContextable.Builder
      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().

      Overrides:
      beanContext in class Serializer.Builder
      Parameters:
      value - The bean context to use.
      Returns:
      This object.

    • beanContext

      public OutputStreamSerializer.Builder beanContext(BeanContext.Builder value)
      Description copied from class: BeanContextable.Builder
      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.

      Overrides:
      beanContext in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      Returns:
      This object.

    • beanDictionary

      public OutputStreamSerializer.Builder beanDictionary(Class<?>... values)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanDictionary in class Serializer.Builder
      Parameters:
      values - The values to add to this setting.
      Returns:
      This object.

    • beanFieldVisibility

      public OutputStreamSerializer.Builder beanFieldVisibility(Visibility value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanFieldVisibility in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC.
      Returns:
      This object.

    • beanInterceptor

      public OutputStreamSerializer.Builder beanInterceptor(Class<?> on, Class<? extends BeanInterceptor<?>> value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanInterceptor in class Serializer.Builder
      Parameters:
      on - The bean that the filter applies to.
      value - The new value for this setting.
      Returns:
      This object.

    • beanMapPutReturnsOldValue

      public OutputStreamSerializer.Builder beanMapPutReturnsOldValue()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanMapPutReturnsOldValue in class Serializer.Builder
      Returns:
      This object.

    • beanMethodVisibility

      public OutputStreamSerializer.Builder beanMethodVisibility(Visibility value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanMethodVisibility in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      The default is Visibility.PUBLIC
      Returns:
      This object.

    • beanProperties

      public OutputStreamSerializer.Builder beanProperties(Map<String,Object> values)
      Description copied from class: BeanContextable.Builder
      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 BeanContextable.Builder.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:
      Overrides:
      beanProperties in class Serializer.Builder
      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 OutputStreamSerializer.Builder beanProperties(Class<?> beanClass, String properties)
      Description copied from class: BeanContextable.Builder
      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 BeanContextable.Builder.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:
      Overrides:
      beanProperties in class Serializer.Builder
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanProperties

      public OutputStreamSerializer.Builder beanProperties(String beanClassName, String properties)
      Description copied from class: BeanContextable.Builder
      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 BeanContextable.Builder.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:
      Overrides:
      beanProperties in class Serializer.Builder
      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 OutputStreamSerializer.Builder beanPropertiesExcludes(Map<String,Object> values)
      Description copied from class: BeanContextable.Builder
      Bean property excludes.

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

      Same as BeanContextable.Builder.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:
      Overrides:
      beanPropertiesExcludes in class Serializer.Builder
      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 OutputStreamSerializer.Builder beanPropertiesExcludes(Class<?> beanClass, String properties)
      Description copied from class: BeanContextable.Builder
      Bean property excludes.

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

      Same as BeanContextable.Builder.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:
      Overrides:
      beanPropertiesExcludes in class Serializer.Builder
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanPropertiesExcludes

      public OutputStreamSerializer.Builder beanPropertiesExcludes(String beanClassName, String properties)
      Description copied from class: BeanContextable.Builder
      Bean property excludes.

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

      Same as BeanContextable.Builder.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:
      Overrides:
      beanPropertiesExcludes in class Serializer.Builder
      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 OutputStreamSerializer.Builder beanPropertiesReadOnly(Map<String,Object> values)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanPropertiesReadOnly in class Serializer.Builder
      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 OutputStreamSerializer.Builder beanPropertiesReadOnly(Class<?> beanClass, String properties)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanPropertiesReadOnly in class Serializer.Builder
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanPropertiesReadOnly

      public OutputStreamSerializer.Builder beanPropertiesReadOnly(String beanClassName, String properties)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanPropertiesReadOnly in class Serializer.Builder
      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 OutputStreamSerializer.Builder beanPropertiesWriteOnly(Map<String,Object> values)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanPropertiesWriteOnly in class Serializer.Builder
      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 OutputStreamSerializer.Builder beanPropertiesWriteOnly(Class<?> beanClass, String properties)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanPropertiesWriteOnly in class Serializer.Builder
      Parameters:
      beanClass - The bean class.
      properties - Comma-delimited list of property names.
      Returns:
      This object.

    • beanPropertiesWriteOnly

      public OutputStreamSerializer.Builder beanPropertiesWriteOnly(String beanClassName, String properties)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beanPropertiesWriteOnly in class Serializer.Builder
      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.

    • beansRequireDefaultConstructor

      public OutputStreamSerializer.Builder beansRequireDefaultConstructor()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beansRequireDefaultConstructor in class Serializer.Builder
      Returns:
      This object.

    • beansRequireSerializable

      public OutputStreamSerializer.Builder beansRequireSerializable()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beansRequireSerializable in class Serializer.Builder
      Returns:
      This object.

    • beansRequireSettersForGetters

      public OutputStreamSerializer.Builder beansRequireSettersForGetters()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      beansRequireSettersForGetters in class Serializer.Builder
      Returns:
      This object.

    • dictionaryOn

      public OutputStreamSerializer.Builder dictionaryOn(Class<?> on, Class<?>... values)
      Description copied from class: BeanContextable.Builder
      Bean dictionary.

      This is identical to BeanContextable.Builder.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:
      Overrides:
      dictionaryOn in class Serializer.Builder
      Parameters:
      on - The class that the dictionary values apply to.
      values - The new values for this setting.
      Returns:
      This object.

    • disableBeansRequireSomeProperties

      public OutputStreamSerializer.Builder disableBeansRequireSomeProperties()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      disableBeansRequireSomeProperties in class Serializer.Builder
      Returns:
      This object.

    • disableIgnoreMissingSetters

      public OutputStreamSerializer.Builder disableIgnoreMissingSetters()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      disableIgnoreMissingSetters in class Serializer.Builder
      Returns:
      This object.

    • disableIgnoreTransientFields

      public OutputStreamSerializer.Builder disableIgnoreTransientFields()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      disableIgnoreTransientFields in class Serializer.Builder
      Returns:
      This object.

    • disableIgnoreUnknownNullBeanProperties

      public OutputStreamSerializer.Builder disableIgnoreUnknownNullBeanProperties()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      disableIgnoreUnknownNullBeanProperties in class Serializer.Builder
      Returns:
      This object.

    • disableInterfaceProxies

      public OutputStreamSerializer.Builder disableInterfaceProxies()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      disableInterfaceProxies in class Serializer.Builder
      Returns:
      This object.

    • example

      public <T> OutputStreamSerializer.Builder example(Class<T> pojoClass, T o)
      Description copied from class: BeanContextable.Builder
      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:

      Overrides:
      example in class Serializer.Builder
      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> OutputStreamSerializer.Builder example(Class<T> pojoClass, String json)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      example in class Serializer.Builder
      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 OutputStreamSerializer.Builder findFluentSetters()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      findFluentSetters in class Serializer.Builder
      Returns:
      This object.

    • findFluentSetters

      public OutputStreamSerializer.Builder findFluentSetters(Class<?> on)
      Description copied from class: BeanContextable.Builder
      Find fluent setters.

      Identical to BeanContextable.Builder.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:
      Overrides:
      findFluentSetters in class Serializer.Builder
      Parameters:
      on - The class that this applies to.
      Returns:
      This object.

    • ignoreInvocationExceptionsOnGetters

      public OutputStreamSerializer.Builder ignoreInvocationExceptionsOnGetters()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      ignoreInvocationExceptionsOnGetters in class Serializer.Builder
      Returns:
      This object.

    • ignoreInvocationExceptionsOnSetters

      public OutputStreamSerializer.Builder ignoreInvocationExceptionsOnSetters()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      ignoreInvocationExceptionsOnSetters in class Serializer.Builder
      Returns:
      This object.

    • ignoreUnknownBeanProperties

      public OutputStreamSerializer.Builder ignoreUnknownBeanProperties()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      ignoreUnknownBeanProperties in class Serializer.Builder
      Returns:
      This object.

    • ignoreUnknownEnumValues

      public OutputStreamSerializer.Builder ignoreUnknownEnumValues()
      Description copied from class: BeanContextable.Builder
      Ignore unknown enum values.

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

      See Also:
      Overrides:
      ignoreUnknownEnumValues in class Serializer.Builder
      Returns:
      This object.

    • implClass

      public OutputStreamSerializer.Builder implClass(Class<?> interfaceClass, Class<?> implClass)
      Description copied from class: BeanContextable.Builder
      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);

      Overrides:
      implClass in class Serializer.Builder
      Parameters:
      interfaceClass - The interface class.
      implClass - The implementation class.
      Returns:
      This object.

    • implClasses

      public OutputStreamSerializer.Builder implClasses(Map<Class<?>,Class<?>> values)
      Description copied from class: BeanContextable.Builder
      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);

      Overrides:
      implClasses in class Serializer.Builder
      Parameters:
      values - The new value for this setting.
      Returns:
      This object.

    • interfaceClass

      public OutputStreamSerializer.Builder interfaceClass(Class<?> on, Class<?> value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      interfaceClass in class Serializer.Builder
      Parameters:
      on - The class that the interface class applies to.
      value - The new value for this setting.
      Returns:
      This object.

    • interfaces

      public OutputStreamSerializer.Builder interfaces(Class<?>... value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      interfaces in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      Returns:
      This object.

    • locale

      public OutputStreamSerializer.Builder locale(Locale value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      locale in class Serializer.Builder
      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • mediaType

      public OutputStreamSerializer.Builder mediaType(MediaType value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      mediaType in class Serializer.Builder
      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • notBeanClasses

      public OutputStreamSerializer.Builder notBeanClasses(Class<?>... values)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      notBeanClasses in class Serializer.Builder
      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 OutputStreamSerializer.Builder notBeanPackages(String... values)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      notBeanPackages in class Serializer.Builder
      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 OutputStreamSerializer.Builder propertyNamer(Class<? extends PropertyNamer> value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      propertyNamer in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      The default is BasicPropertyNamer.
      Returns:
      This object.

    • propertyNamer

      public OutputStreamSerializer.Builder propertyNamer(Class<?> on, Class<? extends PropertyNamer> value)
      Description copied from class: BeanContextable.Builder
      Bean property namer

      Same as BeanContextable.Builder.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:
      Overrides:
      propertyNamer in class Serializer.Builder
      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 OutputStreamSerializer.Builder sortProperties()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      sortProperties in class Serializer.Builder
      Returns:
      This object.

    • sortProperties

      public OutputStreamSerializer.Builder sortProperties(Class<?>... on)
      Description copied from class: BeanContextable.Builder
      Sort bean properties.

      Same as BeanContextable.Builder.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:
      Overrides:
      sortProperties in class Serializer.Builder
      Parameters:
      on - The bean classes to sort properties on.
      Returns:
      This object.

    • stopClass

      public OutputStreamSerializer.Builder stopClass(Class<?> on, Class<?> value)
      Description copied from class: BeanContextable.Builder
      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());

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

    • swap

      public <T, S> OutputStreamSerializer.Builder swap(Class<T> normalClass, Class<S> swappedClass, ThrowingFunction<T,S> swapFunction)
      Description copied from class: BeanContextable.Builder
      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();

      Overrides:
      swap in class Serializer.Builder
      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> OutputStreamSerializer.Builder swap(Class<T> normalClass, Class<S> swappedClass, ThrowingFunction<T,S> swapFunction, ThrowingFunction<S,T> unswapFunction)
      Description copied from class: BeanContextable.Builder
      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();

      Overrides:
      swap in class Serializer.Builder
      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.

    • swaps

      public OutputStreamSerializer.Builder swaps(Class<?>... values)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      swaps in class Serializer.Builder
      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.

    • timeZone

      public OutputStreamSerializer.Builder timeZone(TimeZone value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      timeZone in class Serializer.Builder
      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • typeName

      public OutputStreamSerializer.Builder typeName(Class<?> on, String value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      typeName in class Serializer.Builder
      Parameters:
      on - The class the type name is being defined on.
      value - The new value for this setting.
      Returns:
      This object.

    • typePropertyName

      public OutputStreamSerializer.Builder typePropertyName(String value)
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      typePropertyName in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      The default is "_type".
      Returns:
      This object.

    • typePropertyName

      public OutputStreamSerializer.Builder typePropertyName(Class<?> on, String value)
      Description copied from class: BeanContextable.Builder
      Bean type property name.

      Same as BeanContextable.Builder.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:
      Overrides:
      typePropertyName in class Serializer.Builder
      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 OutputStreamSerializer.Builder useEnumNames()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      useEnumNames in class Serializer.Builder
      Returns:
      This object.

    • useJavaBeanIntrospector

      public OutputStreamSerializer.Builder useJavaBeanIntrospector()
      Description copied from class: BeanContextable.Builder
      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:
      Overrides:
      useJavaBeanIntrospector in class Serializer.Builder
      Returns:
      This object.

    • detectRecursions

      public OutputStreamSerializer.Builder detectRecursions()
      Description copied from class: BeanTraverseContext.Builder
      Automatically detect POJO recursions.

      When enabled, specifies that recursions should be checked for during traversal.

      Recursions can occur when traversing models that aren't true trees but rather contain loops.
      In general, unchecked recursions cause stack-overflow-errors.
      These show up as BeanRecursionException with the message "Depth too deep. Stack overflow occurred.".

      Notes:
      • Checking for recursion can cause a small performance penalty.
      Example:

      // Create a serializer that automatically checks for recursions. WriterSerializer serializer = JsonSerializer .create() .detectRecursions() .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);

      Overrides:
      detectRecursions in class Serializer.Builder
      Returns:
      This object.

    • detectRecursions

      public OutputStreamSerializer.Builder detectRecursions(boolean value)
      Description copied from class: BeanTraverseContext.Builder
      Same as BeanTraverseContext.Builder.detectRecursions() but allows you to explicitly specify the value.
      Overrides:
      detectRecursions in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • ignoreRecursions

      public OutputStreamSerializer.Builder ignoreRecursions()
      Description copied from class: BeanTraverseContext.Builder
      Ignore recursion errors.

      When enabled, when we encounter the same object when traversing a tree, we set the value to null.

      For example, if a model contains the links A->B->C->A, then the JSON generated will look like the following when this setting is true...

      {A:{B:{C:null}}}

      Notes:
      • Checking for recursion can cause a small performance penalty.
      Example:

      // Create a serializer ignores recursions. WriterSerializer serializer = JsonSerializer .create() .ignoreRecursions() .build(); // Create a POJO model with a recursive loop. public class MyBean { public Object f; } MyBean bean = new MyBean(); bean.f = bean; // Produces "{f:null}" String json = serializer.serialize(bean);

      Overrides:
      ignoreRecursions in class Serializer.Builder
      Returns:
      This object.

    • ignoreRecursions

      public OutputStreamSerializer.Builder ignoreRecursions(boolean value)
      Description copied from class: BeanTraverseContext.Builder
      Same as BeanTraverseContext.Builder.ignoreRecursions() but allows you to explicitly specify the value.
      Overrides:
      ignoreRecursions in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • initialDepth

      public OutputStreamSerializer.Builder initialDepth(int value)
      Description copied from class: BeanTraverseContext.Builder
      Initial depth.

      The initial indentation level at the root.

      Useful when constructing document fragments that need to be indented at a certain level when whitespace is enabled.

      Example:

      // Create a serializer with whitespace enabled and an initial depth of 2. WriterSerializer serializer = JsonSerializer .create() .ws() .initialDepth(2) .build(); // Produces "\t\t{\n\t\t\t'foo':'bar'\n\t\t}\n" String json = serializer.serialize(new MyBean());

      Overrides:
      initialDepth in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      The default is 0.
      Returns:
      This object.

    • maxDepth

      public OutputStreamSerializer.Builder maxDepth(int value)
      Description copied from class: BeanTraverseContext.Builder
      Max traversal depth.

      When enabled, abort traversal if specified depth is reached in the POJO tree.

      If this depth is exceeded, an exception is thrown.

      This prevents stack overflows from occurring when trying to traverse models with recursive references.

      Example:

      // Create a serializer that throws an exception if the depth reaches greater than 20. WriterSerializer serializer = JsonSerializer .create() .maxDepth(20) .build();

      See Also:
      Overrides:
      maxDepth in class Serializer.Builder
      Parameters:
      value - The new value for this setting.
      The default is 100.
      Returns:
      This object.

    • accept

      public OutputStreamSerializer.Builder accept(String value)
      Description copied from class: Serializer.Builder
      Specifies the accept media types that the serializer can handle.

      Can contain meta-characters per the media-type specification of RFC2616/14.1

      If empty, then assumes the only media type supported is produces.

      For example, if this serializer produces "application/json" but should handle media types of "application/json" and "text/json", then the arguments should be:

      builder.produces("application/json"); builder.accept("application/json,text/json");

      The accept value can also contain q-values.

      Overrides:
      accept in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • addBeanTypes

      public OutputStreamSerializer.Builder addBeanTypes()
      Description copied from class: Serializer.Builder
      Add "_type" properties when needed.

      When enabled, "_type" properties will be added to beans if their type cannot be inferred through reflection.

      This is used to recreate the correct objects during parsing if the object types cannot be inferred.
      For example, when serializing a Map<String,Object> field where the bean class cannot be determined from the type of the values.

      Note the differences between the following settings:

      Example:

      // Create a serializer that adds _type to nodes. WriterSerializer serializer = JsonSerializer .create() .addBeanTypes() .build(); // Our map of beans to serialize. @Bean(typeName="mybean") public class MyBean { public String foo = "bar"; } JsonMap myMap = JsonMap.of("foo", new MyBean()); // Will contain: {"foo":{"_type":"mybean","foo":"bar"}} String json = serializer.serialize(myMap);

      Overrides:
      addBeanTypes in class Serializer.Builder
      Returns:
      This object.

    • addBeanTypes

      public OutputStreamSerializer.Builder addBeanTypes(boolean value)
      Description copied from class: Serializer.Builder
      Same as Serializer.Builder.addBeanTypes() but allows you to explicitly specify the value.
      Overrides:
      addBeanTypes in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • addRootType

      public OutputStreamSerializer.Builder addRootType()
      Description copied from class: Serializer.Builder
      Add type attribute to root nodes.

      When enabled, "_type" properties will be added to top-level beans.

      When disabled, it is assumed that the parser knows the exact Java POJO type being parsed, and therefore top-level type information that might normally be included to determine the data type will not be serialized.

      For example, when serializing a top-level POJO with a @Bean(typeName) value, a '_type' attribute will only be added when this setting is enabled.

      Note the differences between the following settings:

      Example:

      // Create a serializer that adds _type to root node. WriterSerializer serializer= JsonSerializer .create() .addRootType() .build(); // Our bean to serialize. @Bean(typeName="mybean") public class MyBean { public String foo = "bar"; } // Will contain: {"_type":"mybean","foo":"bar"} String json = serializer.serialize(new MyBean());

      Overrides:
      addRootType in class Serializer.Builder
      Returns:
      This object.

    • addRootType

      public OutputStreamSerializer.Builder addRootType(boolean value)
      Description copied from class: Serializer.Builder
      Same as Serializer.Builder.addRootType() but allows you to explicitly specify the value.
      Overrides:
      addRootType in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • keepNullProperties

      public OutputStreamSerializer.Builder keepNullProperties()
      Description copied from class: Serializer.Builder
      Don't trim null bean property values.

      When enabled, null bean values will be serialized to the output.

      Notes:
      • Not enabling this setting will cause Maps with null values to be lost during parsing.
      Example:

      // Create a serializer that serializes null properties. WriterSerializer serializer = JsonSerializer .create() .keepNullProperties() .build(); // Our bean to serialize. public class MyBean { public String foo = null; } // Will contain "{foo:null}". String json = serializer.serialize(new MyBean());

      Overrides:
      keepNullProperties in class Serializer.Builder
      Returns:
      This object.

    • keepNullProperties

      public OutputStreamSerializer.Builder keepNullProperties(boolean value)
      Description copied from class: Serializer.Builder
      Same as Serializer.Builder.keepNullProperties() but allows you to explicitly specify the value.
      Overrides:
      keepNullProperties in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • listener

      public OutputStreamSerializer.Builder listener(Class<? extends SerializerListener> value)
      Description copied from class: Serializer.Builder
      Serializer listener.

      Class used to listen for errors and warnings that occur during serialization.

      Example:

      // Define our serializer listener. // Simply captures all errors. public class MySerializerListener extends SerializerListener { // A simple property to store our events. public List<String> events = new LinkedList<>(); @Override public <T> void onError(SerializerSession session, Throwable throwable, String msg) { events.add(session.getLastLocation() + "," + msg + "," + throwable); } } // Create a serializer using our listener. WriterSerializer serializer = JsonSerializer .create() .listener(MySerializerListener.class) .build(); // Create a session object. // Needed because listeners are created per-session. try (WriterSerializerSession session = serializer.createSession()) { // Serialize a bean. String json = session.serialize(new MyBean()); // Get the listener. MySerializerListener listener = session.getListener(MySerializerListener.class); // Dump the results to the console. Json5.DEFAULT.println(listener.events); }

      Overrides:
      listener in class Serializer.Builder
      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • produces

      public OutputStreamSerializer.Builder produces(String value)
      Description copied from class: Serializer.Builder
      Specifies the media type that this serializer produces.
      Overrides:
      produces in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • sortCollections

      public OutputStreamSerializer.Builder sortCollections()
      Description copied from class: Serializer.Builder
      Sort arrays and collections alphabetically.

      When enabled, copies and sorts the contents of arrays and collections before serializing them.

      Note that this introduces a performance penalty since it requires copying the existing collection.

      Example:

      // Create a serializer that sorts arrays and collections before serialization. WriterSerializer serializer = JsonSerializer .create() .sortCollections() .build(); // An unsorted array String[] myArray = {"foo","bar","baz"}; // Produces ["bar","baz","foo"] String json = serializer.serialize(myArray);

      Overrides:
      sortCollections in class Serializer.Builder
      Returns:
      This object.

    • sortCollections

      public OutputStreamSerializer.Builder sortCollections(boolean value)
      Description copied from class: Serializer.Builder
      Same as Serializer.Builder.sortCollections() but allows you to explicitly specify the value.
      Overrides:
      sortCollections in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • sortMaps

      public OutputStreamSerializer.Builder sortMaps()
      Description copied from class: Serializer.Builder
      Sort maps alphabetically.

      When enabled, copies and sorts the contents of maps by their keys before serializing them.

      Note that this introduces a performance penalty.

      Example:

      // Create a serializer that sorts maps before serialization. WriterSerializer serializer = JsonSerializer .create() .sortMaps() .build(); // An unsorted map. JsonMap myMap = JsonMap.of("foo",1,"bar",2,"baz",3); // Produces {"bar":2,"baz":3,"foo":1} String json = serializer.serialize(myMap);

      Overrides:
      sortMaps in class Serializer.Builder
      Returns:
      This object.

    • sortMaps

      public OutputStreamSerializer.Builder sortMaps(boolean value)
      Description copied from class: Serializer.Builder
      Same as Serializer.Builder.sortMaps() but allows you to explicitly specify the value.
      Overrides:
      sortMaps in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • trimEmptyCollections

      public OutputStreamSerializer.Builder trimEmptyCollections()
      Description copied from class: Serializer.Builder
      Trim empty lists and arrays.

      When enabled, empty lists and arrays will not be serialized.

      Note that enabling this setting has the following effects on parsing:

      • Map entries with empty list values will be lost.
      • Bean properties with empty list values will not be set.
      Example:

      // Create a serializer that skips empty arrays and collections. WriterSerializer serializer = JsonSerializer .create() .trimEmptyCollections() .build(); // A bean with a field with an empty array. public class MyBean { public String[] foo = {}; } // Produces {} String json = serializer.serialize(new MyBean());

      Overrides:
      trimEmptyCollections in class Serializer.Builder
      Returns:
      This object.

    • trimEmptyCollections

      public OutputStreamSerializer.Builder trimEmptyCollections(boolean value)
      Description copied from class: Serializer.Builder
      Same as Serializer.Builder.trimEmptyCollections() but allows you to explicitly specify the value.
      Overrides:
      trimEmptyCollections in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • trimEmptyMaps

      public OutputStreamSerializer.Builder trimEmptyMaps()
      Description copied from class: Serializer.Builder
      Trim empty maps.

      When enabled, empty map values will not be serialized to the output.

      Note that enabling this setting has the following effects on parsing:

      • Bean properties with empty map values will not be set.
      Example:

      // Create a serializer that skips empty maps. WriterSerializer serializer = JsonSerializer .create() .trimEmptyMaps() .build(); // A bean with a field with an empty map. public class MyBean { public JsonMap foo = JsonMap.of(); } // Produces {} String json = serializer.serialize(new MyBean());

      Overrides:
      trimEmptyMaps in class Serializer.Builder
      Returns:
      This object.

    • trimEmptyMaps

      public OutputStreamSerializer.Builder trimEmptyMaps(boolean value)
      Description copied from class: Serializer.Builder
      Same as Serializer.Builder.trimEmptyMaps() but allows you to explicitly specify the value.
      Overrides:
      trimEmptyMaps in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • trimStrings

      public OutputStreamSerializer.Builder trimStrings()
      Description copied from class: Serializer.Builder
      Trim strings.

      When enabled, string values will be trimmed of whitespace using String.trim() before being serialized.

      Example:

      // Create a serializer that trims strings before serialization. WriterSerializer serializer = JsonSerializer .create() .trimStrings() .build(); // A map with space-padded keys/values JsonMap myMap = JsonMap.of(" foo ", " bar "); // Produces "{foo:'bar'}" String json = serializer.toString(myMap);

      Overrides:
      trimStrings in class Serializer.Builder
      Returns:
      This object.

    • trimStrings

      public OutputStreamSerializer.Builder trimStrings(boolean value)
      Description copied from class: Serializer.Builder
      Same as Serializer.Builder.trimStrings() but allows you to explicitly specify the value.
      Overrides:
      trimStrings in class Serializer.Builder
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • uriContext

      public OutputStreamSerializer.Builder uriContext(UriContext value)
      Description copied from class: Serializer.Builder
      URI context bean.

      Bean used for resolution of URIs to absolute or root-relative form.

      Example:

      // Our URI contextual information. String authority = "http://localhost:10000"; String contextRoot = "/myContext"; String servletPath = "/myServlet"; String pathInfo = "/foo"; // Create a UriContext object. UriContext uriContext = new UriContext(authority, contextRoot, servletPath, pathInfo); // Associate it with our serializer. WriterSerializer serializer = JsonSerializer .create() .uriContext(uriContext) .uriRelativity(RESOURCE) // Assume relative paths are relative to servlet. .uriResolution(ABSOLUTE) // Serialize URLs as absolute paths. .build(); // A relative URL URL myUrl = new URL("bar"); // Produces "http://localhost:10000/myContext/myServlet/foo/bar" String json = serializer.toString(myUrl);

      See Also:
      Overrides:
      uriContext in class Serializer.Builder
      Parameters:
      value - The new value for this property.
      Returns:
      This object.

    • uriRelativity

      public OutputStreamSerializer.Builder uriRelativity(UriRelativity value)
      Description copied from class: Serializer.Builder
      URI relativity.

      Defines what relative URIs are relative to when serializing any of the following:

      • URI
      • URL
      • Properties and classes annotated with @Uri

      See Serializer.Builder.uriContext(UriContext) for examples.

      See Also:
      Overrides:
      uriRelativity in class Serializer.Builder
      Parameters:
      value - The new value for this property.
      The default is UriRelativity.RESOURCE
      Returns:
      This object.

    • uriResolution

      public OutputStreamSerializer.Builder uriResolution(UriResolution value)
      Description copied from class: Serializer.Builder
      URI resolution.

      Defines the resolution level for URIs when serializing any of the following:

      • URI
      • URL
      • Properties and classes annotated with @Uri

      See Serializer.Builder.uriContext(UriContext) for examples.

      See Also:
      Overrides:
      uriResolution in class Serializer.Builder
      Parameters:
      value - The new value for this property.
      The default is UriResolution.NONE
      Returns:
      This object.