Module org.jnetpcap
Package org.jnetpcap

Interface Pcap.LibraryPolicy

Enclosing class:
Pcap
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public static interface Pcap.LibraryPolicy
An interface which provides a hook into Pcap initialization process. Any missing native library symbols during the low level initialization/static process are captured and reported to this policy which may log, report, or even halt the initialization process from continuing.

Logging and handling errors on missing native symbols

A policy also defines a logger output destination, a Appendable, where logs by the default policy on initialization errors are sent. By default a PrintWriter.nullWriter() is used which discards all logging output. Any Appendable implementing output destination can be used such as System.err, StringBuilder, CharBuffer, Writer and so on.

For quick debugging, the default policy can be used by "turning on" the logging message consumer using code LibraryPolicy.setLoggingOutput(System.err) which will print to console any native library missing symbols. Again, this output is discarded by default settings. Can also install a Logger adapter as well instead of sending the output to console, while still using the default policy.

For more sophisticated library handling, you can install a new policy, that does or does not rely on the getLogginOutput() value. It may also throw an IllegalStateException to stop further intialization process from continuing, or try to attempt a different native loading path or method. By throwing an exception in the class static initializer, as this would do, you are preventing the class from loading and initializing the first time an error is encountered. This allows a second attempt with different native library loading algorithm. By providing your own policy which overrides the default native libpcap library loading method loadNativePcapLibrary(boolean), you load the library yourself. It calls on the default library initializer, which is a private instance of ForeignInitializer class.

Native Library Loading

You can define several system properties which control the behavior of how the native pcap library, or one of its derivatives are loaded. These properties, allow changing of the procedure how the library is located and how is actually loaded. The defaults for the native library loading procedure, define a list of possible pcap library undecorated names such as 'wpcap,npcap,pcap' and utilize the relative System.loadLibrary(String) to search for the shared object/native library.

By specifying various system properties on the java command line, you can redefine how, where and what to look for when loading the native library.

