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  package com.gisgraphy.domain.repository;
24  
25  import java.util.List;
26  
27  import com.gisgraphy.domain.geoloc.entity.Adm;
28  import com.gisgraphy.domain.geoloc.entity.GisFeature;
29  import com.gisgraphy.importer.ImporterConfig;
30  
31  /**
32   * Interface for {@link Adm} data access
33   * 
34   * @author <a href="mailto:david.masclet@gisgraphy.com">David Masclet</a>
35   */
36  public interface IAdmDao extends IGisDao<Adm> {
37  
38      /**
39       * @param level
40       *                The level of the Adms to retrieve. The Level is not
41       *                checked (not necessary beetween 1 and 4)
42       * @return all the Adm for the specified level or an Empty List if no Adm
43       *         are found
44       */
45      public List<Adm> getAllbyLevel(int level);
46  
47      /**
48       * @param countryCode
49       *                The country code of the Adm to retrieve
50       * @param adm1Code
51       *                The Adm1Code of the Adm to retrieve
52       * @return The Adm with level 1 for the specified countrycode and adm1Code
53       *         <u>NOTE</u> : The countryCode will be automaticaly converted in
54       *         upperCase
55       * @see #getAdm(String, String, String, String, String)
56       * @see #getAdmByCountryAndCodeAndLevel(String, String, int)
57       * @throws IllegalArgumentException
58       *                 if any of the parameters are null
59       */
60      public Adm getAdm1(final String countryCode, final String adm1Code);
61  
62      /**
63       * @param countryCode
64       *                The country code of the Adm to retrieve
65       * @param adm1Code
66       *                The Adm1Code of the Adm to retrieve
67       * @param adm2Code
68       *                The Adm2Code of the Adm to retrieve <u>NOTE</u> : The
69       *                countryCode will be automaticaly converted in upperCase
70       * @return The Adm with level 2 for the specified countrycode, adm1Code, and
71       *         adm2Code. If adm1code is equals to 00 it will be ignore and more
72       *         than one result could be found, in that case it will return null.
73       * @see #getAdm(String, String, String, String, String)
74       * @see #getAdmByCountryAndCodeAndLevel(String, String, int)
75       * @throws IllegalArgumentException
76       *                 if any of the parameters are null
77       */
78      public Adm getAdm2(final String countryCode, final String adm1Code,
79  	    final String adm2Code);
80  
81      /**
82       * @param countryCode
83       *                The country code of the Adm to retrieve
84       * @param adm1Code
85       *                The Adm1Code of the Adm to retrieve
86       * @param adm2Code
87       *                The Adm2Code of the Adm to retrieve
88       * @param adm3Code
89       *                The Adm3Code of the Adm to retrieve <u>NOTE</u> : The
90       *                countryCode will be automaticaly converted in upperCase
91       * @return The Adm with level 3 for the specified countrycode, adm1Code,
92       *         adm2Code and adm3Code. If adm1code is equals to 00 it will be
93       *         ignore and more than one result could be found, in that case it
94       *         will return null.
95       * @see #getAdm(String, String, String, String, String)
96       * @see #getAdmByCountryAndCodeAndLevel(String, String, int)
97       * @throws IllegalArgumentException
98       *                 if any of the parameters are null
99       */
100     public Adm getAdm3(final String countryCode, final String adm1Code,
101 	    final String adm2Code, final String adm3Code);
102 
103     /**
104      * @param countryCode
105      *                The country code of the Adm to retrieve
106      * @param adm1Code
107      *                The Adm1Code of the Adm to retrieve
108      * @param adm2Code
109      *                The Adm2Code of the Adm to retrieve
110      * @param adm3Code
111      *                The Adm3Code of the Adm to retrieve
112      * @param adm4Code
113      *                The Adm4Code of the Adm to retrieve <u>NOTE</u> : The
114      *                countryCode will be automaticaly converted in upperCase
115      * @return The Adm with level 4 for the specified countrycode, adm1Code,
116      *         adm2Code, adm3Code and adm4Code.If adm1code is equals to 00 it
117      *         will be ignore and more than one result could be found, in that
118      *         case it will return null.
119      * @see #getAdm(String, String, String, String, String)
120      * @throws IllegalArgumentException
121      *                 if any of the parameters are null
122      */
123     public Adm getAdm4(final String countryCode, final String adm1Code,
124 	    final String adm2Code, final String adm3Code, final String adm4Code);
125 
126     /**
127      * Retrieve the Adm of the highest level according to the AdmXcode. The
128      * level will be determine with the highest AdmXcode which is not null (e.g :
129      * if adm1 and adm2 are not null, and adm3 and adm4 are null then the Adm of
130      * Level 2 will be retrieved) This method is a wrapper around
131      * {@link #getAdm1(String, String)},
132      * {@link #getAdm2(String, String, String)},
133      * {@link #getAdm3(String, String, String, String)}, and
134      * {@link #getAdm4(String, String, String, String, String)}. Use This
135      * Method ONLY if you've got some AdmXcode and you don't know the Level.
136      * you'll have better performance with the getAdmX() methods.<br>
137      * 
138      * @param countryCode
139      *                The country code of the Adm to retrieve
140      * @param adm1Code
141      *                The Adm1Code of the Adm to retrieve
142      * @param adm2Code
143      *                The Adm2Code of the Adm to retrieve
144      * @param adm3Code
145      *                The Adm3Code of the Adm to retrieve
146      * @param adm4Code
147      *                The Adm4Code of the Adm to retrieve <u>NOTE</u> : The
148      *                countryCode will be automaticaly converted in upperCase
149      * @return The Adm with the specified countrycode, adm1Code, adm2Code,
150      *         adm3Code and adm4Code
151      * @see #getAdm1(String, String)
152      * @see #getAdm2(String, String, String)
153      * @see #getAdm3(String, String, String, String)
154      * @see #getAdm4(String, String, String, String, String)
155      * @see #getAdmByCountryAndCodeAndLevel(String, String, int)
156      * @see Adm#getProcessedLevelFromCodes(String, String, String, String)
157      * @throws IllegalArgumentException
158      *                 if the countryCode is null
159      */
160     public Adm getAdm(final String countryCode, final String adm1Code,
161 	    final String adm2Code, final String adm3Code, final String adm4Code);
162 
163     /**
164      * Returns The Adm with the specified code and the specified level for the
165      * specified country code. The level determine the admXcode to search for.
166      * (e.g : if level=3 and admCode="C3", the adm with level 3 and adm3Code=c3"
167      * will be retrieved from the datastore <u>NOTE</u> : The countryCode will
168      * be automaticaly converted in upperCase
169      * 
170      * @param countryCode
171      *                The countryCode that the Adm must belongs to
172      * @param admCode
173      *                The code of the Adm for the specified level
174      * @param level
175      *                The level of the Adm : The Level is not checked (not
176      *                necessary beetween 1 and 4)
177      * @return The list of Adm with the specified code and the specified level
178      *         for the specified country code, never return null but an empty
179      *         list
180      * @throws IllegalArgumentException
181      *                 if countryCode or AdmCode is null
182      */
183     public List<Adm> getAdmByCountryAndCodeAndLevel(final String countryCode,
184 	    final String admCode, final int level);
185 
186     /**
187      * Return The Adm for the specified Code in the same way of
188      * {@link #getAdm(String, String, String, String, String)} or the first
189      * valid parent if no Adm is found with the specified codes.<br>
190      * e.g : If no Adm is found with adm1code="AA", adm2Code="BB", and
191      * Adm3Code="CC" but if it exist an Adm with level 2 with the specified
192      * Adm1Code or Adm2Code : the adm with level 2 will be return. If no adm2 is
193      * found and there is an existing Adm with level 1 and adm1code="AA" : the
194      * adm with level 1 will be return this method is to used when you want to
195      * do error correcting (see also
196      * {@link #suggestMostAccurateAdm(String, String, String, String, String, GisFeature)}
197      * 
198      * @param countryCode
199      *                The country code of the Adm to retrieve
200      * @param adm1Code
201      *                The Adm1Code of the Adm to retrieve
202      * @param adm2Code
203      *                The Adm2Code of the Adm to retrieve
204      * @param adm3Code
205      *                The Adm3Code of the Adm to retrieve
206      * @param adm4Code
207      *                The Adm4Code of the Adm to retrieve
208      * @return The Adm for the specified Code in the same way of
209      *         {@link #getAdm(String, String, String, String, String)} or the
210      *         first valid parent if no Adm is found with the specified codes
211      * @see #getAdmByCountryAndCodeAndLevel(String, String, int)
212      * @see Adm#getProcessedLevelFromCodes(String, String, String, String)
213      * @throws IllegalArgumentException
214      *                 if the countryCode is null
215      */
216     public Adm getAdmOrFirstValidParentIfNotFound(final String countryCode,
217 	    final String adm1Code, final String adm2Code,
218 	    final String adm3Code, final String adm4Code);
219 
220     /**
221      * This method is used when
222      * {@link ImporterConfig#isTryToDetectAdmIfNotFound()} is true or when error
223      * correction is needed. the algorithm will return an Adm according the
224      * specified rules:
225      * <ul>
226      * <li>If an Adm with the specified code is found (see
227      * {@link #getAdm(String, String, String, String, String)}) : retrun it</li>
228      * <li>If an Adm with the highest not null level is found for the specified
229      * country (e.g : if adm1,2,3 are specified and adm4 is null and it exist an
230      * adm with level 3 for the specified adm3Code then it will be return)</li>
231      * <ul>
232      * <li>If no parent Adm is found (see
233      * {@link #getAdmOrFirstValidParentIfNotFound(String, String, String, String, String)} :
234      * return Adm with the highest not null level </li>
235      * <li>If a parent Adm is found (see
236      * {@link #getAdmOrFirstValidParentIfNotFound(String, String, String, String, String)} :
237      * <ul>
238      * <li>If the difference beetween the Adm and The parent Adm is <=2 : we
239      * assume that it is an error with only one code and return the Adm with the
240      * highest not null level</li>
241      * <li>If the difference is >1 we assume that there is too much error and
242      * return the nearest parent </li>
243      * </ul>
244      * </li>
245      * </ul>
246      * <li>If No Adm with the highest not null level is found for the specified
247      * country </li>
248      * <ul>
249      * <li>If a parent Adm is found (see
250      * {@link #getAdmOrFirstValidParentIfNotFound(String, String, String, String, String)} :
251      * return Adm with the highest not null level : return the Parent</li>
252      * <li>If no parent is found : return null</li>
253      * </ul>
254      * </ul>
255      * 
256      * @param countryCode
257      *                The country code of the Adm to retrieve
258      * @param adm1Code
259      *                The Adm1Code of the Adm to retrieve
260      * @param adm2Code
261      *                The Adm2Code of the Adm to retrieve
262      * @param adm3Code
263      *                The Adm3Code of the Adm to retrieve
264      * @param adm4Code
265      *                The Adm4Code of the Adm to retrieve
266      * @param gisFeature
267      *                The gisFeature is not really used in the algorithm, but it
268      *                can be useful to have it for logs or for specific
269      *                algorithm implementation.(It is only used for logs)
270      * @return The most accurate Adm for the gisFeature
271      * @see #getAdmOrFirstValidParentIfNotFound(String, String, String, String,
272      *      String)
273      * @throws IllegalArgumentException
274      *                 if the countryCode is null
275      */
276     public Adm suggestMostAccurateAdm(final String countryCode,
277 	    final String adm1Code, final String adm2Code,
278 	    final String adm3Code, final String adm4Code,
279 	    final GisFeature gisFeature);
280 
281     /**
282      * @param level
283      *                The level we want the Adm to count The Level is not
284      *                checked (not necessary beetween 1 and 4)
285      * @return how many Adm exists for the specified level
286      */
287     public long countByLevel(final int level);
288 
289     /**
290      * @return Adm Which are not used by any GisFeature
291      */
292     public List<Adm> getUnused();
293 
294     /**
295      * @param level
296      *                the level we want to delete Adm return the number of
297      *                deleted Adm
298      */
299     public int deleteAllByLevel(final int level);
300     
301     /**
302      * List all the featureId of the Adms of a specified level 
303      * @param level the level
304      * @return a list of all featureId
305      */
306     public List<Long> listFeatureIdByLevel(final int level);
307 
308 }