1
|
/**
|
2
|
* Copyright (C) 2009 EDIT
|
3
|
* European Distributed Institute of Taxonomy
|
4
|
* http://www.e-taxonomy.eu
|
5
|
*
|
6
|
* The contents of this file are subject to the Mozilla Public License Version 1.1
|
7
|
* See LICENSE.TXT at the top of this package for the full license terms.
|
8
|
*/
|
9
|
package eu.etaxonomy.cdm.ext.ipni;
|
10
|
|
11
|
import java.io.InputStream;
|
12
|
import java.net.URL;
|
13
|
import java.util.List;
|
14
|
import java.util.UUID;
|
15
|
|
16
|
import eu.etaxonomy.cdm.api.application.ICdmRepository;
|
17
|
import eu.etaxonomy.cdm.ext.ipni.IpniService.IpniRank;
|
18
|
import eu.etaxonomy.cdm.model.agent.Person;
|
19
|
import eu.etaxonomy.cdm.model.common.ExtensionType;
|
20
|
import eu.etaxonomy.cdm.model.common.IdentifiableSource;
|
21
|
import eu.etaxonomy.cdm.model.name.IBotanicalName;
|
22
|
import eu.etaxonomy.cdm.model.name.Rank;
|
23
|
import eu.etaxonomy.cdm.model.reference.Reference;
|
24
|
|
25
|
|
26
|
/**
|
27
|
* Interface for queying IPNI via webservice ({@link http://www.uk.ipni.org/}).
|
28
|
* Services are available for the plant name index, the autor index and the publication index.
|
29
|
* @author a.mueller
|
30
|
* @since Aug 16, 2010
|
31
|
*/
|
32
|
public interface IIpniService {
|
33
|
|
34
|
|
35
|
|
36
|
/**
|
37
|
* UUID for the reference representing the IPNI database:<BR/>
|
38
|
* 8b6d750f-c7e0-4180-afbf-aa4c50148813
|
39
|
*/
|
40
|
public static final UUID uuidIpni = UUID.fromString("8b6d750f-c7e0-4180-afbf-aa4c50148813");
|
41
|
|
42
|
/**
|
43
|
* UUID for the extension type 'Alternative name':<BR/>
|
44
|
* eee99927-1f9f-4df2-9d8f-11746bf35c0c
|
45
|
*/
|
46
|
public static final UUID uuidAlternativeNames = UUID.fromString("eee99927-1f9f-4df2-9d8f-11746bf35c0c");
|
47
|
|
48
|
|
49
|
public static final String AUTHOR_SERVICE_URL = "http://www.ipni.org/ipni/advAuthorSearch.do";
|
50
|
public static final String SIMPLE_NAME_SERVICE_URL = "http://www.uk.ipni.org/ipni/simplePlantNameSearch.do";
|
51
|
public static final String ADVANCED_NAME_SERVICE_URL = "http://www.uk.ipni.org/ipni/advPlantNameSearch.do";
|
52
|
public static final String PUBLICATION_SERVICE_URL = "http://www.uk.ipni.org/ipni/advPublicationSearch.do";
|
53
|
public static final String ID_PUBLICATION_SERVICE_URL = "http://www.uk.ipni.org/ipni/idPublicationSearch.do";
|
54
|
public static final String ID_NAMESEARCH_SERVICE_URL = "http://www.ipni.org/ipni/idPlantNameSearch.do";
|
55
|
|
56
|
/**
|
57
|
* Enumeration of the four return delimited data formats provided by IPNI.<BR/>
|
58
|
* @see http://www.ipni.org/ipni/delimited_help.html
|
59
|
* @author a.mueller
|
60
|
*/
|
61
|
public enum DelimitedFormat{
|
62
|
/** IPNI classic delimited format */
|
63
|
CLASSIC ("delimited-classic"),
|
64
|
/** IPNI minimal delimited format */
|
65
|
MINIMAL ("delimited-minimal"),
|
66
|
/** IPNI short delimited format */
|
67
|
SHORT ("delimited-short"),
|
68
|
/** IPNI extended delimited format */
|
69
|
EXTENDED ("delimited-extended");
|
70
|
|
71
|
String parameter;
|
72
|
DelimitedFormat(String parameter){
|
73
|
this.parameter = parameter;
|
74
|
}
|
75
|
}
|
76
|
|
77
|
/**
|
78
|
* Returns a list of persons (authors) defined by their abbreviation, surname, forename and/or isoCountry.
|
79
|
* The amount of data added to each person depends on the format and the database connection (appConfig).
|
80
|
* <BR/><BR/>
|
81
|
* The {@link DelimitedFormat#MINIMAL minimal} and {@link DelimitedFormat#SHORT short} format returns the
|
82
|
* <i>standard form</i> as the nomenclatural title, the <i>default author forename</i> as the firstname and
|
83
|
* the <i>default author surname</i> as the lastname of the returned {@link Person person} object.
|
84
|
* The <i>id</i> and the <i>version</i> are added as {@link IdentifiableSource source} where the id is the id,
|
85
|
* the namespace is "Author" and the microcitation is the <i>version</i>. If an a database connection is passed
|
86
|
* (appConig is not <code>null</null>) the database is searched for an existing citation representing the IPNI
|
87
|
* webservice. If not exists a new such reference with the given {@link #uuidIpni ipni uuid} is created and stored
|
88
|
* in the database.<BR/>
|
89
|
* If no database connection is passed a new reference is created each time with a random UUID to avoid duplicate
|
90
|
* key problems when trying to save the returned objects.
|
91
|
* <BR/><BR/>
|
92
|
* The {@link DelimitedFormat#EXTENDED minimal} format returns the same object as the {@link DelimitedFormat#SHORT short} format
|
93
|
* but additionally the <i>date</i> is evaluated as lifespan.
|
94
|
* Also an extension of type
|
95
|
* {@link ExtensionType.INFORMAL_CATEGORY} is added for each semicolon separated part of the 'Alternative names' result.
|
96
|
* TODO make alternative name or alternative title an own ExtensionType
|
97
|
* <BR/><BR/>
|
98
|
* The {@link DelimitedFormat#CLASSIC classic} format at the moment returns the same object as the {@link DelimitedFormat#EXTENDED extended} format
|
99
|
* as the remaining parameters are not yet implemented.
|
100
|
*
|
101
|
* @param abbreviation
|
102
|
* @param surname
|
103
|
* @param forename
|
104
|
* @param isoCountry
|
105
|
* @param format
|
106
|
* @param appConfig
|
107
|
* @return
|
108
|
*/
|
109
|
public List<Person> getAuthors(String abbreviation, String surname, String forename, String isoCountry, ICdmRepository appConfig, IpniServiceAuthorConfigurator config);
|
110
|
|
111
|
|
112
|
/**
|
113
|
* Returns a list of names matching the wholeName parameter according to the IPNI Quick search function.
|
114
|
* See {@link http://www.uk.ipni.org/sample_searches.html#name_quick} for further explanation about the IPNI Quick search.
|
115
|
* <BR/><BR/>
|
116
|
* The format parameter defines the depth of the data returned. See {@link http://www.ipni.org/ipni/delimited_help.html} for further
|
117
|
* information on the supported data formats.
|
118
|
* <BR/>
|
119
|
* Please be aware that not all data returned by IPNI are transformed into CDM data as some of the data types are not available in the
|
120
|
* CDM and some types are just not yet implemented.
|
121
|
*
|
122
|
* @param wholeName
|
123
|
* @param format
|
124
|
* @param appConfig
|
125
|
* @return
|
126
|
*/
|
127
|
public List<IBotanicalName> getNamesSimple(String wholeName, ICdmRepository services, IpniServiceNamesConfigurator config);
|
128
|
|
129
|
/**
|
130
|
* Returns the name matching the id parameter according to the IPNI Quick search function.
|
131
|
* See {@link http://www.uk.ipni.org/sample_searches.html#name_quick} for further explanation about the IPNI Quick search.
|
132
|
* <BR/><BR/>
|
133
|
*
|
134
|
* Please be aware that not all data returned by IPNI are transformed into CDM data as some of the data types are not available in the
|
135
|
* CDM and some types are just not yet implemented.
|
136
|
*
|
137
|
* @param id
|
138
|
* @return
|
139
|
*/
|
140
|
public InputStream getNamesById(String id);
|
141
|
|
142
|
|
143
|
/**
|
144
|
* Returns the publication matching the id parameter according to the IPNI Quick search function.
|
145
|
* See {@link http://www.uk.ipni.org/sample_searches.html#name_quick} for further explanation about the IPNI Quick search.
|
146
|
* <BR/><BR/>
|
147
|
*
|
148
|
* Please be aware that not all data returned by IPNI are transformed into CDM data as some of the data types are not available in the
|
149
|
* CDM and some types are just not yet implemented.
|
150
|
*
|
151
|
* @param id
|
152
|
* @return
|
153
|
*/
|
154
|
public InputStream getPublicationsById(String id);
|
155
|
|
156
|
/**
|
157
|
* Returns a list of names matching the relevant parameters according to the IPNI full search function.
|
158
|
* See {http://www.uk.ipni.org/sample_searches.html#name_full} for further explanation about the IPNI Full search.
|
159
|
* <BR/><BR/>
|
160
|
* The format parameter defines the depth of the data returned. See {@link http://www.ipni.org/ipni/delimited_help.html} for further
|
161
|
* information on the supported data formats.
|
162
|
* <BR/>
|
163
|
* Please be aware that not all data returned by IPNI are transformed into CDM data as some of the data types are not available in the
|
164
|
* CDM and some types are just not yet implemented.
|
165
|
*
|
166
|
* @param family
|
167
|
* @param genus
|
168
|
* @param species
|
169
|
* @param infraFamily
|
170
|
* @param infraGenus
|
171
|
* @param infraSpecies
|
172
|
* @param authorAbbrev
|
173
|
* @param includePublicationAuthors
|
174
|
* @param includeBasionymAuthors
|
175
|
* @param publicationTitle
|
176
|
* @param isAPNIRecord
|
177
|
* @param isGCIRecord
|
178
|
* @param isIKRecord
|
179
|
* @param rankToReturn
|
180
|
* @param sortByFamily
|
181
|
* @param format
|
182
|
* @param appConfig
|
183
|
* @return List of botanical names returned by the IPNI web service.
|
184
|
*/
|
185
|
public List<IBotanicalName> getNamesAdvanced(String family, String genus, String species, String infraFamily,
|
186
|
String infraGenus, String infraSpecies, String authorAbbrev,
|
187
|
String publicationTitle,
|
188
|
IpniRank ipniRankToReturn,
|
189
|
IpniServiceNamesConfigurator config,
|
190
|
ICdmRepository repository);
|
191
|
|
192
|
/**
|
193
|
* As {@link #getNamesAdvanced(String, String, String, String, String, String, String, Boolean, Boolean, String, Boolean, Boolean, Boolean, IpniRank, Boolean, IpniServiceNamesConfigurator, ICdmRepository)}
|
194
|
* but using CDM Rank instead of IpniRank. The CDM Rank is transformed into an IpniRank so it returns all
|
195
|
* names that are in the same IpniRange as the CDM rank. Therefore when using CDM rank 'variety' also a
|
196
|
* 'subspecies' may be returned as 'variety' and 'subspecies' are within the same IpniRange 'Infraspecific'.
|
197
|
*
|
198
|
* @param family
|
199
|
* @param genus
|
200
|
* @param species
|
201
|
* @param infraFamily
|
202
|
* @param infraGenus
|
203
|
* @param infraSpecies
|
204
|
* @param authorAbbrev
|
205
|
* @param includePublicationAuthors
|
206
|
* @param includeBasionymAuthors
|
207
|
* @param publicationTitle
|
208
|
* @param isAPNIRecord
|
209
|
* @param isGCIRecord
|
210
|
* @param isIKRecord
|
211
|
* @param rankToReturn
|
212
|
* @param sortByFamily
|
213
|
* @param format
|
214
|
* @param appConfig
|
215
|
* @return List of botanical names returned by the IPNI web service.
|
216
|
*/
|
217
|
public List<IBotanicalName> getNamesAdvanced(String family, String genus, String species, String infraFamily,
|
218
|
String infraGenus, String infraSpecies, String authorAbbrev,
|
219
|
String publicationTitle,
|
220
|
Rank rankRangeToReturn,
|
221
|
IpniServiceNamesConfigurator config,
|
222
|
ICdmRepository repository);
|
223
|
|
224
|
/**
|
225
|
* Returns a list of publications matching the title and/or the abbreviation parameter according to the IPNI Publication search function.
|
226
|
* See {@link http://www.uk.ipni.org/sample_searches.html#publication_examples} for further explanation about the IPNI Publication search.
|
227
|
* <BR/><BR/>
|
228
|
* Please be aware that not all data returned by IPNI are transformed into CDM data as some of the data types are not available in the
|
229
|
* CDM and some types are just not yet implemented.
|
230
|
*
|
231
|
* @param title
|
232
|
* @param abbreviation
|
233
|
* @param services to retrieve data from the database. Needed to attach the same 'IPNI' reference to each of the resulting objects.
|
234
|
* Otherwise the resulting IPNI reference will be duplicate for each result and each time the service is called.
|
235
|
* @param config for finetuning, maybe null
|
236
|
* @return
|
237
|
*/
|
238
|
public List<Reference> getPublications(String title, String abbreviation, ICdmRepository services, IpniServicePublicationConfigurator config);
|
239
|
|
240
|
public URL getServiceUrl(String url);
|
241
|
}
|
242
|
|