- 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:6This 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 ofMACAddressStringParameters
. When not using the constructor that takes aMACAddressStringParameters
, a default instance ofMACAddressStringParameters
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 = newMACAddressString
("1.2.3.4").getAddress()
;If your application takes user input IP addresses, you can validate with:
For empty addresses, bothtry {
MACAddress
address = new MACAddressString("1.2.3.4").toAddress()
; } catch(AddressStringException
e) { //e.getMessage() provides description of validation failure }toAddress()
andgetAddress()
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:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static MACAddressString
ALL_ADDRESSES
static MACAddressString
EMPTY_ADDRESS
-
Fields inherited from interface inet.ipaddr.HostIdentifierString
SEGMENT_VALUE_DELIMITER
-
-
Constructor Summary
Constructors Constructor Description MACAddressString(MACAddress address)
MACAddressString(java.lang.String addr)
Constructs an MACAddressString instance using the given String instance.MACAddressString(java.lang.String addr, MACAddressStringParameters valOptions)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description int
compareTo(MACAddressString other)
static int
countDelimitedAddresses(java.lang.String str)
Given a string with comma delimiters to denote segment elements, this method will count the possible combinations.boolean
equals(java.lang.Object o)
Two MACAddressString objects are equal if they represent the same set of addresses.MACAddress
getAddress()
Produces theMACAddress
corresponding to this MACAddressString.java.lang.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 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.MACAddress
toAddress()
Produces theMACAddress
corresponding to this MACAddressString.java.lang.String
toNormalizedString()
provides a normalized String representation for the host identified by this HostIdentifierString instancejava.lang.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.
-
-
-
Field Detail
-
EMPTY_ADDRESS
public static final MACAddressString EMPTY_ADDRESS
-
ALL_ADDRESSES
public static final MACAddressString ALL_ADDRESSES
-
-
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
-
getValidationOptions
public MACAddressStringParameters getValidationOptions()
-
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.
-
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 interfaceHostIdentifierString
- Throws:
AddressStringException
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
compareTo
public int compareTo(MACAddressString other)
- Specified by:
compareTo
in interfacejava.lang.Comparable<MACAddressString>
-
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 classjava.lang.Object
-
getAddress
public MACAddress getAddress()
Produces theMACAddress
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 totoAddress()
except for the fact that it does not throw AddressStringException for invalid address formats.- Specified by:
getAddress
in interfaceHostIdentifierString
-
toAddress
public MACAddress toAddress() throws AddressStringException, IncompatibleAddressException
Produces theMACAddress
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 methodgetAddress()
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 interfaceHostIdentifierString
- Throws:
AddressStringException
- if the address format is invalidIncompatibleAddressException
- 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 interfaceHostIdentifierString
- Returns:
- the normalized string
-
toString
public java.lang.String toString()
Gives us the original string provided to the constructor. For variations, callgetAddress()
/toAddress()
and then use string methods on the address object.- Specified by:
toString
in interfaceHostIdentifierString
- Overrides:
toString
in classjava.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:
-
-