inet.ipaddr

Class MACAddressString

java.lang.Object

inet.ipaddr.MACAddressString

All Implemented Interfaces:

HostIdentifierString, Serializable, Comparable<MACAddressString>

public class MACAddressString
extends Object
implements HostIdentifierString, Comparable<MACAddressString>

Parses the string representation of a MAC address. Such a string can represent just a single address or a set of addresses like 1:*:1-3:1-4:5:6

This supports a wide range of address formats and provides specific error messages, and allows specific configuration.

You can control all of the supported formats using MACAddressStringParameters.Builder to build a parameters instance of MACAddressStringParameters. When not using the constructor that takes a MACAddressStringParameters, a default instance of MACAddressStringParameters is used that is generally permissive.

Supported formats

Ranges are supported:

• wildcards '*' and ranges '-' (for example 1:*:1-3:1-4:5:6), useful for working with subnets
• SQL wildcards '%" and "_", although '%' is considered an SQL wildcard only when it is not considered an IPv6 zone indicator

The different methods of representing MAC addresses are supported:

• 6 or 8 bytes in hex representation like aa:bb:cc:dd:ee:ff
• The same but with a hyphen separator like aa-bb-cc-dd-ee-ff (the range separator in this case becomes '/')
• The same but with space separator like aa bb cc dd ee ff
• The dotted representation, 4 sets of 12 bits in hex representation like aaa.bbb.ccc.ddd
• The 12 or 16 hex representation with no separators like aabbccddeeff

All of the above range variations also work for each of these ways of representing MAC addresses.

Some additional formats:

• null or empty strings representing an unspecified address
• the single wildcard address "*" which represents all MAC addresses

Usage

Once you have constructed a MACAddressString object, you can convert it to an MACAddress object with various methods. It is as simple as:

 MACAddress address = new MACAddressString("1.2.3.4").getAddress();
 

If your application takes user input IP addresses, you can validate with:

 try {
  MACAddress address = new MACAddressString("1.2.3.4").toAddress();
 } catch(AddressStringException e) {
        //e.getMessage() provides description of validation failure
 }
 

For empty addresses, both toAddress() and getAddress() returns null. For invalid addresses, getAddress() returns null.

This class is thread-safe. In fact, MACAddressString objects are immutable. A MACAddressString object represents a single MAC address representation that cannot be changed after construction. Some of the derived state is created upon demand and cached, such as the derived MACAddress instances.

See Also:

Serialized Form

Core

Field Summary

Fields

Modifier and Type	Field and Description
static MACAddressString	ALL_ADDRESSES
static MACAddressString	EMPTY_ADDRESS

Fields inherited from interface inet.ipaddr.HostIdentifierString

SEGMENT_VALUE_DELIMITER

Constructor Summary

Constructors

Constructor and Description
MACAddressString(MACAddress address)
MACAddressString(String addr) Constructs an MACAddressString instance using the given String instance.
MACAddressString(String addr, MACAddressStringParameters valOptions)

Method Summary

Modifier and Type	Method and Description
int	compareTo(MACAddressString other)
static int	countDelimitedAddresses(String str) Given a string with comma delimiters to denote segment elements, this method will count the possible combinations.
boolean	equals(Object o) Two MACAddressString objects are equal if they represent the same set of addresses.
MACAddress	getAddress() Produces the MACAddress corresponding to this MACAddressString.
Integer	getPrefixLength()
MACAddressStringParameters	getValidationOptions()
int	hashCode()
boolean	isAllAddresses()
boolean	isEmpty() Returns true if the address is empty (zero-length).
boolean	isPrefixed()
boolean	isValid()
boolean	isZero()
static Iterator<String>	parseDelimitedSegments(String str) Given a string with comma delimiters to denote segment elements, this method will provide an iterator to iterate through the possible combinations.
MACAddress	toAddress() Produces the MACAddress corresponding to this MACAddressString.
String	toNormalizedString() provides a normalized String representation for the host identified by this HostIdentifierString instance
String	toString() Gives us the original string provided to the constructor.
void	validate() Validates this string is a valid address, and if not, throws an exception with a descriptive message indicating why it is not.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_ADDRESS

public static final MACAddressString EMPTY_ADDRESS

ALL_ADDRESSES

public static final MACAddressString ALL_ADDRESSES

Constructor Detail

MACAddressString

public MACAddressString(String addr)

