Index: contrib/spatial/src/java/org/apache/lucene/spatial/geohash/GeoHashDistanceFilter.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/geohash/GeoHashDistanceFilter.java (revision 833867) +++ contrib/spatial/src/java/org/apache/lucene/spatial/geohash/GeoHashDistanceFilter.java Wed Jan 20 14:35:46 CET 2010 @@ -31,8 +31,10 @@ /**

NOTE: This API is still in * flux and might change in incompatible ways in the next * release. + * + * @deprecated This class has been replaced by DistanceFilter and GeoHashPointDecoder. It will be removed. */ - +@Deprecated public class GeoHashDistanceFilter extends DistanceFilter { /** Index: contrib/spatial/src/java/org/apache/lucene/spatial/distance/GeoHashPointDecoder.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/distance/GeoHashPointDecoder.java Wed Jan 20 15:06:23 CET 2010 +++ contrib/spatial/src/java/org/apache/lucene/spatial/distance/GeoHashPointDecoder.java Wed Jan 20 15:06:23 CET 2010 @@ -0,0 +1,65 @@ +/** 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.spatial.distance; + +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.search.FieldCache; +import org.apache.lucene.spatial.geohash.GeoHashUtils; +import org.apache.lucene.spatial.geometry.Point; + +import java.io.IOException; + +/** + * PointDecoder which uses {@link org.apache.lucene.spatial.geohash.GeoHashUtils#decode(String)} to decode the point + * data for a document. + */ +public class GeoHashPointDecoder implements PointDecoder { + + private final String geoHashField; + + /** + * Creates a new GeoHashPointDecoder that decodes the data taken from the given field + * + * @param geoHashField Name of the field in documents where the encoded geohash data is + */ + public GeoHashPointDecoder(String geoHashField) { + this.geoHashField = geoHashField; + } + + /** + * {@inheritDoc} + */ + public Point getPoint(int docId, IndexReader reader) throws IOException { + double[] coords = GeoHashUtils.decode(getGeoHash(docId, reader)); + return new Point(coords[0], coords[1]); + } + + // ================================================= Helper Methods ================================================ + + /** + * Retrieves the geohash for the document through the IndexReader + * + * @param docId ID of the document whose geohash is to be retrieved + * @param reader IndexReader through which the hash can be retrieved + * @return Geohash for the document + * @throws IOException Can be thrown while interacting with the index + */ + String getGeoHash(int docId, IndexReader reader) throws IOException { + FieldCache.StringIndex stringIndex = FieldCache.DEFAULT.getStringIndex(reader, geoHashField); + return stringIndex.lookup[stringIndex.order[docId]]; + } +} Index: contrib/spatial/src/test/org/apache/lucene/spatial/distance/GeoHashPointDecoderTest.java =================================================================== --- contrib/spatial/src/test/org/apache/lucene/spatial/distance/GeoHashPointDecoderTest.java Wed Jan 20 15:08:50 CET 2010 +++ contrib/spatial/src/test/org/apache/lucene/spatial/distance/GeoHashPointDecoderTest.java Wed Jan 20 15:08:50 CET 2010 @@ -0,0 +1,49 @@ +/** 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.spatial.distance; + +import junit.framework.TestCase; +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.spatial.geometry.Point; + +import java.io.IOException; + +/** + * Tests for {@link org.apache.lucene.spatial.distance.GeoHashPointDecoder} + */ +public class GeoHashPointDecoderTest extends TestCase { + + /** + * Pass condition: The geohash for the document is retrieved and decoded into a Point + * + * @throws IOException Can be thrown while interacting with the index + */ + public void testGetPoint() throws IOException { + GeoHashPointDecoder pointDecoder = new GeoHashPointDecoder("geohash") { + + @Override + String getGeoHash(int docId, IndexReader reader) throws IOException { + return "ezs42e44yx96"; + } + }; + + Point point = pointDecoder.getPoint(0, null); + + assertEquals(42.6, point.getX(), 0.00001D); + assertEquals(-5.6, point.getY(), 0.00001D); + } +} Index: contrib/spatial/src/java/org/apache/lucene/spatial/distance/SimpleDocumentDistanceSource.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/distance/SimpleDocumentDistanceSource.java Wed Jan 20 15:08:44 CET 2010 +++ contrib/spatial/src/java/org/apache/lucene/spatial/distance/SimpleDocumentDistanceSource.java Wed Jan 20 15:08:44 CET 2010 @@ -0,0 +1,53 @@ +/** 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.spatial.distance; + +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.spatial.geometry.DistanceUnits; +import org.apache.lucene.spatial.geometry.GeoDistanceCalculator; +import org.apache.lucene.spatial.geometry.Point; + +import java.io.IOException; + +/** + * Simple implementation of {@link DocumentDistanceSource} which calculates the distance eachtime without any caching. + */ +public class SimpleDocumentDistanceSource implements DocumentDistanceSource { + + private final PointDecoder pointDecoder; + private final GeoDistanceCalculator distanceCalculator; + + /** + * Creates a new SimpleDocumentDistanceSource which uses the given PointDecoder to retrieve the Points for documents, + * and the given GeoDistanceCalculator to calculate the distance + * + * @param pointDecoder PointDecoder to use to retrieve Points for documents + * @param distanceCalculator GeoDistanceCalculator to use to calculate the actual distances + */ + public SimpleDocumentDistanceSource(PointDecoder pointDecoder, GeoDistanceCalculator distanceCalculator) { + this.pointDecoder = pointDecoder; + this.distanceCalculator = distanceCalculator; + } + + /** + * {@inheritDoc} + */ + public double getDocumentDistance(int docId, Point src, IndexReader indexReader, DistanceUnits units) throws IOException { + Point docPoint = pointDecoder.getPoint(docId, indexReader); + return distanceCalculator.calculate(src.getX(), src.getY(), docPoint.getX(), docPoint.getY(), units); + } +} Index: contrib/spatial/src/java/org/apache/lucene/spatial/distance/NoOpDistanceFilter.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/distance/NoOpDistanceFilter.java Sun Jan 17 15:37:16 CET 2010 +++ contrib/spatial/src/java/org/apache/lucene/spatial/distance/NoOpDistanceFilter.java Sun Jan 17 15:37:16 CET 2010 @@ -0,0 +1,44 @@ +/** + * 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.spatial.distance; + +import org.apache.lucene.index.IndexReader; + +import java.io.IOException; +import java.util.BitSet; +import java.util.Collections; +import java.util.Map; + +/** + * Implementation of {@link DistanceFilter} that does no actual filtering. This means that there can always be a DistanceFilter + * instantiated, but that the actual process of filtering documents by their distance, which is a computationally expensive + * process, doesn't always have to occur. + * + *

NOTE: This API is still in flux and might change in incompatible ways in the next release. + */ +public class NoOpDistanceFilter implements DistanceFilter { + + /** + * Executes no filtering. Simply returns the given BitSet + *

+ * {@inheritDoc} + */ + public BitSet bits(IndexReader reader, BitSet bits) throws IOException { + return bits; + } +} Index: contrib/spatial/src/test/org/apache/lucene/spatial/distance/TestThreadedDistanceFilter.java =================================================================== --- contrib/spatial/src/test/org/apache/lucene/spatial/distance/TestThreadedDistanceFilter.java Wed Jan 20 15:05:00 CET 2010 +++ contrib/spatial/src/test/org/apache/lucene/spatial/distance/TestThreadedDistanceFilter.java Wed Jan 20 15:05:00 CET 2010 @@ -0,0 +1,264 @@ +/** + * 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.spatial.distance; + +import junit.framework.TestCase; +import org.apache.lucene.analysis.standard.StandardAnalyzer; +import org.apache.lucene.document.Document; +import org.apache.lucene.document.Field; +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.index.IndexWriter; +import org.apache.lucene.spatial.geometry.ArcGeoDistanceCalculator; +import org.apache.lucene.spatial.geometry.DistanceUnits; +import org.apache.lucene.spatial.geometry.GeoDistanceCalculator; +import org.apache.lucene.spatial.geometry.Point; +import org.apache.lucene.store.Directory; +import org.apache.lucene.store.RAMDirectory; +import org.apache.lucene.util.Version; + +import java.io.IOException; +import java.util.*; +import java.util.concurrent.*; + +/** + * Tests for {@link TestThreadedDistanceFilter} + */ +public class TestThreadedDistanceFilter extends TestCase { + + private final List testPoints = Arrays.asList(new Point(4.53, 30.61), new Point(4.51, 31.01), new Point(5.69, 40.89)); + + private final PointDecoder pointDecoder = new PointDecoder() { + + public Point getPoint(int docId, IndexReader reader) throws IOException { + return testPoints.get(docId); + } + }; + + private Directory directory; + + /** + * Creates a new in-memory Directory containing an index with a document for each point in {@link #testPoints} + * + * @throws IOException Can be thrown creating the index + */ + public void setUp() throws IOException { + directory = new RAMDirectory(); + IndexWriter indexWriter = new IndexWriter(directory, new StandardAnalyzer(Version.LUCENE_CURRENT), IndexWriter.MaxFieldLength.UNLIMITED); + for (int i = 0; i < testPoints.size(); i++) { + addDocument(indexWriter, i); + } + indexWriter.commit(); + indexWriter.close(); + } + + /** + * Closes the Directory + * + * @throws IOException Can be thrown closing the Directory + */ + public void tearDown() throws IOException { + directory.close(); + } + + /** + * Adds a Document with a single field "id" with the given id as its value + * + * @param indexWriter IndexWriter to write the document too + * @param id ID that the document will have + * @throws IOException Can be thrown while writing document to the index + */ + private void addDocument(IndexWriter indexWriter, int id) throws IOException { + Document document = new Document(); + document.add(new Field("id", String.valueOf(id), Field.Store.YES, Field.Index.ANALYZED)); + indexWriter.addDocument(document); + } + + /** + * Pass condition: The latitude/longitude values have to be passed to the GeoDistanceCalculator in the correct order + * + * @throws IOException Can be thrown reading from the index + */ + public void testGeoCalculation_correctArgumentPassing() throws IOException { + StubGeoDistanceCalculator distanceCalculator = new StubGeoDistanceCalculator(); + ExecutorService executorService = Executors.newFixedThreadPool(1); + + DocumentDistanceSource distanceSource = new SimpleDocumentDistanceSource(pointDecoder, distanceCalculator); + + ThreadedDistanceFilter filter = + new ThreadedDistanceFilter(new Point(4.51, 31.01), 10, DistanceUnits.KILOMETERS, distanceSource, executorService, 1); + + IndexReader indexReader = IndexReader.open(directory); + BitSet bitSet = new BitSet(1); + bitSet.set(0); + filter.bits(indexReader, bitSet); + + assertEquals(4.51, distanceCalculator.getSourceLatitude(), 0); + assertEquals(31.01, distanceCalculator.getSourceLongitude(), 0); + assertEquals(4.53, distanceCalculator.getTargetLatitude(), 0); + assertEquals(30.61, distanceCalculator.getTargetLongitude(), 0); + + indexReader.close(); + } + + /** + * Pass condition: 2 threads with the correct start and end indexes are created based on the BitSet given in the method + * call, and the number of threads that were requested. + * + * @throws java.io.IOException Can be thrown while reading from the index + */ + public void testBits() throws IOException { + ExecutorService executorService = new ThreadPoolExecutor(2, 6, 8, TimeUnit.SECONDS, new LinkedBlockingQueue()); + DocumentDistanceSource distanceSource = new SimpleDocumentDistanceSource(pointDecoder, new ArcGeoDistanceCalculator()); + + BitSet bitSet = new BitSet(13); + bitSet.set(2, 6); + bitSet.set(8, 9); + bitSet.set(11); + + final List infoList = Collections.synchronizedList(new ArrayList()); + ThreadedDistanceFilter distanceFilter = new ThreadedDistanceFilter(new Point(4.52, 30.81), 30, DistanceUnits.MILES, distanceSource, executorService, 2) { + + @Override + protected IterationResult iterate(BitSet originalBitSet, int start, int end, int size, IndexReader reader) { + infoList.add(new IterateCallInfo(start, end, size)); + return new IterationResult(new BitSet()); + } + }; + + IndexReader indexReader = IndexReader.open(directory); + + distanceFilter.bits(indexReader, bitSet); + + assertEquals(2, infoList.size()); + + Collections.sort(infoList, new Comparator() { + public int compare(IterateCallInfo info1, IterateCallInfo info2) { + return info1.getStart() - info2.getStart(); + } + }); + + IterateCallInfo callInfo = infoList.get(0); + assertEquals(0, callInfo.getStart()); + assertEquals(6, callInfo.getEnd()); + assertEquals(6, callInfo.getSize()); + + callInfo = infoList.get(1); + assertEquals(6, callInfo.getStart()); + assertEquals(12, callInfo.getEnd()); + assertEquals(6, callInfo.getSize()); + + indexReader.close(); + } + + /** + * Pass condition: Of the 3 documents with points, 1 is outside of the radius and should be filtered out, 1 has been + * deleted so it should also be filtered out, leaving just 1 that passes the filter. Its distance should be recorded + * in the calculated distances of the filter + * + * @throws IOException Can be thrown when interactin with the index + */ + public void testIterate() throws IOException { + IndexReader indexReader = IndexReader.open(directory, false); + indexReader.deleteDocument(1); + + BitSet bitSet = new BitSet(2); + bitSet.set(0); + bitSet.set(1); + bitSet.set(2); + + MapCachingDocumentDistanceSource distanceSource = new MapCachingDocumentDistanceSource(new SimpleDocumentDistanceSource(pointDecoder, new ArcGeoDistanceCalculator())); + + ThreadedDistanceFilter distanceFilter = new ThreadedDistanceFilter(new Point(4.52, 30.81), 30, DistanceUnits.MILES, distanceSource, null, 0); + + ThreadedDistanceFilter.IterationResult result = distanceFilter.iterate(bitSet, 0, 3, 3, indexReader); + + assertNotNull(result); + + BitSet resultingBitSet = result.getBitSet(); + assertNotNull(resultingBitSet); + assertTrue(resultingBitSet.get(0)); + assertFalse(resultingBitSet.get(1)); + assertFalse(resultingBitSet.get(2)); + + assertEquals(2, distanceSource.getCachedDistances().size()); + + indexReader.close(); + } + + // ================================================= Inner Classes ================================================= + + private static class IterateCallInfo { + + private final int start; + private final int end; + private final int size; + + private IterateCallInfo(int start, int end, int size) { + this.start = start; + this.end = end; + this.size = size; + } + + public int getStart() { + return start; + } + + public int getEnd() { + return end; + } + + public int getSize() { + return size; + } + } + + /** + * Dummy implementation. Used for unit test to assure that the given arguments to a distance calculator are given correctly . + */ + class StubGeoDistanceCalculator implements GeoDistanceCalculator { + + private double sourceLatitude; + private double sourceLongitude; + private double targetLatitude; + private double targetLongitude; + + public double calculate(double sourceLatitude, double sourceLongitude, double targetLatitude, double targetLongitude, DistanceUnits unit) { + this.sourceLatitude = sourceLatitude; + this.sourceLongitude = sourceLongitude; + this.targetLatitude = targetLatitude; + this.targetLongitude = targetLongitude; + return 0.0; + } + + public double getSourceLatitude() { + return sourceLatitude; + } + + public double getSourceLongitude() { + return sourceLongitude; + } + + public double getTargetLatitude() { + return targetLatitude; + } + + public double getTargetLongitude() { + return targetLongitude; + } + } +} Index: contrib/spatial/src/java/org/apache/lucene/spatial/distance/LatLngPointDecoder.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/distance/LatLngPointDecoder.java Wed Jan 20 15:08:24 CET 2010 +++ contrib/spatial/src/java/org/apache/lucene/spatial/distance/LatLngPointDecoder.java Wed Jan 20 15:08:24 CET 2010 @@ -0,0 +1,66 @@ +/** 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.spatial.distance; + +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.search.FieldCache; +import org.apache.lucene.spatial.geometry.Point; + +import java.io.IOException; + +/** + * PointDecoder that uses latitude and longitude data that is stored in two separate fields. + */ +public class LatLngPointDecoder implements PointDecoder { + + private final String latField; + private final String lngField; + + /** + * Creates a new LatLngPointDecoder that uses the data found in the given latitude and longitude fields + * + * @param latField Name of the field in documents containing laitutde data + * @param lngField Name of the field in documents containing longitude data + */ + public LatLngPointDecoder(String latField, String lngField) { + this.latField = latField; + this.lngField = lngField; + } + + /** + * {@inheritDoc} + */ + public Point getPoint(int docId, IndexReader reader) throws IOException { + double[] latValues = getFieldValues(latField, reader); + double[] lngValues = getFieldValues(lngField, reader); + return new Point(latValues[docId], lngValues[docId]); + } + + // ================================================= Helper Methods ================================================ + + /** + * Gets the values for the given field from the IndexReader + * + * @param field Field whose values are to be retrieved + * @param indexReader IndexReader from where the values are to be retrieved + * @return Values for the field + * @throws IOException Can be thrown while interacting with the index + */ + double[] getFieldValues(String field, IndexReader indexReader) throws IOException { + return FieldCache.DEFAULT.getDoubles(indexReader, field, FieldCache.NUMERIC_UTILS_DOUBLE_PARSER); + } +} Index: contrib/spatial/src/java/org/apache/lucene/spatial/distance/PointDecoder.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/distance/PointDecoder.java Wed Jan 20 15:08:44 CET 2010 +++ contrib/spatial/src/java/org/apache/lucene/spatial/distance/PointDecoder.java Wed Jan 20 15:08:44 CET 2010 @@ -0,0 +1,38 @@ +/** 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.spatial.distance; + +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.spatial.geometry.Point; + +import java.io.IOException; + +/** + * PointDecoders decode the representation of a point for a document into instances of {@link org.apache.lucene.spatial.geometry.Point} + */ +public interface PointDecoder { + + /** + * Retrieves the Point for the document with the given ID + * + * @param docId ID of the document whose point is to be retrieved + * @param reader IndexReader for communicating with the index + * @return Point representation of the decoded data + * @throws IOException Can be thrown while interacting with the index + */ + Point getPoint(int docId, IndexReader reader) throws IOException; +} Index: contrib/spatial/src/java/org/apache/lucene/spatial/distance/DistanceFilter.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/distance/DistanceFilter.java Sun Jan 17 15:33:25 CET 2010 +++ contrib/spatial/src/java/org/apache/lucene/spatial/distance/DistanceFilter.java Sun Jan 17 15:33:25 CET 2010 @@ -0,0 +1,44 @@ +/** 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.spatial.distance; + +import org.apache.lucene.index.IndexReader; + +import java.io.IOException; +import java.util.BitSet; +import java.util.Map; + +/** + * DistanceFilter is responsible for filtering out documents from an existing BitSet, based on their calculated distance + * from the central point. Because the costing of calculating distances for documents is relatively high, this filter + * uses an existing BitSet, which will have been created another filter previously. As such, this is technically not + * a Lucene Filter. + * + *

NOTE: This API is still in flux and might change in incompatible ways in the next release. + */ +public interface DistanceFilter { + + /** + * Filters the documents from the given IndexReader who have bits set in the given BitSet. + * + * @param reader IndexReader from where the documents will be read from + * @param bits BitSet containing bits indicating which documents should be considered to be filtered out + * @return BitSet with bits set representing those documents that passed the filter + * @throws java.io.IOException Can be thrown while reading from the IndexReader + */ + BitSet bits(IndexReader reader, BitSet bits) throws IOException; +} Index: contrib/spatial/src/java/org/apache/lucene/spatial/distance/MapCachingDocumentDistanceSource.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/distance/MapCachingDocumentDistanceSource.java Wed Jan 20 15:08:29 CET 2010 +++ contrib/spatial/src/java/org/apache/lucene/spatial/distance/MapCachingDocumentDistanceSource.java Wed Jan 20 15:08:29 CET 2010 @@ -0,0 +1,69 @@ +/** 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.spatial.distance; + +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.spatial.geometry.DistanceUnits; +import org.apache.lucene.spatial.geometry.Point; + +import java.io.IOException; +import java.util.HashMap; +import java.util.Map; + +/** + * Implementation of {@link DocumentDistanceSource} which caches calculated distances in a Map. Note, the caching does + * not take into account the IndexReader, nor does it apply any multi-thread synchronisation. + */ +public class MapCachingDocumentDistanceSource implements DocumentDistanceSource { + + private final DocumentDistanceSource source; + private final Map cachedDistances = new HashMap(); + + /** + * Creates a new MapCachingDocumentDistanceSource that caches distances from the given DocumentDistanceSource + * + * @param source DocumentDistanceSource whose calculated distances will be cached + */ + public MapCachingDocumentDistanceSource(DocumentDistanceSource source) { + this.source = source; + } + + /** + * {@inheritDoc} + */ + public double getDocumentDistance(int docId, Point src, IndexReader indexReader, DistanceUnits units) throws IOException { + Double cachedDistance = cachedDistances.get(docId); + if (cachedDistance != null) { + return cachedDistance; + } + + double calculatedDistance = source.getDocumentDistance(docId, src, indexReader, units); + cachedDistances.put(docId, calculatedDistance); + return calculatedDistance; + } + + // ================================================= Getters / Setters ============================================= + + /** + * Returns the cached distances + * + * @return Cached distances + */ + public Map getCachedDistances() { + return cachedDistances; + } +} Index: contrib/spatial/src/java/org/apache/lucene/spatial/distance/ThreadedDistanceFilter.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/distance/ThreadedDistanceFilter.java Sun Jan 17 15:35:42 CET 2010 +++ contrib/spatial/src/java/org/apache/lucene/spatial/distance/ThreadedDistanceFilter.java Sun Jan 17 15:35:42 CET 2010 @@ -0,0 +1,175 @@ +/** + * 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.spatial.distance; + +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.spatial.geometry.DistanceUnits; +import org.apache.lucene.spatial.geometry.Point; + +import java.io.IOException; +import java.util.*; +import java.util.concurrent.Callable; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Future; + +/** + * Implementation of {@link DistanceFilter} that uses multiple threads to iterate in parallel, over the BitSet to be filtered. + *

+ * To manage the threads, an ExecutorService is used, which allows users of this class to have fine grained control over + * how many threads should be created, and what to do when there isn't any threads left in the pool. + * + *

NOTE: This API is still in flux and might change in incompatible ways in the next release. + */ +public class ThreadedDistanceFilter implements DistanceFilter { + + private final Point centralPoint; + private final double radius; + private final DistanceUnits unit; + private final DocumentDistanceSource documentDistanceSource; + + private final ExecutorService executorService; + private final int threadCount; + + /** + * Creates a new ThreadedDistanceFilter that will filter out documents that are outside of the given radius of the + * central point defined by the given latitude and longitude + * + * @param centralPoint Point at the centre of the search + * @param radius Radius that documents must be within from the central point to pass the filter + * @param unit Unit of distance the radius is in + * @param distanceSource DocumentDistanceSource from where the distances for documents from the central point, will be + * retrieved from + * @param executorService ExecutorService which will manage the execution of the threads + * @param threadCount Number of threads that the filter should try to split its work across + */ + public ThreadedDistanceFilter( + Point centralPoint, + double radius, + DistanceUnits unit, + DocumentDistanceSource distanceSource, + ExecutorService executorService, + int threadCount) { + this.centralPoint = centralPoint; + this.radius = radius; + this.unit = unit; + this.documentDistanceSource = distanceSource; + this.executorService = executorService; + this.threadCount = threadCount; + } + + /** + * {@inheritDoc} + */ + public BitSet bits(final IndexReader reader, final BitSet bits) throws IOException { + int maxLength = bits.length(); + int threadSize = maxLength / threadCount; + List> tasks = new ArrayList>(); + + for (int i = 0; i < threadCount; i++) { + final int start = i * threadSize; + // if the last batch of documents has been reached, then maxLength should be end + final int end = (i == threadCount - 1) ? maxLength : Math.min((i + 1) * threadSize, maxLength); + tasks.add(new Callable() { + public IterationResult call() throws Exception { + return iterate(bits, start, end, end - start, reader); + } + }); + } + + BitSet result = new BitSet(bits.cardinality()); + + try { + List> results = executorService.invokeAll(tasks); + for (Future resultFuture : results) { + IterationResult iterationResult = resultFuture.get(); + result.or(iterationResult.getBitSet()); + } + } catch (InterruptedException ie) { + throw new RuntimeException("InterruptedException thrown while executing tasks", ie); + } catch (ExecutionException ee) { + throw new RuntimeException("ExecutionException thrown while retrieving results of tasks", ee); + } + + return result; + } + + // ================================================ Helper Methods ================================================= + + /** + * Iterates over the set bits in the given BitSet from the given start to end range, calculating the distance of the + * documents and determining which are within the distance radius of the central point. + * + * @param originalBitSet BitSet which has bits set identifying which documents should be checked to see if their + * distance falls within the radius + * @param start Index in the BitSet that the method will start at + * @param end Index in the BitSet that the method will stop at + * @param size Size the the resulting BitSet should be created at (most likely end - start) + * @param reader IndexReader for checking if the document has been deleted + * @return IterationResult containing all the results of the method. + * @throws IOException Can be thrown while interacting with the index + */ + protected IterationResult iterate(BitSet originalBitSet, int start, int end, int size, IndexReader reader) throws IOException { + BitSet bitSet = new BitSet(size); + + int docId = originalBitSet.nextSetBit(start); + while (docId != -1 && docId < end) { + if (reader.isDeleted(docId)) { + docId = originalBitSet.nextSetBit(docId + 1); + continue; + } + + double distance = documentDistanceSource.getDocumentDistance(docId, centralPoint, reader, unit); + if (distance < radius) { + bitSet.set(docId); + } + + docId = originalBitSet.nextSetBit(docId + 1); + } + return new IterationResult(bitSet); + } + + // ================================================= Inner Classes ================================================= + + /** + * Wrapper of the results from {@link ThreadedDistanceFilter#iterate(BitSet, int, int, int, IndexReader)}. + * This allows the method to operate in almost total isolation in separate threads. + */ + protected class IterationResult { + + private BitSet bitSet; + + /** + * Creates a new IterationResult that wraps the given BitSet + * + * @param bitSet BitSet to wrap + */ + public IterationResult(BitSet bitSet) { + this.bitSet = bitSet; + } + + /** + * Returns the wrapped BitSet + * + * @return Wrapped BitSet + */ + public BitSet getBitSet() { + return bitSet; + } + } +} Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/LatLongDistanceFilter.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/tier/LatLongDistanceFilter.java (revision 833867) +++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/LatLongDistanceFilter.java Fri Dec 18 14:53:45 CET 2009 @@ -29,7 +29,10 @@ *

NOTE: This API is still in * flux and might change in incompatible ways in the next * release. + * + * @deprecated This class has been made replaced by DistanceFilter and LatLngLocationDataSetFactory. It will be removed. */ +@Deprecated public class LatLongDistanceFilter extends DistanceFilter { /** Index: contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceFilter.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceFilter.java (revision 833867) +++ contrib/spatial/src/java/org/apache/lucene/spatial/tier/DistanceFilter.java Fri Dec 18 14:53:40 CET 2009 @@ -29,7 +29,10 @@ *

NOTE: This API is still in * flux and might change in incompatible ways in the next * release. + * + * @deprecated This class has been replaced by DistanceFilter and its implementations. It will be removed. */ +@Deprecated public abstract class DistanceFilter extends Filter { final protected Filter startingFilter; Index: contrib/spatial/src/test/org/apache/lucene/spatial/distance/LatLngPointDecoderTest.java =================================================================== --- contrib/spatial/src/test/org/apache/lucene/spatial/distance/LatLngPointDecoderTest.java Wed Jan 20 15:08:54 CET 2010 +++ contrib/spatial/src/test/org/apache/lucene/spatial/distance/LatLngPointDecoderTest.java Wed Jan 20 15:08:54 CET 2010 @@ -0,0 +1,55 @@ +/** 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.spatial.distance; + +import junit.framework.TestCase; +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.spatial.geometry.Point; + +import java.io.IOException; + +/** + * Tests for {@link org.apache.lucene.spatial.distance.LatLngPointDecoder} + */ +public class LatLngPointDecoderTest extends TestCase { + + /** + * Pass condition: The latitude and longitude for document 0 is correctly decoded from the lat and lng fields + * + * @throws IOException Can be thrown while interacting with the index + */ + public void testGetPoint() throws IOException { + LatLngPointDecoder pointDecoder = new LatLngPointDecoder("lat", "lng") { + + @Override + double[] getFieldValues(String field, IndexReader indexReader) { + if ("lat".equals(field)) { + return new double[]{40.3, 54.2}; + } else if ("lng".equals(field)) { + return new double[]{3.21, 9.65}; + } else { + throw new IllegalArgumentException("Unexpected field name: " + field); + } + } + }; + + Point point = pointDecoder.getPoint(0, null); + + assertEquals(40.3, point.getX(), 0D); + assertEquals(3.21, point.getY(), 0D); + } +} Index: contrib/spatial/src/java/org/apache/lucene/spatial/distance/DocumentDistanceSource.java =================================================================== --- contrib/spatial/src/java/org/apache/lucene/spatial/distance/DocumentDistanceSource.java Wed Jan 20 15:05:37 CET 2010 +++ contrib/spatial/src/java/org/apache/lucene/spatial/distance/DocumentDistanceSource.java Wed Jan 20 15:05:37 CET 2010 @@ -0,0 +1,25 @@ +package org.apache.lucene.spatial.distance; + +import org.apache.lucene.index.IndexReader; +import org.apache.lucene.spatial.geometry.DistanceUnits; +import org.apache.lucene.spatial.geometry.Point; + +import java.io.IOException; + +/** + * Single access point for anything wishing to retrieve the distance a document is from a point. + */ +public interface DocumentDistanceSource { + + /** + * Retrieves the distance the document with the given id is from the given Point. + * + * @param docId ID of the document whose distance is to be retrieved + * @param src Point from where the distance to the document is to be calculated + * @param indexReader IndexReader for interacting with the index + * @param units DistanceUnits that the distance should be returned in + * @return Distance the document is from the point in the defined units + * @throws IOException Can be thrown while interacting with the index + */ + double getDocumentDistance(int docId, Point src, IndexReader indexReader, DistanceUnits units) throws IOException; +}