Documentation ¶
Overview ¶
Package serialization contains serialization functions and types for Hazelcast Go client.
Serialization is the process of converting an object into a stream of bytes to store the object in the memory, a file or database, or transmit it through the network. Its main purpose is to save the state of an object in order to be able to recreate it when needed. The reverse process is called deserialization.
Hazelcast serializes all your objects before sending them to the server. The following table is the conversion of types for Java server side, which cannot be overriden by the user.
Go Java ============ ========= uint8 (byte) Byte bool Boolean uint16 Character int16 Short int32 Integer int64 Long int Long float32 Float float64 Double string String types.UUID UUID time.Time (See the table below) *big.Int java.util.BigInteger types.Decimal java.util.BigDecimal
Types of time.Time are converted to Java using the table below:
Go Java ============ ========= time.Time with year == 0 java.time.LocalTime time.Time with hours, minutes, secs, nanosecs == 0 java.time.localDate time.Time with location == time.Local java.time.LocalDateTime time.Time, otherwise java.time.OffsetDateTime
Slices of the types above are serialized as arrays in the Hazelcast server side and the Hazelcast Java client. Reference types are not supported for builtin types, e.g., *int64.
Hazelcast Go client supports several serializers apart from the builtin serializer for default types. They are Identified Data Serializer, Portable Serializer, JSON Serializer.
We will use the following type for all examples in this section:
const factoryID = 1 const employeeClassID = 1 type Employee struct { Surname string } func (e Employee) String() string { return fmt.Sprintf("Employe: %s", e.Surname) } // Common serialization methods func (e Employee) FactoryID() int32 { return factoryID } func (e Employee) ClassID() int32 { return employeeClassID }
Identified Data Serialization ¶
Hazelcast recommends implementing the Identified Data serialization for faster serialization of values. See https://docs.hazelcast.com/imdg/latest/serialization/implementing-dataserializable.html#identifieddataserializable for details.
In order to be able to serialize/deserialize a custom type using Identified Data serialization, the type has to implement the serialization.IdentifiedDataSerializable interface and a factory which creates values of that type. The same factory can be used to create values of all Identified Data Serializable types with the same factory ID.
Note that Identified Data Serializable factory returns a reference to the created value. Also, it is important to use a reference to the value with the Hazelcast Go client API, since otherwise the value wouldn't be implementing serialization.IdentifiedDataSerializable. That causes the value to be inadvertently serialized by the global serializer.
Here are functions that implement serialization.IdentifiedDataSerializable interface for Employee type. FactoryID and ClassID were defined before and they are also required:
func (e Employee) WriteData(output serialization.DataOutput) { output.WriteString(e.Surname) } func (e *Employee) ReadData(input serialization.DataInput) { e.Surname = input.ReadString() }
Here's an Identified Data Serializable factory that creates Employees:
type IdentifiedFactory struct{} func (f IdentifiedFactory) FactoryID() int32 { return factoryID } func (f IdentifiedFactory) Create(classID int32) serialization.IdentifiedDataSerializable { if classID == employeeClassID { return &Employee{} } // given classID was not found in the factory return nil }
In order to use the factory, you have to register it:
config := hazelcast.Config{} config.Serialization.SetIdentifiedDataSerializableFactories(&IdentifiedFactory{})
Portable Serialization ¶
Hazelcast offers portable serialization as an alternative to the existing serialization methods. Portable serialization has the following advantages: Supports multiple versions of the same object type, can fetch individual fields without having to rely on the reflection and supports querying and indexing without deserialization and/or reflection. In order to support these features, a serialized Portable object contains meta information like the version and concrete location of the each field in the binary data. This way Hazelcast is able to navigate in the binary data and deserialize only the required field without actually deserializing the whole object which improves the query performance.
You can have two members with each one having different versions of the same object by using multiversions. Hazelcast stores meta information and uses the correct one to serialize and deserialize portable objects depending on the member. That enables rolling upgrades without shutting down the cluster.
Also note that portable serialization is totally language independent and is used as the binary protocol between Hazelcast server and clients. See https://docs.hazelcast.com/imdg/latest/serialization/implementing-portable-serialization.html for details.
In order to be able to serialize/deserialize a custom type using Portable serialization, the type has to implement the serialization.Portable interface and a factory which creates values of that type. The same factory can be used to create values of all Portable types with the same factory ID.
Note that Portable factory returns a reference to the created value. Also, it is important to use a reference to the value with the Hazelcast Go client API, since otherwise the value wouldn't be implementing serialization.Portable. That causes the value to be inadvertently serialized by the global serializer.
Here are functions that implement serialization.Portable interface for Employee type:
func (e Employee) WritePortable(writer serialization.PortableWriter) { writer.WriteString("surname", e.Surname) } func (e *Employee) ReadPortable(reader serialization.PortableReader) { e.Surname = reader.ReadString("surname") }
Here's a Portable factory that creates Employees:
type PortableFactory struct{} func (p PortableFactory) FactoryID() int32 { return factoryID } func (f PortableFactory) Create(classID int32) serialization.Portable { if classID == employeeClassID { return &Employee{} } // given classID was not found in the factory return nil }
In order to use the factory, you have to register it:
config := hazelcast.Config{} config.Serialization.SetPortableFactories(&PortableFactory{})
JSON Serialization ¶
Hazelcast has first class support for JSON. You can put/get JSON values and use them in queries. See https://docs.hazelcast.com/imdg/latest/query/how-distributed-query-works.html#querying-json-strings for details.
The data type which is used during serializing/deserializing JSON data is serialization.JSON. It is in fact defined as []byte, but having a separate type helps the client to use the correct type ID when serializing/deserializing the value. Note that the client doesn't check the validity of serialized/deserialized JSON data.
In order to use JSON serialized data with Hazelcast Go client, you have to cast a byte array which contains JSON to `serialization.JSON`. You can use any JSON serializer to convert values to byte arrays, including json.Marshal in Go standard library. Here is an example:
employee := &Employee{Surname: "Schrute"} b, err := json.Marshal(employee) // mark the byte array as JSON, corresponds to HazelcastJsonValue jsonValue := serialization.JSON(b) // use jsonValue like any other value you can pass to Hazelcast err = myHazelcastMap.Set(ctx, "Dwight", jsonValue)
Deserializing JSON values retrieved from Hazelcast is also very easy. Just make sure the retrieved value is of type serialization.JSON.
v, err := myHazelcastMap.Get(ctx, "Angela") jsonValue, ok := v.(serialization.JSON) if !ok { panic("expected a JSON value") } otherEmployee := &Employee{} err = json.Unmarshal(jsonValue, &otherEmployee)
Custom Serialization ¶
Hazelcast lets you plug a custom serializer to be used for serialization of values. See https://docs.hazelcast.com/imdg/latest/serialization/custom-serialization.html for details.
In order to use a custom serializer for a type, the type should implement serialization.Serializer interface. Here is an example:
type EmployeeCustomSerializer struct{} func (e EmployeeCustomSerializer) ID() (id int32) { return 45392 } func (e EmployeeCustomSerializer) Read(input serialization.DataInput) interface{} { surname := input.ReadString() return &Employee{Surname: surname} } func (e EmployeeCustomSerializer) Write(output serialization.DataOutput, object interface{}) { employee, ok := object.(*Employee) if !ok { panic("can serialize only Employee") } output.WriteString(employee.Surname) }
You should register the serializer in the configuration with the corresponding type:
config := hazelcast.Config{} config.Serialization.SetCustomSerializer(reflect.TypeOf(&Employee{}), &EmployeeCustomSerializer{})
Global Serializer ¶
If a serializer cannot be found for a value, the global serializer is used. Values serialized by the global serializer are treated as blobs by Hazelcast, so using them for querying is not possible.
The default global serializer for Hazelcast Go client uses the Gob encoder: https://golang.org/pkg/encoding/gob/ Values serialized by the gob serializer cannot be used by Hazelcast clients in other languages.
You can change the global serializer by implementing the serialization.Serializer interface on a type:
type MyGlobalSerializer struct{} func (s MyGlobalSerializer) ID() int32 { return 123456 } func (s MyGlobalSerializer) Read(input serialization.DataInput) interface{} { surname := input.ReadString() return &Employee{Surname: surname} } func (s MyGlobalSerializer) Write(output serialization.DataOutput, object interface{}) { employee, ok := object.(*Employee) if !ok { panic("can serialize only Employee") } output.WriteString(employee.Surname) }
And setting it in the serialization configuration:
config := hazelcast.Config{} config.Serialization.SetGlobalSerializer(&MyGlobalSerializer{})
Index ¶
- type ClassDefinition
- func (cd *ClassDefinition) AddBoolArrayField(fieldName string) error
- func (cd *ClassDefinition) AddBoolField(fieldName string) error
- func (cd *ClassDefinition) AddByteArrayField(fieldName string) error
- func (cd *ClassDefinition) AddByteField(fieldName string) error
- func (cd *ClassDefinition) AddDateArrayField(fieldName string) error
- func (cd *ClassDefinition) AddDateField(fieldName string) error
- func (cd *ClassDefinition) AddDecimalArrayField(fieldName string) error
- func (cd *ClassDefinition) AddDecimalField(fieldName string) error
- func (cd *ClassDefinition) AddField(definition FieldDefinition) error
- func (cd *ClassDefinition) AddFloat32ArrayField(fieldName string) error
- func (cd *ClassDefinition) AddFloat32Field(fieldName string) error
- func (cd *ClassDefinition) AddFloat64ArrayField(fieldName string) error
- func (cd *ClassDefinition) AddFloat64Field(fieldName string) error
- func (cd *ClassDefinition) AddInt16ArrayField(fieldName string) error
- func (cd *ClassDefinition) AddInt16Field(fieldName string) error
- func (cd *ClassDefinition) AddInt32ArrayField(fieldName string) error
- func (cd *ClassDefinition) AddInt32Field(fieldName string) error
- func (cd *ClassDefinition) AddInt64ArrayField(fieldName string) error
- func (cd *ClassDefinition) AddInt64Field(fieldName string) error
- func (cd *ClassDefinition) AddPortableArrayField(fieldName string, def *ClassDefinition) error
- func (cd *ClassDefinition) AddPortableField(fieldName string, def *ClassDefinition) error
- func (cd *ClassDefinition) AddStringArrayField(fieldName string) error
- func (cd *ClassDefinition) AddStringField(fieldName string) error
- func (cd *ClassDefinition) AddTimeArrayField(fieldName string) error
- func (cd *ClassDefinition) AddTimeField(fieldName string) error
- func (cd *ClassDefinition) AddTimestampArrayField(fieldName string) error
- func (cd *ClassDefinition) AddTimestampField(fieldName string) error
- func (cd *ClassDefinition) AddTimestampWithTimezoneArrayField(fieldName string) error
- func (cd *ClassDefinition) AddTimestampWithTimezoneField(fieldName string) error
- func (cd *ClassDefinition) AddUInt16ArrayField(fieldName string) error
- func (cd *ClassDefinition) AddUInt16Field(fieldName string) error
- type Config
- func (b *Config) ClassDefinitions() []*ClassDefinition
- func (c *Config) Clone() Config
- func (b *Config) CustomSerializers() map[reflect.Type]Serializer
- func (b *Config) GlobalSerializer() Serializer
- func (b *Config) IdentifiedDataSerializableFactories() []IdentifiedDataSerializableFactory
- func (b *Config) PortableFactories() []PortableFactory
- func (b *Config) SetClassDefinitions(definitions ...*ClassDefinition)
- func (b *Config) SetCustomSerializer(t reflect.Type, serializer Serializer) error
- func (b *Config) SetGlobalSerializer(serializer Serializer)
- func (b *Config) SetIdentifiedDataSerializableFactories(factories ...IdentifiedDataSerializableFactory)
- func (b *Config) SetPortableFactories(factories ...PortableFactory)
- func (c *Config) Validate() error
- type DataInput
- type DataOutput
- type FieldDefinition
- type FieldDefinitionType
- type IdentifiedDataSerializable
- type IdentifiedDataSerializableFactory
- type JSON
- type Portable
- type PortableFactory
- type PortableReader
- type PortableWriter
- type Serializer
- type VersionedPortable
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ClassDefinition ¶
type ClassDefinition struct { Fields map[string]FieldDefinition FactoryID int32 ClassID int32 Version int32 }
ClassDefinition defines a class schema for Portable structs.
func NewClassDefinition ¶ added in v1.0.0
func NewClassDefinition(factoryID int32, classID int32, version int32) *ClassDefinition
func (*ClassDefinition) AddBoolArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddBoolArrayField(fieldName string) error
func (*ClassDefinition) AddBoolField ¶ added in v1.0.0
func (cd *ClassDefinition) AddBoolField(fieldName string) error
func (*ClassDefinition) AddByteArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddByteArrayField(fieldName string) error
func (*ClassDefinition) AddByteField ¶ added in v1.0.0
func (cd *ClassDefinition) AddByteField(fieldName string) error
func (*ClassDefinition) AddDateArrayField ¶ added in v1.2.0
func (cd *ClassDefinition) AddDateArrayField(fieldName string) error
func (*ClassDefinition) AddDateField ¶ added in v1.2.0
func (cd *ClassDefinition) AddDateField(fieldName string) error
func (*ClassDefinition) AddDecimalArrayField ¶ added in v1.2.0
func (cd *ClassDefinition) AddDecimalArrayField(fieldName string) error
func (*ClassDefinition) AddDecimalField ¶ added in v1.2.0
func (cd *ClassDefinition) AddDecimalField(fieldName string) error
func (*ClassDefinition) AddField ¶ added in v1.0.0
func (cd *ClassDefinition) AddField(definition FieldDefinition) error
func (*ClassDefinition) AddFloat32ArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddFloat32ArrayField(fieldName string) error
func (*ClassDefinition) AddFloat32Field ¶ added in v1.0.0
func (cd *ClassDefinition) AddFloat32Field(fieldName string) error
func (*ClassDefinition) AddFloat64ArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddFloat64ArrayField(fieldName string) error
func (*ClassDefinition) AddFloat64Field ¶ added in v1.0.0
func (cd *ClassDefinition) AddFloat64Field(fieldName string) error
func (*ClassDefinition) AddInt16ArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddInt16ArrayField(fieldName string) error
func (*ClassDefinition) AddInt16Field ¶ added in v1.0.0
func (cd *ClassDefinition) AddInt16Field(fieldName string) error
func (*ClassDefinition) AddInt32ArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddInt32ArrayField(fieldName string) error
func (*ClassDefinition) AddInt32Field ¶ added in v1.0.0
func (cd *ClassDefinition) AddInt32Field(fieldName string) error
func (*ClassDefinition) AddInt64ArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddInt64ArrayField(fieldName string) error
func (*ClassDefinition) AddInt64Field ¶ added in v1.0.0
func (cd *ClassDefinition) AddInt64Field(fieldName string) error
func (*ClassDefinition) AddPortableArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddPortableArrayField(fieldName string, def *ClassDefinition) error
func (*ClassDefinition) AddPortableField ¶ added in v1.0.0
func (cd *ClassDefinition) AddPortableField(fieldName string, def *ClassDefinition) error
func (*ClassDefinition) AddStringArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddStringArrayField(fieldName string) error
func (*ClassDefinition) AddStringField ¶ added in v1.0.0
func (cd *ClassDefinition) AddStringField(fieldName string) error
func (*ClassDefinition) AddTimeArrayField ¶ added in v1.2.0
func (cd *ClassDefinition) AddTimeArrayField(fieldName string) error
func (*ClassDefinition) AddTimeField ¶ added in v1.2.0
func (cd *ClassDefinition) AddTimeField(fieldName string) error
func (*ClassDefinition) AddTimestampArrayField ¶ added in v1.2.0
func (cd *ClassDefinition) AddTimestampArrayField(fieldName string) error
func (*ClassDefinition) AddTimestampField ¶ added in v1.2.0
func (cd *ClassDefinition) AddTimestampField(fieldName string) error
func (*ClassDefinition) AddTimestampWithTimezoneArrayField ¶ added in v1.2.0
func (cd *ClassDefinition) AddTimestampWithTimezoneArrayField(fieldName string) error
func (*ClassDefinition) AddTimestampWithTimezoneField ¶ added in v1.2.0
func (cd *ClassDefinition) AddTimestampWithTimezoneField(fieldName string) error
func (*ClassDefinition) AddUInt16ArrayField ¶ added in v1.0.0
func (cd *ClassDefinition) AddUInt16ArrayField(fieldName string) error
func (*ClassDefinition) AddUInt16Field ¶ added in v1.0.0
func (cd *ClassDefinition) AddUInt16Field(fieldName string) error
type Config ¶
type Config struct { // PortableVersion will be used to differentiate two versions of the same struct that have changes on the struct, // like adding/removing a field or changing a type of a field. PortableVersion int32 `json:",omitempty"` // LittleEndian sets byte order to Little Endian. Default is false. LittleEndian bool `json:",omitempty"` // contains filtered or unexported fields }
Config contains the serialization configuration of a Hazelcast instance.
func (*Config) ClassDefinitions ¶
func (b *Config) ClassDefinitions() []*ClassDefinition
ClassDefinitions returns a copy of class definitions. class definitions contains classDefinitions for portable structs.
func (*Config) CustomSerializers ¶
func (b *Config) CustomSerializers() map[reflect.Type]Serializer
CustomSerializers returns a copy of custom serializers. custom serializers is a map of object types and corresponding custom serializers.
func (*Config) GlobalSerializer ¶
func (b *Config) GlobalSerializer() Serializer
GlobalSerializer returns the global serializer. Global serializer is the serializer that will be used if no other serializer is applicable.
func (*Config) IdentifiedDataSerializableFactories ¶ added in v1.0.0
func (b *Config) IdentifiedDataSerializableFactories() []IdentifiedDataSerializableFactory
IdentifiedDataSerializableFactories returns a copy of identified data serializable factories. Identified data serializable factories is a map of factory IDs and corresponding IdentifiedDataSerializable factories.
func (*Config) PortableFactories ¶
func (b *Config) PortableFactories() []PortableFactory
PortableFactories returns a copy of portable factories portable factories is a map of factory IDs and corresponding Portable factories.
func (*Config) SetClassDefinitions ¶ added in v1.0.0
func (b *Config) SetClassDefinitions(definitions ...*ClassDefinition)
SetClassDefinitions adds zore or more class definitions for portable factories.
func (*Config) SetCustomSerializer ¶ added in v1.0.0
func (b *Config) SetCustomSerializer(t reflect.Type, serializer Serializer) error
SetCustomSerializer adds a customer serializer for the given type. custom serializers is a map of object types and corresponding custom serializers.
Example ¶
package main import ( "context" "fmt" "log" "reflect" "github.com/hazelcast/hazelcast-go-client" "github.com/hazelcast/hazelcast-go-client/serialization" ) type Employee struct { Surname string } type EmployeeCustomSerializer struct{} func (e EmployeeCustomSerializer) ID() int32 { return 45392 } func (e EmployeeCustomSerializer) Read(input serialization.DataInput) interface{} { surname := input.ReadString() return &Employee{Surname: surname} } func (e EmployeeCustomSerializer) Write(output serialization.DataOutput, object interface{}) { employee, ok := object.(*Employee) if !ok { panic("can serialize only Employee") } output.WriteString(employee.Surname) } func main() { // Configure serializer config := hazelcast.NewConfig() config.Serialization.SetCustomSerializer(reflect.TypeOf(&Employee{}), &EmployeeCustomSerializer{}) // Start the client with custom serializer ctx := context.TODO() client, err := hazelcast.StartNewClientWithConfig(ctx, config) if err != nil { log.Fatal(err) } // Get a random map m, err := client.GetMap(ctx, "map-1") if err != nil { log.Fatal(err) } // Store an object in the map _, err = m.Put(ctx, "employee-1", Employee{"Doe"}) if err != nil { log.Fatal(err) } // Retrieve the object and print value, err := m.Get(ctx, "employee-1") if err != nil { log.Fatal(err) } fmt.Println("Surname of stored employee:", value.(Employee).Surname) // Shutdown client client.Shutdown(ctx) }
Output:
func (*Config) SetGlobalSerializer ¶
func (b *Config) SetGlobalSerializer(serializer Serializer)
SetGlobalSerializer sets the global serializer. Global serializer is the serializer that will be used if no other serializer is applicable.
func (*Config) SetIdentifiedDataSerializableFactories ¶ added in v1.0.0
func (b *Config) SetIdentifiedDataSerializableFactories(factories ...IdentifiedDataSerializableFactory)
SetIdentifiedDataSerializableFactories adds zore or more identified data serializable factories. Identified data serializable factories is a map of factory IDs and corresponding IdentifiedDataSerializable factories.
func (*Config) SetPortableFactories ¶ added in v1.0.0
func (b *Config) SetPortableFactories(factories ...PortableFactory)
SetPortableFactories adds zero or more portable factories. Portable factories is a map of factory IDs and corresponding Portable factories.
Example ¶
package main import ( "context" "fmt" "log" "time" "github.com/hazelcast/hazelcast-go-client" "github.com/hazelcast/hazelcast-go-client/serialization" ) const ( factoryID = 1 employeeClassID = 1 baseObjectClassID = 2 ) type EmployeePortable struct { Name string Age int32 } func (e EmployeePortable) FactoryID() int32 { return factoryID } func (e EmployeePortable) ClassID() int32 { return employeeClassID } func (e EmployeePortable) WritePortable(writer serialization.PortableWriter) { writer.WriteString("name", e.Name) writer.WriteInt32("age", e.Age) } func (e *EmployeePortable) ReadPortable(reader serialization.PortableReader) { e.Name = reader.ReadString("name") e.Age = reader.ReadInt32("age") } type MyPortableFactory struct { } func (m MyPortableFactory) Create(classID int32) serialization.Portable { if classID == employeeClassID { return &EmployeePortable{} } if classID == baseObjectClassID { return &BaseObject{} } return nil } func (m MyPortableFactory) FactoryID() int32 { return factoryID } type BaseObject struct { Employee *EmployeePortable } func (b BaseObject) FactoryID() int32 { return factoryID } func (b BaseObject) ClassID() int32 { return 2 } func (b BaseObject) WritePortable(writer serialization.PortableWriter) { if b.Employee == nil { writer.WriteNilPortable("employee", factoryID, employeeClassID) return } writer.WritePortable("employee", b.Employee) } func (b *BaseObject) ReadPortable(reader serialization.PortableReader) { b.Employee = reader.ReadPortable("employee").(*EmployeePortable) } func main() { // create the configuration config := hazelcast.NewConfig() config.Serialization.PortableVersion = 1 config.Serialization.SetPortableFactories(&MyPortableFactory{}) employeeCD := serialization.NewClassDefinition(factoryID, employeeClassID, 1) employeeCD.AddStringField("name") employeeCD.AddInt32Field("age") baseObjectCD := serialization.NewClassDefinition(factoryID, baseObjectClassID, 1) baseObjectCD.AddPortableField("employee", employeeCD) config.Serialization.SetClassDefinitions(employeeCD, baseObjectCD) // start the client with the given configuration ctx := context.TODO() client, err := hazelcast.StartNewClientWithConfig(ctx, config) if err != nil { log.Fatal(err) } // retrieve a map m, err := client.GetMap(ctx, "example") if err != nil { log.Fatal(err) } // set / get portable serialized value employee := &EmployeePortable{Name: "Jane Doe", Age: 30} if err := m.Set(ctx, "employee", employee); err != nil { log.Fatal(err) } if v, err := m.Get(ctx, "employee"); err != nil { log.Fatal(err) } else { fmt.Println(v) } // set / get portable serialized nullable value baseObj := &BaseObject{Employee: employee} if err := m.Set(ctx, "base-obj", baseObj); err != nil { log.Fatal(err) } if v, err := m.Get(ctx, "base-obj"); err != nil { log.Fatal(err) } else { fmt.Println(v) } // stop the client time.Sleep(1 * time.Second) client.Shutdown(ctx) }
Output:
type DataInput ¶
type DataInput interface { // Position returns the head position in the byte array. Position() int32 // SetPosition sets the head position in the byte array. SetPosition(pos int32) // ReadByte returns byte read . // It returns zero if an error is set previously. ReadByte() byte // ReadBool returns bool read. // It returns false if an error is set previously. ReadBool() bool // ReadUInt16 returns uint16 read. // It returns zero if an error is set previously. ReadUInt16() uint16 // ReadInt16 returns int16 read. // It returns zero if an error is set previously. ReadInt16() int16 // ReadInt32 returns int32 read. // It returns zero if an error is set previously. ReadInt32() int32 // ReadInt64 returns int64 read. // It returns zero if an error is set previously. ReadInt64() int64 // ReadFloat32 returns float32 read. // It returns zero if an error is set previously. ReadFloat32() float32 // ReadFloat64 returns float64 read. // It returns zero if an error is set previously. ReadFloat64() float64 // ReadString returns string read. // It returns empty string if an error is set previously. ReadString() string // ReadObject returns object read. // It returns nil if an error is set previously. ReadObject() interface{} // ReadByteArray returns []byte read. // It returns nil if an error is set previously. ReadByteArray() []byte // ReadBoolArray returns []bool read. // It returns nil if an error is set previously. ReadBoolArray() []bool // ReadUInt16Array returns []uint16 read. // It returns nil if an error is set previously. ReadUInt16Array() []uint16 // ReadInt16Array returns []int16 read. // It returns nil if an error is set previously. ReadInt16Array() []int16 // ReadInt32Array returns []int32 read. // It returns nil if an error is set previously. ReadInt32Array() []int32 // ReadInt64Array returns []int64 read. // It returns nil if an error is set previously. ReadInt64Array() []int64 // ReadFloat32Array returns []float32 read. // It returns nil if an error is set previously. ReadFloat32Array() []float32 // ReadFloat64Array returns []float64 read. // It returns nil if an error is set previously. ReadFloat64Array() []float64 // ReadStringArray returns []string read. // It returns nil if an error is set previously. ReadStringArray() []string }
DataInput provides deserialization methods. If any of the methods results in an error, all following methods will return the zero value for that type immediately. Example usage:
field1 = input.ReadString() field2 = input.ReadString()
type DataOutput ¶
type DataOutput interface { // Position returns the head position in the byte array. Position() int32 // SetPosition sets the head position in the byte array. SetPosition(pos int32) // WriteByte writes a byte. WriteByte(v byte) // WriteBool writes a bool. WriteBool(v bool) // WriteUInt16 writes an uint16. WriteUInt16(v uint16) // WriteInt16 writes an int16. WriteInt16(v int16) // WriteInt32 writes an int32. WriteInt32(v int32) // WriteInt64 writes an int64. WriteInt64(v int64) // WriteFloat32 writes a float32. WriteFloat32(v float32) // WriteFloat64 writes a float64. WriteFloat64(v float64) // WriteString writes a string in UTF-8 format. WriteString(v string) // WriteObject writes an object. WriteObject(i interface{}) // WriteByteArray writes a []byte. WriteByteArray(v []byte) // WriteBoolArray writes a []bool. WriteBoolArray(v []bool) // WriteUInt16Array writes an []uint16. WriteUInt16Array(v []uint16) // WriteInt16Array writes an []int16. WriteInt16Array(v []int16) // WriteInt32Array writes an []int32. WriteInt32Array(v []int32) // WriteInt64Array writes an []int64. WriteInt64Array(v []int64) // WriteFloat32Array writes a []float32. WriteFloat32Array(v []float32) // WriteFloat64Array writes a []float64. WriteFloat64Array(v []float64) // WriteStringArray writes a []string in UTF-8 format. WriteStringArray(v []string) // WriteStringBytes writes a string's characters. WriteStringBytes(bytes string) // WriteZeroBytes writes zero bytes as given length. WriteZeroBytes(count int) }
DataOutput provides serialization methods.
type FieldDefinition ¶
type FieldDefinition struct { Name string Index int32 Type FieldDefinitionType FactoryID int32 ClassID int32 Version int32 }
FieldDefinition defines name, type, index of a field.
type FieldDefinitionType ¶ added in v1.0.0
type FieldDefinitionType int32
const ( TypePortable FieldDefinitionType = 0 TypeByte FieldDefinitionType = 1 TypeBool FieldDefinitionType = 2 TypeUint16 FieldDefinitionType = 3 TypeInt16 FieldDefinitionType = 4 TypeInt32 FieldDefinitionType = 5 TypeInt64 FieldDefinitionType = 6 TypeFloat32 FieldDefinitionType = 7 TypeFloat64 FieldDefinitionType = 8 TypeString FieldDefinitionType = 9 TypePortableArray FieldDefinitionType = 10 TypeByteArray FieldDefinitionType = 11 TypeBoolArray FieldDefinitionType = 12 TypeUInt16Array FieldDefinitionType = 13 TypeInt16Array FieldDefinitionType = 14 TypeInt32Array FieldDefinitionType = 15 TypeInt64Array FieldDefinitionType = 16 TypeFloat32Array FieldDefinitionType = 17 TypeFloat64Array FieldDefinitionType = 18 TypeStringArray FieldDefinitionType = 19 TypeDecimal FieldDefinitionType = 20 TypeDecimalArray FieldDefinitionType = 21 TypeTime FieldDefinitionType = 22 TypeTimeArray FieldDefinitionType = 23 TypeDate FieldDefinitionType = 24 TypeDateArray FieldDefinitionType = 25 TypeTimestamp FieldDefinitionType = 26 TypeTimestampArray FieldDefinitionType = 27 TypeTimestampWithTimezone FieldDefinitionType = 28 TypeTimestampWithTimezoneArray FieldDefinitionType = 29 )
type IdentifiedDataSerializable ¶
type IdentifiedDataSerializable interface { // FactoryID returns IdentifiedDataSerializableFactory factory ID for this struct. FactoryID() int32 // ClassID returns type identifier for this struct. It should be unique per IdentifiedDataSerializableFactory. ClassID() int32 // WriteData writes object fields to output stream. WriteData(output DataOutput) // ReadData reads fields from the input stream. ReadData(input DataInput) }
IdentifiedDataSerializable is a serialization method as an alternative to standard Gob serialization. Each IdentifiedDataSerializable is created by a registered IdentifiedDataSerializableFactory.
type IdentifiedDataSerializableFactory ¶
type IdentifiedDataSerializableFactory interface { // Create ceates an IdentifiedDataSerializable instance using given type ID. Create(id int32) IdentifiedDataSerializable // FactoryID returns the factory ID. FactoryID() int32 }
IdentifiedDataSerializableFactory is used to create IdentifiedDataSerializable instances during deserialization.
type JSON ¶ added in v1.0.0
type JSON []byte
func (JSON) MarshalJSON ¶ added in v1.1.0
MarshalJSON is used by functions in the Go `encoding/json` package. This function ensures that a `serialization.JSON` value is correctly serialized by this package. This is mostly applicable when `serialization.JSON` is serialized as a field of a larger struct.
func (*JSON) UnmarshalJSON ¶ added in v1.1.0
UnmarshalJSON is used by functions in the Go `encoding/json` package. This function ensures that a `serialization.JSON` value is correctly deserialized from JSON objects that contain a field of this type.
type Portable ¶
type Portable interface { // FactoryID returns PortableFactory ID for this portable struct. FactoryID() int32 // ClassID returns type identifier for this portable struct. Class ID should be unique per PortableFactory. ClassID() int32 // WritePortable serializes this portable object using PortableWriter. WritePortable(writer PortableWriter) // ReadPortable reads portable fields using PortableReader. ReadPortable(reader PortableReader) }
Portable provides an alternative serialization method. Instead of relying on reflection, each Portable is created by a registered PortableFactory. Portable serialization has the following advantages: * Supporting multiversion of the same object type. * Fetching individual fields without having to rely on reflection. * Querying and indexing support without deserialization and/or reflection.
type PortableFactory ¶
type PortableFactory interface { // Create creates a Portable instance using given class ID and // returns portable instance or nil if class ID is not known by this factory. Create(classID int32) Portable // FactoryID returns the factory ID. FactoryID() int32 }
PortableFactory is used to create Portable instances during deserialization.
type PortableReader ¶
type PortableReader interface { // ReadByte takes fieldName Name of the field and returns the byte value read. // It returns zero if an error is set previously. ReadByte(fieldName string) byte // ReadBool takes fieldName Name of the field and returns the bool value read. // It returns false if an error is set previously. ReadBool(fieldName string) bool // ReadUInt16 takes fieldName Name of the field and returns the uint16 value read. // It returns zero if an error is set previously. ReadUInt16(fieldName string) uint16 // ReadInt16 takes fieldName Name of the field and returns the int16 value read. // It returns zero if an error is set previously. ReadInt16(fieldName string) int16 // ReadInt32 takes fieldName Name of the field and returns the int32 value read. // It returns zero if an error is set previously. ReadInt32(fieldName string) int32 // ReadInt64 takes fieldName Name of the field and returns the int64 value read. // It returns zero if an error is set previously. ReadInt64(fieldName string) int64 // ReadFloat32 takes fieldName Name of the field and returns the float32 value read. // It returns zero if an error is set previously. ReadFloat32(fieldName string) float32 // ReadFloat64 takes fieldName Name of the field and returns the float64 value read. // It returns zero if an error is set previously. ReadFloat64(fieldName string) float64 // ReadString takes fieldName Name of the field and returns the string value read. // It returns empty string if an error is set previously. ReadString(fieldName string) string // ReadPortable takes fieldName Name of the field and returns the Portable value read. // It returns nil if an error is set previously. ReadPortable(fieldName string) Portable // ReadByteArray takes fieldName Name of the field and returns the []byte value read. // It returns nil if an error is set previously. ReadByteArray(fieldName string) []byte // ReadBoolArray takes fieldName Name of the field and returns the []bool value read. // It returns nil if an error is set previously. ReadBoolArray(fieldName string) []bool // ReadUInt16Array takes fieldName Name of the field and returns the []uint16 value read. // It returns nil if an error is set previously. ReadUInt16Array(fieldName string) []uint16 // ReadInt16Array takes fieldName Name of the field and returns the []int16 value read. // It returns nil if an error is set previously. ReadInt16Array(fieldName string) []int16 // ReadInt32Array takes fieldName Name of the field and returns the []int32 value read. // It returns nil if an error is set previously. ReadInt32Array(fieldName string) []int32 // ReadInt64Array takes fieldName Name of the field and returns the []int64 value read. // It returns nil if an error is set previously. ReadInt64Array(fieldName string) []int64 // ReadFloat32Array takes fieldName Name of the field and returns the []float32 value read. // It returns nil if an error is set previously. ReadFloat32Array(fieldName string) []float32 // ReadFloat64Array takes fieldName Name of the field and returns the []float64 value read. // It returns nil if an error is set previously. ReadFloat64Array(fieldName string) []float64 // ReadStringArray takes fieldName Name of the field and returns the []string value read. // It returns nil if an error is set previously. ReadStringArray(fieldName string) []string // ReadPortableArray takes fieldName Name of the field and returns the []Portable value read. // It returns nil if an error is set previously. ReadPortableArray(fieldName string) []Portable // GetRawDataInput returns raw DataInput to read unnamed fields like // IdentifiedDataSerializable does. All unnamed fields must be read after // portable fields. Attempts to read named fields after GetRawDataInput is // called will panic. GetRawDataInput() DataInput // ReadDate reads the date. // It may return nil. ReadDate(fieldName string) *types.LocalDate // ReadTime reads the time. // It may return nil. ReadTime(fieldName string) *types.LocalTime // ReadTimestamp reads the time stamp. // It may return nil. ReadTimestamp(fieldName string) *types.LocalDateTime // ReadTimestampWithTimezone reads the time stamp with time zone. // It may return nil. ReadTimestampWithTimezone(fieldName string) *types.OffsetDateTime // ReadDateArray reads the date array. ReadDateArray(fieldName string) []types.LocalDate // ReadTimeArray reads the time array. ReadTimeArray(fieldName string) []types.LocalTime // ReadTimestampArray reads the time stamp array. ReadTimestampArray(fieldName string) []types.LocalDateTime // ReadTimestampWithTimezoneArray reads the time stamp with time zone array. ReadTimestampWithTimezoneArray(fieldName string) []types.OffsetDateTime // ReadDecimal reads a decimal. // It may return nil. ReadDecimal(fieldName string) (d *types.Decimal) // ReadDecimalArray a decimal array. ReadDecimalArray(fieldName string) (ds []types.Decimal) }
PortableReader provides a mean of reading portable fields from a binary in form of go primitives arrays of go primitives, nested portable fields and array of portable fields. Example usage:
s.id = reader.ReadInt16("id") s.age = reader.ReadInt32("age") return reader.Error()
type PortableWriter ¶
type PortableWriter interface { // WriteByte writes a byte with fieldName. WriteByte(fieldName string, value byte) // WriteBool writes a bool with fieldName. WriteBool(fieldName string, value bool) // WriteUInt16 writes a uint16 with fieldName. WriteUInt16(fieldName string, value uint16) // WriteInt16 writes a int16 with fieldName. WriteInt16(fieldName string, value int16) // WriteInt32 writes a int32 with fieldName. WriteInt32(fieldName string, value int32) // WriteInt64 writes a int64 with fieldName. WriteInt64(fieldName string, value int64) // WriteFloat32 writes a float32 with fieldName. WriteFloat32(fieldName string, value float32) // WriteFloat64 writes a float64 with fieldName. WriteFloat64(fieldName string, value float64) // WriteString writes a string in UTF-8 format with fieldName. WriteString(fieldName string, value string) // WritePortable writes a Portable with fieldName. WritePortable(fieldName string, value Portable) // WriteNilPortable writes a NilPortable with fieldName, factoryID and classID. WriteNilPortable(fieldName string, factoryID int32, classID int32) // WriteByteArray writes a []byte with fieldName. WriteByteArray(fieldName string, value []byte) // WriteBoolArray writes a []bool with fieldName. WriteBoolArray(fieldName string, value []bool) // WriteUInt16Array writes a []uint16 with fieldName. WriteUInt16Array(fieldName string, value []uint16) // WriteInt16Array writes a []int16 with fieldName. WriteInt16Array(fieldName string, value []int16) // WriteInt32Array writes a []int32 with fieldName. WriteInt32Array(fieldName string, value []int32) // WriteInt64Array writes a []int64 with fieldName. WriteInt64Array(fieldName string, value []int64) // WriteFloat32Array writes a []float32 with fieldName. WriteFloat32Array(fieldName string, value []float32) // WriteFloat64Array writes a []float64 with fieldName. WriteFloat64Array(fieldName string, value []float64) // WriteStringArray writes a []string in UTF-8 format with fieldName. WriteStringArray(fieldName string, value []string) // WritePortableArray writes a []Portable with fieldName. WritePortableArray(fieldName string, value []Portable) // GetRawDataOutput returns raw DataOutput to write unnamed fields like IdentifiedDataSerializable does. // All unnamed fields must be written after portable fields. // Attempts to write named fields after GetRawDataOutput is called will panic. GetRawDataOutput() DataOutput // WriteDate writes a date. WriteDate(fieldName string, t *types.LocalDate) // WriteTime writes a time. WriteTime(fieldName string, t *types.LocalTime) // WriteTimestamp writes the date and time without the timezone offset. WriteTimestamp(fieldName string, t *types.LocalDateTime) // WriteTimestampWithTimezone writes the date and time with the timezone offset. WriteTimestampWithTimezone(fieldName string, t *types.OffsetDateTime) // WriteDateArray writes a date array. WriteDateArray(fieldName string, t []types.LocalDate) // WriteTimeArray writes a time array. WriteTimeArray(fieldName string, t []types.LocalTime) // WriteTimestampArray writes a timestamp array. WriteTimestampArray(fieldName string, t []types.LocalDateTime) // WriteTimestampWithTimezoneArray writes a timestamp with timezone array. WriteTimestampWithTimezoneArray(fieldName string, t []types.OffsetDateTime) // WriteDecimal writes the given decimal value. // The decimal value may be nil. WriteDecimal(fieldName string, d *types.Decimal) // WriteDecimalArray writes the given decimal array. WriteDecimalArray(fieldName string, ds []types.Decimal) }
PortableWriter provides a mean of writing portable fields to a binary in form of go primitives arrays of go primitives, nested portable fields and array of portable fields.
type Serializer ¶
type Serializer interface { // ID returns id of serializer. ID() int32 // Read reads an object from ObjectDataInput. Read(input DataInput) interface{} // Write writes an object to ObjectDataOutput. Write(output DataOutput, object interface{}) }
Serializer is base interface of serializers.
type VersionedPortable ¶
type VersionedPortable interface { Portable // Version returns version for this Portable struct. Version() int32 }
VersionedPortable is an extension to Portable to support per class version instead of a global serialization version.