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 and Description
    --- | ---
    `static int` | `BYTES` The number of bytes per dimension: 128 bits
    `static InetAddress` | `MAX_VALUE` The maximum value that an ip address can hold.
    `static InetAddress` | `MIN_VALUE` The minimum value that an ip address can hold.

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

      `fieldsData, name, tokenStream, type`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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)`
    `void` | `setInetAddressValue(InetAddress value)` Change the values of this field
    `String` | `toString()`

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

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

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

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

- - ### Field Detail

    - #### 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 Detail

    - #### 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 Detail

    - #### 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)

      Overrides:
        `setBytesValue` in class `Field`

    - #### toString

          public String toString()

      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

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.