Reorganize propagation code (shrink PR 381) (#444)

* Rename distributedcontext package to correlation

Correlation is the name we agreed upon.

* Move trace propagators to api/trace

The trace propagators tests had to be moved to a testtrace subpackage
to avoid import cycles between api/trace and internal/trace.

Needed to shut up golint about stutter in trace.TraceContext -
TraceContext is a name of a W3C spec, so this stutter is
expected. It's certainly still better than golint's suggestion of
having trace.Context.

* Rename api/propagators to api/propagation

This package will not contain any propagators in the long run, just
the interface definitions.

Co-authored-by: Joshua MacDonald <jmacd@users.noreply.github.com>

api/correlation/map.go

@@ -0,0 +1,96 @@
+// Copyright 2019, OpenTelemetry Authors
+//
+// 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 correlation
+
+import (
+	"go.opentelemetry.io/otel/api/core"
+)
+
+// TODO Comments needed! This was formerly known as distributedcontext.Map
+
+type entry struct {
+	value core.Value
+}
+
+type rawMap map[core.Key]entry
+
+type Map struct {
+	m rawMap
+}
+
+type MapUpdate struct {
+	SingleKV core.KeyValue
+	MultiKV  []core.KeyValue
+}
+
+func newMap(raw rawMap) Map {
+	return Map{
+		m: raw,
+	}
+}
+
+func NewEmptyMap() Map {
+	return newMap(nil)
+}
+
+func NewMap(update MapUpdate) Map {
+	return NewEmptyMap().Apply(update)
+}
+
+func (m Map) Apply(update MapUpdate) Map {
+	r := make(rawMap, len(m.m)+len(update.MultiKV))
+	for k, v := range m.m {
+		r[k] = v
+	}
+	if update.SingleKV.Key.Defined() {
+		r[update.SingleKV.Key] = entry{
+			value: update.SingleKV.Value,
+		}
+	}
+	for _, kv := range update.MultiKV {
+		r[kv.Key] = entry{
+			value: kv.Value,
+		}
+	}
+	if len(r) == 0 {
+		r = nil
+	}
+	return newMap(r)
+}
+
+func (m Map) Value(k core.Key) (core.Value, bool) {
+	entry, ok := m.m[k]
+	return entry.value, ok
+}
+
+func (m Map) HasValue(k core.Key) bool {
+	_, has := m.Value(k)
+	return has
+}
+
+func (m Map) Len() int {
+	return len(m.m)
+}
+
+func (m Map) Foreach(f func(kv core.KeyValue) bool) {
+	for k, v := range m.m {
+		if !f(core.KeyValue{
+			Key:   k,
+			Value: v.value,
+		}) {
+			return
+		}
+	}
+}