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