View Javadoc

    1   /* $Id: Generator.java 4495 2006-08-15 00:25:03Z paul_jack $
    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: 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  }