org.jnetstream.capture
Interface PacketModifier<T extends CapturePacket>

public interface PacketModifier<T extends CapturePacket>

ElementModifier interface allows a capture session that is mutable (see Capture.isMutable()) to add, insert, swap and remove packets from the underlying packet dataset of the capture session. For example if the capture session is file based, such as FileCapture then packets are added, inserted or removed from the underlying capture file in response to the operations performed by this interface.

Adding new packets

New packets can be added in several different ways. Use one of the add(java.nio.ByteBuffer, org.jnetstream.protocol.Protocol, long, long) methods to add the packet at the current position which is not determined by this interface. (Usually ElementModifier objects are iterators that maintain their own position.) There are several overloaded various of the add(java.nio.ByteBuffer, org.jnetstream.protocol.Protocol, long, long) methods. You can use the add method to add a previously captured packet, or you can specify the ByteBuffer containing the packet's data and supply additional information so that appropriate packet representation is created for the underlying capture session. The add(java.nio.ByteBuffer, org.jnetstream.protocol.Protocol, long, long) methods are used for both appending a new packet at the end of the dataset and inserting it if the current position is not at the end of the dataset.

Removing packets

The interface also provides several remove() and retain(java.util.Collection) methods which can be used to remove packets from the current capture session. These methods only take CapturePackets that came from the underlying capture session, otherwise IllegalArgumentException will be thrown. If you want to delete a packet, you can use the following approaches.

• use the remove() method to remove the packet at the current location
• use the bulk remove(Collection) method which will remove several packet at the same time, found in the collection, from the underlying capture session.
• use the bulk retain(Collection) which will remove all packets from the capture session, other then the ones found in the supplied collection.

Efficiency

Please note that it is much more efficient to utilize bulk methods as opposed to accomplishing the same task single packet at a time. The implementation is optimized to be as efficient as possible given the supplied information and the request.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Method Summary

T	add(java.nio.ByteBuffer b, Protocol p, long s, long n) Adds a new packet to the current capture session.
T	add(java.nio.ByteBuffer b, Protocol p, long s, long n, int o) Adds a new packet to the current capture session.
java.util.List<T>	add(java.util.List<? extends CapturePacket> elements) Bulk add, which adds several packets at the same time to the capture session.
T	add(Packet element) Adds the supplied packet after the current position.
T	add(Packet element, long s, long n) Adds the supplied packet after the current position.
void	remove() Removes the current element.
void	remove(java.util.Collection<T> elements) Bulk remove, that removes several packets from the collection.
void	retain(java.util.Collection<T> elements) Bulk remove, that removes all packets other then the ones found in the collection.
void	swap(T first, T second) Swaps the two elements so that first element occupies second element's space while second element occupies previous first element's space.

Method Detail

add

T add(java.nio.ByteBuffer b,
      Protocol p,
      long s,
      long n)
                            throws java.io.IOException

Adds a new packet to the current capture session. The new packet is built from the supplied values which include raw buffer data, the protocol number of the first header within the packet buffer, and timestamp comprised of seconds and nanosecond fraction.

Parameters:

b - packet buffer which contains the packet's content. The packet data retrieved from the ByteBuffer.position() upto the ByteBuffer.limit() properties. The included and original lengths are calculated from these values.

p - protocol number of the first protocol within the packet buffer

s - capture timestamp of when the packet was first captured in seconds

n - capture timestamp of when the packet was first captured in nanosecond fraction

Returns:

new packet that was created from the supplied values

Throws:

java.io.IOException - any IO errors

add

T add(java.nio.ByteBuffer b,
      Protocol p,
      long s,
      long n,
      int o)
                            throws java.io.IOException

Adds a new packet to the current capture session. The new packet is built from the supplied values which include raw buffer data, the protocol number of the first header within the packet buffer, and timestamp comprised of seconds and nanosecond fraction.

Parameters:

b - packet buffer which contains the packet's content. The packet data retrieved from the ByteBuffer.position() upto the ByteBuffer.limit() properties. The included length is calculated from these values.

p - protocol number of the first protocol within the packet buffer

s - capture timestamp of when the packet was first captured in seconds

n - capture timestamp of when the packet was first captured in nanosecond fraction

o - original length of the packet data

Returns:

new packet that was created from the supplied values

Throws:

java.io.IOException - any IO errors

add

java.util.List<T> add(java.util.List<? extends CapturePacket> elements)
                                            throws java.io.IOException

Bulk add, which adds several packets at the same time to the capture session. All packets within the collection must be of type CapturePacket as capture timestamp is extracted from the packets themselves.

Parameters:

elements - collection of packets to add to the capture session

Returns:

a list of newly created packets by this operation

Throws:

java.io.IOException - any IO errors

add

T add(Packet element)
                            throws java.io.IOException

Adds the supplied packet after the current position. The capture timestamp is extracted from the Packet.

Parameters:

element - the packet which contains the packet buffer

Returns:

new packet that was created from the supplied values

Throws:

java.io.IOException - any IO errors

add

T add(Packet element,
      long s,
      long n)
                            throws java.io.IOException

Adds the supplied packet after the current position.

Parameters:

element - the packet which contains the packet buffer

s - capture timestamp in seconds

n - capture timestamp in nanosecond fraction with value between 0 and 999,999,999

Returns:

new packet that was created from the supplied values

Throws:

java.io.IOException - any IO errors

remove

void remove()
            throws java.io.IOException

Removes the current element. The position is maintained by the underlying object that implements this interface, but typically that is an interator type object that maintains a current position. In that particular case the remove would happen at the current position of the iterator.

Throws:

java.io.IOException - any IO errors

remove

void remove(java.util.Collection<T> elements)
            throws java.io.IOException

Bulk remove, that removes several packets from the collection. The packets that are part of the collection, must have been created by the underlying capture session associated with this interface. For example FilePackets retain certain information about the position within the file, the packet came from and this information is needed to efficiently perform the operation.

Parameters:

elements - collection of packets to be removed from the underlying capture session

Throws:

java.io.IOException - any IO errors

retain

void retain(java.util.Collection<T> elements)
            throws java.io.IOException

Bulk remove, that removes all packets other then the ones found in the collection. The packets that are part of the collection, must have been created by the underlying capture session associated with this interface. For example FilePackets retain certain information about the position within the file, the packet came from and this information is needed to efficiently perform the operation.

Parameters:

elements - collection of packets to be removed from the underlying capture session

Throws:

java.io.IOException - any IO errors

swap

void swap(T first,
          T second)
          throws java.io.IOException

Swaps the two elements so that first element occupies second element's space while second element occupies previous first element's space. Record's in between first and second may need to be moved in order to accomodate the change.

Parameters:

first - element to swap with 'second'

second - element to swap with 'first'

Throws:

java.io.IOException - any IO errors