com.netflix.server.context.ContextSerializer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of rxnetty-contexts Show documentation
rxnetty-contexts
There is a newer version: 0.5.1
/*
 * Copyright 2014 Netflix, Inc.
 *
 * 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 com.netflix.server.context;

import io.reactivex.netty.contexts.ContextsContainer;

/**
 * A serializer for serialization/de-serialization any arbitrary context objects added to {@link ContextsContainer}. 
 * This serializer will be used to serialize when the context objects are to be sent across the wire to another service
 * vai NIWS client. 

 * This serializer will be used to de-serialize when the context objects are received on the wire from another service
 * as HTTP request headers.
 *
 * 
Versioning
 * A context serializer provides a serialization mechanism version which will be passed during de-serialization. The
 * intention of this versioning is not to select which versions can be de-serialized but to give a hint of
 * what is the format of the content to be de-serialized. Any serializer is always expected to be backward compatible
 * to handle services with multiple serializer versions in the request processing pipeline.
 *
 * @param  The object type that the serializer can serialize/de-serialize
 *
 * @author Nitesh Kant ([email protected])
 */
public interface ContextSerializer {

    /**
     * Returns the version of this serializer.
     *
     * @return The version of this serializer.
     */
    int getVersion();

    /**
     * Serializes the passed object {@code toSerialize}
     *
     * @param toSerialize The object to serialize. This object will never be {@code null}
     *
     * @return The serialized string. The serialization will be deemed failed if the returned object is {@code null}
     * and hence the callee will throw a {@link ContextSerializationException} upon receiving a {@code null}
     *
     * @throws ContextSerializationException If the serialization failed.
     */
    String serialize(T toSerialize) throws ContextSerializationException;

    /**
     * De-serializes the passed object {@code serialized}.
     *
     * @param serialized The serialized object to de-serialize. This string will never be {@code null}
     * @param version The version of the serializer as returned by {@link ContextSerializer#getVersion()} used to
     *                serialize the passed string.
     *
     * @return The de-serialized object. The de-serialization will be deemed failed if the returned object is {@code null}
     * and hence the callee will throw a {@link ContextSerializationException} upon receiving a {@code null}
     *
     * @throws ContextSerializationException If the de-serialization failed.
     */
    T deserialize(String serialized, int version) throws ContextSerializationException;
}