serialization

package
v1.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 7, 2024 License: Apache-2.0 Imports: 6 Imported by: 56

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 Compact Serializer, Identified Data Serializer, Portable Serializer, JSON Serializer.

We will use the following type for all examples in this section: 

type Employee struct {
	Surname string
}

Compact Serialization

Compact serialization has the following main features:

  • Separates the schema from the data and stores it per type, not per object. This approach results in less memory and bandwidth usage compared to other formats.
  • Does not require a class to implement an interface or change the source code of the class in any way.
  • Supports schema evolution which permits adding or removing fields, or changing the types of fields.
  • Platform and language independent.
  • Supports partial deserialization of fields during queries or indexing.

Hazelcast achieves these features by having well-known schemas of objects and replicating them across the cluster. That approach enables members and clients to fetch schemas they don't have in their local registries. Each serialized object carries just a schema identifier and relies on the schema distribution service or configuration to match identifiers with the actual schema. Once the schemas are fetched, they are cached locally on the members and clients so that the next operations that use the schema do not incur extra costs.

Schemas help Hazelcast to identify the locations of the fields on the serialized binary data. With this information, Hazelcast can deserialize individual fields of the data, without deserializing the whole binary. This results in a better query and indexing performance.

Schemas can evolve freely by adding or removing fields. Even the types of the fields can be changed. Multiple versions of the schema may live in the same cluster and both the old and new readers may read the compatible parts of the data. This feature is especially useful in rolling upgrade scenarios.

The Compact serialization does not require any changes in the user classes as it doesn't need a class to implement a particular interface. Serializers might be implemented and registered separately from the classes.

The underlying format of the Compact serialized objects is platform and language independent.

NOTE: Compact serialization is promoted to the stable status in the 5.2 Hazelcast release. Hazelcast Go Client can use compact serialization only with Hazelcast version 5.2 and higher.

In order to implement a compact serializer, serialization.CompactSerializer interface must be implemented. The interface consists of four methods:

  • Type: Returns the type that the serializer works on.
  • TypeName: Choosing a type name will associate that name with the schema and will make the polyglot use cases, where there are multiple clients from different languages, possible. Serializers in different languages can work on the same data, provided that their read and write methods are compatible, and they have the same type name. If you evolve your class in the later versions of your application, by adding or removing fields, you should continue using the same type name for that class.
  • Read: Creates a value of the target type using by reading from a serialization.CompactReader.
  • Write: Writes the value by writing to a serialization.CompactWriter.

Here is how a compact serializer for the Employee type may be written: 

type EmployeeSerializer struct{}

func (s EmployeeSerializer) Type() reflect.Type {
	return reflect.TypeOf(Employee{})
}

func (s EmployeeSerializer) TypeName() string {
	return "Employee"
}

func (s EmployeeSerializer) Read(r serialization.CompactReader) interface{} {
	return Employee{
		Surname: r.ReadString("surname")
	}
}

func (s SampleCompactSerializer) Write(w serialization.CompactWriter, value interface{}) {
	v := value.(Employee)
	w.WriteString("surname", v.Surname)
}

Once the necessary methods are implemented, the serializer should be registered: 

var cfg hazelcast.Config
cfg.Serialization.Compact.SetSerializers(&EmployeeSerializer{})

The table of supported types in compact serialization and their Java counterparts is below: 

Go                        Java
============              =========
bool                      boolean
[]bool                    boolean[]
*bool                     Boolean
[]*bool                   Boolean[]
int8                      byte
[]int8                    byte[]
*int8                     Byte
[]*int8                   Byte[]
int16                     short
[]int16                   short[]
*int16                    Short
[]*int16                  Short[]
int32                     int
[]int32                   int[]
*int32                    Integer
[]*int32                  Integer[]
int64                     long
[]int64                   long[]
*int64                    Long
[]*int64                  Long[]
float32                   float
[]float32                 float32[]
*float32                  Float
[]*float32                Float[]
float64                   double
[]float64                 double[]
*float64                  Double
[]*float64                Double[]
*string                   String
[]*string                 String[]
*types.Decimal            BigDecimal
[]*types.Decimal          BigDecimal[]
*types.LocalTime          LocalTime
[]*types.LocalTime        LocalTime[]
*types.LocalDate          LocalDate
[]*types.LocalDate        LocalDate[]
*types.LocalDateTime      LocalDateTime
[]*types.LocalDateTime    LocalDateTime[]
*types.OffsetDateTime     OffsetDateTime
[]*types.OffsetDateTime   OffsetDateTime[]

