org.apache.lucene.spatial.query.SpatialOperation.java Source code

Introduction

Here is the source code for org.apache.lucene.spatial.query.SpatialOperation.java

Source

/*
 * 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.query;

import org.locationtech.spatial4j.shape.Rectangle;
import org.locationtech.spatial4j.shape.Shape;
import org.locationtech.spatial4j.shape.SpatialRelation;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;

/**
 * A predicate that compares a stored geometry to a supplied geometry. It's enum-like. For more
 * explanation of each predicate, consider looking at the source implementation
 * of {@link #evaluate(org.locationtech.spatial4j.shape.Shape, org.locationtech.spatial4j.shape.Shape)}. It's important
 * to be aware that Lucene-spatial makes no distinction of shape boundaries, unlike many standardized
 * definitions. Nor does it make dimensional distinctions (e.g. line vs polygon).
 * You can lookup a predicate by "Covers" or "Contains", for example, and you will get the
 * same underlying predicate implementation.
 *
 * @see <a href="http://en.wikipedia.org/wiki/DE-9IM">DE-9IM at Wikipedia, based on OGC specs</a>
 * @see <a href="http://edndoc.esri.com/arcsde/9.1/general_topics/understand_spatial_relations.htm">
 *   ESRIs docs on spatial relations</a>
 *
 * @lucene.experimental
 */
public abstract class SpatialOperation implements Serializable {
    //TODO rename to SpatialPredicate. Use enum?  LUCENE-5771

    // Private registry
    private static final Map<String, SpatialOperation> registry = new HashMap<>();//has aliases
    private static final List<SpatialOperation> list = new ArrayList<>();

    // Geometry Operations

    /** Bounding box of the *indexed* shape, then {@link #Intersects}. */
    public static final SpatialOperation BBoxIntersects = new SpatialOperation("BBoxIntersects") {
        @Override
        public boolean evaluate(Shape indexedShape, Shape queryShape) {
            return indexedShape.getBoundingBox().relate(queryShape).intersects();
        }
    };
    /** Bounding box of the *indexed* shape, then {@link #IsWithin}. */
    public static final SpatialOperation BBoxWithin = new SpatialOperation("BBoxWithin") {
        {
            register("BBoxCoveredBy");//alias -- the better name
        }

        @Override
        public boolean evaluate(Shape indexedShape, Shape queryShape) {
            Rectangle bbox = indexedShape.getBoundingBox();
            return bbox.relate(queryShape) == SpatialRelation.WITHIN || bbox.equals(queryShape);
        }
    };
    /** Meets the "Covers" OGC definition (boundary-neutral). */
    public static final SpatialOperation Contains = new SpatialOperation("Contains") {
        {
            register("Covers");//alias -- the better name
        }

        @Override
        public boolean evaluate(Shape indexedShape, Shape queryShape) {
            return indexedShape.relate(queryShape) == SpatialRelation.CONTAINS || indexedShape.equals(queryShape);
        }
    };
    /** Meets the "Intersects" OGC definition. */
    public static final SpatialOperation Intersects = new SpatialOperation("Intersects") {
        @Override
        public boolean evaluate(Shape indexedShape, Shape queryShape) {
            return indexedShape.relate(queryShape).intersects();
        }
    };
    /** Meets the "Equals" OGC definition. */
    public static final SpatialOperation IsEqualTo = new SpatialOperation("Equals") {
        {
            register("IsEqualTo");//alias (deprecated)
        }

        @Override
        public boolean evaluate(Shape indexedShape, Shape queryShape) {
            return indexedShape.equals(queryShape);
        }
    };
    /** Meets the "Disjoint" OGC definition. */
    public static final SpatialOperation IsDisjointTo = new SpatialOperation("Disjoint") {
        {
            register("IsDisjointTo");//alias (deprecated)
        }

        @Override
        public boolean evaluate(Shape indexedShape, Shape queryShape) {
            return !indexedShape.relate(queryShape).intersects();
        }
    };
    /** Meets the "CoveredBy" OGC definition (boundary-neutral). */
    public static final SpatialOperation IsWithin = new SpatialOperation("Within") {
        {
            register("IsWithin");//alias (deprecated)
            register("CoveredBy");//alias -- the more appropriate name.
        }

        @Override
        public boolean evaluate(Shape indexedShape, Shape queryShape) {
            return indexedShape.relate(queryShape) == SpatialRelation.WITHIN || indexedShape.equals(queryShape);
        }
    };
    /** Almost meets the "Overlaps" OGC definition, but boundary-neutral (boundary==interior). */
    public static final SpatialOperation Overlaps = new SpatialOperation("Overlaps") {
        @Override
        public boolean evaluate(Shape indexedShape, Shape queryShape) {
            return indexedShape.relate(queryShape) == SpatialRelation.INTERSECTS;//not Contains or Within or Disjoint
        }
    };

    private final String name;

    protected SpatialOperation(String name) {
        this.name = name;
        register(name);
        list.add(this);
    }

    protected void register(String name) {
        registry.put(name, this);
        registry.put(name.toUpperCase(Locale.ROOT), this);
    }

    public static SpatialOperation get(String v) {
        SpatialOperation op = registry.get(v);
        if (op == null) {
            op = registry.get(v.toUpperCase(Locale.ROOT));
        }
        if (op == null) {
            throw new IllegalArgumentException("Unknown Operation: " + v);
        }
        return op;
    }

    public static List<SpatialOperation> values() {
        return list;
    }

    public static boolean is(SpatialOperation op, SpatialOperation... tst) {
        for (SpatialOperation t : tst) {
            if (op == t) {
                return true;
            }
        }
        return false;
    }

    /**
     * Returns whether the relationship between indexedShape and queryShape is
     * satisfied by this operation.
     */
    public abstract boolean evaluate(Shape indexedShape, Shape queryShape);

    public String getName() {
        return name;
    }

    @Override
    public String toString() {
        return name;
    }
}