Constructs an MACAddressString instance using the given String instance.

Parameters:

addr - the address in string format, in some valid MAC address form.

You can also alter the addresses to include ranges using the wildcards * and -, such as 1:*:1-2:3:4:5.

MACAddressString

public MACAddressString(String addr,
                        MACAddressStringParameters valOptions)

Parameters:

addr - the address in string format This constructor allows you to alter the default validation options.

MACAddressString

public MACAddressString(MACAddress address)

Method Detail

getValidationOptions

public MACAddressStringParameters getValidationOptions()

isPrefixed

public boolean isPrefixed()

Returns:

whether this address represents the set of all addresses with the same prefix

getPrefixLength

public Integer getPrefixLength()

Returns:

if this address is a valid prefixed address this returns that prefix length, otherwise returns null

isAllAddresses

public boolean isAllAddresses()

Returns:

whether the address represents the set all all valid MAC addresses

isEmpty

public boolean isEmpty()

Returns true if the address is empty (zero-length).

Returns:

isZero

public boolean isZero()

isValid

public boolean isValid()

Returns:

whether the address represents one of the accepted address types, which are: a MAC address, the address representing all addresses of all types, or an empty string. If it does not, and you want more details, call validate() and examine the thrown exception.

validate

public void validate()
              throws AddressStringException

Validates this string is a valid address, and if not, throws an exception with a descriptive message indicating why it is not.

Specified by:

validate in interface HostIdentifierString

Throws:

AddressStringException

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(MACAddressString other)

Specified by:

compareTo in interface Comparable<MACAddressString>

equals

public boolean equals(Object o)

Two MACAddressString objects are equal if they represent the same set of addresses. If a MACAddressString is invalid, it is equal to another address only if the other address was constructed from the same string.

Overrides:

equals in class Object

getAddress

public MACAddress getAddress()

Produces the MACAddress corresponding to this MACAddressString. If this object does not represent a specific MACAddress or a ranged MACAddress, or if the string used to construct this object is not a known format, null is returned. It is equivalent to toAddress() except for the fact that it does not throw AddressStringException for invalid address formats.

Specified by:

getAddress in interface HostIdentifierString

toAddress

public MACAddress toAddress()
                     throws AddressStringException,
                            IncompatibleAddressException

Produces the MACAddress corresponding to this MACAddressString. If this object does not represent a specific MACAddress or a ranged MACAddress, null is returned, which may be the case if this object represents the empty address string. If the string used to construct this object is not a known format then this method throws AddressStringException, unlike the equivalent method getAddress() which simply returns null in such cases. As long as this object represents a valid address (but not necessarily a specific address), this method does not throw.

Specified by:

toAddress in interface HostIdentifierString

Throws:

AddressStringException - if the address format is invalid

IncompatibleAddressException - if a valid address string representing multiple addresses cannot be represented

toNormalizedString

public String toNormalizedString()

Description copied from interface: HostIdentifierString

provides a normalized String representation for the host identified by this HostIdentifierString instance

Specified by:

toNormalizedString in interface HostIdentifierString

Returns:

the normalized string

toString

public String toString()

Gives us the original string provided to the constructor. For variations, call getAddress()/toAddress() and then use string methods on the address object.

Specified by:

toString in interface HostIdentifierString

Overrides:

toString in class Object

countDelimitedAddresses

public static int countDelimitedAddresses(String str)

Given a string with comma delimiters to denote segment elements, this method will count the possible combinations. For example, given "1,2:3:4,5:6:7:8", this method will return 4 for the possible combinations: "1:3:4:6:7:8", "1:3:5:6:7:8", "2:3:4:6:7:8" and "2:3:5:6:7:8"

Parameters:

str -

Returns:

parseDelimitedSegments

public static Iterator<String> parseDelimitedSegments(String str)

Given a string with comma delimiters to denote segment elements, this method will provide an iterator to iterate through the possible combinations. For example, given "1,2:3:4,5:6:7:8" this will iterate through "1:3:4:6:7:8", "1:3:5:6:7:8", "2:3:4:6:7:8" and "2:3:5:6:7:8" Another example: "1-2,3:4:5:6:7:8" will iterate through "1-2:4:5:6:7:8" and "1-3:4:5:6:7:8" This method will not validate strings. Each string produced can be validated using an instance of MACAddressString.

Parameters:

str -

Returns: