edu.rit.m2mp
Class Packet

java.lang.Object
  extended by edu.rit.m2mp.Packet

public class Packet
extends Object

Class Packet provides an M2MP packet.

To get a packet object, call the Packet() constructor or call the allocate() method in class PacketPool. Allocating a packet from a packet pool lets you reuse an already-existing free packet, avoiding the overhead of constructing a new packet. When done using a packet, call the packet pool's deallocate() method to make the packet available for allocation again.

To read a packet's header fields, call the packet object's getMessageID(), isLastPacket(), and getFragmentNumber() methods. To read the message fragment, call the packet object's rewind() method, then call the get() method to read each message fragment byte.

To write a packet's header fields, call the packet object's setMessageID(), and setLastPacketAndFragmentNumber() methods. To write the message fragment, call the packet object's clear() method, call the put() method to write each message fragment byte, then call the flip() method to record the packet's length.

To fill in a packet from an external source, such as a network datagram, call the packet object's getBuffer() method to get the byte buffer; store the packet's contents, including the header, in the byte buffer starting at index 0; then call the limit(int) method to record the packet's length including the header.

Note: Class Packet is not multiple thread safe. Be sure only one thread at a time calls methods on a packet object.


Constructor Summary
Packet()
          Construct a new packet.
Packet(Packet thePacket)
          Construct a new packet which is a copy of the given packet.
 
Method Summary
 void clear()
          Begin writing the message fragment bytes into this packet.
 void copy(Packet thePacket)
          Make this packet be a copy of the given packet.
 void dump(HexPrintStream debugout)
          Do a debug printout of this packet's contents.
 void flip()
          Finish writing the message fragment bytes into this packet.
 byte get()
          Read the next message fragment byte from this packet.
 void get(byte[] buf, int off, int len)
          Read the next block of message fragment bytes from this packet.
 byte[] getBuffer()
          Returns this packet's byte buffer.
 int getFragmentNumber()
          Obtain this packet's fragment number field.
 int getLastPacketAndFragmentNumber()
          Obtain this packet's last packet flag and fragment number fields.
 int getMessageID()
          Obtain this packet's message ID field.
 Packet getNext()
          Get the next packet after this packet in a linked list.
 boolean headerEquals(Packet thePacket)
          Determine if this packet's header fields are equal to the given packet's header fields.
 boolean isLastPacket()
          Determine whether this packet is the last packet of the message.
static boolean isValidLength(int len)
          Determine if the given length is a valid length for a packet.
 int limit()
          Returns the total number of bytes in this packet.
 void limit(int len)
          Sets the total number of bytes in this packet.
 void put(byte b)
          Write the next message fragment byte into this packet.
 void put(byte[] buf, int off, int len)
          Write the next block of message fragment bytes into this packet.
 int remaining()
          Returns the number of bytes remaining in this packet.
 void rewind()
          Begin reading the message fragment bytes from this packet.
 void setLastPacketAndFragmentNumber(boolean isLastPacket, int theFragmentNumber)
          Set this packet's last packet flag and fragment number fields.
 void setLastPacketAndFragmentNumber(int theLastPacketFlagAndFragmentNumber)
          Set this packet's last packet flag and fragment number fields.
 void setMessageID(int theMessageID)
          Set this packet's message ID field.
 void setNext(Packet thePacket)
          Set the next packet after this packet in a linked list.
 void skip(int len)
          Skip over the given number of message fragment bytes from this packet.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Packet

public Packet()
Construct a new packet. All the packet's fields are set to default values.


Packet

public Packet(Packet thePacket)
Construct a new packet which is a copy of the given packet.

Parameters:
thePacket - Packet to copy.
Method Detail

isValidLength

public static boolean isValidLength(int len)
Determine if the given length is a valid length for a packet.

Parameters:
len - Length (bytes).
Returns:
True if len is a valid length for a packet, false otherwise.

copy

public void copy(Packet thePacket)
Make this packet be a copy of the given packet.

Parameters:
thePacket - Packet to copy.

getNext

public Packet getNext()
Get the next packet after this packet in a linked list.

Returns:
Next packet, or null if there is no next packet.

setNext

public void setNext(Packet thePacket)
Set the next packet after this packet in a linked list.

Parameters:
thePacket - Next packet, or null if there is no next packet.

headerEquals

public boolean headerEquals(Packet thePacket)
Determine if this packet's header fields are equal to the given packet's header fields.

Parameters:
thePacket - Packet to test.
Returns:
True if this packet's header equals thePacket's header, false otherwise.

getMessageID

