01: /* $Id: Generator.java 4495 2006-08-15 00:25:03Z paul_jack $
02: *
03: * Created on July 27th, 2006
04: *
05: * Copyright (C) 2006 Internet Archive.
06: *
07: * This file is part of the Heritrix web crawler (crawler.archive.org).
08: *
09: * Heritrix is free software; you can redistribute it and/or modify
10: * it under the terms of the GNU Lesser Public License as published by
11: * the Free Software Foundation; either version 2.1 of the License, or
12: * any later version.
13: *
14: * Heritrix is distributed in the hope that it will be useful,
15: * but WITHOUT ANY WARRANTY; without even the implied warranty of
16: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17: * GNU Lesser Public License for more details.
18: *
19: * You should have received a copy of the GNU Lesser Public License
20: * along with Heritrix; if not, write to the Free Software
21: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22: */
23: package org.archive.uid;
24:
25: import java.net.URI;
26: import java.net.URISyntaxException;
27: import java.util.Map;
28:
29: /**
30: * A <code>record-id</code> generator.
31: * {@link GeneratorFactory} assumes implementations have a no-arg Constructor.
32: * @see GeneratorFactory
33: * @author stack
34: * @version $Revision: 4495 $ $Date: 2006-08-15 00:25:03 +0000 (Tue, 15 Aug 2006) $
35: */
36: public interface Generator {
37: /**
38: * @return A URI that can serve as a record-id.
39: * @throws URISyntaxException
40: */
41: public URI getRecordID() throws URISyntaxException;
42:
43: /**
44: * @param qualifiers Qualifiers to add.
45: * @return A URI qualified with passed <code>qualifiers</code> that can
46: * serve as a record-id, or, a new, unique record-id without qualifiers
47: * (if qualifiers not easily implemented using passed URI scheme).
48: * @throws URISyntaxException
49: */
50: public URI getQualifiedRecordID(final Map<String, String> qualifiers)
51: throws URISyntaxException;
52:
53: /**
54: * @param key Name of qualifier
55: * @param value Value of qualifier
56: * @return A URI qualified with passed <code>qualifiers</code> that can
57: * serve as a record-id, or, a new, unique record-id without qualifiers
58: * (if qualifiers not easily implemented using passed URI scheme).
59: * @throws URISyntaxException
60: */
61: public URI getQualifiedRecordID(final String key, final String value)
62: throws URISyntaxException;
63:
64: /**
65: * Append (or if already present, update) qualifiers to passed
66: * <code>recordId</code>. Use with caution. Guard against turning up a
67: * result that already exists. Use when writing a group of records inside
68: * a single transaction.
69: *
70: * How qualifiers are appended/updated varies with URI scheme. Its allowed
71: * that an invocation of this method does nought but call
72: * {@link #getRecordID()}, returning a new URI unrelated to the passed
73: * recordId and passed qualifier.
74: * @param recordId URI to append qualifier to.
75: * @param qualifiers Map of qualifier values keyed by qualifier name.
76: * @return New URI based off passed <code>uri</code> and passed qualifier.
77: * @throws URISyntaxException if probably constructing URI OR if the
78: * resultant UUID does not differ from the one passed.
79: */
80: public URI qualifyRecordID(final URI recordId,
81: final Map<String, String> qualifiers)
82: throws URISyntaxException;
83: }
|