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.

Author:
sfoley
See Also:

  • Field Details

  • Constructor Details

    • 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 Details

    • 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
      Returns:

    • 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: