lucene/spatial-extras/src/java/org/apache/lucene/spatial/query/SpatialOperation.java

/*
 * 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;
  }
}