| /* |
| * 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.prefix.tree; |
| |
| import org.apache.lucene.util.BytesRef; |
| import org.locationtech.spatial4j.shape.Shape; |
| import org.locationtech.spatial4j.shape.SpatialRelation; |
| |
| /** |
| * Represents a grid cell. Cell instances are generally very transient and may be re-used |
| * internally. To get an instance, you could start with {@link SpatialPrefixTree#getWorldCell()}. |
| * And from there you could either traverse down the tree with {@link |
| * #getNextLevelCells(org.locationtech.spatial4j.shape.Shape)}, or you could read an indexed term |
| * via {@link SpatialPrefixTree#readCell(org.apache.lucene.util.BytesRef,Cell)}. When a cell is read |
| * from a term, it is comprised of just the base bytes plus optionally a leaf flag. |
| * |
| * @lucene.experimental |
| */ |
| public interface Cell { |
| |
| // If we bring this back; perhaps do so as a method that un-shares its internal state: void |
| // unshare(); |
| // /** Resets the state of this cell such that it is identical to {@code source}. This can be |
| // used for |
| // * cloning a cell to have a safe copy, and it also might be used to position this cell |
| // * before calling {@link #readCell(org.apache.lucene.util.BytesRef)} in a loop if you know the |
| // first term |
| // * is going to be close to some other cell, thereby saving some computations. */ |
| // void copyFrom(Cell source); |
| |
| /** |
| * Gets the relationship this cell has with the shape from which it was filtered from, assuming it |
| * came from a {@link CellIterator}. Arguably it belongs there but it's very convenient here. |
| */ |
| SpatialRelation getShapeRel(); |
| |
| /** |
| * See {@link #getShapeRel()}. |
| * |
| * @lucene.internal |
| */ |
| void setShapeRel(SpatialRelation rel); |
| |
| /** |
| * Some cells are flagged as leaves, which are indexed as such. A leaf cell is either within some |
| * shape or it both intersects and the cell is at an accuracy threshold such that no smaller cells |
| * for the shape will be represented. |
| */ |
| boolean isLeaf(); |
| |
| /** |
| * Set this cell to be a leaf. Warning: never call on a cell initialized to reference the same |
| * bytes from termsEnum, which should be treated as immutable. Note: not supported at level 0. |
| * |
| * @lucene.internal |
| */ |
| void setLeaf(); |
| |
| /** |
| * Returns the bytes for this cell, with a leaf byte <em>if this is a leaf cell</em>. The result |
| * param is used to save object allocation, though its bytes aren't used. |
| * |
| * @param result where the result goes, or null to create new |
| */ |
| BytesRef getTokenBytesWithLeaf(BytesRef result); |
| |
| /** |
| * Returns the bytes for this cell, without a leaf set. The bytes should sort before {@link |
| * #getTokenBytesWithLeaf(org.apache.lucene.util.BytesRef)}. The result param is used to save |
| * object allocation, though its bytes aren't used. |
| * |
| * @param result where the result goes, or null to create new |
| */ |
| BytesRef getTokenBytesNoLeaf(BytesRef result); |
| |
| /** |
| * Level 0 is the world (and has no parent), from then on a higher level means a smaller cell than |
| * the level before it. |
| */ |
| int getLevel(); |
| |
| /** |
| * Gets the cells at the next grid cell level underneath this one, optionally filtered by {@code |
| * shapeFilter}. The returned cells should have {@link #getShapeRel()} set to their relation with |
| * {@code shapeFilter}. In addition, for non-points {@link #isLeaf()} must be true when that |
| * relation is WITHIN. |
| * |
| * <p>IMPORTANT: Cells returned from this iterator can be shared, as well as the bytes. |
| * |
| * <p>Precondition: Never called when getLevel() == maxLevel. |
| * |
| * @param shapeFilter an optional filter for the returned cells. |
| * @return A set of cells (no dups), sorted. Not Modifiable. |
| */ |
| CellIterator getNextLevelCells(Shape shapeFilter); |
| |
| /** Gets the shape for this cell; typically a Rectangle. */ |
| Shape getShape(); |
| |
| /** |
| * Returns if the target term is within/underneath this cell; not necessarily a direct descendant. |
| * |
| * @param c the term |
| */ |
| boolean isPrefixOf(Cell c); |
| |
| /** |
| * Equivalent to {@code |
| * this.getTokenBytesNoLeaf(null).compareTo(fromCell.getTokenBytesNoLeaf(null))}. |
| */ |
| int compareToNoLeaf(Cell fromCell); |
| } |