zipkin2.codec.BytesDecoder Maven / Gradle / Ivy
/*
* Copyright 2015-2023 The OpenZipkin 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 zipkin2.codec;
import java.util.Collection;
import java.util.List;
import zipkin2.internal.Nullable;
/**
* This type accepts a collection that receives decoded elements.
*
* {@code
* ArrayList out = new ArrayList<>();
* SpanBytesDecoder.JSON_V2.decodeList(spans, out)
* }
*
* @param type of the object to deserialize
*/
// This receives a collection, not a function because it profiles 10% faster and all use cases are
// collections. This receives collection as opposed to list as zipkin-dependencies decodes into a
// set to dedupe redundant messages.
public interface BytesDecoder {
Encoding encoding();
/**
* This is used seldom as the canonical message form is a {@link #decodeList(byte[], Collection)
* list}.
*
* Note: multiple elements can be consumed from a single serialized object. For example, if the
* input is Zipkin v1, the list might receive two elements if the serialized object was a shared
* span.
*
* @param serialized a single message, for example a json object
* @return true if an element was decoded
* @throws {@linkplain IllegalArgumentException} if the type couldn't be decoded
*/
// used by zipkin-dependencies which reads elements one-at-a-time from ES documents
boolean decode(byte[] serialized, Collection out);
/** Visible for testing. This returns the first element parsed from the serialized object or null */
@Nullable T decodeOne(byte[] serialized);
/** Returns {@code true} if an element was decoded or throws {@link IllegalArgumentException}. */
boolean decodeList(byte[] serialized, Collection out);
/** Convenience method for {@link #decodeList(byte[], Collection)} */
List decodeList(byte[] serialized);
}