Simplify Codec and split responsibilities

Break Codec into two general purpose interfaces, Encoder and Decoder,
and move parameter codec responsibilities to ParameterCodec.

Make unversioned types explicit when registering - these types go
through conversion without modification.

Switch to use "__internal" instead of "" to represent the internal
version. Future commits will also add group defaulting (so that "" is
expanded internally into a known group version, and only cleared during
set).

For embedded types like runtime.Object -> runtime.RawExtension, put the
responsibility on the caller of Decode/Encode to handle transformation
into destination serialization. Future commits will expand RawExtension
and Unknown to accept a content encoding as well as bytes.

Make Unknown a bit more powerful and use it to carry unrecognized types.

pkg/runtime/interfaces.go

@@ -23,70 +23,84 @@ import (
 	"k8s.io/kubernetes/pkg/api/unversioned"
 )
 
-// Codec defines methods for serializing and deserializing API objects.
-type Codec interface {
-	Decoder
-	Encoder
+const (
+	APIVersionInternal    = "__internal"
+	APIVersionUnversioned = "__unversioned"
+)
+
+// Typer retrieves information about an object's group, version, and kind.
+type Typer interface {
+	// ObjectKind returns the version and kind of the provided object, or an
+	// error if the object is not recognized (IsNotRegisteredError will return true).
+	// It returns whether the object is considered unversioned at the same time.
+	// TODO: align the signature of ObjectTyper with this interface
+	ObjectKind(Object) (*unversioned.GroupVersionKind, bool, error)
 }
 
-// Decoder defines methods for deserializing API objects into a given type
-type Decoder interface {
-	// TODO: change the signature of this method
-	Decode(data []byte) (Object, error)
-	// DEPRECATED: This method is being removed
-	DecodeToVersion(data []byte, groupVersion unversioned.GroupVersion) (Object, error)
-	// DEPRECATED: This method is being removed
-	DecodeInto(data []byte, obj Object) error
-	// DEPRECATED: This method is being removed
-	DecodeIntoWithSpecifiedVersionKind(data []byte, obj Object, groupVersionKind unversioned.GroupVersionKind) error
-
-	DecodeParametersInto(parameters url.Values, obj Object) error
-}
-
-// Encoder defines methods for serializing API objects into bytes
 type Encoder interface {
-	// DEPRECATED: This method is being removed
-	Encode(obj Object) (data []byte, err error)
-	EncodeToStream(obj Object, stream io.Writer) error
-
-	// TODO: Add method for processing url parameters.
-	// EncodeParameters(obj Object) (url.Values, error)
+	// EncodeToStream writes an object to a stream. Override versions may be provided for each group
+	// that enforce a certain versioning. Implementations may return errors if the versions are incompatible,
+	// or if no conversion is defined.
+	EncodeToStream(obj Object, stream io.Writer, overrides ...unversioned.GroupVersion) error
 }
 
-// ObjectCodec represents the common mechanisms for converting to and from a particular
-// binary representation of an object.
-// TODO: Remove this interface - it is used only in CodecFor() method.
-type ObjectCodec interface {
-	Decoder
-
-	// EncodeToVersion convert and serializes an object in the internal format
-	// to a specified output version. An error is returned if the object
-	// cannot be converted for any reason.
-	EncodeToVersion(obj Object, outVersion string) ([]byte, error)
-	EncodeToVersionStream(obj Object, outVersion string, stream io.Writer) error
+type Decoder interface {
+	// Decode attempts to deserialize the provided data using either the innate typing of the scheme or the
+	// default kind, group, and version provided. It returns a decoded object as well as the kind, group, and
+	// version from the serialized data, or an error. If into is non-nil, it will be used as the target type
+	// and implementations may choose to use it rather than reallocating an object. However, the object is not
+	// guaranteed to be populated. The returned object is not guaranteed to match into. If defaults are
+	// provided, they are applied to the data by default. If no defaults or partial defaults are provided, the
+	// type of the into may be used to guide conversion decisions.
+	Decode(data []byte, defaults *unversioned.GroupVersionKind, into Object) (Object, *unversioned.GroupVersionKind, error)
 }
 
-// ObjectDecoder is a convenience interface for identifying serialized versions of objects
-// and transforming them into Objects. It intentionally overlaps with ObjectTyper and
-// Decoder for use in decode only paths.
-// TODO: Consider removing this interface?
-type ObjectDecoder interface {
+// Serializer is the core interface for transforming objects into a serialized format and back.
+// Implementations may choose to perform conversion of the object, but no assumptions should be made.
+type Serializer interface {
+	Encoder
 	Decoder
-	// DataVersionAndKind returns the group,version,kind of the provided data, or an error
-	// if another problem is detected. In many cases this method can be as expensive to
-	// invoke as the Decode method.
-	DataKind([]byte) (unversioned.GroupVersionKind, error)
-	// Recognizes returns true if the scheme is able to handle the provided group,version,kind
-	// of an object.
-	Recognizes(unversioned.GroupVersionKind) bool
+}
+
+// Codec is a Serializer that deals with the details of versioning objects. It offers the same
+// interface as Serializer, so this is a marker to consumers that care about the version of the objects
+// they receive.
+type Codec Serializer
+
+// ParameterCodec defines methods for serializing and deserializing API objects to url.Values and
+// performing any necessary conversion. Unlike the normal Codec, query parameters are not self describing
+// and the desired version must be specified.
+type ParameterCodec interface {
+	// DecodeParameters takes the given url.Values in the specified group version and decodes them
+	// into the provided object, or returns an error.
+	DecodeParameters(parameters url.Values, from unversioned.GroupVersion, into Object) error
+	// EncodeParameters encodes the provided object as query parameters or returns an error.
+	EncodeParameters(obj Object, to unversioned.GroupVersion) (url.Values, error)
+}
+
+// NegotiatedSerializer is an interface used for obtaining encoders, decoders, and serializers
+// for multiple supported media types.
+type NegotiatedSerializer interface {
+	SupportedMediaTypes() []string
+	SerializerForMediaType(mediaType string, options map[string]string) (Serializer, bool)
+	EncoderForVersion(serializer Serializer, gv unversioned.GroupVersion) Encoder
+	DecoderToVersion(serializer Serializer, gv unversioned.GroupVersion) Decoder
 }
 
 ///////////////////////////////////////////////////////////////////////////////
 // Non-codec interfaces
 
+type ObjectVersioner interface {
+	ConvertToVersion(in Object, outVersion string) (out Object, err error)
+}
+
 // ObjectConvertor converts an object to a different version.
 type ObjectConvertor interface {
+	// Convert attempts to convert one object into another, or returns an error. This method does
+	// not guarantee the in object is not mutated.
 	Convert(in, out interface{}) error
+	// ConvertToVersion takes the provided object and converts it the provided version. This
+	// method does not guarantee that the in object is not mutated.
 	ConvertToVersion(in Object, outVersion string) (out Object, err error)
 	ConvertFieldLabel(version, kind, label, value string) (string, string, error)
 }
@@ -94,10 +108,6 @@ type ObjectConvertor interface {
 // ObjectTyper contains methods for extracting the APIVersion and Kind
 // of objects.
 type ObjectTyper interface {
-	// DataKind returns the group,version,kind of the provided data, or an error
-	// if another problem is detected. In many cases this method can be as expensive to
-	// invoke as the Decode method.
-	DataKind([]byte) (unversioned.GroupVersionKind, error)
 	// ObjectKind returns the default group,version,kind of the provided object, or an
 	// error if the object is not recognized (IsNotRegisteredError will return true).
 	ObjectKind(Object) (unversioned.GroupVersionKind, error)
@@ -108,6 +118,10 @@ type ObjectTyper interface {
 	// or more precisely that the provided version is a possible conversion or decoding
 	// target.
 	Recognizes(gvk unversioned.GroupVersionKind) bool
+	// IsUnversioned returns true if the provided object is considered unversioned and thus
+	// should have Version and Group suppressed in the output. If the object is not recognized
+	// in the scheme, ok is false.
+	IsUnversioned(Object) (unversioned bool, ok bool)
 }
 
 // ObjectCreater contains methods for instantiating an object by kind and version.