View Javadoc
1   /*******************************************************************************
2    *   Gisgraphy Project 
3    * 
4    *   This library is free software; you can redistribute it and/or
5    *   modify it under the terms of the GNU Lesser General Public
6    *   License as published by the Free Software Foundation; either
7    *   version 2.1 of the License, or (at your option) any later version.
8    * 
9    *   This library is distributed in the hope that it will be useful,
10   *   but WITHOUT ANY WARRANTY; without even the implied warranty of
11   *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12   *   Lesser General Public License for more details.
13   * 
14   *   You should have received a copy of the GNU Lesser General Public
15   *   License along with this library; if not, write to the Free Software
16   *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
17   * 
18   *  Copyright 2008  Gisgraphy project 
19   *  David Masclet <davidmasclet@gisgraphy.com>
20   *  
21   *  
22   *******************************************************************************/
23  /**
24   *
25   */
26  package com.gisgraphy.domain.repository;
27  
28  import java.util.List;
29  
30  import com.gisgraphy.domain.geoloc.entity.GisFeature;
31  import com.gisgraphy.domain.valueobject.GisFeatureDistance;
32  import com.vividsolutions.jts.geom.Point;
33  
34  /**
35   * Interface for a Generic Dao for GIS Object (java-5 meaning) it suppose that
36   * the PK is of type long because its goal is to be used with class gisfeatures
37   * and class that extends GisFeature. if it is note the case. it is possible to
38   * create an other inteface<br>: public interface IGisDao<T,PK extends
39   * Serializable> extends IDao<T,PK> it adds some method to the IDao in order to
40   * acess GIS objects
41   * 
42   * @see GenericGisDao
43   * @see IDao
44   * @author <a href="mailto:david.masclet@gisgraphy.com">David Masclet</a>
45   */
46  public interface IGisDao<T> extends IDao<T, java.lang.Long> {
47  
48      /**
49       * It is not the same as {@link IDao#get(java.io.Serializable)} which
50       * retrieve an object from his PK.
51       * 
52       * @param featureId
53       *                the featureid of the GIS object to retrieve
54       * @return the Gis Object with the specified GisFeature id.
55       * @throws IllegalArgumentException
56       *                 if the FeatureId is null
57       */
58      public T getByFeatureId(final Long featureId);
59  
60      /**
61       * Returns inconsistant object (in most case object With featureid < 0)
62       * 
63       * @return List of populated objects (never return null, but an empty list)
64       */
65      public List<T> getDirties();
66  
67      /**
68       * Same as IDao#get(java.io.Serializable) but load the AlternateNames and
69       * The linked Adm
70       * 
71       * @param id
72       *                the id of the features to retrieve
73       * @return The Feature with the alternateName and the Adm loaded
74       * @see IDao#get(java.io.Serializable)
75       */
76      public T getEager(final Long id);
77  
78      /**
79       * 
80       * @param gisFeature
81       *                The GisFeature from which we want to find GIS Object
82       * @param distance
83       *                distance The radius in meters
84       * @param includeDistanceField 
85       * 				Field whether or not we should process calculate the distance
86       * @return A List of GisFeatureDistance with the nearest elements or an
87       *         emptylist (never return null), ordered by distance. <u>note</u>
88       *         the specified gisFeature will not be included into results the
89       *         results will be of the type of the currentDao
90       * @see GisFeatureDistance
91       */
92      public List<GisFeatureDistance> getNearestAndDistanceFromGisFeature(
93  	    final GisFeature gisFeature, final double distance,boolean includeDistanceField);
94  
95      /**
96       * @param gisFeature
97       *                The GisFeature from which we want to find GIS Object
98       * @param distance
99       *                distance The radius in meters
100      * @param firstResult
101      *                the firstResult index (for pagination), numbered from 1,
102      *                if < 1 : it will not be taken into account
103      * @param maxResults
104      *                The Maximum number of results to retrieve (for
105      *                pagination), if <= 0 : it will not be taken into acount
106      * @param includeDistanceField
107      * 				Field whether or not we should process calculate the distance
108      * @return A List of GisFeatureDistance with the nearest elements or an
109      *         emptylist (never return null), ordered by distance. <u>note</u>
110      *         the specified gisFeature will not be included into results the
111      *         results will be of the type of the currentDao<br/> <u>tips</u> :
112      *         to search the nearest place use firstresult=1 and maxResults=1
113      * @see GisFeatureDistance
114      */
115     public List<GisFeatureDistance> getNearestAndDistanceFromGisFeature(
116 	    final GisFeature gisFeature, final double distance,
117 	    final int firstResult, final int maxResults, final boolean includeDistanceField);
118 
119     /**
120      * same as
121      * {@link #getNearestAndDistanceFromGisFeature(GisFeature, double, int, int, boolean)} but
122      * without paginate
123      * 
124      * @param point
125      *                The point from which we want to find GIS Object
126      * @param distance
127      *                distance The radius in meters
128      * @return A List of GisFeatureDistance with the nearest elements or an
129      *         emptylist (never return null), ordered by distance. <u>note</u>
130      *         the specified gisFeature will not be included into results the
131      *         results will be of the type of the currentDao
132      * @see GisFeatureDistance
133      */
134     public List<GisFeatureDistance> getNearestAndDistanceFrom(
135 	    final Point point, final double distance);
136 
137     /**
138      * @param point
139      *                The point from which we want to find GIS Object
140      * @param distance
141      *                distance The radius in meters
142      * @param firstResult
143      *                the firstResult index (for pagination), numbered from 1,
144      *                if < 1 : it will not be taken into account
145      * @param maxResults
146      *                The Maximum number of results to retrieve (for
147      *                pagination), if <= 0 : it will not be taken into acount
148      * @param includeDistanceField 
149      * 				Field whether or not we should process calculate the distance
150      * @param isMunicipality whether we should filter on city that are flag as 'municipality'.
151 						act as a filter, if false it doesn't filters( false doesn't mean that we return non municipality)
152      * @return A List of GisFeatureDistance with the nearest elements or an
153      *         emptylist (never return null), ordered by distance. <u>note</u>
154      *         the specified gisFeature will not be included into results the
155      *         results will be of the type of the currentDao<br/> <u>tips</u>:
156      *         to search the nearest place use firstresult=1 and maxResults=1
157      * @see GisFeatureDistance
158      */
159     public List<GisFeatureDistance> getNearestAndDistanceFrom(
160 	    final Point point, final double distance, final int firstResult,
161 	    final int maxResults,final boolean includeDistanceField, boolean isMunicipality );
162 
163     /**
164      * retrieve the Objects with the specified name (not the ASCII one)
165      * 
166      * @param name
167      *                the name of the objects to retrieve
168      * @return List of populated objects list (never return null, but an empty
169      *         list)
170      * @see #listFromText(String, boolean)
171      */
172 
173     public List<T> listByName(final String name);
174 
175     /**
176      * return all the Object with the specified featureIds (not ids :id is the
177      * PK (aka datastore id), featureId is the domain value). return an
178      * emptylist if the list of ids is null or empty). The features will be of
179      * the type of the Dao.
180      * 
181      * @param ids
182      *                the list of the ids of the object to retrieve
183      * @return List of populated objects list (never return null, but an empty
184      *         list)
185      */
186     public List<T> listByFeatureIds(final List<Long> ids);
187 
188     /**
189      * Do a full text search for the given name. The search will be case,
190      * iso-latin, comma-separated insensitive<br>
191      * search for 'saint-André', 'saint-Andre', 'SaInT-andré', 'st-andré', etc
192      * will return the same results Polymorphism is not supported, e.g : if you
193      * use gisfeatureDao the results will only be of that type and no feature of
194      * type City that extends gisFeature...etc will be returned.
195      * 
196      * @param name
197      *                the name or zipcode of the GisFeature to search
198      * @param includeAlternateNames
199      *                whether we search in the alternatenames too
200      * @return a list of gisFeatures of type of the class for the given text.
201      *         the max list size is {@link GenericGisDao#MAX_FULLTEXT_RESULTS};
202      * @see IGisFeatureDao#listAllFeaturesFromText(String, boolean)
203      */
204     public List<T> listFromText(String name, boolean includeAlternateNames);
205     
206     
207     /**
208      * Create the database GIST index for the column 'location' for this entity if it doesn't already exists
209      */
210     public void createGISTIndexForLocationColumn();
211     
212     /**
213      * @param location The point from which we want to find GIS Object
214      * @param countryCode restrict the search to a given country code (useful for feature near a frontier
215      * @param filterMunicipality if  we should  filter municipality or not
216      * @param distance te distance in meter
217      * @return the nearest city differ from getnearestAndDistance because doesn't return distance field and with zip and alternateNames are populated
218      */
219     public T getNearest(final Point location,final String countryCode,final boolean filterMunicipality,final int distance);
220 
221 
222     /**
223      * create the shape index for the entity if it doesn't already exists. 
224      */
225     public void createGISTIndexForShapeColumn();
226     
227     
228     /**
229      * @param featureId
230      * @return the shape as wkt or null;
231      */
232     public String getShapeAsWKTByFeatureId(Long featureId);
233 }