- All Implemented Interfaces:
HostIdentifierString
,Serializable
,Comparable<MACAddressString>
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 Summary
FieldsFields inherited from interface inet.ipaddr.HostIdentifierString
SEGMENT_VALUE_DELIMITER
-
Constructor Summary
ConstructorsConstructorDescriptionMACAddressString
(MACAddress address) MACAddressString
(String addr) Constructs an MACAddressString instance using the given String instance.MACAddressString
(String addr, MACAddressStringParameters valOptions) -
Method Summary
Modifier and TypeMethodDescriptionint
compareTo
(MACAddressString other) static int
Given a string with comma delimiters to denote segment elements, this method will count the possible combinations.boolean
Two MACAddressString objects are equal if they represent the same set of addresses.Produces theMACAddress
corresponding to this MACAddressString.int
hashCode()
boolean
boolean
isEmpty()
Returns true if the address is empty (zero-length).boolean
boolean
isValid()
boolean
isZero()
Given a string with comma delimiters to denote segment elements, this method will provide an iterator to iterate through the possible combinations.Produces theMACAddress
corresponding to this MACAddressString.provides a normalized String representation for the host identified by this HostIdentifierString instancetoString()
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 Details
-
EMPTY_ADDRESS
-
ALL_ADDRESSES
-
-
Constructor Details
-
MACAddressString
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
- Parameters:
addr
- the address in string format This constructor allows you to alter the default validation options.
-
MACAddressString
-
-
Method Details
-
getValidationOptions
-
isPrefixed
public boolean isPrefixed()- Returns:
- whether this address represents the set of all addresses with the same prefix
-
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
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() -
compareTo
- Specified by:
compareTo
in interfaceComparable<MACAddressString>
-
equals
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. -
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
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
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
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 classObject
- Returns:
-
countDelimitedAddresses
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
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:
-