User Guide


Since Release 0.4, the JSocket Wrench library has become far more straightforward to use. The introduction of the IProtocolMessage and IServiceMessage interfaces and the resulting simplification of the JSWDatagramSocket class mean that it is now scarcely more difficult to send and receive complicated protocol messages from raw sockets than it is to use the standard JDK Socket and DatagramSocket classes.

In order to use the library, the user must:

Each step is now described in turn.

To load the native library

The JSocket Wrench library contains a shared library of native code written in C++. Generally in Java, a shared library is loaded through the System.loadLibrary() function call. However, in the JSocketWrench library, the static initializer of the SocketWrenchSession class will call System.loadLibrary() on behalf of the user and, furthermore, will call any functions within the shared library necessary to initiate the socket library on the current platform. (No such calls are necessary on Linux but the Winsock 2 library on Windows has to be initiated and closed down explicitly). All the user has to do is to ensure that the shared library, which will carry the name on Linux or com_act365_net_Sockets.dll on Windows, is placed on a path from which it is available to be loaded, i.e. the library should be placed on the directory from which the project is to be executed (the CLASSPATH) or on one of the standard directories from which shared libraries are loaded on the current platform, i.e. the directories listed on $LD_LIBRARY_PATH (Linux) or %PATH% (Windows).

The rules of Java dictate that when a class has been defined with a static initializer, the code will be executed prior to the first use of the class. So the first (and only) call to SocketWrenchSession.setProtocol() (the function is described in the next section) will implicitly load the native library. The user does not have to create an instance of the SocketWrenchSession class in order to complete the task.

To select the protocol

The rules of Java dictate that it is only possible to call the JDK functions Socket.setSocketImplFactory(), ServerSocket.setSocketFactory() or DatagramSocket.setDatagramSocketImplFactory() once within an application. Since the function SocketWrenchSession.setProtocol() typically calls each of these three functions, it follows that it is only possible to call SocketWrenchSession.setProtocol() once within an application, i.e. that any app is restricted to the use of a single IP protocol. This is not as stringent a limitation as it might seem at first given that it is possible to send any type of message from a raw socket. For instance, the traceroute application in UDP mode will send UDP messages and receive ICMP messages. The socket type is set to ICMP (it should always be set to the protocol that the app expects to receive), which necessitates the use of raw sockets, but manipulation of the header allows UDP messages to be sent from the socket.

There are two forms of the SocketWrenchSession.setProtocol() function. One accepts an enumeration argument, such as SocketConstants.JSWPROTO_HDRICMP, while the other accepts a string argument, such as "HdrICMP". The various available protocols are described fully on a separate page.


Any call to create a raw socket in the JSocketWrench library is translated into the equivalent C runtime library call for the current platform, so it follows that the user will have to have the necessary operating system permissions for the call to succeed. In short, that means the user will have to have root privileges on Linux or Administrator privileges on Win 32. Default operating system installations on home PCs should grant these privileges.

The JSWDatagramSocket class

JSWDatagramSocket is a subclass of DatagramSocket. In addition to the datagram sockets supported by DatagramSocket, JSWDatagramSocket will support any socket type supported by the underlying operating system, including raw sockets. The class makes it straightforward to send or receive message classes that implement the IProtocolMessage or IServiceMessage interfaces.

Since the JSWDatagram class potentially has to construct IP or protocol-specific headers, it has several properties, some optional, which aren't encountered in the DatagramSocket class:

The IProtocolMessage and IServiceMessage interfaces

The user should create a new class that implements the IProtocolMessage interface in order to support a new protocol type. See the ICMPMessage, UDPMessage or TCPMessage classes for examples.

The user should create a new class that implements the IServiceMessage interface in order to support a new service type. See the DNSMessage class for an example. Logo