################################################################################

#
# Copyright (C) 2007-2010 Sly Technologies, Inc.
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
#
################################################################################

jNetPcap Package
Version 1.3.b4
Release Notes
Created on 2010-12-15

INTRODUCTION:
============

This is a stable release beta #4 of jNetPcap library. The feature set for
1.3 release cycle is frozen and only bug fixes will be released in future
1.3 updates.

Beta 4 addresses a significant memory utilization issue. Beta 4 replaced

Object finalization memory cleanup model, with java Reference and ReferenceQueue
managed objects. No classes in jNetPcap library rely on Object.finalize() to
perform any type of cleanup. Any class requiring cleanup, now uses the
java.lang.reference package mechanism to be notified when cleanup needs to
occur. This is Sun/Oracle recommended way of performing cleanup.

Beta 4 adds a background system thread which schedules cleanup of resources. The
cleanup thread, named after the class implementing most of the functionality,
DisposableGC class, works in conjunction with memory allocation mechanism to
ensure that memory is kept within default limits of 64mb.

Several system properties were added to control the behavior and limits of
DisposableGC. Properties 'nio.mx', 'nio.ms', 'nio.blocksize' control native
memory allocation. These properties can be defined on the command line
as '-Dnio.mx=64mb', '-Dnio.ms=64mb', '-Dnio.blocksize=32kb'. Property 'nio.mx'
defines an absolute limit on the amount of native memory that can be allocated.
When the limit is reached, and memory cleanup is unable to free sufficient
amount of memory to fulfill the original request, an OutOfMemory exception is
thrown. Property 'nio.ms' defines a soft limit, where forcible memory cleanup
is attempted, while memory requests continue to be honored. Property
'nio.blocksize' defines the minimum size for the smallest memory allocation
request. Memory is allocated in larger 'nio.blocksize' blocks and sub-allocated
per each allocation request. This prevents excessive system memory fragmentation,
improves overall performance (since most subsequent allocation requests are
fulfilled in java).
The default values for all 3 properties are: nio.mx=64mb, nio.ms=64mb,
nio.blocksize=32kb. The defaults are applied to all platforms and hardware
architectures (32-bit and 64-bit).

Beta 4 also improves some critical areas of jNetPcap API. Specifically, peering,
memory allocation and use of accessor methods in JBuffer class, are
significantly improved.

The API classes are compiled with Java 1.5.X compiler and require Java 1.5
compatibility. The package is platform dependent as there is a native library
components supplied for each supported operating system
(i.e. jnetpcap.dll file for win32 systems.)

This release provides the API for a complete list of Libpcap's operations which
are to openLive, openOffline, openDead, compile filters, set them and many
others. For capturing packets, both packet at a time and dispatched handler
methods are implemented. Also various low level kernel buffer operations that
are natively available through WinPcap extension library are implemented as
well, but only available on windows based platforms.

The javadoc API documentation and a user guide is available at the project's
website at: http://jnetpcap.org.

== Installation Instructions ==

To install the library unzip the binary platform-dependent package into any
directory, or install the RPM package on unix based systems into its default
directories. There are 2 parts to setting up environment for jNetPcap.

*) Win32 Dependency: jNetPcap requires WinPcap 3.1 or greater installed.

WinPcap version 4.0.1 or greater is recommended, but not
neccessary. (http://winpcap.org)

*) FC notes: main files of interest from linux RPM package are installed
in the following locations:

- /usr/lib/libjnetpcap.so
- /usr/share/java/jnetpcap-1.3.a1.jar
- /usr/share/doc/jnetpcap-1.3.a1 = contains RELEASE notes and javadocs

*) Debian notes: main files of interest from linux deb package are installed
in the following locations:

- /usr/lib/libjnetpcap.so
- /usr/share/java/jnetpcap-1.3.a1.jar
- /usr/share/doc/jnetpcap-1.3.a1 = contains RELEASE notes and javadocs

1) Add supplied jnetpcap-version.jar file to your build system's CLASSPATH.

The jar file is found at the root of the installation directory in zip
files and in /usr/share/java on linux systems.

2) Setup native jnetpcap dynamically loadable library. This varies between

operating systems.

* On Win32 systems do only one of the following

- copy the jnetpcap.dll library file, found at root of jnetpcap's

installation directory to one of the window's system folders. This
 could be \windows or \windows\system32 directory.

- add the jNetPcap's installation directory to system PATH variable. This

is the same variable used access executables and scripts.

- Tell Java VM at startup exactly where to find jnetpcap.dll by setting

