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: