EthernetAddress (JUG)

java.lang.Object
- 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:
- Determine which shared library module you need.
- Copy the shared library module to its final location.
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

Fields
Modifier and Type Field and Description

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

Fields
Modifier and Type	Field and Description
`static EthernetAddress`	`NULL` Constant ethernet address object which has the "null address".

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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:
    - The necessary native library must be installed (as described in the class overview.
    - The native code must find at least one ethernet address for the system.
    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)

Class EthernetAddress

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NULL

Method Detail

isNull

getPrimaryAdapter

getAllAdapters

fromBytes

getBytes

fromString

hashCode

equals

toString