Definition of Protocol: In computing, a protocol is a convention or standard that controls or enables the connection, communication, and data transfer between computing endpoints. In its simplest form, a protocol can be defined as the rules governing the syntax, semantics, and synchronization of communication. Protocols may be implemented by hardware, software, or a combination of the two. At the lowest level, a protocol defines the behavior of a hardware connection. (source: Wikipedia.org)

A protocol's header is essentially a static snapshot of just the structure of a header within a single packet buffer. The header only provides easy access to the data found within the contents of that particular packet. Protocols are typically more involved then a single header.

For that reason, protocols are a collection of at least 1 static header definition and any number of support classes, including analyzers. An analyzer is a special java object that is specifically written for a particular protocol. It is allowed to examine a whole stream of packets. As it analyzes each packet, any information it deems important, an analyzer will store in its own internal tables, maps, arrays, lists in whatever fashion it deems necessary. An analyzer will preserve external and persistent state according to specific protocol rules.

For example Ip4Analyzer, Ip4Sequencer and Ip4Assembler will inspect all incoming packets. All 3 are analyzers that perform a specialized task. The analyzers will specifically pay attention to packets that have Ip4 headers in them. They will analyze packets for fragments, errors, delay and timeout thresholds. They will also listen of ICMP packets which carry Ip specific error messages about timeouts, drops and other error conditions. They will keep that information in tables and allow other analyzers, from higher layer protocols, to use that information for whatever is necessary.

Analyzers will also attach "analysis" information directly to packets and headers. This information can be queried and retrieved using methods getAnalysis(), hasAnalysis() on JPacket and JHeader classes. These methods may look familiar as they follow the same pattern as the header accessor methods.

All analyzers are registered with JRegistry which is a repository for this type of information. There is one special analyzer called JController. This is the top-level analyzer that all other analyzers are registered as listeners to. That is JController is the main analyzer that all of the packets are send to. It then maintains a table of sub-analyzers for each protocol.

For example, Ip4 protocol analyzer registers itself with JController as Ip4 listener, as well as Icmp listener in order to receive ICMP based packets so it can look at the control messages being passed around that are Ip4 specific.

Analyzers provide various callback interfaces. Each analyzer can provide its own unique, or custom callback interface. There is also a standard callback interface called AnalyzerListener which is generic and well suited to dispatching analyzer specific events. Each analyzer generates various events, which are protocol specific, that inform listeners of various protocol level states. Such as protocol transitions, i.e. TcpAnalyzer dispatches events to notify that Tcp 3-way handshake has begun and for each subsequent state transition, all on a per stream basis. Sequencers generate events when they start to find related packets and put them in sequence. Assemblers listen to the sequencer events, prepare for reassembly and when they receive an event letting them know that sequence is complete, to reassemble the entire sequence.

Analyzers can also buffer packets. Specifically analyzers tell the main JController which is responsible for receiving packets as well as passing them out, when to put the outbound packets on hold. Packets at that point are buffered in input and output queues, as necessary, until the hold is released at which point the queues are drained and the user receives packets.

Analyzers keep track of time, using packet capture timestamps. That is, the current time they use, is the time that is part of the packet. This allows packets that are read from a file to be properly analyzed for timeout conditions, errors, issue warning etc. Time mode can be changed and even augmented.

Therefore analyzers provide a higher level view of the protocol, with state being maintained across multiple packets and time. Analyzers provide a higher level interface for accessing this information. For example if a user is interested only in Ip4 packets, they can register an Ip4Handler which will receive only Ip4 headers:

Ip4Analyzer ipAnalyzer = JRegistry.getAnalyzer(Ip4Analyzer.class);
ipAnalyzer.addListener(new Ip4Handler() {

  public void processIp4(Ip4 ip) {
    System.out.println(ip.toString());
  }
});

This particular handler is registered with Ip4Analyzer and will only receive Ip4 headers. Since you can use JHeader.getPacket() method to retrieve the source packet that this header belongs to, its trivial to do so, if a packet is needed. More importantly you get an already peered ip header, that has been fully analyzed. It may contain reassembled data already if this particular packet was a fragment. The reassembly would happen automatically. You could check with Ip4 header if this is a fragment and if it is, retrieve the reassembled ip datagram:

  private FragmentAssembly assembly = new FragmentAssembly();

  public void processIp4(Ip4 ip) {
    if (ip.hasAnalysis(assembly)) {
      /* Its a fragment that has been reassembled. Reassembled fragments are returned
       * as brand new packets, that did not exist in reality on the network, but were
       * constructed and carry the new Ip4 datagram state and reassembled data.
       */
      JPacket reassembled = assembly.getPacket();
      
    } else {
      // It was just a normal non fragment datagram
    }
  }

Note that FragmentAssembly class resides under org.jnetpcap.packet.analysis package. It is also used for Tcp segmentation reassembly. FragmentAssembly is reused for various protocols that perform reassembly work. A different type of reassembled packet will be returned for Tcp protocol, one that contains reassembled tcp headers. The reassembled packets may be very large, especially in the tcp case. Ip datagrams are typically limited to under 64K by the protocol definition itself. Ip fragments are typically much smaller then 64k ceiling, such as 8K for NFS under Udp protocol.