org.ceryle.util
Class IDFactory

java.lang.Object
  org.ceryle.util.IDFactory

All Implemented Interfaces:

IDGenerator

public class IDFactory
extends Object
implements IDGenerator

IDFactory produces a unique String identifier (ID) upon demand. All are suitable as XML IDs.

Factory Type

The class uses either an int value provided in the constructor or a preset System property to determine the type of IDs to generate (as noted above). If the System property is set, its value will take priority and the parameter values provided during construction are ignored.

The recognized property values for the type property:

    http://purl.org/ceryle/prop/#idfactory
  

are as follows (case insensitive):

incremental

constructs an incremental IDFactory (equivalent to TYPE_INCREMENTAL, where IDs are incremental integers are appended to a base string with no hyphen, though this can be supplied as part of the prefix itself (e.g., "id1", "id2", "id3", ...).

randomword

constructs a random word IDFactory (equivalent to TYPE_RANDOM_WORD, where IDs are generated pseudo-random ("nonsense") words (e.g., "Zeef", "Goyg", "Dath", ...). This is probably not suitable for very large numbers of IDs. or,

timestamp

constructs a timestamp IDFactory (equivalent to TYPE_TIMESTAMP, where IDs are timestamp-based long values converted to base 64 appended to a base string. Because the backing ID generator is guaranteed to generate unique values (within the JVM), no registry is used.

ID Structure

The structure of the generated ID is in four parts, depending on the factory type and whether the prefix is supplied at construction time and/or method call:

       prefix + initialValue + '-' + generated_value
  

The prefix is used when a prefix value has been set prior to construction using setPrefix(String), so that context-specific IDs can be generated, such as "topic-[generated_value]" or "assoc-[generated_value]". The initialValue is an option long value that can be used to create a unique numeric context, such as generated by a timestamp. The constructor will check if the parameter is larger than the millisecond count at the millenium (ID64Generator.MILLENIUM_MILLIS), and if so convert the parameter to a base 64 value.

IDGenerator Implementation

This class implements the TM4J IDGenerator interface; hence it can be used wherever implementations of that interface are called for. The default constructor creates an IDFactory (whose type is TYPE_TIMESTAMP), which produces output similar to the TM4J IDGeneratorImpl class.

Since:

JDK1.3

Version:

$Id: IDFactory.java,v 3.9 2007-06-15 12:09:55 altheim Exp $

Author:

Murray Altheim

Field Summary

static boolean	FORCE_FIRSTCHAR_LOWERCASE When true, the first character of autogenerated IDs will be lowercased.
static int	ID_MAXLENGTH A recommended maximum length for ID values.
protected int	m_factory_type A member variable indicating which format of output this IDFactory will generate.
static String	PROPERTY_FACTORY_TYPE The property name for the ID factory type.
static String	PROPERTY_VALUE_INCREMENTAL The property value for the ID factory type incremental.
static String	PROPERTY_VALUE_RANDOMWORD The property value for the ID factory type random word.
static String	PROPERTY_VALUE_TIMESTAMP The property value for the ID factory type time stamp.
static int	RADIX Used as the radix value for the incremental counter for timestamped IDs.
static int	TYPE_INCREMENTAL An enumerated type contant indicating that this IDFactory IDFactory will generate incremental values.
static int	TYPE_RANDOM_WORD An enumerated type contant indicating that this IDFactory IDFactory will generate random word values.
static int	TYPE_TIMESTAMP An enumerated type contant indicating that this IDFactory IDFactory will generate timestamp-based values.

Constructor Summary

IDFactory()
Default constructor creating a timestamp IDFactory, similar to the output of org.tm4j.topicmap.util.IDGeneratorImpl.

IDFactory(int factoryType, String prefix, long initialValue)
Full constructor with an int type factoryType (see PROPERTY_FACTORY_TYPE), an ID prefix String prefix, and an initial ID value initialValue.

IDFactory(String prefix)
Constructor with an ID prefix String prefix.

Method Summary

String	getID() Generate a unique ID.
String	getID(String prefix) Generate a unique ID, depending on factory type.
String	getIDFromName_old(String name) Generate a unique ID as a transform of a provided String name.
String	getIDFromName(String name) Generate a unique ID as a transform of a provided String name.
static String	getPrefix() Returns the ID prefix String.
String	getRandomWord() Generate a random nonsense word.
String	getUniqueID(String id, Collection list, int max) Given a String id, removes any whitespace or disallowed XML Name characters, then provides an alternate rendition by appending or incrementing an existing end-number.
static boolean	isID(String s) Returns true if the provided String is a valid ID.
static boolean	isName(String s) Returns true if the provided String is a valid XML Name.
boolean	registerID(String id) Register a foreign-generated ID with this IDFactory.
boolean	registerIDs(Collection ids, boolean clear) Register a Set of foreign-generated IDs with this IDFactory.
void	reset() Resets the counter to its initial value.
static void	setPrefix(String prefix) Sets the ID prefix String used by this IDFactory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTY_FACTORY_TYPE

public static final String PROPERTY_FACTORY_TYPE

The property name for the ID factory type. The value is "http://purl.org/ceryle/prop/#idfactory".

See Also:

Constant Field Values

PROPERTY_VALUE_INCREMENTAL

public static final String PROPERTY_VALUE_INCREMENTAL

The property value for the ID factory type incremental. When set, this is equivalent to type TYPE_INCREMENTAL. The value is "incremental".

See Also:

Constant Field Values

PROPERTY_VALUE_RANDOMWORD

public static final String PROPERTY_VALUE_RANDOMWORD

The property value for the ID factory type random word. When set, this is equivalent to type TYPE_RANDOM_WORD. The value is "randomword".

See Also:

Constant Field Values

PROPERTY_VALUE_TIMESTAMP

public static final String PROPERTY_VALUE_TIMESTAMP

The property value for the ID factory type time stamp. When set, this is equivalent to type TYPE_TIMESTAMP. The value is "timestamp".

See Also:

Constant Field Values

ID_MAXLENGTH

public static int ID_MAXLENGTH

A recommended maximum length for ID values. The default value is 64.

TYPE_INCREMENTAL

public static final int TYPE_INCREMENTAL

An enumerated type contant indicating that this IDFactory IDFactory will generate incremental values.

See Also:

PROPERTY_FACTORY_TYPE, Constant Field Values

TYPE_RANDOM_WORD

public static final int TYPE_RANDOM_WORD

An enumerated type contant indicating that this IDFactory IDFactory will generate random word values.

See Also:

PROPERTY_FACTORY_TYPE, Constant Field Values

TYPE_TIMESTAMP

public static final int TYPE_TIMESTAMP

An enumerated type contant indicating that this IDFactory IDFactory will generate timestamp-based values. These are the most reliably unique across multiple topic maps, but are substantially longer than the other forms.

See Also:

PROPERTY_FACTORY_TYPE, Constant Field Values

m_factory_type

protected int m_factory_type

A member variable indicating which format of output this IDFactory will generate. The constructor defaults to TYPE_INCREMENTAL.

RADIX

public static int RADIX

Used as the radix value for the incremental counter for timestamped IDs. Use 36 for alphanumeric, 16 for hex, 10 for decimal (default).

FORCE_FIRSTCHAR_LOWERCASE

public static boolean FORCE_FIRSTCHAR_LOWERCASE

When true, the first character of autogenerated IDs will be lowercased. The default is false, since (nowadays) we want default IDs to be wiki words.

Constructor Detail

IDFactory

public IDFactory()

Default constructor creating a timestamp IDFactory, similar to the output of org.tm4j.topicmap.util.IDGeneratorImpl.

See Also:

IDGeneratorImpl

IDFactory

public IDFactory(String prefix)

Constructor with an ID prefix String prefix. This constructor will create an IDFactory that creates Strings that are random, generated "words", unique within the IDFactory's registry. If the supplied prefix is null, no prefix will be used.

IDFactory

public IDFactory(int factoryType,
                 String prefix,
                 long initialValue)

Full constructor with an int type factoryType (see PROPERTY_FACTORY_TYPE), an ID prefix String prefix, and an initial ID value initialValue. Note that if the System property is set prior to construction, the value provided here will be ignored.

Notes

• If using the incremental factory, the provided initialValue is used as the initial counter value.
• If using the timestamp factory and the initial value is a positive number, the prefix (default "id") and its value will be prepended as a base prefix (e.g., "34" would prepend "id34-" to all generated IDs).
• When using the random word factory, the initialValue is ignored.
• If the factoryType is unrecognized, an incremental ID factory is created.

Parameters:

factoryType - the type of factory to create

prefix - the optional prefix string (if null, no prefix is used)

initialValue - the optional initial numeric value (used as part of the prefix)

Method Detail

isID

public static boolean isID(String s)

Returns true if the provided String is a valid ID. This is an XML Name that does not include the colon character.

isName

public static boolean isName(String s)

Returns true if the provided String is a valid XML Name. Note that this includes the colon character.

registerID

public boolean registerID(String id)

Register a foreign-generated ID with this IDFactory.

Returns:

true if the value of id was not already in the registry and it was successfully added.

registerIDs

public boolean registerIDs(Collection ids,
                           boolean clear)

Register a Set of foreign-generated IDs with this IDFactory. This clears the list first, if clear is true.

Returns:

true if the registry was altered by the addition.

getID

public String getID()

Generate a unique ID. A convenience method equivalent to getID(null), also required for conformance to the org.tm4j.topicmap.util.IDGenerator API.

Specified by:

getID in interface IDGenerator

See Also:

IDGenerator

getID

public String getID(String prefix)

Generate a unique ID, depending on factory type. This checks the generated ID against those in the registry and retries until a unique one is created. If the String prefix is non-null, its value will be prepended to the ID instead of the baseID set at construction time.

getIDFromName_old

public String getIDFromName_old(String name)

Generate a unique ID as a transform of a provided String name. The value of name may contain invalid characters, spaces, etc. The returned ID is guaranteed to be an XML Name, unique within the IDFactory's internal ID registry.

getIDFromName

public String getIDFromName(String name)

Generate a unique ID as a transform of a provided String name. The value of name may contain invalid characters, spaces, etc. The returned ID is guaranteed to be an XML Name, unique within the IDFactory's internal ID registry.

setPrefix

public static void setPrefix(String prefix)

Sets the ID prefix String used by this IDFactory. This sets a static variable that is only pertinent during class initialization in creation of the base ID. All IDs produced will be prefixed with the prefix String, so if the IDs must be XML Names, the prefix must begin with an XML NameStart character and contain only valid XML Name characters. Attempts to set the prefix to null or non-names are ignored.

getPrefix

public static String getPrefix()

Returns the ID prefix String.

reset

public void reset()

Resets the counter to its initial value. (This is only pertinent when the counter is actually being used.)

getRandomWord

public String getRandomWord()

Generate a random nonsense word. This is a utility method within IDFactory (whose output is not entered into the ID registry).

getUniqueID

public String getUniqueID(String id,
                          Collection list,
                          int max)

Given a String id, removes any whitespace or disallowed XML Name characters, then provides an alternate rendition by appending or incrementing an existing end-number. This is compared against the Strings in the supplied Collection (if provided) and the end value incremented until a unique value is encountered. This collection is independent of the registry within the IDFactory (i.e., this method may be used independently of the IDFactory) and is not modified by this method. This is principally useful in creating a unique ID value related to the title.

The maximum length of the base String (i.e, not including the end number) is set by max, with a max value less than one interpreted as no maximum. For example, provided "abc", returns "abc1"; provided "abc77", returns "abc78"; provided "the Cat in the Hat 77" with max of 5, returns "theCat78". If the provided String does not begin with an XML Name start character, the IDFactory prefix String (default "id") is prepended. Also, this will strip out colons and removes the first three characters of the String if they case-insensitively match "xml" (since that's a disallowed ID).

Parameters:

id - a source for the generated ID

list - the list of existing IDs to compare against

max - the maximum length in characters of the generated ID