1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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 }