BinaryObject (Ignite 2.16.0)

All Superinterfaces:

Cloneable, Serializable
```
public interface BinaryObject
extends Serializable, Cloneable
```
Wrapper for binary object in binary format. Once an object is defined as binary, Ignite will always store it in memory in the binary format. User can choose to work either with the binary format or with the deserialized form (assuming that class definitions are present in the classpath).
NOTE: user does not need to (and should not) implement this interface directly.
To work with the binary format directly, user should create a cache projection over BinaryObject class and then retrieve individual fields as needed:
```
 IgniteCache<BinaryObject, BinaryObject> prj = cache.withKeepBinary();

 // Convert instance of MyKey to binary format.
 // We could also use BinaryObjectBuilder to create the key in binary format directly.
 BinaryObject key = ignite.binary().toBinary(new MyKey());

 BinaryObject val = prj.get(key);

 String field = val.field("myFieldName");
 
```
Alternatively, if we have class definitions in the classpath, we may choose to work with deserialized typed objects at all times. In this case we do incur the deserialization cost.
```
 IgniteCache<MyKey.class, MyValue.class> cache = grid.cache(null);

 MyValue val = cache.get(new MyKey());

 // Normal java getter.
 String fieldVal = val.getMyFieldName();
 
```
Working With Maps and Collections
All maps and collections in binary objects are serialized automatically. When working with different platforms, e.g. C++ or .NET, Ignite will automatically pick the most adequate collection or map in either language. For example, ArrayList in Java will become List in C#, LinkedList in Java is LinkedList in C#, HashMap in Java is Dictionary in C#, and TreeMap in Java becomes SortedDictionary in C#, etc.
Dynamic Structure Changes
Since objects are always cached in the binary format, server does not need to be aware of the class definitions. Moreover, if class definitions are not present or not used on the server, then clients can continuously change the structure of the binary objects without having to restart the cluster. For example, if one client stores a certain class with fields A and B, and another client stores the same class with fields B and C, then the server-side binary object will have the fields A, B, and C. As the structure of a binary object changes, the new fields become available for SQL queries automatically.
Building Binary Objects
Ignite comes with BinaryObjectBuilder which allows to build binary objects dynamically:
```
 BinaryObjectBuilder builder = Ignition.ignite().binary().builder("org.project.MyObject");

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

 BinaryObject binaryObj = builder.build();
 
```
For the cases when class definition is present in the class path, it is also possible to populate a standard POJO and then convert it to binary format, like so:
```
 MyObject obj = new MyObject();

 obj.setFieldA("A");
 obj.setFieldB(123);

 BinaryObject binaryObj = Ignition.ignite().binary().toBinary(obj);
 
```
Binary Type Metadata
Even though Ignite binary protocol only works with hash codes for type and field names to achieve better performance, Ignite provides metadata for all binary types which can be queried ar runtime via any of the IgniteBinary.type(Class) methods. Having metadata also allows for proper formatting of BinaryObject.toString() method, even when binary objects are kept in binary format only, which may be necessary for audit reasons.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`BinaryObject`	`clone()` Copies this binary object.
`<T> T`	`deserialize()` Gets fully deserialized instance of binary object.
`<T> T`	`deserialize(ClassLoader ldr)` Gets fully deserialized instance of binary object.
`String`	`enumName()` Get name for this enum object.
`int`	`enumOrdinal()` Get ordinal for this enum object.
`<F> F`	`field(String fieldName)` Gets field value.
`boolean`	`hasField(String fieldName)` Checks whether field exists in the object.
`int`	`size()` Get the size of the object
`BinaryObjectBuilder`	`toBuilder()` Creates a new `BinaryObjectBuilder` based on this binary object.
`BinaryType`	`type()` Gets type information for this binary object.

- Method Detail
  - type
```
BinaryType type()
         throws BinaryObjectException
```
    Gets type information for this binary object.
    
    Returns:
    
    Binary object type information.
    
    Throws:
    
    BinaryObjectException - In case of error.
  - field
```
<F> F field(String fieldName)
     throws BinaryObjectException
```
    Gets field value.
    
    Type Parameters:
    
    F - Type of the field value.
    
    Parameters:
    
    fieldName - Field name.
    
    Returns:
    
    Field value.
    
    Throws:
    
    BinaryObjectException - In case of any other error.
  - hasField
```
boolean hasField(String fieldName)
```
    Checks whether field exists in the object.
    
    Parameters:
    
    fieldName - Field name.
    
    Returns:
    
    True if field exists.
  - deserialize
```
<T> T deserialize()
           throws BinaryObjectException
```
    Gets fully deserialized instance of binary object.
    
    Type Parameters:
    
    T - Type of the deserialized object.
    
    Returns:
    
    Fully deserialized instance of binary object.
    
    Throws:
    
    BinaryInvalidTypeException - If class doesn't exist.
    
    BinaryObjectException - In case of any other error.
  - deserialize
```
<T> T deserialize(ClassLoader ldr)
           throws BinaryObjectException
```
    Gets fully deserialized instance of binary object. If ldr was not specified, configured class loader will be used IgniteConfiguration.getClassLoader().
    
    Type Parameters:
    
    T - Type of the deserialized object.
    
    Parameters:
    
    ldr - Class loader.
    
    Returns:
    
    Fully deserialized instance of binary object.
    
    Throws:
    
    BinaryInvalidTypeException - If class doesn't exist.
    
    BinaryObjectException - In case of any other error.
  - clone
```
BinaryObject clone()
            throws CloneNotSupportedException
```
    Copies this binary object.
    
    Returns:
    
    Copy of this binary object.
    
    Throws:
    
    CloneNotSupportedException
  - toBuilder
```
BinaryObjectBuilder toBuilder()
                       throws BinaryObjectException
```
    Creates a new BinaryObjectBuilder based on this binary object. The following code
```
 BinaryObjectBuilder builder = binaryObject.toBuilder();
 
```
    is equivalent to
```
 BinaryObjectBuilder builder = ignite.binary().builder(binaryObject);
 
```
    Returns:
    
    Binary object builder.
    
    Throws:
    
    BinaryObjectException - If builder cannot be created.
  - enumOrdinal
```
int enumOrdinal()
         throws BinaryObjectException
```
    Get ordinal for this enum object. Use BinaryType.isEnum() to check if object is of enum type.
    
    Returns:
    
    Ordinal.
    
    Throws:
    
    BinaryObjectException - If object is not enum.
  - enumName
```
String enumName()
         throws BinaryObjectException
```
    Get name for this enum object. Use BinaryType.isEnum() to check if object is of enum type.
    
    Returns:
    
    Name.
    
    Throws:
    
    BinaryObjectException - If object is not enum.
  - size
```
int size()
```
    Get the size of the object
    
    Returns:
    
    Size of the object

Interface BinaryObject

Working With Maps and Collections

Dynamic Structure Changes

Building Binary Objects

Binary Type Metadata

Method Summary

Method Detail

type

field

hasField

deserialize

deserialize

clone

toBuilder

enumOrdinal

enumName

size