...
▽

Package mgocompat

import "go.mongodb.org/mongo-driver/bson/mgocompat"
Overview
Index

Overview ▾

Package mgocompat provides Registry, a BSON registry compatible with globalsign/mgo's BSON, with some remaining differences. It also provides RegistryRespectNilValues for compatibility with mgo's BSON with RespectNilValues set to true. A registry can be configured on a mongo.Client with the SetRegistry option. See the bsoncodec docs for more details on registries.

Registry supports Getter and Setter equivalents by registering hooks. Note that if a value matches the hook for bsoncodec.Marshaler, bsoncodec.ValueMarshaler, or bsoncodec.Proxy, that hook will take priority over the Getter hook. The same is true for the hooks for bsoncodec.Unmarshaler and bsoncodec.ValueUnmarshaler and the Setter hook.

The functional differences between Registry and globalsign/mgo's BSON library are:

1) Registry errors instead of silently skipping mismatched types when decoding.

2) Registry does not have special handling for marshaling array ops ("$in", "$nin", "$all").

The driver uses different types than mgo's bson. The differences are:

  1. The driver's bson.RawValue is equivalent to mgo's bson.Raw, but uses Value instead of Data and uses Type, which is a bsontype.Type object that wraps a byte, instead of bson.Raw's Kind, a byte.

  2. The driver uses primitive.ObjectID, which is a [12]byte instead of mgo's bson.ObjectId, a string. Due to this, the zero value marshals and unmarshals differently for Extended JSON, with the driver marshaling as {"ID":"000000000000000000000000"} and mgo as {"Id":""}. The driver can unmarshal {"ID":""} to a primitive.ObjectID.

  3. The driver's primitive.Symbol is equivalent to mgo's bson.Symbol.

  4. The driver uses primitive.Timestamp instead of mgo's bson.MongoTimestamp. While MongoTimestamp is an int64, primitive.Timestamp stores the time and counter as two separate uint32 values, T and I respectively.

  5. The driver uses primitive.MinKey and primitive.MaxKey, which are struct{}, instead of mgo's bson.MinKey and bson.MaxKey, which are int64.

  6. The driver's primitive.Undefined is equivalent to mgo's bson.Undefined.

  7. The driver's primitive.Binary is equivalent to mgo's bson.Binary, with variables named Subtype and Data instead of Kind and Data.

  8. The driver's primitive.Regex is equivalent to mgo's bson.RegEx.

  9. The driver's primitive.JavaScript is equivalent to mgo's bson.JavaScript with no scope and primitive.CodeWithScope is equivalent to mgo's bson.JavaScript with scope.

  10. The driver's primitive.DBPointer is equivalent to mgo's bson.DBPointer, with variables named DB and Pointer instead of Namespace and Id.

  11. When implementing the Setter interface, mgocompat.ErrSetZero is equivalent to mgo's bson.ErrSetZero.

Variables

var (
    // ErrSetZero may be returned from a SetBSON method to have the value set to its respective zero value.
    ErrSetZero = errors.New("set to zero")
)

Registry is the mgo compatible bsoncodec.Registry. It contains the default and primitive codecs with mgo compatible options. 

var Registry = NewRegistryBuilder().Build()

RegistryRespectNilValues is the bsoncodec.Registry compatible with mgo withSetRespectNilValues set to true. 

var RegistryRespectNilValues = NewRespectNilValuesRegistryBuilder().Build()

func GetterEncodeValue 

func GetterEncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error

GetterEncodeValue is the ValueEncoderFunc for Getter types.

func NewRegistryBuilder 

func NewRegistryBuilder() *bsoncodec.RegistryBuilder

NewRegistryBuilder creates a new bsoncodec.RegistryBuilder configured with the default encoders and decoders from the bsoncodec.DefaultValueEncoders and bsoncodec.DefaultValueDecoders types and the PrimitiveCodecs type in this package.

func NewRespectNilValuesRegistryBuilder 

func NewRespectNilValuesRegistryBuilder() *bsoncodec.RegistryBuilder

NewRespectNilValuesRegistryBuilder creates a new bsoncodec.RegistryBuilder configured to behave like mgo/bson with RespectNilValues set to true.

func SetterDecodeValue 

func SetterDecodeValue(_ bsoncodec.DecodeContext, vr bsonrw.ValueReader, val reflect.Value) error

SetterDecodeValue is the ValueDecoderFunc for Setter types.

type Getter

Getter interface: a value implementing the bson.Getter interface will have its GetBSON method called when the given value has to be marshalled, and the result of this method will be marshaled in place of the actual object.

If GetBSON returns return a non-nil error, the marshalling procedure will stop and error out with the provided value. 

type Getter interface {
    GetBSON() (interface{}, error)
}

type Setter

Setter interface: a value implementing the bson.Setter interface will receive the BSON value via the SetBSON method during unmarshaling, and the object itself will not be changed as usual.

If setting the value works, the method should return nil or alternatively mgocompat.ErrSetZero to set the respective field to its zero value (nil for pointer types). If SetBSON returns a non-nil error, the unmarshalling procedure will stop and error out with the provided value.

This interface is generally useful in pointer receivers, since the method will want to change the receiver. A type field that implements the Setter interface doesn't have to be a pointer, though.

For example: 

type MyString string

func (s *MyString) SetBSON(raw bson.RawValue) error {
    return raw.Unmarshal(s)
}

type Setter interface {
    SetBSON(raw bson.RawValue) error
}