a java system property 'java.library.path' such as:
c:\> java -Djava.library.path=%JNETPCAP_HOME%

- You can change working directory into the root of jnetpcap's

installation directory.

* On unix based systems, use one of the following

- add /usr/lib directory to LD_LIBRARY_PATH variable as java JRE does not
look in this directory by default

- Tell Java VM at startup exactly where to find jnetpcap.dll by setting

a java system property 'java.library.path' such as:
shell > java -Djava.library.path=$JNETPCAP_HOME

- You can change working directory into the root of jnetpcap's

installation directory.

* For further trouble shooting information, please see the following link:
(http://jnetpcap.wiki.sourceforge.net/Troubleshooting+native+library)

== Project Website and Support ==

The project is actively maintained at (http://jnetpcap.org).

Also please join project's jnetpcap-users@lists.sourceforge.net list, to discuss

the project or report bugs at (http://sourceforge.net/mail/?group_id=164277).

== Distributed Jar Files ==

The file jnetpcap-version.jar provides the java implementation of the

public API. The jar file will not function on its own and requires that the
supplied "native shared library" be also utilized (see below.) Without the
library, most of the classes in this jar file will throw a java
'UnsatisfiedLinkException'.

== Distributed native shared library ==

The base directory of the distributed package contains a "native shared library"
either called 'jnetpcap.dll' on windows platforms, or 'libjnetpcap.so' on
unix based systems. The library is required in order to utilize this
distribution. Most of the java classes included in this package will throw
'UnsatisfiedLinkException' without this library being loaded.

An environment variable pointing to the directory where the native library

is located needs to be setup. This is either LD_LIBRARY_PATH on unix system,
or PATH variable on windows systems. The library resides within the jnetpcap
installation directory using zip packages and in /usr/lib directory using RPM
packages.

Within the package zip file, jnetpcap-version-arch.zip that would be

'jnetpcap-version-arch' directory.

== Dependencies ==
 * On win32 systems

- Install of WinPcap 3.1 or greater

+ This is the main program pacakge. It installs drivers and DLLs

(http://winpcap.org)

- No requirement for cgywin or mingw for runtime support, only to build.

* To run supplied tests (optional)

- jUnit any version

(http://www.junit.org/index.htm)

* To build from source (compiled binaries provided in package bundle)

- ANT build tool for both Java and C++ sources

(http://ant.apache.org)

- Optinal ANT task for <CC> tag

(http://ant-contrib.sourceforge.net/cc.html)

- Win32 MinGW with GCC (doesn't require 'cgywin' or any compatibility layers)

- gcc on unix

Both the jnetpcap-version.jar file and native jnetpcap library have to be

loaded in order to use this package. The jnetpcap-version.jar file needs
to be added to CLASSPATH, while the native library to either LD_LIBRARY_PATH
on unix system, or PATH variable on windows systems.

Also if you want to run the included junit tests in the 'tests' sub directory,
you will need to included any version of 'jUnit' in the CLASSPATH.

== Operating System Notes ==

* WinPcap OS support

- "Starting from WinPcap 4.0beta3, support for the Windows 9x/ME family of
operating systems has been dropped. The last builds supporting such OSes
are WinPcap 3.1 and WinPcap 4.0beta2", source http://winpcap.org website.

- Current version of jNetPcap has been tested with WinPcap versions 3.1,
4.0, 4.0.1, 4.1.1

- jNetPcap will not work with versions prior to 3.1 including 3.0 itself.

- WinPcap extension API is only available on windows based platforms. You

must use org.jnetpcap.winpcap.WinPcap.isSupport method to check if the
extension is available on this particular platform, even when code was
built under windows environment. The java classes are included even
on platforms that don't support WinPcap extensions, but those classes and
any methods inkoved will throw a PcapExtensionNotAvailableException.

* On Linux/Debian

- current release of jNetPcap only provides support for all linux based
 operating platforms. The RPM package does not place any explicit
dependencies but does require libpcap RPM package to be installed. Any
version of 0.8 or above will do.

- only org.jnetpcap package is supported on all Unix based platforms.

WinPcap extensions are disabled for non windows based platforms. (Use
WinPcap.isSupported() method to check for support.)

* On Apple OS support

- no immediate support planned, but will release support at some point.

== General Notes ==

This is a major feature release. Adds support for high level protocol analysis,
fixes several bugs, adds Http and Html header support and moves header package
to new protocol package.

== Changes ==

* See CHANGE_LOG.txt in the doc/ directory