inet.ipaddr

Class MACAddressString

  • java.lang.Object
    • inet.ipaddr.MACAddressString
  • All Implemented Interfaces:
    HostIdentifierString, java.io.Serializable, java.lang.Comparable<MACAddressString>

    public class MACAddressString
extends java.lang.Object
implements HostIdentifierString, java.lang.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

    • Constructor Detail

      • MACAddressString

        public MACAddressString(java.lang.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(java.lang.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

      • isPrefixed

        public boolean isPrefixed()
        Returns:
        whether this address represents the set of all addresses with the same prefix

      • getPrefixLength

        public java.lang.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.

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals(java.lang.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 java.lang.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 java.lang.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 java.lang.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.
        Overrides:
        toString in class java.lang.Object

      • countDelimitedAddresses

        public static int countDelimitedAddresses(java.lang.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 java.util.Iterator<java.lang.String> parseDelimitedSegments(java.lang.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:
Skip navigation links