/*#####################################################################
*
* CLAVIN (Cartographic Location And Vicinity INdexer)
* ---------------------------------------------------
*
* Copyright (C) 2012-2013 Berico Technologies
* http://clavin.bericotechnologies.com
*
* ====================================================================
*
* Licensed 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.
*
* ====================================================================
*
* GazetteerQuery.java
*
*###################################################################*/
package com.bericotech.clavin.gazetteer.query;
import com.bericotech.clavin.extractor.LocationOccurrence;
import com.bericotech.clavin.gazetteer.FeatureCode;
import java.util.Collections;
import java.util.EnumSet;
import java.util.HashSet;
import java.util.Set;
/**
* Configuration parameters for querying a Gazetteer. The
* {@link QueryBuilder} contains convenience methods to make
* query construction more readable.
*/
public class GazetteerQuery {
/**
* The location occurrence to search for.
*/
private final LocationOccurrence occurrence;
/**
* The maximum number of results.
*/
private final int maxResults;
/**
* Indicates how fuzzy matching should be applied.
*/
private final FuzzyMode fuzzyMode;
/**
* Indicates how the ancestry of the matched locations should be loaded.
*/
private final AncestryMode ancestryMode;
/**
* Should historical locations be included?
*/
private final boolean includeHistorical;
/**
* When <code>true</code>, queries that match multiple names for the
* same location (e.g. "Virginia" and "Commonwealth of Virginia") will
* only return the best match for that location.
*/
private final boolean filterDupes;
/**
* Searches should be restricted to locations found in at least
* one of this set of parents.
*/
private final Set<Integer> parentIds;
/**
* Searches should be restricted to locations matching one of
* these feature codes.
*/
private final Set<FeatureCode> featureCodes;
/**
* Create a new GazetteerQuery.
* @param occurrence the location occurrence
* @param maxResults the maximum number of results
* @param fuzzyMode the fuzzy mode for this query
* @param ancestryMode the ancestry loading mode for this query
* @param includeHistorical <code>true</code> to include historical locations
* @param filterDupes <code>true</code> to return only the highest scoring match for each individual location
* @param parentIds the set of parent IDs to restrict the search to; these will be OR'ed
* @param featureCodes the set of feature codes to restrict the search to; these will be OR'ed
*/
@SuppressWarnings("unchecked")
public GazetteerQuery(final LocationOccurrence occurrence, final int maxResults, final FuzzyMode fuzzyMode,
final AncestryMode ancestryMode, final boolean includeHistorical, final boolean filterDupes,
final Set<Integer> parentIds, final Set<FeatureCode> featureCodes) {
this.occurrence = occurrence;
this.maxResults = maxResults;
this.fuzzyMode = fuzzyMode;
this.ancestryMode = ancestryMode;
this.includeHistorical = includeHistorical;
this.filterDupes = filterDupes;
this.parentIds = parentIds != null ? new HashSet<Integer>(parentIds) : Collections.EMPTY_SET;
this.featureCodes = featureCodes != null ? EnumSet.copyOf(featureCodes) : EnumSet.noneOf(FeatureCode.class);
}
/**
* Get the LocationOccurrence to search on.
* @return the LocationOccurrence to search for
*/
public LocationOccurrence getOccurrence() {
return occurrence;
}
/**
* Get the maximum number of results that should be returned by this query.
* @return the maximum number of search results
*/
public int getMaxResults() {
return maxResults;
}
/**
* Indicates how fuzzy matching should be used.
* @return the fuzzy matching mode
*/
public FuzzyMode getFuzzyMode() {
return fuzzyMode;
}
/**
* Indicates how the ancestry, the hierarchy of political divisions, for matching
* locations should be loaded.
* @return the ancestry mode
*/
public AncestryMode getAncestryMode() {
return ancestryMode;
}
/**
* Should historical locations be included in the search results?
* @return <code>true</code> if historical locations should be included
*/
public boolean isIncludeHistorical() {
return includeHistorical;
}
/**
* Should duplicate results be filtered so only the best match for each
* location is returned?
* @return <code>true</code> if duplicates should be filtered
*/
public boolean isFilterDupes() {
return filterDupes;
}
/**
* Get the set of parents that should be used to restrict the search.
* @return the IDs of the parents that should be used to restrict the search
*/
public Set<Integer> getParentIds() {
return Collections.unmodifiableSet(parentIds);
}
/**
* Get the set of FeatureCodes that should be used to restrict the search.
* @return the set of FeatureCodes that should be used to restrict the search
*/
public Set<FeatureCode> getFeatureCodes() {
return Collections.unmodifiableSet(featureCodes);
}
}