/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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 org.apache.tinkerpop.gremlin.structure.io.gryo.kryoshim;

import org.apache.commons.configuration.Configuration;

import java.io.InputStream;
import java.io.OutputStream;

/**
 * This interface exists to decouple HadoopPools from TinkerPop's shaded Kryo.
 * <p>
 * VertexWritable and ObjectWritable formerly implemented Serializable by
 * resorting to statically-pooled shaded Kryo instances maintained by the HadoopPools class.
 * This is awkward because those shaded Kryo instances require class registration by default.
 * <p>
 * Consider what happens with custom property datatypes reachable from the reference graph rooted at an ObjectWritable
 * or VertexWritable instance.  It is not enough for these property classes to merely implement
 * Serializable, though one think that from skimming ObjectWritable/VertexWritable.  Those classes
 * must also register with TinkerPop's internal, shaded Kryo instances as maintained by HadoopPools,
 * or else configure those instances to accept unregistered classes.
 * Otherwise, TinkerPop's shaded Kryo will refuse to serialize those properties (even though
 * they implement Serializable, and even though the user might think they are only using
 * Java's standard Serialization mechanism!).
 * <p>
 * By hiding the mechanics of serialization behind this interface instead of hardcoding it in
 * HadoopPools, the user can decide how to implement serialization for ObjectWritable/VertexWritable
 * (and whatever other classes in TinkerPop decide to implement Serializable but then delegate
 * all of the implementation details, like ObjectWritable/VertexWritable do now).
 */
public interface KryoShimService {

    /**
     * Deserializes an object from an input stream.
     *
     * @param source the stream from which to read an object's serialized form
     * @return the first deserialized object available from {@code source}
     */
    public Object readClassAndObject(final InputStream source);

    /**
     * Serializes an object to an output stream.  This may flush the output stream.
     *
     * @param o    the object to serialize
     * @param sink the stream into which the serialized object is written
     */
    public void writeClassAndObject(final Object o, final OutputStream sink);

    /**
     * Returns this service's relative priority number.  Unless explicitly overridden through a
     * system property ({@link KryoShimServiceLoader#KRYO_SHIM_SERVICE}),
     * the service implementation with the numerically highest priority will be used
     * and all others ignored.  In other words, the highest priority wins (in the absence of a
     * system property override).
     * <p>
     * TinkerPop's current default implementation uses priority value zero.
     * <p>
     * Third-party implementations of this interface should (but are not technically required)
     * to use a priority value with absolute value greater than 100.
     * <p>
     * The implementation currently breaks priority ties by lexicographical comparison of
     * fully-qualified package-and-classname, but this tie-breaking behavior should be
     * considered undefined and subject to future change.  Ties are ignored if the service
     * is explicitly set through the system property mentioned above.
     *
     * @return this implementation's priority value
     */
    public int getPriority();

    /**
     * Attempt to incorporate the supplied configuration in future read/write calls.
     * This method is not guaranteed to have any effect on an instance of this interface
     * after {@link #writeClassAndObject(Object, OutputStream)} or {@link #readClassAndObject(InputStream)}
     * has been invoked on that particular instance.
     *
     * @param conf the configuration to apply to this service's internal serializer
     */
    public void applyConfiguration(final Configuration conf);

    /**
     * Release all resources associated with the shim service.
     * This is called on a forced reload or when the {@link KryoShimServiceLoader} is closed.
     */
    public void close();
}