jnetpcap.capture
Class CaptureFactory

java.lang.Object
  jnetpcap.capture.CaptureFactory

public final class CaptureFactory
extends java.lang.Object

Static factory methods for creating and accessing capture sessions. This class provides a number of static methods for manipulating capture files such as concatenating multiple files into one, or reverse and splitting a single large file into multiple smaller ones. Easily get the capture file type or validate its contents. The most imporant methods though are newFile(java.io.File, jnetpcap.capture.file.SuppliedFileTypes), openFile(java.io.File) and openLive() which create new blank capture files, open existing capture file or open network interfaces for live network packet capture where packets are received directly from the network and passed to the user.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Nested Class Summary

static interface	CaptureFactory.Factory An Abstract Factory pattern which creates concrete capture objects.
static interface	CaptureFactory.LocalFactory Factory interface for local sessions.
static interface	CaptureFactory.RemoteFactory Factory interface for remote sessions.

Method Summary

static void	append(MutableCapture destination, Capture... sources) Copies all of the CapturePackets returned by the sources into the already open capture file.
static void	catFile(java.io.File file, Capture... sources) Copies all of the CapturePackets returned by the source a destination capture file.
static void	catFile(java.io.File dst, java.io.File... src) Concatenate all the files into single dst file
static boolean	compactFile(java.io.File file) Cleans up and compacts the file contents to most efficient size and layout.
static void	convertFile(java.io.File source, java.io.File destination, FileType destinationType) Converts the source file into new file with the destinationType file format.
static CaptureFactory.LocalFactory	getLocal() Returns an instance of the current local capture factory which is responsible for creating local capture instances.
static java.util.List<MutableCaptureInterface>	listInterfaces()
static FileCapture	newFile(java.io.File file, SuppliedFileTypes type) Creates a new file of the request type
static FileCapture	newFile(java.io.File file, SuppliedFileTypes type, Capture capture) A convenience utility method which creates a new file and dumps all of the packet from capture to the new file in the proper format.
static FileCapture	newFile(java.io.File file, SuppliedFileTypes type, Version version, java.nio.ByteOrder encoding) Creates a new file in the specified format, specified version and using the specified byte encoding.
static MutableFileCapture	openFile(java.io.File file) Opens a file for reading and writting.
static MutableFileCapture	openFile(java.io.File file, Filter filter) Opens a file for reading and writting while applying a filter to limit what is returned.
static FileCapture	openFile(java.io.InputStream in) Uses an InputStream for reading in a capture.
static LiveCapture	openLive() Opens up a network interfaces for live packet capture.
static LiveCapture	openLive(CaptureInterface nic) Opens up a network interface for live packet capture.
static LiveCapture	openLive(java.util.Collection<CaptureInterface> nics) Opens up a network interfaces for live packet capture.
static LiveCapture	openLive(Filter filter, CaptureInterface nic) Opens up a network interface for live packet capture with a filter.
static LiveCapture	openLive(Filter filter, java.util.Collection<CaptureInterface> nics) Opens up a network interfaces for live packet capture with a filter.
static void	setLocalCaptureFactory(CaptureFactory.LocalFactory local) Allows complete override of the implementation of Capture Framework.
static java.util.List<java.io.File>	splitFile(java.io.File file) Splits the file into smaller files according to default rules defined for each file format.
static java.util.List<java.io.File>	splitFile(java.io.File file, long packetCount, boolean maxCompression) Split the specified file into smaller files containing specified number of packets each from the source file.
static FileType	typeOfFile(java.io.File file) Determines the file type of the supplied file.
static FileType	typeOfFile(java.io.InputStream fileStream) Determines the file type of the supplied stream.
static boolean	validateFile(java.io.File file) Checks if the specified file is in a proper format 100% compabile with specification.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

append

public static void append(MutableCapture destination,
                          Capture... sources)
                   throws java.io.IOException

Copies all of the CapturePackets returned by the sources into the already open capture file. The order in which the CapturePackets are read from the sources is unspecified as various muxing algorithms may be used in order to avoid blocking on a single source.