See https://docs.hazelcast.com/hazelcast/latest/serialization/compact-serialization#supported-types for more information.

Compact serialized objects can be used in SQL statements, provided that mappings are created, similar to other serialization formats.

Schema Evolution

Compact serialization permits schemas and classes to evolve by adding or removing fields, or by changing the types of fields. More than one version of a class may live in the same cluster and different clients or members might use different versions of the class.

Hazelcast handles the versioning internally. So, you don’t have to change anything in the classes or serializers apart from the added, removed, or changed fields.

Hazelcast achieves this by identifying each version of the class by a unique fingerprint. Any change in a class results in a different fingerprint. Hazelcast uses a 64-bit Rabin Fingerprint to assign identifiers to schemas, which has an extremely low collision rate.

Different versions of the schema with different identifiers are replicated in the cluster and can be fetched by clients or members internally. That allows old readers to read fields of the classes they know when they try to read data serialized by a new writer. Similarly, new readers might read fields of the classes available in the data, when they try to read data serialized by an old writer.

Assume that the two versions of the following Employee class lives in the cluster. 

// version 0
type Employee struct {
	Surname string
}

// version1
type Employee struct {
	Surname string
	Age int // newly added field
}

Then, when faced with binary data serialized by the new writer, old readers will be able to read the following fields. 

	func (s EmployeeSerializer) Read(r serialization.CompactReader) interface{} {
		v := Employee{}
		v.Surname = r.ReadString("surname")
        // The new "Age" field is there, but the old reader does not
        // know anything about it. Hence, it will simply ignore that field.
		return v
	}

Then, when faced with binary data serialized by the old writer, new readers will be able to read the following fields. Also, Hazelcast provides convenient APIs to check the existence of fields in the data when there is no such field. 

func (s EmployeeSerializer) Read(r serialization.CompactReader) interface{} {
	v := Employee{}
	v.Surname = r.ReadString("surname")
	// Read the "age" if it exists, or use the default value 0.
	// r.ReadInt32("age") would panic if the "age" field does not exist in data.
	if r.getFieldKind("age") == serialization.FieldKindInt32 {
		v.Age = r.ReadInt32("age")
	}
	return v
}

Note that, when an old reader reads data written by an old writer, or a new reader reads a data written by a new writer, they will be able to read all fields written.

One thing to be careful while evolving the class is to not have any conditional code in the Write method. That method must write all the fields available in the current version of the class to the writer, with appropriate field names and types. Write method of the serializer is used to extract a schema out of the object, hence any conditional code that may or may not run depending on the object in that method might result in an undefined behavior.

For more information about compact serialization, check out https://docs.hazelcast.com/hazelcast/latest/serialization/compact-serialization.

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: 

const factoryID = 1
const employeeClassID = 1

func (e Employee) FactoryID() int32 {
	return factoryID
}

func (e Employee) ClassID() int32 {
	return employeeClassID
}

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: 

const factoryID = 1
const employeeClassID = 1

func (e Employee) FactoryID() int32 {
	return factoryID
}

