org.jnetpcap.packet.annotate
Annotation Type Validate

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

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.

Optional Element Summary

java.lang.Class<? extends JHeader>[]	hueristics Binds this validation method as a heuristic discovery method for each protocol listed.
int	max Maximum header length in bytes.
int	min Minimum header length that is allowed by this protocol.

hueristics

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

Binds this validation method as a heuristic discovery method for each protocol listed.

Returns:

a list of protocols to bind as a heuristic validator

Default:

{}

max

public abstract int max

Maximum header length in bytes.

Returns:

the maximum allowed

Default:

2147483647

min

public abstract int min

Minimum header length that is allowed by this protocol.

Returns:

the minimum allowed

Default:

0