Package jsonvalues.spec

Class JsObjSpecBuilder

java.lang.Object
jsonvalues.spec.JsObjSpecBuilder
public final class JsObjSpecBuilder extends Object
The JsObjSpecBuilder class is a builder for creating instances of JsObjSpec with additional metadata. It allows configuring the name, namespace, documentation, field orders, aliases, and default values for a JSON object specification.

Example usage: 

 
 // Creating a simple JsObjSpec
 JsObjSpec simpleSpec = JsObjSpecBuilder
         .withName("Person")
         .withNamespace("example.namespace")
         .withDoc("Specification for representing a person")
         .withFieldDocs(Map.of("name", "Full name of the person", "age", "Age of the person"))
         .withFieldOrders(Map.of("name", MetaData.ORDERS.DESC))
         .withFieldAliases(Map.of("firstName", List.of("name")))
         .withAliases(List.of("PersonRecord"))
         .withFieldsDefaults(Map.of("age", JsInt.of(30)))
         .build(existingJsObjSpec);

 // Creating a recursive JsObjSpec with defaults
 JsObjSpec recursiveSpec = JsObjSpecBuilder.withName("person")
                                   .withFieldsDefaults(Map.of("father", JsNull.NULL))
                                   .build(JsObjSpec.of("name", JsSpecs.str(),
                                                       "age", JsSpecs.integer(),
                                                       "father", JsSpecs.ofNamedSpec("person").nullable()
                                                      )
                                                   .withOptKeys("father")
                                         );

Note: When creating named specs using this builder, the specs are cached by `[namespace.]?name`. Aliases are also cached. Attempting to create two specs with the same full name will result in an error.

When dealing with recursive specifications or generating Avro schemas with [avro-spec](...), using the builder pattern is mandatory to create complex specifications. For example, the creation of a recursive JsObjSpec with defaults is shown above.

Field aliases and field defaults configured through this builder are utilized by the JsObjSpecParser when parsing JSON objects.

  • Method Details

    • withName

      public static JsObjSpecBuilder withName(String name)
      Sets the name of the JSON object specification. The name must follow the Avro naming conventions, adhering to the regex pattern: [A-Za-z_][A-Za-z0-9_]*.
      Parameters:
      name - The name of the JSON object specification.
      Returns:
      A reference to this JsObjSpecBuilder instance for method chaining.
      Throws:
      IllegalArgumentException - If the provided name does not follow the Avro naming conventions.

    • withNamespace

      public JsObjSpecBuilder withNamespace(String nameSpace)
      Sets the namespace of the JSON object specification. The namespace must follow the Avro naming conventions, adhering to the regex pattern: [A-Za-z_][A-Za-z0-9_.]+. It should start with a letter or an underscore, followed by letters, numbers, underscores, or dots.
      Parameters:
      nameSpace - The namespace of the JSON object specification.
      Returns:
      A reference to this JsObjSpecBuilder instance for method chaining.
      Throws:
      IllegalArgumentException - If the provided namespace does not follow the Avro naming conventions.

    • withDoc

      public JsObjSpecBuilder withDoc(String doc)
      Sets the documentation for the JsObjSpec.
      Parameters:
      doc - The documentation for the JsObjSpec.
      Returns:
      This JsObjSpecBuilder for method chaining.

    • withFieldDocs

      public JsObjSpecBuilder withFieldDocs(Map<String,String> fieldsDoc)
      Sets the field-level documentation for the JsObjSpec.
      Parameters:
      fieldsDoc - A map containing field names as keys and their corresponding documentation as values.
      Returns:
      This JsObjSpecBuilder for method chaining.

    • withFieldOrders

      public JsObjSpecBuilder withFieldOrders(Map<String,JsObjSpecBuilder.ORDERS> fieldsOrder)
      Sets the order for fields in the JsObjSpec.
      Parameters:
      fieldsOrder - A map containing field names as keys and their corresponding order as values.
      Returns:
      This JsObjSpecBuilder for method chaining.

    • withFieldAliases

      public JsObjSpecBuilder withFieldAliases(Map<String,List<String>> fieldsAliases)
      Sets field aliases for the JsObjSpec.

      Field aliases are used by the `JsObjSpecParser` to replace an alias with its corresponding main field during JSON parsing. For example, if field 'b' is specified as an alias for field 'a', and the JSON input contains a field named 'b', the parser will replace 'b' with 'a'.

      Parameters:
      fieldsAliases - A map containing field names as keys and a list of their corresponding aliases as values.
      Returns:
      This JsObjSpecBuilder for method chaining.

    • withAliases

      public JsObjSpecBuilder withAliases(List<String> aliases)
      Sets aliases for the JsObjSpec. Must follow the avro naming conventions and, adhering to the regex pattern: [A-Za-z_][A-Za-z0-9_.]+

      Aliases provide alternative names for the JsObjSpec, and they can be used interchangeably when referring to the same specification.

      Parameters:
      aliases - A list of alternative names (aliases) for the JsObjSpec.
      Returns:
      This JsObjSpecBuilder for method chaining.
      Throws:
      IllegalArgumentException - If any of the provided aliases does not follow the naming pattern.

    • withFieldsDefaults

      public JsObjSpecBuilder withFieldsDefaults(Map<String,JsValue> fieldsDefaults)
      Sets default values for fields in the JsObjSpec.

      Default values are used when parsing JSON objects to replace missing fields with specified values. The provided default values must conform to the specifications of the corresponding fields in the JsObjSpec.

      Parameters:
      fieldsDefaults - A map containing field names and their corresponding default values.
      Returns:
      This JsObjSpecBuilder for method chaining.
      Throws:
      IllegalArgumentException - If any default value does not conform to the field specification, or if a field with a default value is not defined in the JsObjSpec.
      See Also:

    • build

      public JsObjSpec build(JsObjSpec spec)
      Builds the final JsObjSpec by combining the specified configuration with the provided base JsObjSpec.

      This method validates and merges the configured metadata with the base JsObjSpec to create a new JsObjSpec. The resulting JsObjSpec is then cached for future reference.

      Parameters:
      spec - The base JsObjSpec to which the configured metadata is applied.
      Returns:
      The final JsObjSpec with the specified configuration.
      Throws:
      IllegalArgumentException - If any configured metadata is invalid or conflicts with the base JsObjSpec.
      See Also: