public interface IgniteBinary
circular or null references.BinaryObject format).
To work with the binary format directly, user should create a special cache projection using IgniteCache.withKeepBinary() method and then retrieve individual fields as needed:
IgniteCache<BinaryObject, BinaryObject> prj = cache.withKeepBinary();
// Convert instance of MyKey to binary format.
// We could also use BinaryBuilder to create the key in binary format directly.
BinaryObject key = grid.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.
IgniteCache<MyKey.class, MyValue.class> cache = grid.cache(null); MyValue val = cache.get(new MyKey()); // Normal java getter. String fieldVal = val.getMyFieldName();If we used, for example, one of the automatically handled binary types for a key, like integer, and still wanted to work with binary binary format for values, then we would declare cache projection as follows:
IgniteCache<Integer.class, BinaryObject> prj = cache.withKeepBinary();
BinaryObject format. Following
classes are never converted (e.g., toBinary(Object) method will return original
object, and instances of these classes will be stored in cache without changes):
String and array of StringsUUID and array of UUIDsDate and array of DatesTimestamp and array of TimestampsArrayList 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.
BinaryObjectBuilder which allows to build binary objects dynamically:
BinaryBuilder builder = Ignition.ignite().binary().builder();
builder.typeId("MyObject");
builder.stringField("fieldA", "A");
build.intField("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);
NOTE: you don't need to convert typed objects to binary format before storing
them in cache, Ignite will do that automatically.
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.
Here is an example of binary configuration (note that star (*) notation is supported):
...
<!-- Explicit binary objects configuration. -->
<property name="marshaller">
<bean class="org.apache.ignite.marshaller.binary.BinaryMarshaller">
<property name="classNames">
<list>
<value>my.package.for.binary.objects.*</value>
<value>org.apache.ignite.examples.client.binary.Employee</value>
</list>
</property>
</bean>
</property>
...
or from code:
IgniteConfiguration cfg = new IgniteConfiguration();
BinaryMarshaller marsh = new BinaryMarshaller();
marsh.setClassNames(Arrays.asList(
Employee.class.getName(),
Address.class.getName())
);
cfg.setMarshaller(marsh);
You can also specify class name for a binary object via BinaryTypeConfiguration.
Do it in case if you need to override other configuration properties on per-type level, like
ID-mapper, or serializer.
Employee object with
Organization, and want to colocate employees with organization they work for,
so you can process them together, you need to specify an alternate affinity key.
With binary objects you would have to do it as following:
<property name="marshaller">
<bean class="org.gridgain.grid.marshaller.binary.BinaryMarshaller">
...
<property name="typeConfigurations">
<list>
<bean class="org.apache.ignite.binary.BinaryTypeConfiguration">
<property name="className" value="org.apache.ignite.examples.client.binary.EmployeeKey"/>
<property name="affinityKeyFieldName" value="organizationId"/>
</bean>
</list>
</property>
...
</bean>
</property>
Binarylizable interface, like so:
public class Address implements BinaryMarshalAware {
private String street;
private int zip;
// Empty constructor required for binary deserialization.
public Address() {}
@Override public void writeBinary(BinaryWriter writer) throws BinaryException {
writer.writeString("street", street);
writer.writeInt("zip", zip);
}
@Override public void readBinary(BinaryReader reader) throws BinaryException {
street = reader.readString("street");
zip = reader.readInt("zip");
}
}
Alternatively, if you cannot change class definitions, you can provide custom serialization
logic in BinarySerializer either globally in
BinaryConfiguration or
for a specific type via BinaryTypeConfiguration instance.
Similar to java serialization you can use writeReplace() and readResolve() methods.
readResolve is defined as follows: ANY-ACCESS-MODIFIER Object readResolve().
It may be used to replace the de-serialized object by another one of your choice.
writeReplace is defined as follows: ANY-ACCESS-MODIFIER Object writeReplace(). This method
allows the developer to provide a replacement object that will be serialized instead of the original one.
BinaryIdMapper implementation.
ID-mapper may be provided either globally in BinaryConfiguration,
or for a specific type via BinaryTypeConfiguration instance.
CacheTypeMetadata inside of specific
CacheConfiguration instance,
like so:
...
<bean class="org.apache.ignite.cache.CacheConfiguration">
...
<property name="typeMetadata">
<list>
<bean class="CacheTypeMetadata">
<property name="type" value="Employee"/>
<!-- Fields to index in ascending order. -->
<property name="ascendingFields">
<map>
<entry key="name" value="java.lang.String"/>
<!-- Nested binary objects can also be indexed. -->
<entry key="address.zip" value="java.lang.Integer"/>
</map>
</property>
</bean>
</list>
</property>
</bean>
| Modifier and Type | Method and Description |
|---|---|
BinaryObject |
buildEnum(String typeName,
int ord)
Create enum object.
|
BinaryObjectBuilder |
builder(BinaryObject binaryObj)
Creates binary builder initialized by existing binary object.
|
BinaryObjectBuilder |
builder(String typeName)
Creates new binary builder.
|
<T> T |
toBinary(Object obj)
Converts provided object to instance of
BinaryObject. |
BinaryType |
type(Class<?> cls)
Gets metadata for provided class.
|
BinaryType |
type(int typeId)
Gets metadata for provided type ID.
|
BinaryType |
type(String typeName)
Gets metadata for provided class name.
|
int |
typeId(String typeName)
Gets type ID for given type name.
|
Collection<BinaryType> |
types()
Gets metadata for all known types.
|
int typeId(String typeName)
typeName - Type name.<T> T toBinary(@Nullable Object obj) throws BinaryObjectException
BinaryObject.obj - Object to convert.BinaryObjectException - In case of error.BinaryObjectBuilder builder(String typeName) throws BinaryObjectException
typeName - Type name.BinaryObjectExceptionBinaryObjectBuilder builder(BinaryObject binaryObj) throws BinaryObjectException
binaryObj - Binary object to initialize builder.BinaryObjectExceptionBinaryType type(Class<?> cls) throws BinaryObjectException
cls - Class.BinaryObjectException - In case of error.BinaryType type(String typeName) throws BinaryObjectException
typeName - Type name.BinaryObjectException - In case of error.BinaryType type(int typeId) throws BinaryObjectException
typeId - Type ID.BinaryObjectException - In case of error.Collection<BinaryType> types() throws BinaryObjectException
BinaryObjectException - In case of error.BinaryObject buildEnum(String typeName, int ord)
typeName - Type name.ord - Ordinal.
Follow @ApacheIgnite
Ignite Fabric : ver. 1.5.11 Release Date : April 8 2016