Package org.apache.ignite.binary

## Interface BinaryObjectBuilder

-     public interface BinaryObjectBuilder

  Binary object builder. Provides ability to build binary objects dynamically without having class definitions.

  Here is an example of how a binary object can be built dynamically:

       BinaryObjectBuilder builder = Ignition.ignite().binary().builder("org.project.MyObject");

       builder.setField("fieldA", "A");
       builder.setField("fieldB", "B");

       BinaryObject binaryObj = builder.build();

  Also builder can be initialized by existing binary object. This allows changing some fields without affecting other fields.

       BinaryObjectBuilder builder = Ignition.ignite().binary().builder(person);

       builder.setField("name", "John");

       person = builder.build();

  If you need to modify nested binary object you can get an instance of a builder for nested binary object using `getField(String)`, changes made on nested builder will affect parent object, for example:

       BinaryObjectBuilder personBuilder = grid.binary().createBuilder(personBinaryObj);
       BinaryObjectBuilder addressBuilder = personBuilder.getField("address");

       addressBuilder.setField("city", "New York");

       personBinaryObj = personBuilder.build();

       // Should be "New York".
       String city = personBinaryObj.getField("address").getField("city");

  Make sure to set values for all the fields that an object from your domain model has. If you need to set null as a value use `setField(String, Object, Class)` method directly specifying field's type.

  If to follow this recommendation you'll reduce the size of internal metadata object that every binary object of a particular type has. Usually the metadata size grows because particular fields are not set to an instance of a binary object constructed with the builder. Every time when you construct an object setting only a subset of the fields the metadata object related to this type is expanded by the metadata processor which treats every new combination of the fields as the new version of the binary object.

  See Also:
    `IgniteBinary.builder(String)`, `IgniteBinary.builder(BinaryObject)`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `BinaryObject` | `build()` | Builds binary object.
    `<T> T` | `getField​(String name)` | Returns value assigned to the specified field.
    `BinaryObjectBuilder` | `removeField​(String fieldName)` | Removes field from this builder.
    `BinaryObjectBuilder` | `setField​(String name, @Nullable BinaryObjectBuilder builder)` | Sets field value.
    `BinaryObjectBuilder` | `setField​(String name, Object val)` | Sets field value.
    `<T> BinaryObjectBuilder` | `setField​(String name, T val, Class<? super T> type)` | Sets field value with value type specification.

- - ### Method Detail

    - #### getField

          <T> T getField​(String name)

      Returns value assigned to the specified field. If the value is a binary object then an instance of `BinaryObjectBuilder` will be returned, which can be modified.

      Collections and maps returned from this method are modifiable.

      Type Parameters:
        `T` - Type of the field value.
      Parameters:
        `name` - Field name.
      Returns:
        Field value.

    - #### setField

          BinaryObjectBuilder setField​(String name,
                                       Object val)

      Sets field value.
      Parameters:
        `name` - Field name.
        `val` - Field value (cannot be `null`).
      Returns:
        `this` for chaining.
      See Also:
        `BinaryObject.type()`

    - #### setField

          <T> BinaryObjectBuilder setField​(String name,
                                           @Nullable
                                           T val,
                                           Class<? super T> type)

      Sets field value with value type specification.

      Field type is needed for proper metadata update.

      Type Parameters:
        `T` - Type of the field value.
      Parameters:
        `name` - Field name.
        `val` - Field value.
        `type` - Field type.
      Returns:
        `this` for chaining.
      See Also:
        `BinaryObject.type()`

    - #### setField

          BinaryObjectBuilder setField​(String name,
                                       @Nullable
                                       @Nullable BinaryObjectBuilder builder)

      Sets field value.

      This method should be used if field is binary object.

      Parameters:
        `name` - Field name.
        `builder` - Builder for object field.
      Returns:
        `this` for chaining.

    - #### removeField

          BinaryObjectBuilder removeField​(String fieldName)

      Removes field from this builder.
      Parameters:
        `fieldName` - Field name.
      Returns:
        `this` instance for chaining.

    - #### build

          BinaryObject build()
                      throws BinaryObjectException

      Builds binary object.
      Returns:
        Binary object.
      Throws:
        `BinaryObjectException` - In case of error.