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 String
sUUID
and array of UUID
sDate
and array of Date
sTimestamp
and array of Timestamp
sArrayList
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.
QueryEntity
inside of specific
CacheConfiguration
instance,
like so:
... <bean class="org.apache.ignite.cache.CacheConfiguration"> ... <property name="queryEntities"> <list> <bean class="QueryEntity"> <property name="type" value="Employee"/> <!-- Fields available from query. --> <property name="fields"> <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> <!-- Aliases for full property name in dot notation. --> <property name="fields"> <map> <entry key="address.zip" value="zip" /> </map> </property> <!-- Indexes configuration. --> <property name="indexes"> <list> <bean class="org.apache.ignite.cache.QueryIndex"> <property name="fields"> <map> <!-- The boolean value is the acceding flag. --> <entry key="name" value="true"/> </map> </property> </bean> </list> </property> </bean> </list> </property> </bean>
Modifier and Type | Method and Description |
---|---|
BinaryObject |
buildEnum(String typeName,
int ord)
Create enum object using value.
|
BinaryObject |
buildEnum(String typeName,
String name)
Create enum object using name.
|
BinaryObjectBuilder |
builder(BinaryObject binaryObj)
Creates binary builder initialized by existing binary object.
|
BinaryObjectBuilder |
builder(String typeName)
Creates new binary builder.
|
BinaryType |
registerClass(Class<?> cls)
Register binary type for specified class.
|
BinaryType |
registerEnum(String typeName,
Map<String,Integer> vals)
Register enum type.
|
void |
removeType(int typeId)
Remove (de-register) binary type with the specified id.
|
<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)
BinaryIdMapper
is configured
via BinaryConfiguration
, then system mapper will be used.typeName
- Type name.NullPointerException
- if typeName
is null
.<T> T toBinary(Object obj) throws BinaryObjectException
BinaryObject
.obj
- Object to convert (may be null
).null
if obj is null.BinaryObjectException
- In case of error.BinaryObjectBuilder builder(String typeName) throws BinaryObjectException
typeName
- Type name.BinaryObjectException
- In case of error.BinaryObjectBuilder builder(BinaryObject binaryObj) throws BinaryObjectException
binaryObj
- Binary object to initialize builder.BinaryObjectException
BinaryType 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) throws BinaryObjectException
typeName
- Type name.ord
- Ordinal.BinaryObjectException
- In case of error.BinaryObject buildEnum(String typeName, String name) throws BinaryObjectException
typeName
- Type name.name
- Name.BinaryObjectException
- In case of error.BinaryType registerEnum(String typeName, Map<String,Integer> vals) throws BinaryObjectException
typeName
- Type name.vals
- Mapping of enum constant names to ordinals.BinaryObjectException
- In case of error.BinaryType registerClass(Class<?> cls) throws BinaryObjectException
cls
- Class.BinaryObjectException
- In case of error.void removeType(int typeId) throws IgniteException
typeId
- Type id.IgniteException
- In case of error (type not found or already being removed).
GridGain In-Memory Computing Platform : ver. 8.9.11 Release Date : September 6 2024