org.jnetpcap.packet.annotate
Annotation Type Bind

@Target(value=METHOD)
@Documented
@Retention(value=RUNTIME)
public @interface Bind

Defines a binding method. Any method annotated with Bind must be of specific java method signature and must supply annotation's 'to' parameter. In addition, bindings that are defined in non JHeader based classes, must also provide the 'from' parameter.

The required method signature varies depending how it is declared. Here are the possible binding method declarations and their required Bind annotation parameters.

• A static method declared inside a JHeader based class - only requires the 'to' parameter. The 'from' paramter is optional and the default value is the class of the parent header definition that the binding is defined in.
• A static method declared inside a non JHeader based class - requires both 'to' and 'from' parameters to be defined.
• A instance method (non static) declared inside an annonymous class that extends Object.class - requires both 'to' and 'from' parameters to be defined.

Bind annotation is allowed only on methods. The name of the method is insignicant as long as the return type and formal parameters the method takes are as specified below. Both static and instance methods are supported but only for the described cases above. The required method signatures are identical in all cases with the exception that the 'static' java modifier is dropped for instance method. The signature is as follows:

 Static signature:
 public static boolean bindSourceClassToDestinationClass(JPacket packet, <? extends JHeader> header);
 
 Instance signature:
 public boolean bindSourceClassToDestinationClass(JPacket packet, <? extends JHeader> header);
 

The method names are irrelevant and are provided in the above only as an example. It is recommended that implementors of binding methods, follow the following method naming convention to be consistent with other implementors and implementations. Here is the recommended naming convention:

 methodName := "bind" fromClass "To" toClass
 fromClass  := HEADER_NAME
 toClass    := HEADER_NAME
 

The naming convention is not enforced.

Here is an example of a complete binding method in a code fragment:

 public class TestBindings {
        @Bind(from = Ip4.class, to = Ethernet.class)
        public static boolean bindIp4ToEthernet(JPacket packet, Ethernet eth) {
                return eth.type() == 0x800;
        }
 
        @Bind(from = Ip4.class, to = IEEESnap.class)
        public static boolean bindIp4ToIEEESnap(JPacket packet, IEEESnap snap) {
                return snap.pid() == 0x800;
        }
 }
 

Here is an example of a single instance method.

 Object o = new Object() {
  @SuppressWarnings("unused")
  @Bind(from = Ip4.class, to = Ethernet.class)
  public boolean bindIp4ToMyHeader(JPacket packet, Ethernet eth) {
    return eth.type() == 0x800;
 }
 

The second parameter to the method must match the 'to' annotation parameter type. The types are verified at runtime and errors generated if those parameters do not match.

The Bind annotation also takes an optional "intValue" parameter. This parameter is used for making bindings that matches up with a BindValue marked field. Any field or method that is marked with BindValue annotation within the "to" class, can be used to make a match with "intValue" parameter. Since this is completely optional operation, that may or may not be implemented or utilized, it is also neccessary to provide the complete binding method with its logic as well. The "intValue" parameter is used to optimize bindings that use constant value for linking one protocol to the other.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Required Element Summary

java.lang.Class<? extends JHeader>

to The protocol that wants to bind to another protocol.

Optional Element Summary

java.lang.Class<? extends JHeader>[]	dependencies (Optional) parameter that allows the binding to specify via an array of header classes additional protocol dependencies.
java.lang.Class<? extends JHeader>	from (Optional in JHeader based declarations) The protocol that is being bound to.
int[]	intValue (Optional) Constant value that can be used to bind one protocol to another based on this value.
java.lang.String[]	stringValue (Optional) Constant value that can be used to bind one protocol to another based on this value.

Element Detail

to

public abstract java.lang.Class<? extends JHeader> to

The protocol that wants to bind to another protocol. In the diagram below B is binding to A. That is "to" == A.class. This is called the target protocol.

In this example, to paramter is assigned to header A class

 +----------+----------------+----------+ 
 | Ethernet | => header A <= | header B |
 +----------+----------------+----------+
 

Another words, B header is binding to A header

Returns:

a header class that is the target of the binding

intValue

public abstract int[] intValue

(Optional) Constant value that can be used to bind one protocol to another based on this value. The header specified using the "to" parameter must supply methods or mark fields with @BindValue annotation.

Returns:

value to use to ia bind-to-value matchup

Default:

2147483647

stringValue

public abstract java.lang.String[] stringValue

(Optional) Constant value that can be used to bind one protocol to another based on this value. The header specified using the "to" parameter must supply methods or mark fields with @BindValue annotation.

Returns:

value to use to ia bind-to-value matchup

Default:

""

from

public abstract java.lang.Class<? extends JHeader> from

(Optional in JHeader based declarations) The protocol that is being bound to. In the diagram below B is binding to A. That is "from" == B.class. This is called the source protocol.

In this example, from paramter is assigned to header B class

 +----------+----------+----------------+ 
 | Ethernet | header A | => header B <= |
 +----------+----------+----------------+
 

Another words, A header is bind is bound from B header

Returns:

header class that is the source of the binding

Default:

org.jnetpcap.packet.JHeader.class

dependencies

public abstract java.lang.Class<? extends JHeader>[] dependencies

(Optional) parameter that allows the binding to specify via an array of header classes additional protocol dependencies. This dependency list is used to optimize the binding making sure that atleast one header in the list is found within the packet for which binding is being evaluated before actually checking the binding.

Returns:

list of header classes that this binding is dependent on

Default:

{}