Parameters:

sources - capture sources to read packets from

destination - mutable capture to write the packets into

Throws:

java.io.IOException - any IO errors

catFile

public static void catFile(java.io.File file,
                           Capture... sources)
                    throws java.io.IOException

Copies all of the CapturePackets returned by the source a destination capture file. The order in which the CapturePackets are read from the sources is unspecified as various muxing algorithms may be used in order to avoid blocking on a single source.

Parameters:

sources - capture sources to read packets from

file - destination file to write the packets into

Throws:

java.io.IOException - any IO errors

catFile

public static void catFile(java.io.File dst,
                           java.io.File... src)
                    throws java.io.FileNotFoundException,
                           java.io.IOException

Concatenate all the files into single dst file

Parameters:

dst - destination file to concatenate the src files to

src - array of source files to concatenate contents from

Throws:

java.io.IOException

java.io.FileNotFoundException

compactFile

public static boolean compactFile(java.io.File file)

Cleans up and compacts the file contents to most efficient size and layout.

Parameters:

file - file to compact

Returns:

true if successfull, otherwise false

convertFile

public static void convertFile(java.io.File source,
                               java.io.File destination,
                               FileType destinationType)
                        throws java.io.IOException

Converts the source file into new file with the destinationType file format. You can convert any supported file type into any other supported file type including different versions of the same file format.

Parameters:

source - source file to do conversion on

destination - will create a new destination file in the destinationType format

destinationType - the format that new destination file will be created

Throws:

java.io.IOException - any IO errors

getLocal

public static CaptureFactory.LocalFactory getLocal()

Returns an instance of the current local capture factory which is responsible for creating local capture instances. This is synonymous with the RemoteSession counter part which extends the RemoteFactory interface. The methods between Factory, LocalFactory and RemoteFactory are partitioned in a such a way to only allow operations that make sense with the given interface. For example, the RemoteLocalFactory interface does not contain any of the methods that LocalFactory does to open a live network capture using standard java.net.NetworkInterface objects. This is because NetworkInterface objects don't make sense on client machine, they are only instantiated by runtime environment for local machines. Therefore you need to use one of the methods that are allowed for remote capture such as openLive(CaptureInterface) method where CaptureInterface is this frameworks concept and is allowed to be shared accross multiple machines.

Returns:

current local capture factory

setLocalCaptureFactory

public static void setLocalCaptureFactory(CaptureFactory.LocalFactory local)

Allows complete override of the implementation of Capture Framework. User can supply its own implementation of the comprehensive LocalFactory which is called to full fill "capture framework's" operations.

Parameters:

local - new local factory for all capture framework's operations

newFile

public static FileCapture newFile(java.io.File file,
                                  SuppliedFileTypes type)
                           throws java.io.IOException

Creates a new file of the request type

Parameters:

file -

type -

Returns:

Throws:

java.io.IOException

newFile

public static FileCapture newFile(java.io.File file,
                                  SuppliedFileTypes type,
                                  Capture capture)
                           throws java.io.IOException

A convenience utility method which creates a new file and dumps all of the packet from capture to the new file in the proper format.

Parameters:

file - file to create

type - the type of file to create

capture - source of CapturePackets which will be dumped into the new file

Returns:

open instance of this new file

Throws:

java.io.IOException - any IO errors

newFile

public static FileCapture newFile(java.io.File file,
                                  SuppliedFileTypes type,
                                  Version version,
                                  java.nio.ByteOrder encoding)
                           throws java.io.IOException

Creates a new file in the specified format, specified version and using the specified byte encoding. If the file type does not support encoding its headers in the requested type, an exception will be thrown.

Parameters:

file -

type -

version -

encoding -

Returns:

Throws:

java.io.IOException

openFile

public static MutableFileCapture openFile(java.io.File file)
                                   throws java.io.IOException

Opens a file for reading and writting.

Parameters:

file -

Returns:

Throws:

java.io.IOException

