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. &lt;fgdc:metadata&gt; 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 &lt;EchoedRequest&gt; element,
283         * and may include an optionally generated request identifier using the &lt;RequestId&gt;
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    }