InetAddressPoint (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.document, class: InetAddressPoint

Package org.apache.lucene.document

# Class InetAddressPoint

java.lang.Object
org.apache.lucene.document.Field
org.apache.lucene.document.InetAddressPoint

All Implemented Interfaces:
  `IndexableField`

public class InetAddressPoint extends Field
An indexed 128-bit `InetAddress` field.

Finding all documents within a range at search time is efficient. Multiple values for the same field in one document is allowed.

This field defines static factory methods for creating common queries:

- `newExactQuery(String, InetAddress)` for matching an exact network address.
- `newPrefixQuery(String, InetAddress, int)` for matching a network based on CIDR prefix.
- `newRangeQuery(String, InetAddress, InetAddress)` for matching arbitrary network address ranges.
- `newSetQuery(String, InetAddress...)` for matching a set of network addresses.

This field supports both IPv4 and IPv6 addresses: IPv4 addresses are converted to IPv4-Mapped IPv6 Addresses: indexing `1.2.3.4` is the same as indexing `::FFFF:1.2.3.4`.

See Also:
  - `PointValues`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.document.Field

  `Field.Store`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BYTES`
  The number of bytes per dimension: 128 bits
  `static final InetAddress`
  `MAX_VALUE`
  The maximum value that an ip address can hold.
  `static final InetAddress`
  `MIN_VALUE`
  The minimum value that an ip address can hold.

  ### Fields inherited from class org.apache.lucene.document.Field

  `fieldsData, name, type`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `InetAddressPoint(String name, InetAddress point)`
  Creates a new InetAddressPoint, indexing the provided address.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static InetAddress`
  `decode(byte[] value)`
  Decodes InetAddress value from binary encoding
  `static byte[]`
  `encode(InetAddress value)`
  Encode InetAddress value into binary encoding
  `static Query`
  `newExactQuery(String field, InetAddress value)`
  Create a query for matching a network address.
  `static Query`
  `newPrefixQuery(String field, InetAddress value, int prefixLength)`
  Create a prefix query for matching a CIDR network range.
  `static Query`
  `newRangeQuery(String field, InetAddress lowerValue, InetAddress upperValue)`
  Create a range query for network addresses.
  `static Query`
  `newSetQuery(String field, InetAddress... values)`
  Create a query matching any of the specified 1D values.
  `static InetAddress`
  `nextDown(InetAddress address)`
  Return the `InetAddress` that compares immediately less than `address`.
  `static InetAddress`
  `nextUp(InetAddress address)`
  Return the `InetAddress` that compares immediately greater than `address`.
  `void`
  `setBytesValue(BytesRef bytes)`
  Expert: change the value of this field.
  `void`
  `setInetAddressValue(InetAddress value)`
  Change the values of this field
  `String`
  `toString()`
  Prints a Field for human consumption.

  ### Methods inherited from class org.apache.lucene.document.Field

  `binaryValue, fieldType, getCharSequenceValue, invertableType, name, numericValue, readerValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, storedValue, stringValue, tokenStream, tokenStreamValue`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### BYTES

    public static final int BYTES
    The number of bytes per dimension: 128 bits
    See Also:
      - Constant Field Values

  - ### MIN_VALUE

    public static final InetAddress MIN_VALUE
    The minimum value that an ip address can hold.

  - ### MAX_VALUE

    public static final InetAddress MAX_VALUE
    The maximum value that an ip address can hold.

- ## Constructor Details

  - ### InetAddressPoint

    public InetAddressPoint(String name, InetAddress point)
    Creates a new InetAddressPoint, indexing the provided address.
    Parameters:
      `name` - field name
      `point` - InetAddress value
    Throws:
      `IllegalArgumentException` - if the field name or value is null.

- ## Method Details

  - ### nextUp

    public static InetAddress nextUp(InetAddress address)
    Return the `InetAddress` that compares immediately greater than `address`.
    Throws:
      `ArithmeticException` - if the provided address is the `maximum ip address`

  - ### nextDown

    public static InetAddress nextDown(InetAddress address)
    Return the `InetAddress` that compares immediately less than `address`.
    Throws:
      `ArithmeticException` - if the provided address is the `minimum ip address`

  - ### setInetAddressValue

    public void setInetAddressValue(InetAddress value)
    Change the values of this field

  - ### setBytesValue

    public void setBytesValue(BytesRef bytes)
    Description copied from class: `Field`
    Expert: change the value of this field. See `Field.setStringValue(String)`.

    NOTE: the provided BytesRef is not copied so be sure not to change it until you're done with this field.

    Overrides:
      `setBytesValue` in class `Field`

  - ### toString

    public String toString()
    Description copied from class: `Field`
    Prints a Field for human consumption.
    Overrides:
      `toString` in class `Field`

  - ### encode

    public static byte[] encode(InetAddress value)
    Encode InetAddress value into binary encoding

  - ### decode

    public static InetAddress decode(byte[] value)
    Decodes InetAddress value from binary encoding

  - ### newExactQuery

    public static Query newExactQuery(String field, InetAddress value)
    Create a query for matching a network address.
    Parameters:
      `field` - field name. must not be `null`.
      `value` - exact value
    Returns:
      a query matching documents with this exact value
    Throws:
      `IllegalArgumentException` - if `field` is null.

  - ### newPrefixQuery

    public static Query newPrefixQuery(String field, InetAddress value, int prefixLength)
    Create a prefix query for matching a CIDR network range.
    Parameters:
      `field` - field name. must not be `null`.
      `value` - any host address
      `prefixLength` - the network prefix length for this address. This is also known as the subnet mask in the context of IPv4 addresses.
    Returns:
      a query matching documents with addresses contained within this network
    Throws:
      `IllegalArgumentException` - if `field` is null, or prefixLength is invalid.

  - ### newRangeQuery

    public static Query newRangeQuery(String field, InetAddress lowerValue, InetAddress upperValue)
    Create a range query for network addresses.

    You can have half-open ranges (which are in fact </≤ or >/≥ queries) by setting `lowerValue = InetAddressPoint.MIN_VALUE` or `upperValue = InetAddressPoint.MAX_VALUE`.

    Ranges are inclusive. For exclusive ranges, pass `InetAddressPoint#nextUp(lowerValue)` or `InetAddressPoint#nexDown(upperValue)`.

    Parameters:
      `field` - field name. must not be `null`.
      `lowerValue` - lower portion of the range (inclusive). must not be null.
      `upperValue` - upper portion of the range (inclusive). must not be null.
    Returns:
      a query matching documents within this range.
    Throws:
      `IllegalArgumentException` - if `field` is null, `lowerValue` is null, or `upperValue` is null

  - ### newSetQuery

    public static Query newSetQuery(String field, InetAddress... values)
    Create a query matching any of the specified 1D values. This is the points equivalent of `TermsQuery`.
    Parameters:
      `field` - field name. must not be `null`.
      `values` - all values to match