io.hekate.codec.CodecService Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of hekate-all Show documentation
Java library for cluster communications and computing.
There is a newer version: 4.1.3
/*
 * Copyright 2020 The Hekate Project
 *
 * The Hekate Project 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 io.hekate.codec;

import io.hekate.core.Hekate;
import io.hekate.core.HekateBootstrap;
import io.hekate.core.service.Service;
import java.io.IOException;

/**
 * « start hereMain entry point to data serialization API.
 *
 * Overview
 * 
 * {@link CodecService} represents the {@link Service} interface adaptor for {@link CodecFactory} in order to make it easily
 * accessible via {@link Hekate#codec()} method. All data encoding/decoding operations are delegated to the {@link CodecFactory}
 * instance that is registered via the {@link HekateBootstrap#setDefaultCodec(CodecFactory)} method.
 * 
 *
 * Accessing the Service
 * 
 * Instances of this service can be obtained via {@link Hekate#codec()} method as shown in the example below:
 * ${source: codec/CodecServiceJavadocTest.java#access}
 * 
 *
 * @see Codec
 * @see HekateBootstrap#setDefaultCodec(CodecFactory)
 */
public interface CodecService extends Service {
    /**
     * Returns an underlying codec factory (see {@link HekateBootstrap#setDefaultCodec(CodecFactory)}).
     *
     * @param  Type that should be supported by the returned codec factory.
     *
     * @return Codec factory.
     */
     CodecFactory codecFactory();

    /**
     * Returns encoder/decoder for the specified type.
     *
     * 
     * Such encoder/decoder uses the underlying {@link #codecFactory()} of this service to perform encoding/decoding operations.
     * 
     *
     * @param type Data type.
     * @param  Data type.
     *
     * @return Encoder/decoder for the specified type.
     *
     * @see HekateBootstrap#setDefaultCodec(CodecFactory)
     */
     EncoderDecoder forType(Class type);

    /**
     * Returns encoder/decoder for the specified type and encoding/decoding functions.
     *
     * @param type Data type.
     * @param encode Encode function.
     * @param decode Decode function.
     * @param  Data type.
     *
     * @return Encoder/decoder.
     */
     EncoderDecoder forType(Class type, EncodeFunction encode, DecodeFunction decode);

    /**
     * Returns encoder/decoder for the codec factory.
     *
     * @param codecFactory Codec factory.
     * @param  Data type.
     *
     * @return Encoder/decoder for the specified factory.
     */
     EncoderDecoder forFactory(CodecFactory codecFactory);

    /**
     * Encodes the specified object via the specified function and returns a byte array of encoded data.
     *
     * @param obj Object to encode (can be {@code null}, in such case the {@code encoder} function's parameter will be {@code null} too).
     * @param encoder Encoder function.
     * @param  Object type.
     *
     * @return Byte array of encoded data.
     *
     * @throws IOException If object couldn't be decoded.
     * @see #decode(byte[], DecodeFunction)
     */
     byte[] encode(T obj, EncodeFunction encoder) throws IOException;

    /**
     * Encodes the specified object into an array of bytes.
     *
     * @param obj Object.
     *
     * @return Bytes.
     *
     * @throws IOException Signals encoding failure.
     * @see #decode(byte[])
     */
    byte[] encode(Object obj) throws IOException;

    /**
     * Decodes an object from the specified byte array by using the supplied decode function.
     *
     * @param bytes Bytes.
     * @param decoder Decode function.
     * @param  Decoded object type.
     *
     * @return Decoded object.
     *
     * @throws IOException If object couldn't be decoded.
     * @see #encode(Object, EncodeFunction)
     */
     T decode(byte[] bytes, DecodeFunction decoder) throws IOException;

    /**
     * Decodes an object from the specified array of bytes.
     *
     * @param bytes Bytes.
     * @param offset Offset of the first byte to read.
     * @param limit Maximum number of bytes to read.
     *
     * @return Decoded object.
     *
     * @throws IOException Signals decoding failure.
     */
    Object decode(byte[] bytes, int offset, int limit) throws IOException;

    /**
     * Decodes an object from the specified array of bytes.
     *
     * @param bytes Bytes.
     *
     * @return Decoded object.
     *
     * @throws IOException Signals decoding failure.
     * @see #encode(Object)
     */
    Object decode(byte[] bytes) throws IOException;

    /**
     * Decodes an object from the specified byte array by using the supplied decode function.
     *
     * @param bytes Bytes.
     * @param offset Offset to
     * @param limit Maximum number of bytes to read.
     * @param decoder Decode function.
     * @param  Decoded object type.
     *
     * @return Decoded object.
     *
     * @throws IOException If object couldn't be decoded.
     */
     T decode(byte[] bytes, int offset, int limit, DecodeFunction decoder) throws IOException;
}