Merge branch 'simplenet'

src/main/java/cpw/mods/fml/common/network/ByteBufUtils.java

@@ -1,16 +1,39 @@
 package cpw.mods.fml.common.network;
 
+import java.io.IOException;
+import net.minecraft.item.ItemStack;
+import net.minecraft.nbt.NBTTagCompound;
+import net.minecraft.network.PacketBuffer;
 import org.apache.commons.lang3.Validate;
 
 import com.google.common.base.Charsets;
+import com.google.common.base.Throwables;
 
 import io.netty.buffer.ByteBuf;
 
+/**
+ * Utilities for interacting with {@link ByteBuf}.
+ * @author cpw
+ *
+ */
 public class ByteBufUtils {
+    /**
+     * The number of bytes to write the supplied int using the 7 bit varint encoding.
+     *
+     * @param toCount The number to analyse
+     * @return The number of bytes it will take to write it (maximum of 5)
+     */
     public static int varIntByteCount(int toCount)
     {
-        return (toCount & -128) == 0 ? 1 : ((toCount & -16384) == 0 ? 2 : ((toCount & -2097152) == 0 ? 3 : ((toCount & -268435456) == 0 ? 4 : 5)));
+        return (toCount & 0xFFFFFF80) == 0 ? 1 : ((toCount & 0xFFFFC000) == 0 ? 2 : ((toCount & 0xFFE00000) == 0 ? 3 : ((toCount & 0xF0000000) == 0 ? 4 : 5)));
     }
+    /**
+     * Read a varint from the supplied buffer.
+     *
+     * @param buf The buffer to read from
+     * @param maxSize The maximum length of bytes to read
+     * @return The integer
+     */
     public static int readVarInt(ByteBuf buf, int maxSize)
     {
         Validate.isTrue(maxSize < 6 && maxSize > 0, "Varint length is between 1 and 5, not %d", maxSize);
@@ -33,9 +56,17 @@ public class ByteBufUtils {
         return i;
     }
 
+    /**
+     * Write an integer to the buffer using variable length encoding. The maxSize constrains
+     * how many bytes (and therefore the maximum number) that will be written.
+     *
+     * @param to The buffer to write to
+     * @param toWrite The integer to write
+     * @param maxSize The maximum number of bytes to use
+     */
     public static void writeVarInt(ByteBuf to, int toWrite, int maxSize)
     {
-        Validate.isTrue(varIntByteCount(toWrite) < maxSize, "Integer is too big for %d bytes", maxSize);
+        Validate.isTrue(varIntByteCount(toWrite) <= maxSize, "Integer is too big for %d bytes", maxSize);
         while ((toWrite & -128) != 0)
         {
             to.writeByte(toWrite & 127 | 128);
@@ -44,6 +75,13 @@ public class ByteBufUtils {
 
         to.writeByte(toWrite);
     }
+    /**
+     * Read a UTF8 string from the byte buffer.
+     * It is encoded as <varint length>[<UTF8 char bytes>]
+     *
+     * @param from The buffer to read from
+     * @return The string
+     */
     public static String readUTF8String(ByteBuf from)
     {
         int len = readVarInt(from,2);
@@ -52,6 +90,12 @@ public class ByteBufUtils {
         return str;
     }
 
+    /**
+     * Write a String with UTF8 byte encoding to the buffer.
+     * It is encoded as <varint length>[<UTF8 char bytes>]
+     * @param to the buffer to write to
+     * @param string The string to write
+     */
     public static void writeUTF8String(ByteBuf to, String string)
     {
         byte[] utf8Bytes = string.getBytes(Charsets.UTF_8);
@@ -59,4 +103,80 @@ public class ByteBufUtils {
         writeVarInt(to, utf8Bytes.length, 2);
         to.writeBytes(utf8Bytes);
     }
+
+    /**
+     * Write an {@link ItemStack} using minecraft compatible encoding.
+     *
+     * @param to The buffer to write to
+     * @param stack The itemstack to write
+     */
+    public static void writeItemStack(ByteBuf to, ItemStack stack)
+    {
+        PacketBuffer pb = new PacketBuffer(to);
+        try
+        {
+            pb.func_150788_a(stack);
+        } catch (IOException e)
+        {
+            // Unpossible?
+            throw Throwables.propagate(e);
+        }
+    }
+
+    /**
+     * Read an {@link ItemStack} from the byte buffer provided. It uses the minecraft encoding.
+     *
+     * @param from The buffer to read from
+     * @return The itemstack read
+     */
+    public static ItemStack readItemStack(ByteBuf from)
+    {
+        PacketBuffer pb = new PacketBuffer(from);
+        try
+        {
+            return pb.func_150791_c();
+        } catch (IOException e)
+        {
+            // Unpossible?
+            throw Throwables.propagate(e);
+        }
+    }
+
+    /**
+     * Write an {@link NBTTagCompound} to the byte buffer. It uses the minecraft encoding.
+     *
+     * @param to The buffer to write to
+     * @param tag The tag to write
+     */
+    public static void writeTag(ByteBuf to, NBTTagCompound tag)
+    {
+        PacketBuffer pb = new PacketBuffer(to);
+        try
+        {
+            pb.func_150786_a(tag);
+        } catch (IOException e)
+        {
+            // Unpossible?
+            throw Throwables.propagate(e);
+        }
+    }
+
+    /**
+     * Read an {@link NBTTagCompound} from the byte buffer. It uses the minecraft encoding.
+     *
+     * @param from The buffer to read from
+     * @return The read tag
+     */
+    public static NBTTagCompound readTag(ByteBuf from)
+    {
+        PacketBuffer pb = new PacketBuffer(from);
+        try
+        {
+            return pb.func_150793_b();
+        } catch (IOException e)
+        {
+            // Unpossible?
+            throw Throwables.propagate(e);
+        }
+    }
 }

src/main/java/cpw/mods/fml/common/network/NetworkRegistry.java

@@ -39,6 +39,7 @@ import cpw.mods.fml.common.discovery.ASMDataTable;
 import cpw.mods.fml.common.network.handshake.NetworkDispatcher;
 import cpw.mods.fml.common.network.internal.FMLProxyPacket;
 import cpw.mods.fml.common.network.internal.NetworkModHolder;
+import cpw.mods.fml.common.network.simpleimpl.SimpleNetworkWrapper;
 import cpw.mods.fml.relauncher.Side;
 
 /**
@@ -69,7 +70,21 @@ public enum NetworkRegistry
         channels.put(Side.SERVER, Maps.<String,FMLEmbeddedChannel>newConcurrentMap());
     }
 
+    /**
+     * Represents a target point for the ALLROUNDPOINT target.
+     *
+     * @author cpw
+     *
+     */
     public static class TargetPoint {
+        /**
+         * A target point
+         * @param dimension The dimension to target
+         * @param x The X coordinate
+         * @param y The Y coordinate
+         * @param z The Z coordinate
+         * @param range The range
+         */
         public TargetPoint(int dimension, double x, double y, double z, double range)
         {
             this.x = x;
@@ -86,6 +101,16 @@ public enum NetworkRegistry
     }
     /**
      * Create a new synchronous message channel pair based on netty.
+     *
+     * There are two preconstructed models available:
+     * <ul>
+     * <li> {@link #newSimpleChannel(String)} provides {@link SimpleNetworkWrapper}, a simple implementation of a netty handler, suitable for those who don't
+     * wish to dive too deeply into netty.
+     * <li> {@link #newEventChannel(String)} provides {@link FMLEventChannel} an event driven implementation, with lower level
+     * access to the network data stream, for those with advanced bitbanging needs that don't wish to poke netty too hard.
+     * <li> Alternatively, simply use the netty features provided here and implement the full power of the netty stack.
+     * </ul>
+     *
      * There are two channels created : one for each logical side (considered as the source of an outbound message)
      * The returned map will contain a value for each logical side, though both will only be working in the
      * integrated server case.
@@ -127,6 +152,22 @@ public enum NetworkRegistry
         return result;
     }
 
+    /**
+     * Construct a new {@link SimpleNetworkWrapper} for the channel.
+     *
+     * @param name The name of the channel
+     * @return A {@link SimpleNetworkWrapper} for handling this channel
+     */
+    public SimpleNetworkWrapper newSimpleChannel(String name)
+    {
+        return new SimpleNetworkWrapper(name);
+    }
+    /**
+     * Construct a new {@link FMLEventChannel} for the channel.
+     *
+     * @param name The name of the channel
+     * @return An {@link FMLEventChannel} for handling this channel
+     */
     public FMLEventChannel newEventDrivenChannel(String name)
     {
         return new FMLEventChannel(name);