001/*******************************************************************************
002 * Copyright (c) 2017 Red Hat Inc and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Red Hat Inc - initial API and implementation
011 *******************************************************************************/
012package org.eclipse.kapua.gateway.client;
013
014import java.nio.ByteBuffer;
015
016/**
017 * A codec for BLOB based payload transports
018 */
019public interface BinaryPayloadCodec {
020
021    /**
022     * Encode a {@link Payload} structure into a BLOB
023     * <p>
024     * The payload information gets encoded into a blob and appended at the end of the
025     * provided buffer. If the provided buffer is {@code null} a new buffer will be allocated.
026     * </p>
027     * <p>
028     * <b>Note:</b> The returning buffer may not be the same as the provided buffer. If the
029     * provided buffer has less remaining space than required a new buffer is allocated and
030     * returned, which will contain both the existing content as well as the newly appended.
031     * </p>
032     * 
033     * @param payload The payload to encode, must not be {@code null}
034     * @param buffer An optional buffer to append the output to, may be {@code null}
035     * @return A buffer with the appended payload output, must never be {@code null}
036     * @throws Exception if anything goes wrong
037     */
038    public ByteBuffer encode(Payload payload, ByteBuffer buffer) throws Exception;
039
040    /**
041     * Decode a {@link Payload} structure from the provided BLOB
042     * @param buffer The buffer to read from, must not be {@code null}
043     * @return the decoded payload structure, may be {@code null}
044     * @throws Exception if anything goes wrong
045     */
046    public Payload decode(ByteBuffer buffer) throws Exception;
047}