func (e Employee) ClassID() int32 {
	return employeeClassID
}

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 := object.(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

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

NewClassDefinition creates a new class definition for Portable. For non-versioned portables, version must be sent as zero which is default version in serialization service.

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 CompactConfig added in v1.4.0 

type CompactConfig struct {
	// contains filtered or unexported fields
}

CompactConfig contains compact serializers.

func (*CompactConfig) Clone added in v1.4.0 

func (cc *CompactConfig) Clone() CompactConfig

Clone creates a copy of the CompactConfig value. This method is intended for internal use.

func (*CompactConfig) Serializers added in v1.4.0 

func (cc *CompactConfig) Serializers() map[string]CompactSerializer

Serializers returns the registered compact serializers. This method is intended for internal use.

func (*CompactConfig) SetSerializers added in v1.4.0 

func (cc *CompactConfig) SetSerializers(serializers ...CompactSerializer)

SetSerializers sets the compact serializers. Each call overrides the previously set serializers. It has no effect after hazelcast.Client.StartNewClientWithConfig is called.

func (*CompactConfig) Validate added in v1.4.0 

func (cc *CompactConfig) Validate() error

Validate validates the CompactConfig and adds default values. This method is intended for internal use.

type CompactReader added in v1.4.0 

type CompactReader interface {
	// ReadBoolean reads and returns a boolean.
	ReadBoolean(fieldName string) bool
	// ReadInt8 reads and returns an int8.
	ReadInt8(fieldName string) int8
	// ReadInt16 reads and returns and int16
	ReadInt16(fieldName string) int16
	// ReadInt32 reads and returns an int32
	ReadInt32(fieldName string) int32
	// ReadInt64 reads and returns an int64
	ReadInt64(fieldName string) int64
	// ReadFloat32 reads and returns a float32
	ReadFloat32(fieldName string) float32
	// ReadFloat64 reads and returns a float64
	ReadFloat64(fieldName string) float64
	// ReadString reads and returns a string which may be nil.
	ReadString(fieldName string) *string
	// ReadDecimal reads and returns a *types.Decimal value which may be nil.
	ReadDecimal(fieldName string) *types.Decimal
	// ReadTime reads and returns a *types.LocalTime value which may be nil.
	ReadTime(fieldName string) *types.LocalTime
	// ReadDate reads and returns a *types.LocalDate value which may be nil.
	ReadDate(fieldName string) *types.LocalDate
	// ReadTimestamp reads and returns a *types.LocalDateTime value which may be nil.
	ReadTimestamp(fieldName string) *types.LocalDateTime
	// ReadTimestampWithTimezone reads and returns a *types.OffsetDateTime value which may be nil.
	ReadTimestampWithTimezone(fieldName string) *types.OffsetDateTime
	// ReadCompact reads and returns a compact serialized value which may be nil.
	ReadCompact(fieldName string) interface{}
	// ReadArrayOfBoolean reads and returns a slice of bools.
	ReadArrayOfBoolean(fieldName string) []bool
	// ReadArrayOfInt8 reads and returns a slice of int8s.
	ReadArrayOfInt8(fieldName string) []int8
	// ReadArrayOfInt16 reads and returns a slice of int16s.
	ReadArrayOfInt16(fieldName string) []int16
	// ReadArrayOfInt32 reads and returns a slice of int32s.
	ReadArrayOfInt32(fieldName string) []int32
	// ReadArrayOfInt64 reads and returns a slice of int64s.
	ReadArrayOfInt64(fieldName string) []int64
	// ReadArrayOfFloat32 reads and returns a slice of float32s.
	ReadArrayOfFloat32(fieldName string) []float32
	// ReadArrayOfFloat64 reads and returns a slice of float64s.
	ReadArrayOfFloat64(fieldName string) []float64
	// ReadArrayOfString reads and returns a slice of string pointers.
	// The returned pointers may be nil.
	ReadArrayOfString(fieldName string) []*string
	// ReadArrayOfDecimal reads and returns a slice of type.Decimal pointers.
	// The returned pointers may be nil.
	ReadArrayOfDecimal(fieldName string) []*types.Decimal
	// ReadArrayOfTime reads and returns a slice of type.LocalTime pointers.
	// The returned pointers may be nil.
	ReadArrayOfTime(fieldName string) []*types.LocalTime
	// ReadArrayOfDate reads and returns a slice of type.LocalDate pointers.
	// The returned pointers may be nil.
	ReadArrayOfDate(fieldName string) []*types.LocalDate
	// ReadArrayOfTimestamp reads and returns a slice of type.LocalDateTime pointers.
	// The returned pointers may be nil.
	ReadArrayOfTimestamp(fieldName string) []*types.LocalDateTime
	// ReadArrayOfTimestampWithTimezone reads and returns a slice of type.OffsetDateTime pointers.
	// The returned pointers may be nil.
	ReadArrayOfTimestampWithTimezone(fieldName string) []*types.OffsetDateTime
	// ReadArrayOfCompact reads and returns a slice of values.
	ReadArrayOfCompact(fieldName string) []interface{}
	// ReadNullableBoolean reads and returns a bool pointer.
	// The returned pointer may be nil.
	ReadNullableBoolean(fieldName string) *bool
	// ReadNullableInt8 reads and returns an int8 pointer.
	// The returned pointer may be nil.
	ReadNullableInt8(fieldName string) *int8
	// ReadNullableInt16 reads and returns an int16 pointer.
	// The returned pointer may be nil.
	ReadNullableInt16(fieldName string) *int16
	// ReadNullableInt32 reads and returns an int32 pointer.
	// The returned pointer may be nil.
	ReadNullableInt32(fieldName string) *int32
	// ReadNullableInt64 reads and returns an int64 pointer.
	// The returned pointer may be nil.
	ReadNullableInt64(fieldName string) *int64
	// ReadNullableFloat32 reads and returns a float32 pointer.
	// The returned pointer may be nil.
	ReadNullableFloat32(fieldName string) *float32
	// ReadNullableFloat64 reads and returns a float64 pointer.
	// The returned pointer may be nil.
	ReadNullableFloat64(fieldName string) *float64
	// ReadArrayOfNullableBoolean reads and returns a slice of bool pointers.
	// The returned pointers may be nil.
	ReadArrayOfNullableBoolean(fieldName string) []*bool
	// ReadArrayOfNullableInt8 reads and returns a slice of int8 pointers.
	// The returned pointers may be nil.
	ReadArrayOfNullableInt8(fieldName string) []*int8
	// ReadArrayOfNullableInt16 reads and returns a slice of int16 pointers.
	// The returned pointers may be nil.
	ReadArrayOfNullableInt16(fieldName string) []*int16
	// ReadArrayOfNullableInt32 reads and returns a slice of int32 pointers.
	// The returned pointers may be nil.
	ReadArrayOfNullableInt32(fieldName string) []*int32
	// ReadArrayOfNullableInt64 reads and returns a slice of int64 pointers.
	// The returned pointers may be nil.
	ReadArrayOfNullableInt64(fieldName string) []*int64
	// ReadArrayOfNullableFloat32 reads and returns a slice of float32 pointers.
	// The returned pointers may be nil.
	ReadArrayOfNullableFloat32(fieldName string) []*float32
	// ReadArrayOfNullableFloat64 reads and returns a slice of float64 pointers.
	// The returned pointers may be nil.
	ReadArrayOfNullableFloat64(fieldName string) []*float64
	// GetFieldKind returns the kind of the given field.
	// If the field does not exist, it returns FieldKindNotAvailable
	GetFieldKind(fieldName string) FieldKind
}

CompactReader is an interface implemented by types passed to CompactSerializer.Read method.

type CompactSerializer added in v1.4.0 

type CompactSerializer interface {
	// Type returns the target type for this serializer.
	Type() reflect.Type
	/*
		TypeName returns a string which uniquely identifies this serializers.
		Choosing a type name will associate that name with the schema and will make the polyglot use cases, where there are multiple clients from different languages, possible.
		Serializers in different languages can work on the same data, provided that their read and write methods are compatible, and they have the same type name.
		If you evolve your class in the later versions of your application, by adding or removing fields, you should continue using the same type name for that class.
	*/
	TypeName() string
	// Read reads the fields from reader and creates a value of the type returned from Type()
	Read(reader CompactReader) interface{}
	// Write writes the fields of value using the writer.
	Write(writer CompactWriter, value interface{})
}

CompactSerializer must be implemented to serialize a value with compact serialization.

type CompactWriter added in v1.4.0 

type CompactWriter interface {
	// WriteBoolean writes a bool value.
	WriteBoolean(fieldName string, value bool)
	// WriteInt8 writes an int8 value.
	WriteInt8(fieldName string, value int8)
	// WriteInt16 writes an int16 value.
	WriteInt16(fieldName string, value int16)
	// WriteInt32 writes an int32 value.
	WriteInt32(fieldName string, value int32)
	// WriteInt64 writes an int64 value.
	WriteInt64(fieldName string, value int64)
	// WriteFloat32 writes a float32 value.
	WriteFloat32(fieldName string, value float32)
	// WriteFloat64 writes a float64 value.
	WriteFloat64(fieldName string, value float64)
	// WriteString writes a string pointer value.
	// The pointer may be nil.
	WriteString(fieldName string, value *string)
	// WriteDecimal writes a types.Decimal pointer value.
	// The pointer may be nil.
	WriteDecimal(fieldName string, value *types.Decimal)
	// WriteTime writes a types.LocalTime pointer value.
	// The pointer may be nil.
	WriteTime(fieldName string, value *types.LocalTime)
	// WriteDate writes a types.LocalDate pointer value.
	// The pointer may be nil.
	WriteDate(fieldName string, value *types.LocalDate)
	// WriteTimestamp writes a types.LocalDateTime pointer value.
	// The pointer may be nil.
	WriteTimestamp(fieldName string, value *types.LocalDateTime)
	// WriteTimestampWithTimezone writes a types.OffsetDateTime pointer value.
	// The pointer may be nil.
	WriteTimestampWithTimezone(fieldName string, value *types.OffsetDateTime)
	// WriteCompact writes a value which can be serialized by a CompactSerializer.
	WriteCompact(fieldName string, value interface{})
	// WriteArrayOfBoolean writes a slice of bools.
	WriteArrayOfBoolean(fieldName string, value []bool)
	// WriteArrayOfInt8 writes a slice of int8s.
	WriteArrayOfInt8(fieldName string, value []int8)
	// WriteArrayOfInt16 writes a slice of int16s.
	WriteArrayOfInt16(fieldName string, value []int16)
	// WriteArrayOfInt32 writes a slice of int32s.
	WriteArrayOfInt32(fieldName string, value []int32)
	// WriteArrayOfInt64 writes a slice of int64s.
	WriteArrayOfInt64(fieldName string, value []int64)
	// WriteArrayOfFloat32 writes a slice of float32s.
	WriteArrayOfFloat32(fieldName string, value []float32)
	// WriteArrayOfFloat64 writes a slice of float64s.
	WriteArrayOfFloat64(fieldName string, value []float64)
	// WriteArrayOfString writes a slice of string pointers.
	// The pointers may be nil.
	WriteArrayOfString(fieldName string, value []*string)
	// WriteArrayOfDecimal writes a slice of types.Decimal pointers.
	// The pointers may be nil.
	WriteArrayOfDecimal(fieldName string, value []*types.Decimal)
	// WriteArrayOfTime writes a slice of types.LocalTime pointers.
	// The pointers may be nil.
	WriteArrayOfTime(fieldName string, value []*types.LocalTime)
	// WriteArrayOfDate writes a slice of types.LocalDate pointers.
	// The pointers may be nil.
	WriteArrayOfDate(fieldName string, value []*types.LocalDate)
	// WriteArrayOfTimestamp writes a slice of types.LocalDateTime pointers.
	// The pointers may be nil.
	WriteArrayOfTimestamp(fieldName string, value []*types.LocalDateTime)
	// WriteArrayOfTimestampWithTimezone writes a slice of types.OffsetDateTime pointers.
	// The pointers may be nil.
	WriteArrayOfTimestampWithTimezone(fieldName string, value []*types.OffsetDateTime)
	// WriteArrayOfCompact writes a slice of values which can be serialized using a CompactSerializer.
	WriteArrayOfCompact(fieldName string, value []interface{})
	// WriteNullableBoolean writes a bool pointer.
	// The pointer may be nil.
	WriteNullableBoolean(fieldName string, value *bool)
	// WriteNullableInt8 writes an int8 pointer.
	// The pointer may be nil.
	WriteNullableInt8(fieldName string, value *int8)
	// WriteNullableInt16 writes an int16 pointer.
	// The pointer may be nil.
	WriteNullableInt16(fieldName string, value *int16)
	// WriteNullableInt32 writes an int32 pointer.
	// The pointer may be nil.
	WriteNullableInt32(fieldName string, value *int32)
	// WriteNullableInt64 writes an int64 pointer.
	// The pointer may be nil.
	WriteNullableInt64(fieldName string, value *int64)
	// WriteNullableFloat32 writes a float32 pointer.
	// The pointer may be nil.
	WriteNullableFloat32(fieldName string, value *float32)
	// WriteNullableFloat64 writes a float64 pointer.
	// The pointer may be nil.
	WriteNullableFloat64(fieldName string, value *float64)
	// WriteArrayOfNullableBoolean writes a slice of bool pointers.
	// The pointers may be nil.
	WriteArrayOfNullableBoolean(fieldName string, value []*bool)
	// WriteArrayOfNullableInt8 writes a slice of int8 pointers.
	// The pointers may be nil.
	WriteArrayOfNullableInt8(fieldName string, value []*int8)
	// WriteArrayOfNullableInt16 writes a slice of int16 pointers.
	// The pointers may be nil.
	WriteArrayOfNullableInt16(fieldName string, value []*int16)
	// WriteArrayOfNullableInt32 writes a slice of int32 pointers.
	// The pointers may be nil.
	WriteArrayOfNullableInt32(fieldName string, value []*int32)
	// WriteArrayOfNullableInt64 writes a slice of int64 pointers.
	// The pointers may be nil.
	WriteArrayOfNullableInt64(fieldName string, value []*int64)
	// WriteArrayOfNullableFloat32 writes a slice of float32 pointers.
	// The pointers may be nil.
	WriteArrayOfNullableFloat32(fieldName string, value []*float32)
	// WriteArrayOfNullableFloat64 writes a slice of float64 pointers.
	// The pointers may be nil.
	WriteArrayOfNullableFloat64(fieldName string, value []*float64)
}

CompactWriter is an interface implemented by types passed to CompactSerializer.Write method.

type Config 

type Config struct {
	Compact CompactConfig

	// 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) Clone added in v1.0.0 

func (c *Config) Clone() Config

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 zero 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 
/*
 * Copyright (c) 2008-2023, Hazelcast, Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License")
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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{}) {
	v := object.(Employee)
	output.WriteString(v.Surname)
}

func main() {
	// Configure serializer
	config := hazelcast.NewConfig()
	if err := config.Serialization.SetCustomSerializer(reflect.TypeOf(&Employee{}), &EmployeeCustomSerializer{}); err != nil {
		panic(err)
	}
	ctx := context.TODO()
	client, err := hazelcast.StartNewClientWithConfig(ctx, config)
	if err != nil {
		log.Fatal(err)
	}
	m, err := client.GetMap(ctx, "map-1")
	if err != nil {
		log.Fatal(err)
	}
	if _, err := m.Put(ctx, "employee-1", Employee{"Doe"}); err != nil {
		panic(err)
	}
	value, err := m.Get(ctx, "employee-1")
	if err != nil {
		panic(err)
	}
	fmt.Println("Surname of stored employee:", value.(Employee).Surname)
}

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 
/*
 * Copyright (c) 2008-2022, Hazelcast, Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License")
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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{})
	// version must be equivalent to PortableVersion
	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:

func (*Config) Validate added in v1.0.0 

func (c *Config) Validate() error

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 FieldKind added in v1.4.0 

type FieldKind int32
const (
	FieldKindNotAvailable                 FieldKind = 0
	FieldKindBoolean                      FieldKind = 1
	FieldKindArrayOfBoolean               FieldKind = 2
	FieldKindInt8                         FieldKind = 3
	FieldKindArrayOfInt8                  FieldKind = 4
	FieldKindChar                         FieldKind = 5
	FieldKindArrayOfChar                  FieldKind = 6
	FieldKindInt16                        FieldKind = 7
	FieldKindArrayOfInt16                 FieldKind = 8
	FieldKindInt32                        FieldKind = 9
	FieldKindArrayOfInt32                 FieldKind = 10
	FieldKindInt64                        FieldKind = 11
	FieldKindArrayOfInt64                 FieldKind = 12
	FieldKindFloat32                      FieldKind = 13
	FieldKindArrayOfFloat32               FieldKind = 14
	FieldKindFloat64                      FieldKind = 15
	FieldKindArrayOfFloat64               FieldKind = 16
	FieldKindString                       FieldKind = 17
	FieldKindArrayOfString                FieldKind = 18
	FieldKindDecimal                      FieldKind = 19
	FieldKindArrayOfDecimal               FieldKind = 20
	FieldKindTime                         FieldKind = 21
	FieldKindArrayOfTime                  FieldKind = 22
	FieldKindDate                         FieldKind = 23
	FieldKindArrayOfDate                  FieldKind = 24
	FieldKindTimestamp                    FieldKind = 25
	FieldKindArrayOfTimestamp             FieldKind = 26
	FieldKindTimestampWithTimezone        FieldKind = 27
	FieldKindArrayOfTimestampWithTimezone FieldKind = 28
	FieldKindCompact                      FieldKind = 29
	FieldKindArrayOfCompact               FieldKind = 30
	FieldKindPortable                     FieldKind = 31
	FieldKindArrayOfPortable              FieldKind = 32
	FieldKindNullableBoolean              FieldKind = 33
	FieldKindArrayOfNullableBoolean       FieldKind = 34
	FieldKindNullableInt8                 FieldKind = 35
	FieldKindArrayOfNullableInt8          FieldKind = 36
	FieldKindNullableInt16                FieldKind = 37
	FieldKindArrayOfNullableInt16         FieldKind = 38
	FieldKindNullableInt32                FieldKind = 39
	FieldKindArrayOfNullableInt32         FieldKind = 40
	FieldKindNullableInt64                FieldKind = 41
	FieldKindArrayOfNullableInt64         FieldKind = 42
	FieldKindNullableFloat32              FieldKind = 43
	FieldKindArrayOfNullableFloat32       FieldKind = 44
	FieldKindNullableFloat64              FieldKind = 45
	FieldKindArrayOfNullableFloat64       FieldKind = 46
)

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 creates 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 

func (j JSON) MarshalJSON() ([]byte, error)

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) String added in v1.0.0 

func (j JSON) String() string

func (*JSON) UnmarshalJSON added in v1.1.0 

func (j *JSON) UnmarshalJSON(data []byte) error

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 reads 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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.