Package org.apache.juneau.marshall

Class Context.Builder<SELF extends Context.Builder<SELF>>

java.lang.Object
org.apache.juneau.marshall.Context.Builder<SELF>
Direct Known Subclasses:
Config.Builder, ConfigStore.Builder, MarshallingContext.Builder, MarshallingContextable.Builder
Enclosing class:
Context
public abstract static class Context.Builder<SELF extends Context.Builder<SELF>> extends Object
Builder class.

  • Constructor Details

    • Builder

      protected Builder()
      Constructor. Default settings.

    • Builder

      protected Builder(Context.Builder<?> copyFrom)
      Copy constructor.
      Parameters:
      copyFrom - The builder to copy from.
      Cannot be null.

    • Builder

      protected Builder(Context copyFrom)
      Copy constructor.
      Parameters:
      copyFrom - The bean to copy from.
      Cannot be null.

  • Method Details

    • self

      protected final SELF self()
      Returns this object cast to the self (CRTP) type.
      Returns:
      This object.

    • annotations

      public SELF annotations(Annotation... values)
      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 @Marshalled annotation:

      // Class with explicit annotation. @Marshalled(properties="street,city,state") public class A {...} // Class with annotation applied via @MarshalledConfig public class B {...} // Java REST method with @MarshalledConfig annotation. @RestGet(...) @Marshalled(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 @Marshalled annotation. Marshalled annotation = MarshalledAnnotation.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.write(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:
      Parameters:
      values - The annotations to register with the context.
      Cannot contain null values.
      Returns:
      This object.

    • annotations

      public SELF annotations(List<Annotation> values)
      Same as annotations(Annotation...) but uses a list as input.
      Parameters:
      values - The annotations to register with the context.
      Cannot be null or contain null values.
      Returns:
      This object.

    • apply

      public SELF apply(AnnotationWorkList work)
      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. @MarshalledConfig(unsortedProperties="$S{unsortedProperties,false}") public class MyClass {...} // Find all annotations that themselves are annotated with @ContextPropertiesApply. Stream<AnnotationInfo<?>> annotations = ClassInfo.of(MyClass.class).getAnnotations().stream().filter(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();

      Parameters:
      work - The list of annotations and appliers to apply to this builder.
      Cannot be null.
      Returns:
      This object.

    • applyAnnotations

      public SELF applyAnnotations(Class<?>... from)
      Same as applyAnnotations(Object...) but explicitly specifies a class varargs to avoid compilation warnings.
      Parameters:
      from - The classes or methods on which the annotations are defined.
      Cannot contain null values.
      Returns:
      This object.

    • applyAnnotations

      public SELF applyAnnotations(Object... from)
      Applies any of the various @XConfig annotations on the specified classes or methods 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.

      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 class annotated with a config annotation. @MarshalledConfig(unsortedProperties="$S{unsortedProperties,false}") public class MyClass {...} // Apply any settings found on the annotations. WriterSerializer serializer = JsonSerializer .create() .applyAnnotations(MyClass.class) .build(); // A method annotated with a config annotation. public class MyClass { @MarshalledConfig(unsortedProperties="$S{unsortedProperties,false}") public void myMethod() {...} } // Apply any settings found on the annotations. WriterSerializer serializer = JsonSerializer .create() .applyAnnotations(MyClass.class.getMethod("myMethod")) .build();

      Parameters:
      from - The classes or methods on which the annotations are defined. Can be any of the following types:
      Returns:
      This object.

    • asSubtype

      public <T extends Context.Builder<?>> Optional<T> asSubtype(Class<T> subtype)
      Returns this builder cast to the specified subtype if it is an instance of that type.

      This is a type-safe way to check if this builder is an instance of a specific builder subtype and cast it accordingly. Returns an empty Optional if this builder is not an instance of the specified subtype.

      Example:

      Builder b = JsonSerializer.create(); Optional<JsonSerializer.Builder<?>> jsonBuilder = b.asSubtype(JsonSerializer.Builder.class); if (jsonBuilder.isPresent()) { // Use JsonSerializer.Builder<?>-specific methods jsonBuilder.get().pretty(); }

      Type Parameters:
      T - The builder subtype.
      Parameters:
      subtype - The builder subtype class to cast to.
      Cannot be null.
      Returns:
      An Optional containing this builder cast to the subtype, or empty if not an instance.

    • build

      public Context build()
      Build the object.
      Returns:
      The built object.

    • build

      public final <T extends Context> T build(Class<T> c)
      Convenience method for calling build() while avoiding a cast.
      Type Parameters:
      T - The type to cast the built object to.
      Parameters:
      c - The type to cast the built object to.
      Cannot be null.
      Returns:
      The built context bean.

    • cache

      public SELF cache(Cache<HashKey,? extends Context> value)
      Specifies a cache to use for hashkey-based caching.

      When a cache is specified, contexts with the same hash key will be reused from the cache instead of creating new instances. This improves performance when building multiple contexts with identical configurations.

      If null is specified, caching is disabled and each call to build() will create a new context instance.

      Parameters:
      value - The cache.
      Can be null (disables caching, each build creates a new instance).
      Returns:
      This object.

    • canApply

      public boolean canApply(AnnotationWorkList work)
      Returns true if any of the annotations/appliers can be applied to this builder.
      Parameters:
      work - The work to check.
      Cannot be null.
      Returns:
      true if any of the annotations/appliers can be applied to this builder.

    • copy

      public abstract SELF copy()
      Copy creator.
      Returns:
      A new mutable copy of this builder.

    • copyOrNull

      public static Context.Builder<?> copyOrNull(Context.Builder<?> value)
      Null-safe copy: returns a deep copy of the specified value, or null if the value is null.
      Parameters:
      value - The value to copy. Can be null (returns null).
      Returns:
      A copy of the value, or null if the value was null.

    • debug

      public SELF debug()
      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.write(bean);

      See Also:
      Returns:
      This object.

    • debug

      public SELF debug(boolean value)
      Same as debug() but allows you to explicitly specify the value.
      Parameters:
      value - The value for this setting.
      Returns:
      This object.

    • getApplied

      public AnnotationWorkList getApplied()
      Returns all the annotations that have been applied to this builder.
      Returns:
      All the annotations that have been applied to this builder.

    • getType

      public Optional<Class<?>> getType()
      Returns the context class that this builder should create.
      Returns:
      The context class if it was specified.

    • hashKey

      public HashKey hashKey()
      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.

      Returns:
      The hashkey of this builder.

    • impl

      public SELF impl(Context value)
      Specifies a pre-instantiated bean for the build() method to return.

      If a non-null value is provided and it's an instance of the context type, build() will return that instance instead of creating a new one. If null, the normal build process continues.

      Parameters:
      value - The value for this setting.
      Can be null (normal build process will continue).
      Returns:
      This object.

    • isDebug

      public boolean isDebug()
      Returns true if debug is enabled.
      Returns:
      true if debug is enabled.

    • type

      public SELF type(Class<? extends Context> value)
      Associates a context class with this builder.

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

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

      If null is set, build() will throw an exception. The default constructor automatically sets this to the outer class, so null should only be set explicitly if you want to override the default.

      Parameters:
      value - The context class that this builder should create.
      Can be null (will cause build() to throw an exception).
      Returns:
      This object.

    • registerBuilders

      protected void registerBuilders(Object... values)
      Registers the specified secondary builders with this context builder.

      When apply(AnnotationWorkList) is called, it gets called on all registered builders.

      Parameters:
      values - The builders to add to the list of builders.
      Cannot contain null values.