001 //$HeadURL: svn+ssh://jwilden@svn.wald.intevation.org/deegree/base/branches/2.5_testing/src/org/deegree/ogcwebservices/csw/manager/Harvest.java $
002 /*----------------------------------------------------------------------------
003 This file is part of deegree, http://deegree.org/
004 Copyright (C) 2001-2009 by:
005 Department of Geography, University of Bonn
006 and
007 lat/lon GmbH
008
009 This library is free software; you can redistribute it and/or modify it under
010 the terms of the GNU Lesser General Public License as published by the Free
011 Software Foundation; either version 2.1 of the License, or (at your option)
012 any later version.
013 This library is distributed in the hope that it will be useful, but WITHOUT
014 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
016 details.
017 You should have received a copy of the GNU Lesser General Public License
018 along with this library; if not, write to the Free Software Foundation, Inc.,
019 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
020
021 Contact information:
022
023 lat/lon GmbH
024 Aennchenstr. 19, 53177 Bonn
025 Germany
026 http://lat-lon.de/
027
028 Department of Geography, University of Bonn
029 Prof. Dr. Klaus Greve
030 Postfach 1147, 53001 Bonn
031 Germany
032 http://www.geographie.uni-bonn.de/deegree/
033
034 e-mail: info@deegree.org
035 ----------------------------------------------------------------------------*/
036
037 package org.deegree.ogcwebservices.csw.manager;
038
039 import java.net.URI;
040 import java.net.URISyntaxException;
041 import java.util.ArrayList;
042 import java.util.Date;
043 import java.util.GregorianCalendar;
044 import java.util.List;
045 import java.util.Map;
046
047 import org.deegree.datatypes.time.TimeDuration;
048 import org.deegree.framework.log.ILogger;
049 import org.deegree.framework.log.LoggerFactory;
050 import org.deegree.framework.util.TimeTools;
051 import org.deegree.framework.xml.XMLParsingException;
052 import org.deegree.ogcwebservices.AbstractOGCWebServiceRequest;
053 import org.deegree.ogcwebservices.InvalidParameterValueException;
054 import org.deegree.ogcwebservices.MissingParameterValueException;
055 import org.w3c.dom.Element;
056
057 /**
058 * <p>
059 * The general model defines two operations in the Manager class that may be used to create or
060 * update records in the catalogue. They are the transaction operation and the harvestRecords
061 * operation. The transaction operation may be used to "push" data into the catalogue and is defined
062 * in Subclause 10.11. of CS-W specification. This subclause defines the optional Harvest operation,
063 * which is an operation that "pulls" data into the catalogue. That is, this operation only
064 * references the data to be inserted or updated in the catalogue, and it is the job of the
065 * catalogue service to resolve the reference, fetch that data, and process it into the catalogue.
066 * </p>
067 * <p>
068 * The Harvest operation had two modes of operation, controlled by a flag in the request. The first
069 * mode of operation is a synchronous mode in whice the CSW receives a Harvest request from the
070 * client, processes it immediately, and sends the results to the client while the client waits. The
071 * second mode of operation is asynchronous in that the server receives a Harvest request from the
072 * client, and sends the client an immediate acknowledgement that the request has been successfully
073 * received. The server can then process the Harvest request whenever it likes, taking as much time
074 * as is required and then send the results of the processing to a URI specified in the original
075 * Harvest request. This latter mode of operation is included to support Harvest requests that could
076 * run for a period of time longer than most HTTP timeout’s will allow.
077 * </p>
078 * <p>
079 * Processing a Harvest request means that the CSW resolves the URI pointing to the metadata
080 * resource, parses the resource, and then creates or modifies metadata records in the catalogue in
081 * order to register the resource. This operation may be performed only once or periodically
082 * depending on how the client invokes the operation.
083 * </p>
084 *
085 * @version $Revision: 18195 $
086 * @author <a href="mailto:poth@lat-lon.de">Andreas Poth</a>
087 * @author last edited by: $Author: mschneider $
088 *
089 * @version 1.0. $Revision: 18195 $, $Date: 2009-06-18 17:55:39 +0200 (Do, 18 Jun 2009) $
090 *
091 * @since 2.0
092 */
093 public class Harvest extends AbstractOGCWebServiceRequest {
094
095 private static final long serialVersionUID = -3531806711669781486L;
096
097 private static final ILogger LOG = LoggerFactory.getLogger( Harvest.class );
098
099 private URI source = null;
100
101 private URI resourceType = null;
102
103 private String resourceFormat = null;
104
105 private TimeDuration harvestInterval = null;
106
107 private List<URI> responseHandler = null;
108
109 private Date startTimestamp = null;
110
111 /**
112 * factory method for creating a Harvest request from its KVP representation
113 *
114 * @param param
115 * @return the harvest
116 * @throws InvalidParameterValueException
117 * @throws MissingParameterValueException
118 */
119 public static Harvest create( Map<String, String> param )
120 throws InvalidParameterValueException, MissingParameterValueException {
121
122 LOG.logInfo( "parse harvest request KVP-encoded" );
123
124 String id = param.get( "ID" );
125 if ( id == null ) {
126 throw new MissingParameterValueException( "ID parameter must be set" );
127 }
128
129 String version = param.get( "VERSION" );
130 if ( version == null ) {
131 throw new MissingParameterValueException( "VERSION parameter must be set for " + "a harvest request" );
132 }
133
134 String tmp = param.get( "SOURCE" );
135 if ( tmp == null ) {
136 throw new MissingParameterValueException( "SOURCE parameter must be set for " + "a harvest request" );
137 }
138 URI source = null;
139 try {
140 source = new URI( tmp );
141 } catch ( URISyntaxException e ) {
142 throw new InvalidParameterValueException( tmp + " is no valid source URI for a " + "harvest request" );
143 }
144
145 tmp = param.get( "RESOURCETYPE" );
146 URI resourceType = null;
147 if ( tmp != null ) {
148 try {
149 resourceType = new URI( tmp );
150 } catch ( URISyntaxException e ) {
151 throw new InvalidParameterValueException( tmp + " is no valid resourceType URI "
152 + "for a harvest request" );
153 }
154 }
155
156 String resourceFormat = param.get( "RESOURCEFORMAT" );
157 if ( resourceFormat == null ) {
158 resourceFormat = "text/xml";
159 }
160
161 List<URI> list = new ArrayList<URI>();
162 tmp = param.get( "RESPONSEHANDLER" );
163 URI responseHandler = null;
164 if ( tmp != null ) {
165 try {
166 responseHandler = new URI( tmp );
167 } catch ( URISyntaxException e ) {
168 throw new InvalidParameterValueException( tmp + " is no valid resourceHandler URI "
169 + "for a harvest request" );
170 }
171 list.add( responseHandler );
172 }
173
174 tmp = param.get( "HARVESTINTERVAL" );
175 TimeDuration timeDuration = null;
176 if ( tmp != null ) {
177 timeDuration = TimeDuration.createTimeDuration( tmp );
178 }
179
180 Date date = new GregorianCalendar().getTime();
181 tmp = param.get( "STARTTIMESTAMP" );
182 if ( tmp != null ) {
183 date = TimeTools.createCalendar( tmp ).getTime();
184 }
185
186 return new Harvest( version, id, null, source, resourceType, resourceFormat, timeDuration, list, date );
187 }
188
189 /**
190 * creates a Harvesting Request from its XM representation
191 *
192 * @param id
193 * @param transRoot
194 * @return the new transaction
195 * @throws XMLParsingException
196 */
197 public static final Transaction create( String id, Element transRoot )
198 throws XMLParsingException {
199 throw new UnsupportedOperationException( "create( String, Element )" );
200 }
201
202 /**
203 *
204 * @param version
205 * @param id
206 * @param vendorSpecificParameter
207 * @param source
208 * @param resourceType
209 * @param resourceFormat
210 * @param harvestTimeDuration
211 * @param responseHandler
212 */
213 Harvest( String version, String id, Map<String, String> vendorSpecificParameter, URI source, URI resourceType,
214 String resourceFormat, TimeDuration harvestTimeDuration, List<URI> responseHandler, Date startTimestamp ) {
215 super( version, id, vendorSpecificParameter );
216 this.source = source;
217 this.resourceType = resourceType;
218 this.resourceFormat = resourceFormat;
219 this.harvestInterval = harvestTimeDuration;
220 this.responseHandler = responseHandler;
221 this.startTimestamp = startTimestamp;
222 }
223
224 /**
225 * <p>
226 * The HarvestTimeDuration parameter is used to specify the period of time, in ISO 8601 period
227 * format, that should elapse before a CSW attempts to re-harvest the specified resource thus
228 * refreshing it copy of a resource.
229 * </p>
230 * <p>
231 * If no HarvestTimeDuration parameter is specified then the resource is harvested only once in
232 * response to the Harvest request.
233 * </p>
234 *
235 * @return the interval
236 */
237 public TimeDuration getHarvestInterval() {
238 return harvestInterval;
239 }
240
241 /**
242 * The ResourceFormat paramter is used to indicate the encoding used for the resource being
243 * harvested. This parameter is included to support the harvesting of metadata resources
244 * available in various formats such as plain text, XML or HTML. The values of this parameter
245 * must be a MIME type. If the parameter is not specified then the default value of text/xml
246 * should be assumed.
247 *
248 * @return the format
249 */
250 public String getResourceFormat() {
251 return resourceFormat;
252 }
253
254 /**
255 * The ResourceType parameter is a reference to a schema document that defines the structure of
256 * the resource being harvested. This is an optional parameter and if it not specified then the
257 * catalogue must employee other means to determine the type of resource being harvested. For
258 * example, the catalogue may use schema references in the input document to determine the
259 * resource type, or perhaps parse the root element to determine the type of metadata being
260 * harvested (e.g. <fgdc:metadata> is the root element of an FGDC document).
261 *
262 * @return the uri
263 */
264 public URI getResourceType() {
265 return resourceType;
266 }
267
268 /**
269 * <p>
270 * The ResponseHandler parameter is a flag that indicates how the Harvest operation should be
271 * processed by a CSW server.
272 * </p>
273 * <p>
274 * If the parameter is not present, then the Harvest operation is processed synchronously
275 * meaning that the client sends the Harvest request to a CSW and then waits to receive a
276 * HarvestResponse or exception message. The CSW immediately processes the Harvest request,
277 * while the client waits for a response. The problem with this mode of operation is that the
278 * client may timeout waiting for the server to process the request.
279 * </p>
280 * If the parameter is present, the Harvest operation is processed asynchronously. In this case,
281 * the server responds immediately to a client’s request with an acknowledgement message. The
282 * acknowlegment message echos the client’s request, using the <EchoedRequest> element,
283 * and may include an optionally generated request identifier using the <RequestId>
284 * element. The acknowledgement message tells the client that the request has been received and
285 * notification of completion will be send to the URL specified as the value of the
286 * ResponseHandler parameter. The Harvest request may then be processed at some later time
287 * taking as much time as is required to complete the operation. When the operation is
288 * completed, a HarvestResponse message or exception message (if a problem was encountered) is
289 * sent to the URL specified as the value of the ResponseHandler parameter.
290 *
291 * @return the list of uris
292 */
293 public List<URI> getResponseHandler() {
294 return responseHandler;
295 }
296
297 /**
298 * The Source parameter is used to specify a URI reference to the metadata resource to be
299 * harvested.
300 *
301 * @return the uri
302 */
303 public URI getSource() {
304 return source;
305 }
306
307 /**
308 * returns the deegree specific timestamp when harvesting shall start. If <code>null</code> is
309 * returned harvesting shall start as soon as possible
310 *
311 * @return the date
312 */
313 public Date getStartTimestamp() {
314 return startTimestamp;
315 }
316
317 /**
318 * will always return 'CSW'
319 */
320 public String getServiceName() {
321 return "CSW";
322 }
323
324 }