openFile

public static MutableFileCapture openFile(java.io.File file,
                                          Filter filter)
                                   throws java.io.IOException

Opens a file for reading and writting while applying a filter to limit what is returned.

Parameters:

file -

filter -

Returns:

Throws:

java.io.IOException

openFile

public static FileCapture openFile(java.io.InputStream in)
                            throws java.io.IOException

Uses an InputStream for reading in a capture. The format of the stream is expected to be exactly the same as found in the file version. Typically you would simply use FileInputStream class to open a file and pass it to this factory method.

 FileInputStream filestream = new FileInputStream("somefile.pcap");
 FileCapture capture = CaptureFactory.openFile(filestream);
 capture.close();
 

It is expected that the format of the stream as the same as in the physical file. This method is useful in situations if a file must be decompressed or decrypted using a stream. The only difference between this version of openFile and others that open the file directly is that no mutable or seekable operations are permitted on stream based files. Since InputStream is readonly object. Also think if you have a huge capture file on disk in compressed format, if all that is needed is to decompress the file content on the fly for read-only access, this method is perfect. Otherwise you can decompress this huge file potentially huge file on the disk and then open it for mutable operations.

Parameters:

in - input stream to read the capture contents in supported file format from

Returns:

Read-only, IOIterable FileCapture object

Throws:

java.io.IOException - any IO errors

openLive

public static LiveCapture openLive()
                            throws java.io.IOException

Opens up a network interfaces for live packet capture. All available network interfaces are opened for capture with the exception of any interfaces that carry the loopback address of 127.0.0.0/8. LiveCapture extends the Capture interface which provides simple iterator through which all the captured packets are returned one after the other. There is no guarrantee as to the order in which packets are returned when more then one interface is used for packet capture at the same time. Its simply left upto the underlying implementation to determine the order. Each CapturePacket maintains a reference to a CaptureInterface which is associated with the interface that captured the particular packet.

Returns:

reference to a live capture session

Throws:

java.io.IOException - any IO errors

openLive

public static LiveCapture openLive(java.util.Collection<CaptureInterface> nics)
                            throws java.io.IOException

Opens up a network interfaces for live packet capture. The specified network interfaces are opened for capture with including loopback interface if specified. LiveCapture extends the Capture interface which provides simple iterator through which all the captured packets are returned one after the other. There is no guarrantee as to the order in which packets are returned when more then one interface is used for packet capture at the same time. Its simply left upto the underlying implementation to determine the order. Each CapturePacket maintains a reference to a CaptureInterface which is associated with the interface that captured the particular packet.

Parameters:

nics - collection of network interfaces to open, including loopbacks if part of the collection

Returns:

a single capture session which captures packets from all of the opened interface at the same time

Throws:

java.io.IOException - any IO errors

openLive

public static LiveCapture openLive(Filter filter,
                                   java.util.Collection<CaptureInterface> nics)
                            throws java.io.IOException

Opens up a network interfaces for live packet capture with a filter. The specified network interfaces are opened for capture with including loopback interface if specified. LiveCapture extends the Capture interface which provides simple iterator through which all the captured packets are returned one after the other. There is no guarrantee as to the order in which packets are returned when more then one interface is used for packet capture at the same time. Its simply left upto the underlying implementation to determine the order. Each CapturePacket maintains a reference to a CaptureInterface which is associated with the interface that captured the particular packet.

Filter is applied directly by the kernel, this feature is operating system dependent, to efficiently accept or reject packets as close to the hardware level as possible with no extraneous in memory copies. Most modern operating system support this feature. If this feature is not available the filter is applied in "userland" or in user space which is less efficient.

Parameters:

nics -

filter -

Returns:

Throws:

java.io.IOException

openLive

public static LiveCapture openLive(CaptureInterface nic)
                            throws java.io.IOException

