Generator


1   /* $Id: Generator.java,v 1.2 2006/08/15 00:25:01 paul_jack Exp $
2    *
3    * Created on July 27th, 2006
4    *
5    * Copyright (C) 2006 Internet Archive.
6    *
7    * This file is part of the Heritrix web crawler (crawler.archive.org).
8    *
9    * 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: 1.2 $ $Date: 2006/08/15 00:25:01 $
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  }
84
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags