diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txt index 9407dfad486..c2fe191c39c 100644 --- a/lucene/CHANGES.txt +++ b/lucene/CHANGES.txt @@ -131,6 +131,9 @@ API Changes New Features +* LUCENE-7738: Add new InetAddressRangeField for indexing and querying + InetAddress ranges. (Nick Knize) + * LUCENE-7449: Add CROSSES relation support to RangeFieldQuery. (Nick Knize) * LUCENE-7623: Add FunctionScoreQuery and FunctionMatchQuery (Alan Woodward, diff --git a/lucene/sandbox/src/java/org/apache/lucene/document/InetAddressRangeField.java b/lucene/sandbox/src/java/org/apache/lucene/document/InetAddressRangeField.java new file mode 100644 index 00000000000..c6ebc83d20f --- /dev/null +++ b/lucene/sandbox/src/java/org/apache/lucene/document/InetAddressRangeField.java @@ -0,0 +1,168 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.lucene.document; + +import java.net.InetAddress; + +import org.apache.lucene.document.RangeFieldQuery.QueryType; +import org.apache.lucene.search.Query; +import org.apache.lucene.util.BytesRef; +import org.apache.lucene.util.StringHelper; + +/** + * An indexed InetAddress Range Field + *

+ * This field indexes an {@code InetAddress} range defined as a min/max pairs. It is single + * dimension only (indexed as two 16 byte paired values). + *

+ * Multiple values are supported. + * + *

+ * This field defines the following static factory methods for common search operations over Ip Ranges + *

+ */ +public class InetAddressRangeField extends Field { + /** The number of bytes per dimension : sync w/ {@code InetAddressPoint} */ + public static final int BYTES = InetAddressPoint.BYTES; + + private static final FieldType TYPE; + static { + TYPE = new FieldType(); + TYPE.setDimensions(2, BYTES); + TYPE.freeze(); + } + + /** + * Create a new InetAddressRangeField from min/max value + * @param name field name. must not be null. + * @param min range min value; defined as an {@code InetAddress} + * @param max range max value; defined as an {@code InetAddress} + */ + public InetAddressRangeField(String name, final InetAddress min, final InetAddress max) { + super(name, TYPE); + setRangeValues(min, max); + } + + /** + * Change (or set) the min/max values of the field. + * @param min range min value; defined as an {@code InetAddress} + * @param max range max value; defined as an {@code InetAddress} + */ + public void setRangeValues(InetAddress min, InetAddress max) { + if (StringHelper.compare(BYTES, min.getAddress(), 0, max.getAddress(), 0) > 0) { + throw new IllegalArgumentException("min value cannot be greater than max value for range field (name=" + name + ")"); + } + final byte[] bytes; + if (fieldsData == null) { + bytes = new byte[BYTES*2]; + fieldsData = new BytesRef(bytes); + } else { + bytes = ((BytesRef)fieldsData).bytes; + } + encode(min, max, bytes); + } + + /** encode the min/max range into the provided byte array */ + private static void encode(final InetAddress min, final InetAddress max, final byte[] bytes) { + System.arraycopy(InetAddressPoint.encode(min), 0, bytes, 0, BYTES); + System.arraycopy(InetAddressPoint.encode(max), 0, bytes, BYTES, BYTES); + } + + /** encode the min/max range and return the byte array */ + private static byte[] encode(InetAddress min, InetAddress max) { + byte[] b = new byte[BYTES*2]; + encode(min, max, b); + return b; + } + + /** + * Create a query for matching indexed ip ranges that {@code INTERSECT} the defined range. + * @param field field name. must not be null. + * @param min range min value; provided as an {@code InetAddress} + * @param max range max value; provided as an {@code InetAddress} + * @return query for matching intersecting ranges (overlap, within, crosses, or contains) + * @throws IllegalArgumentException if {@code field} is null, {@code min} or {@code max} is invalid + */ + public static Query newIntersectsQuery(String field, final InetAddress min, final InetAddress max) { + return newRelationQuery(field, min, max, QueryType.INTERSECTS); + } + + /** + * Create a query for matching indexed ip ranges that {@code CONTAINS} the defined range. + * @param field field name. must not be null. + * @param min range min value; provided as an {@code InetAddress} + * @param max range max value; provided as an {@code InetAddress} + * @return query for matching intersecting ranges (overlap, within, crosses, or contains) + * @throws IllegalArgumentException if {@code field} is null, {@code min} or {@code max} is invalid + */ + public static Query newContainsQuery(String field, final InetAddress min, final InetAddress max) { + return newRelationQuery(field, min, max, QueryType.CONTAINS); + } + + /** + * Create a query for matching indexed ip ranges that are {@code WITHIN} the defined range. + * @param field field name. must not be null. + * @param min range min value; provided as an {@code InetAddress} + * @param max range max value; provided as an {@code InetAddress} + * @return query for matching intersecting ranges (overlap, within, crosses, or contains) + * @throws IllegalArgumentException if {@code field} is null, {@code min} or {@code max} is invalid + */ + public static Query newWithinQuery(String field, final InetAddress min, final InetAddress max) { + return newRelationQuery(field, min, max, QueryType.WITHIN); + } + + /** + * Create a query for matching indexed ip ranges that {@code CROSS} the defined range. + * @param field field name. must not be null. + * @param min range min value; provided as an {@code InetAddress} + * @param max range max value; provided as an {@code InetAddress} + * @return query for matching intersecting ranges (overlap, within, crosses, or contains) + * @throws IllegalArgumentException if {@code field} is null, {@code min} or {@code max} is invalid + */ + public static Query newCrossesQuery(String field, final InetAddress min, final InetAddress max) { + return newRelationQuery(field, min, max, QueryType.CROSSES); + } + + /** helper method for creating the desired relational query */ + private static Query newRelationQuery(String field, final InetAddress min, final InetAddress max, QueryType relation) { + return new RangeFieldQuery(field, encode(min, max), 1, relation) { + @Override + protected String toString(byte[] ranges, int dimension) { + return InetAddressRangeField.toString(ranges, dimension); + } + }; + } + + /** + * Returns the String representation for the range at the given dimension + * @param ranges the encoded ranges, never null + * @param dimension the dimension of interest (not used for this field) + * @return The string representation for the range at the provided dimension + */ + private static String toString(byte[] ranges, int dimension) { + byte[] min = new byte[BYTES]; + System.arraycopy(ranges, 0, min, 0, BYTES); + byte[] max = new byte[BYTES]; + System.arraycopy(ranges, BYTES, max, 0, BYTES); + return "[" + InetAddressPoint.decode(min) + " : " + InetAddressPoint.decode(max) + "]"; + } +} diff --git a/lucene/sandbox/src/test/org/apache/lucene/search/TestIpRangeFieldQueries.java b/lucene/sandbox/src/test/org/apache/lucene/search/TestIpRangeFieldQueries.java new file mode 100644 index 00000000000..1563584b817 --- /dev/null +++ b/lucene/sandbox/src/test/org/apache/lucene/search/TestIpRangeFieldQueries.java @@ -0,0 +1,220 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.lucene.search; + +import java.net.InetAddress; +import java.net.UnknownHostException; + +import org.apache.lucene.document.InetAddressRangeField; +import org.apache.lucene.util.StringHelper; + +/** + * Random testing for {@link InetAddressRangeField} + */ +public class TestIpRangeFieldQueries extends BaseRangeFieldQueryTestCase { + private static final String FIELD_NAME = "ipRangeField"; + + private IPVersion ipVersion; + + private enum IPVersion {IPv4, IPv6} + + @Override + protected Range nextRange(int dimensions) { + try { + InetAddress min = nextInetaddress(); + byte[] bMin = min.getAddress(); + InetAddress max = nextInetaddress(); + byte[] bMax = max.getAddress(); + if (StringHelper.compare(bMin.length, bMin, 0, bMax, 0) > 0) { + return new IpRange(max, min); + } + return new IpRange(min, max); + } catch (UnknownHostException e) { + e.printStackTrace(); + } + return null; + } + + /** return random IPv4 or IPv6 address */ + private InetAddress nextInetaddress() throws UnknownHostException { + byte[] b; + switch (ipVersion) { + case IPv4: + b = new byte[4]; + break; + case IPv6: + b = new byte[16]; + break; + default: + throw new IllegalArgumentException("incorrect IP version: " + ipVersion); + } + random().nextBytes(b); + return InetAddress.getByAddress(b); + } + + /** randomly select version across tests */ + private IPVersion ipVersion() { + return random().nextBoolean() ? IPVersion.IPv4 : IPVersion.IPv6; + } + + @Override + public void testRandomTiny() throws Exception { + ipVersion = ipVersion(); + super.testRandomTiny(); + } + + @Override + public void testMultiValued() throws Exception { + ipVersion = ipVersion(); + super.testRandomMedium(); + } + + @Override + public void testRandomMedium() throws Exception { + ipVersion = ipVersion(); + super.testMultiValued(); + } + + @Nightly + @Override + public void testRandomBig() throws Exception { + ipVersion = ipVersion(); + super.testRandomBig(); + } + + /** return random range */ + @Override + protected InetAddressRangeField newRangeField(Range r) { + return new InetAddressRangeField(FIELD_NAME, ((IpRange)r).min, ((IpRange)r).max); + } + + /** return random intersects query */ + @Override + protected Query newIntersectsQuery(Range r) { + return InetAddressRangeField.newIntersectsQuery(FIELD_NAME, ((IpRange)r).min, ((IpRange)r).max); + } + + /** return random contains query */ + @Override + protected Query newContainsQuery(Range r) { + return InetAddressRangeField.newContainsQuery(FIELD_NAME, ((IpRange)r).min, ((IpRange)r).max); + } + + /** return random within query */ + @Override + protected Query newWithinQuery(Range r) { + return InetAddressRangeField.newWithinQuery(FIELD_NAME, ((IpRange)r).min, ((IpRange)r).max); + } + + /** return random crosses query */ + @Override + protected Query newCrossesQuery(Range r) { + return InetAddressRangeField.newCrossesQuery(FIELD_NAME, ((IpRange)r).min, ((IpRange)r).max); + } + + /** encapsulated IpRange for test validation */ + private class IpRange extends Range { + InetAddress min; + InetAddress max; + + IpRange(InetAddress min, InetAddress max) { + this.min = min; + this.max = max; + } + + @Override + protected int numDimensions() { + return 1; + } + + @Override + protected InetAddress getMin(int dim) { + return min; + } + + @Override + protected void setMin(int dim, Object val) { + byte[] v = ((InetAddress)val).getAddress(); + + if (StringHelper.compare(v.length, min.getAddress(), 0, v, 0) < 0) { + max = (InetAddress)val; + } else { + min = (InetAddress) val; + } + } + + @Override + protected InetAddress getMax(int dim) { + return max; + } + + @Override + protected void setMax(int dim, Object val) { + byte[] v = ((InetAddress)val).getAddress(); + + if (StringHelper.compare(v.length, max.getAddress(), 0, v, 0) > 0) { + min = (InetAddress)val; + } else { + max = (InetAddress) val; + } + } + + @Override + protected boolean isEqual(Range o) { + IpRange other = (IpRange)o; + return this.min.equals(other.min) && this.max.equals(other.max); + } + + @Override + protected boolean isDisjoint(Range o) { + IpRange other = (IpRange)o; + byte[] bMin = min.getAddress(); + byte[] bMax = max.getAddress(); + return StringHelper.compare(bMin.length, bMin, 0, other.max.getAddress(), 0) > 0 || + StringHelper.compare(bMax.length, bMax, 0, other.min.getAddress(), 0) < 0; + } + + @Override + protected boolean isWithin(Range o) { + IpRange other = (IpRange)o; + byte[] bMin = min.getAddress(); + byte[] bMax = max.getAddress(); + return StringHelper.compare(bMin.length, bMin, 0, other.min.getAddress(), 0) >= 0 && + StringHelper.compare(bMax.length, bMax, 0, other.max.getAddress(), 0) <= 0; + } + + @Override + protected boolean contains(Range o) { + IpRange other = (IpRange)o; + byte[] bMin = min.getAddress(); + byte[] bMax = max.getAddress(); + return StringHelper.compare(bMin.length, bMin, 0, other.min.getAddress(), 0) <= 0 && + StringHelper.compare(bMax.length, bMax, 0, other.max.getAddress(), 0) >= 0; + } + + @Override + public String toString() { + StringBuilder b = new StringBuilder(); + b.append("Box("); + b.append(min.getHostAddress()); + b.append(" TO "); + b.append(max.getHostAddress()); + b.append(")"); + return b.toString(); + } + } +}