binary/object.go

// Copyright (C) 2014 The Android Open Source Project
//
// 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 binary

import "fmt"

// Object is the interface to any class that wants to be encoded/decoded.
type Object interface {
	// Class returns the serialize information and functionality for this type.
	// The method should be valid on a nil pointer.
	Class() Class
}

// Class represents a struct type in the binary registry.
type Class interface {
	// ID should be a sha1 has of the types signature, such that
	// no two classes generate the same ID, and any change to the types name or
	// fields causes it's id to change.
	ID() ID

	// New can be used to build a new default initialized instance of the type.
	New() Object

	// Encode writes the supplied object to the supplied Encoder.
	// The object must be a type the Class understands, the implementation is
	// allowed to panic if it is not.
	Encode(Encoder, Object) error

	// Decode reads a single object from the supplied Decoder.
	Decode(Decoder) (Object, error)

	// DecodeTo reads into the supplied object from the supplied Decoder.
	// The object must be a type the Class understands, the implementation is
	// allowed to panic if it is not.
	DecodeTo(Decoder, Object) error

	// Skip moves over a single object from the supplied Decoder.
	// This must skip the same data that Decode would have read.
	Skip(Decoder) error
}

// Generate is used to tag structures that need an auto generated Class.
// The codergen function searches packages for structs that have this type as an
// anonymous field, and then automatically generates the encoding and decoding
// functionality for those structures. For example, the following struct would
// create the Class with methods needed to encode and decode the Name and Value
// fields, and register that class.
// The embedding will also fully implement the binary.Object interface, but with
// methods that panic. This will get overridden with the generated Methods.
// This is important because it means the package is resolvable without the
// generated code, which means the types can be correctly evaluated during the
// generation process.
//
// type MyNamedValue struct {
//    binary.Generate
//    Name  string
//    Value []byte
// }
type Generate struct{}

func (Generate) Class() Class { panic(fmt.Errorf("Class() not implemented")) }

var _ Object = Generate{} // Verify that Generate implements Object.