Packet.java

package com.gmail.woodyc40.common.protocol;

import io.netty.buffer.ByteBuf;

/**
 * Defines a packet (a form of communication as bits of data sent between the server and client)
 *
 * <p>An index starts at 0 and ends at the amount of fields a packet has - 1. Index refers to the field index, in the
 * order which they appear. Rather than field names, which are easy to misspell and annoying to have to check, just
 * count the fields and insert them as the index. In fact, just write or read in order which the fields appear in and
 * no problems should arise.</p>
 *
 * <p>Reading or writing using an index argument (that is, those with an int parameter) DO NOT have effects on the read
 * or write index.</p>
 *
 * @author Pierre C
 */
public interface Packet {
    /**
     * Writes the object into the packet at the specified field position
     *
     * @param idx the index to write the object
     * @param o the object to write
     */
    void write(int idx, Object o);

    /**
     * Writes the object into the current index, then advances the write index
     *
     * @param o the object to write
     */
    void write(Object o);

    /**
     * Obtains the index which the writer using {@link #write(Object)} is using
     *
     * @return the write index
     */
    int writeIndex();

    /**
     * Sets the index at which the next write will occur at
     *
     * @param index the index
     */
    void setWriteIndex(int index);

    /**
     * Reads the object at the particular index using the decoding type provided
     *
     * @param idx the index
     * @return the object at that index
     */
    Object read(int idx);

    /**
     * Reads the object at the current read index and advances the index
     *
     * @return the object at the index
     */
    Object read();

    /**
     * Obtains the index at which the next read will occur
     *
     * @return the index
     */
    int readIndex();

    /**
     * Sets the index at which the next read will occur
     *
     * @param index the index
     */
    void setReadIndex(int index);

    /**
     * Obtains the ID for the packet represented
     *
     * @return the packet id
     */
    int id();

    /**
     * Encodes the packet into the <em>next segment</em> of the byte appender
     *
     * <p>The appender will always be segmented before the write of the byte contents of the packet</p>
     *
     * @param appender the appender
     */
    void encode(ByteAppender appender);

    /**
     * Decodes the data in the appender back into the packet
     *
     * <p>The packet will use the last appendage of data in byte appender</p>
     *
     * @param buf the appender containing data which will go back into the packet
     */
    void decode(ByteBuf buf);

    /**
     * Obtains the Trident representation for the packet, which can be casted
     *
     * @return the Trident packet representation
     */
    Object asTridentForm();
}