Opens up a network interface for live packet capture. The specified network interface will be opened for live network packet capture. LiveCapture extends the Capture interface which provides simple iterator through which all the captured packets are returned one after the other. There is no guarrantee as to the order in which packets are returned when more then one interface is used for packet capture at the same time. Its simply left upto the underlying implementation to determine the order. Each CapturePacket maintains a reference to a CaptureInterface which is associated with the interface that captured the particular packet.

Parameters:

nic -

Returns:

Throws:

java.io.IOException

openLive

public static LiveCapture openLive(Filter filter,
                                   CaptureInterface nic)
                            throws java.io.IOException

Opens up a network interface for live packet capture with a filter. The specified network interface will be opened for live network packet capture. LiveCapture extends the Capture interface which provides simple iterator through which all the captured packets are returned one after the other. There is no guarrantee as to the order in which packets are returned when more then one interface is used for packet capture at the same time. Its simply left upto the underlying implementation to determine the order. Each CapturePacket maintains a reference to a CaptureInterface which is associated with the interface that captured the particular packet.

Filter is applied directly by the kernel, this feature is operating system dependent, to efficiently accept or reject packets as close to the hardware level as possible with no extraneous in memory copies. Most modern operating system support this feature. If this feature is not available the filter is applied in "userland" or in user space which is less efficient.

Parameters:

nic -

filter -

Returns:

Throws:

java.io.IOException

splitFile

public static java.util.List<java.io.File> splitFile(java.io.File file)
                                              throws java.io.IOException

Splits the file into smaller files according to default rules defined for each file format. For NAP the file will be split with each Block Record being split into its own seperate file. For other files, the defaults are to split the files into byte files.

The base filename supplied is used as the base filename for all newly created files with the -XXXX appended to them.

The source file is unmodified

Parameters:

file - file to be split

Returns:

list of newly created files

Throws:

java.io.IOException

splitFile

public static java.util.List<java.io.File> splitFile(java.io.File file,
                                                     long packetCount,
                                                     boolean maxCompression)
                                              throws java.io.IOException

Split the specified file into smaller files containing specified number of packets each from the source file. New files are created to hold only the specified number of packets and associated meta records. The supplied filename is used as a base filename for all newly created files with the post fix of -XXXX appended to them.

The source file is unmodified

Parameters:

file - source file to split

packetCount - split using this many packets from the source file copied into the newly created files

maxCompression - true means produce the smallest possible file, while false means leave it upto the default algorithm for each spcific file type. For example NAP files pad their files to 512Kb by default which means that files containing even only a single packet are of minimum size 512 Kb, but this can be overriden by setting maxCompression to true. Notice that it will be harder to split the NAP file with regular unix commands if default padding is not used.

Returns:

list of all the new files created

Throws:

java.io.IOException

typeOfFile

public static FileType typeOfFile(java.io.File file)
                           throws java.io.IOException

Determines the file type of the supplied file. This similar method to the dynamic counter part CaptureFile.getType(), but does not require the file to be opened before hand and is quicker then using CaptureFile.openFile().getType() sequence. As more specific algorithm is used.

Parameters:

file - file to check and return file type

Returns:

file type of the supplied file or null if file type unknown or not supported

Throws:

java.io.IOException

typeOfFile

public static FileType typeOfFile(java.io.InputStream fileStream)
                           throws java.io.IOException

Determines the file type of the supplied stream. This similar method to the dynamic counter part CaptureFile.getType(), but does not require the file to be opened before hand and is quicker then using CaptureFile.openFile().getType() sequence. As more specific algorithm is used.

Parameters:

file - file to check and return file type

Returns:

file type of the supplied file or null if file type unknown or not supported

Throws:

java.io.IOException

validateFile

public static boolean validateFile(java.io.File file)
                            throws java.io.IOException

Checks if the specified file is in a proper format 100% compabile with specification.

Parameters:

file - file to validate

Returns:

true if file is valid with the specification, otherwise false, even if minor infringements are found

Throws:

java.io.IOException

listInterfaces

public static java.util.List<MutableCaptureInterface> listInterfaces()
                                                              throws java.io.IOException

Returns:

Throws:

java.io.IOException