    001    //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/branches/2.4_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    }