com.ccg.net.ethernet
Class EthernetAddress

java.lang.Object
  extended by com.ccg.net.ethernet.EthernetAddress

public final class EthernetAddress
extends Object

Manage ethernet address objects and provide a means to determine the ethernet address of the machine the JVM is running on.

This class is used to examine (work with) ethernet addresses. It was primarily created to provide a means to determine the ethernet address(es) of the local machine (which turned out to be a non-trivial project).

IMPORTANT INSTALLATION INSTRUCTIONS

This class relies on native code when determining the ethernet address. Because of this, a shared library module needs to be installed BEFORE you will be able to use the methods in this class related to the local ethernet address of the machine.

To do the installation, you need to:

It is important to note that the shared libraries need to be copied to a location that is within the library search path for your environment. I've found that the $(JREHOME)/bin directory tends to always be in the search path (at least for Linux/Windows). For Sun's JRE installation, look for $(JREHOME)/lib/ARCH (like "/opt/jdk/jre/lib/sparc"). If you are unable to copy the library to this location, you may need to update your library search path before executing code.

The source code for each of the libraries is available, however, it is often easier not to have to locate a compiler and simply use one of the pre-compiled binary files. The following binary files are available:

$COMHOME/ccg/native/linux/x86/libEthernetAddress.so
This library is intended for use on Intel x86 based Linux platforms. This file needs to be installed within your shared library search path with a final name of "libEthernetAddress.so". A developer can typically install this library with the following command (as root):
 cp $COMHOME/ccg/native/linux/x86/libEthernetAddress.so \
   $JREHOME/bin/libEthernetAddress.so
$COMHOME/ccg/native/solaris/sparc/libEthernetAddress.so
This library is intended for use on Sparc based Solaris platforms. This file needs to be installed within your shared library search path with a final name of "libEthernetAddress.so". A developer can typically install this library with the following command (as root):
 cp $COMHOME/ccg/native/solaris/sparc/libEthernetAddress.so \
   $JREHOME/lib/sparc/libEthernetAddress.so
$COMHOME/native/win/x86/EthernetAddress.dll
This library is intended for use on Intel x86 based Windows platforms. This file needs to be installed within your shared library search path with a final name of "EthernetAddress.dll". If you put this file in the same directory as your "java.exe" file, it seems to be found. A developer can typically install this library with the following command:
 copy %COMHOME%/ccg/native/win/x86/EthernetAddress.dll \
   %JREHOME%/bin/EthernetAddress.dll

Developer Notes:

If you need to add support for additional platforms (such as a Mac/Beos/etc), you should take one of the source 'C' files (like EthernetAddress_linux.c) as your starting point and create a new 'C' source file for the native platform you'd like to support.

Since:
1.0
Version:
$Revision: 1.2 $
Author:
$Author: pkb $
See Also:
getPrimaryAdapter(), PrintMAC.java

Field Summary
static EthernetAddress NULL
          Constant ethernet address object which has the "null address".
 
Method Summary
 boolean equals(Object o)
          Determine if two ethernet address objects are "equal".
static EthernetAddress fromBytes(byte[] val)
          Set the binary ID of your ethernet adapter.
static EthernetAddress fromString(String sval)
          Parse a ethernet address object from a string.
static Collection getAllAdapters()
          Get all of the ethernet addresses associated with the local machine.
 byte[] getBytes()
          Get the binary ID of your ethernet adapter.
static EthernetAddress getPrimaryAdapter()
          Try to determine the primary ethernet address of the machine.
 int hashCode()
          Get a hash code for the object.
 boolean isNull()
          Check to see if all bytes of the ethernet address are zero.
 String toString()
          Get the string representation of the ethernet address.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

NULL

public static final EthernetAddress NULL
Constant ethernet address object which has the "null address".

This constant can be used when you want a non-null EthernetAddress object reference, but want a invalid (or null) ethernet address contained.

The isNull() method will ALWAYS return true for this constant.

Since:
1.0
See Also:
isNull()
Method Detail

isNull

public boolean isNull()
Check to see if all bytes of the ethernet address are zero.

This method checks all of the bytes of a ethernet address to see if they are zero. If they are, then the ethernet address is "0:0:0:0:0:0", which we consider the "null" ethernet address.

Returns:
true if all bytes of the ethernet address are 0.
Since:
1.0
See Also:
NULL

getPrimaryAdapter

public static EthernetAddress getPrimaryAdapter()
                                         throws UnsatisfiedLinkError
Try to determine the primary ethernet address of the machine.

This method will try to return the primary ethernet address of the machine. In order for this to succeed:

Returns:
Ethernet address of the machine if able to determine/guess - otherwise null.
Throws:
UnsatisfiedLinkError - This exception is thrown if we are unable to load the native library (like: libEthernetAddress.so or EthernetAddress.dll) which is required to query the system for the ethernet address.
Since:
1.0
See Also:
getAllAdapters()

getAllAdapters

public static Collection getAllAdapters()
                                 throws UnsatisfiedLinkError
Get all of the ethernet addresses associated with the local machine.

This method will try and find ALL of the ethernet adapters which are currently available on the system. This is heavily OS dependent and may not be supported on all platforms. When not supported, you should still get back a collection with the primary adapter in it.

Returns:
Array of all ethernet adapters (never returns null, but may return a 0 length array if no adapters could be found).
Throws:
UnsatisfiedLinkError - This exception is thrown if we are unable to load the native library (like: libEthernetAddress.so or EthernetAddress.dll) which is required to query the system for the ethernet address.
See Also:
getPrimaryAdapter()

fromBytes

public static EthernetAddress fromBytes(byte[] val)
                                 throws BadAddressException
Set the binary ID of your ethernet adapter.

Parameters:
val - New byte[] value to assign.
Throws:
BadAddressException
See Also:
getBytes()

getBytes

public byte[] getBytes()
Get the binary ID of your ethernet adapter.

Returns:
Copy of the current byte[] value assigned.
See Also:
fromBytes(byte[])

fromString

public static EthernetAddress fromString(String sval)
                                  throws BadAddressException
Parse a ethernet address object from a string.

Ethernet addresses are typically shown as 6 hexadecimal values (range: [0,ff]) separated by colons. They have the form:

 x:x:x:x:x:x
 

This method is fairly lenient in its parsing. It allows any character (and omission) of the separator (shown above). And each hex value may be one or two digits long and upper or lower case.

The following shows several different ways to list the same ethernet address:

 00:E0:98:06:92:0E
 0:e0:98:6:92:e
 0-e0-98 6-92-e
 00e0980692e0
 

Parameters:
sval - String value to try and parse a ethernet address from (must not be null).
Throws:
BadAddressException - If we could not parse a ethernet address from the string you passed.
See Also:
toString()

hashCode

public int hashCode()
Get a hash code for the object.

This method obeys the hash code contract and returns a hash value that will try to be random, but will be identical for objects which are equal.

Overrides:
hashCode in class Object
Returns:
A reasonable hash code for the object.
Since:
1.0

equals

public boolean equals(Object o)
Determine if two ethernet address objects are "equal".

Overrides:
equals in class Object
Parameters:
o - Other object to compare to (you can pass null).
Returns:
true if two objects have same Ethernet address, false if not.
Since:
1.0

toString

public String toString()
Get the string representation of the ethernet address.

Overrides:
toString in class Object
Returns:
String representation of ehternet address in form: "xx:xx:xx:xx:xx:xx".
See Also:
fromString(java.lang.String)