com.netflix.server.context.DirectionAwareContextSerializer 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;

/**
 * A replacement for {@link ContextSerializer} for {@link BiDirectional} contexts that requires information about the
 * direction of flow (i.e. request or response). For legacy reasons, this class extends {@link ContextSerializer}, the
 * easier way to implement a direction aware serializer will be to extend {@link DirectionAwareSerializerAdapter} which
 * provides a default implementation of the methods in {@link ContextSerializer} 

 *
 * Directions
 *
 * Directions carry different meanings when associated with serialization type. Infact its usually the opposite for
 * serialization and de-serialization. Following is the definition:
 *
 * {@link Direction#Inbound}
 * Serialization:  Serializing for adding to the response.
 * De-serialization:  De-serializing for reading the request.
 *
 * {@link Direction#Outbound}
 * Serialization:  Serializing for adding to the request.
 * De-serialization:  De-serializing for reading the response.
 *
 * @author Nitesh Kant
 */
public interface DirectionAwareContextSerializer extends ContextSerializer {

    /**
     * Directions defined by this interface. See {@link DirectionAwareContextSerializer} for definitions.
     */
    enum Direction {
        // Direction when an app receives the context.
        Inbound,
        Outbound
    }

    /**
     * Serializes the passed object {@code toSerialize}
     *
     * @param toSerialize The object to serialize. This object will never be {@code null}
     * @param direction Direction of message flow. See {@link DirectionAwareContextSerializer} for definitions.
     *
     * @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.
     *
     * @see DirectionAwareContextSerializer
     */
    String serialize(T toSerialize, Direction direction) 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.
     * @param direction Direction of message flow. See {@link DirectionAwareContextSerializer} for definitions.
     *
     * @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.
     *
     * @see DirectionAwareContextSerializer
     */
    T deserialize(String serialized, Direction direction, int version) throws ContextSerializationException;

}