The following properties are used in a search, in the following order:
"java.library.path":
Defines directories where the native library will searched for.
"org.jnetpcap.libpcap.file":
Defines an absolute directory and decorated filename path to load the native library using System.load(String) system call.
"org.jnetpcap.libpcap.filename":
Defines a decorated filename only of the native library. The decorated filename will be appended to the "java.library.path" and an absolute library load call will be attempted System.load(String).
"org.jnetpcap.libpcap.names":
A comma separated list of undecorated library names. Each of the undecorated names in the list will be attempted to load using System.loadLibrary(String) combined with the "java.library.path" property value.
"org.jnetpcap.so.extensions":
Lastly, as a long-shot attempt, a list of absolute files will be built by combining all the property values given, with fully decorated filenames which utilize the provided extensions, to try and locate the native library on the platform. The default extension list are defined as "so,dylib". Each one will be tried in turn.
See Also:

  • Field Details

    • SYSTEM_PROPERTY_JAVA_LIBRARY_PATH

      static final String SYSTEM_PROPERTY_JAVA_LIBRARY_PATH
      System property used to search for native libraries.
      See Also:

    • SYSTEM_PROPERTY_LIBPCAP_FILE

      static final String SYSTEM_PROPERTY_LIBPCAP_FILE
      System property containing the absolute native file path to the pcap library. For example -Dorg.jnetpcap.libpcap.file="/usr/lib/x86_64-linux-gnu/libpcap.so"
      See Also:

    • SYSTEM_PROPERTY_LIBPCAP_FILENAME

      static final String SYSTEM_PROPERTY_LIBPCAP_FILENAME
      System property containing full native library filename, but no directory path. The value of the 'java.library.path' is prepended to the filename and an attempt to load the library is made. For example: -Dorg.jnetpcap.libpcap.names="libpcap.so"
      See Also:

    • SYSTEM_PROPERTY_LIBPCAP_NAMES

      static final String SYSTEM_PROPERTY_LIBPCAP_NAMES
      A list of comma separated, undecorated library names. The default is to search for npcap,wpcap,pcap in the directories specified by 'java.library.path'
      See Also:

    • SYSTEM_PROPERTY_SO_EXTENSIONS

      static final String SYSTEM_PROPERTY_SO_EXTENSIONS
      Platform dependent list of shared-object extensions to use while attempting to load the native library. This property, combined with the 'org.jnetpcap.libpcap.names' property and 'java.library.path' propeties are used to try and load native library by building absolute file path to each named library. The default is so,dylib extensions.
      See Also:

    • SYSTEM_PROPERTY_SO_IGNORE_LOAD_ERRORS

      static final String SYSTEM_PROPERTY_SO_IGNORE_LOAD_ERRORS
      The system property which is used to define if load error messages should be ignored or not. If ignored, when shared library is not found, it will be silently ignored and no errors reported. If set to 'false', when native shared object is not found, and exception will be thrown by the default LibraryPolicy currently set. Default is 'true' or ignore errors and be silent.

      Note: errors are always detectible by using the method Pcap.isSupported() call, which will return false if the pcap library was not loaded. Also invoking any of the native methods, will throw an IllegalStateException. This propery applies to the act of native library loading itself, and does not silence IllegalStateExceptions when native methods are invoked and corresponding native library has not been loaded at runtime.

      See Also:

    • SYSTEM_PROPERTY_ABI

      static final String SYSTEM_PROPERTY_ABI
      System property used to override the selection of the PcapHeaderABI. ABI stands for Application Binary Interface, a low level hardware architecture dependent description how native primitive data structures are encoded.

      The main difference between "compact" and "padded" native C structures is how individual members within a give C structure an encoded. Specifically the struct pcap_pkthdr in libpcap is susceptible to such encoding differences. The timestamp field is defined as two int sub-fields (seconds and micro-seconds), each of which is typically 32-bits but on modern 64-bit machines. Therefore the sizeof(pcap_pkthdr) can be either 16 or 24 bytes, depending on the architecture. Further more, even on 64-bit machines, when reading offline files, the header stored is byte encoded to the machine that wrote the offline file. Thus you can have a "compact" header on a 64-bit machine, and even with its bytes swapped for integer values. The ABI values determines the best ABI to utilize to read such binary headers.

      The applicable values are:

      COMPACT_LE
      Native C structure is "compact" encoded with LITTLE endian byte encoding. The total length of pcap_pkthdr is 16 bytes.
      COMPACT_BE
      Native C structure is "compact" encoded with BIG endian byte encoding. The total length of pcap_pkthdr is 16 bytes.
      PADDED_LE
      Native C structure is "padded" encoded with LITTLE endian byte encoding. The total length of pcap_pkthdr is 24 bytes.
      PADDED_BE
      Native C structure is "padded" encoded with BIG endian byte encoding. The total length of pcap_pkthdr is 24 bytes.
      See Also:

    • DEFAULT_SO_IGNORE_LOAD_ERRORS

      static final String DEFAULT_SO_IGNORE_LOAD_ERRORS
      Default value ("true") for SYSTEM_PROPERTY_SO_IGNORE_LOAD_ERRORS property if not specified in system properties.
      See Also:

    • DEFAULT_JAVA_LIBRARY_PATH

      static final String DEFAULT_JAVA_LIBRARY_PATH
      The default java library path made up of many common paths on different platforms where libpcap is typically installed.
      See Also:

    • DEFAULT_LOGGING_OUTPUT

      static final Appendable DEFAULT_LOGGING_OUTPUT
      The Constant which defines the default logging output which discards all of its input.

  • Method Details

    • getDefault

      static Pcap.LibraryPolicy getDefault()
      Gets the default missing symbols policy.
      Returns:
      the default missing symbols policy

    • getLogginOutput

      static Appendable getLogginOutput()
      Gets the current logging output produced by the default missing symbols policy receiver. By default the output is sent to PrintWriter.nullWriter() which discards all output. You can set another output consumer or override the policy using setDefault(LibraryPolicy).
      Returns:
      the loggin output receiver

    • setDefault

      static void setDefault(Pcap.LibraryPolicy newPolicy)
      Sets the default native Pcap library policy.

      Native policy is executed during early/static initialization phase of Pcap library. The policy object receives a list of symbols both for 'downcall' and 'upcall' symbols which were not found during loading of the native pcap libarary. The ForeignInitializer creates stubs for each missing symbol, that when called at runtime will throw a safe exception. A missing symbols policy can intercept missing symbols during initialization phase and if so desired can throw an appropriate exception, halting any further initialization. A different policy might simply log an error using application's logger.

      Parameters:
      newPolicy - the new default missing symbols policy
      See Also:

    • setLoggingOutput

      static void setLoggingOutput(Appendable out)
      Sets the logging output produced by the default native library policy receiver. By default the output is sent to PrintWriter.nullWriter() which discards all output. You can set another output consumer or override the policy using setDefault(LibraryPolicy).
      Parameters:
      out - the new logging output
      See Also:

    • loadNativePcapLibrary

      default boolean loadNativePcapLibrary(boolean ignoreErrors)
      Calls on the private instanceof ForeignInitializer to load the native libpcap library.
      Parameters:
      ignoreErrors - when library loading error occures, the error will be ignore and no exception will be thrown
      Returns:
      true, if library was loaded successfully or false when ignoreErrors parameter is true and library failed to load

    • onMissingSymbols

      void onMissingSymbols(String name, List<String> missingDowncallSymbols, List<String> missingUpcallMethods) throws Throwable
      Called when a ForeignInitializer finishes initializing a class with native functions.
      Parameters:
      name - the name of the ForeignInitializer, usually the name of the class in which it was executed
      missingDowncallSymbols - a list of all missing/unresolved downcall symbols
      missingUpcallMethods - a list of all missing/unresolved upcall methods
      Throws:
      Throwable - any exception deemed appropriate by the policy implementation. This method is called during static Initializer phase of class loading, so this exception will be wrapped in the JRE's ExceptionInInitializerError exception.