public int getMessageID()
Obtain this packet's message ID field.

Returns:
Message ID.

isLastPacket

public boolean isLastPacket()
Determine whether this packet is the last packet of the message.

Returns:
True if this packet is the last packet of the message, false if it isn't.

getFragmentNumber

public int getFragmentNumber()
Obtain this packet's fragment number field.

Returns:
Fragment number.

getLastPacketAndFragmentNumber

public int getLastPacketAndFragmentNumber()
Obtain this packet's last packet flag and fragment number fields.

Returns:
Last packet flag (most significant bit) and fragment number (least significant 31 bits).

rewind

public void rewind()
Begin reading the message fragment bytes from this packet. This packet's limit is unchanged and its position is set to the beginning of the message fragment field.


get

public byte get()
Read the next message fragment byte from this packet. This packet's position is increased by 1.

Returns:
Message fragment byte.
Throws:
IndexOutOfBoundsException - (unchecked exception) Thrown if there are no more bytes in the message fragment.

get

public void get(byte[] buf,
                int off,
                int len)
Read the next block of message fragment bytes from this packet. The bytes read are stored at buf[off] through buf[off+len-1] inclusive. This packet's position is increased by len.

Parameters:
buf - Message fragment byte array.
off - Index of the first byte to read.
len - Number of bytes to read.
Throws:
NullPointerException - (unchecked exception) Thrown if buf is null.
IndexOutOfBoundsException - (unchecked exception) Thrown if off < 0, len < 0, off+len > buf.length, or there are fewer than len bytes remaining in the message fragment.

skip

public void skip(int len)
Skip over the given number of message fragment bytes from this packet. This packet's position is increased by len.

Parameters:
len - Number of bytes to skip.
Throws:
IndexOutOfBoundsException - (unchecked exception) Thrown if len < 0 or there are fewer than len bytes remaining in the message fragment.

setMessageID

public void setMessageID(int theMessageID)
Set this packet's message ID field.

Parameters:
theMessageID - Message ID.

setLastPacketAndFragmentNumber

public void setLastPacketAndFragmentNumber(boolean isLastPacket,
                                           int theFragmentNumber)
Set this packet's last packet flag and fragment number fields.

Parameters:
isLastPacket - True if this is the last packet, false otherwise.
theFragmentNumber - Fragment number.

setLastPacketAndFragmentNumber

public void setLastPacketAndFragmentNumber(int theLastPacketFlagAndFragmentNumber)
Set this packet's last packet flag and fragment number fields.

Parameters:
theLastPacketFlagAndFragmentNumber - Last packet flag (most significant bit) and fragment number (least significant 31 bits).

clear

public void clear()
Begin writing the message fragment bytes into this packet. This packet's limit is set to the maximum size of an M2MP packet and its position is set to the beginning of the message fragment field.


put

public void put(byte b)
Write the next message fragment byte into this packet. This packet's position is increased by 1.

Parameters:
b - Message fragment byte.
Throws:
IndexOutOfBoundsException - (unchecked exception) Thrown if there is no more room in the message fragment.

put

public void put(byte[] buf,
                int off,
                int len)
Write the next block of message fragment bytes into this packet. The bytes stored at buf[off] through buf[off+len-1] inclusive are written. This packet's position is increased by len.

Parameters:
buf - Message fragment byte array.
off - Index of the first byte to write.
len - Number of bytes to write.
Throws:
NullPointerException - (unchecked exception) Thrown if buf is null.
IndexOutOfBoundsException - (unchecked exception) Thrown if off < 0, len < 0, off+len > buf.length, or there is not enough room in the message fragment.

flip

public void flip()
Finish writing the message fragment bytes into this packet. This packet's limit is set to its position and its position is set to the beginning of the message fragment field.


getBuffer

public byte[] getBuffer()
Returns this packet's byte buffer.


limit

public void limit(int len)
Sets the total number of bytes in this packet. This method assumes that this packet's byte buffer has been filled in from an external source, such as a network datagram.

Parameters:
len - Total number of bytes in this packet.
Throws:
IllegalArgumentException - (unchecked exception) Thrown if len is not a valid length for a packet.

limit

public int limit()
Returns the total number of bytes in this packet.


remaining

public int remaining()
Returns the number of bytes remaining in this packet.


dump

public void dump(HexPrintStream debugout)
Do a debug printout of this packet's contents.

Parameters:
debugout - Hex print stream on which to print.


Copyright © 2001-2006 by Alan Kaminsky. All rights reserved. Send comments to ark­@­cs.rit.edu.