org.neo4j.kernel.impl.nioneo.store
Class IdGeneratorImpl

java.lang.Object
  org.neo4j.kernel.impl.nioneo.store.IdGeneratorImpl

All Implemented Interfaces:

IdGenerator

public class IdGeneratorImpl
extends Object
implements IdGenerator

This class generates unique ids for a resource type. For example, nodes in a nodes space are connected to each other via relationships. On nodes and relationship one can add properties. We have three different resource types here (nodes, relationships and properties) where each resource needs a unique id to be able to differ resources of the same type from each other. Creating three id generators (one for each resource type ) will do the trick.

IdGenerator makes use of so called "defragged" ids. A defragged id is an id that has been in use one or many times but the resource that was using it doesn't exist anymore. This makes it possible to reuse the id and that in turn makes it possible to write a resource store with fixed records and size (you can calculate the position of a record by knowing the id without using indexes or a translation table).

The id returned from nextId() may not be the lowest available id but will be one of the defragged ids if such exist or the next new free id that has never been used.

The freeId(long) will not check if the id passed in to it really is free. Passing a non free id will corrupt the id generator and nextId() method will eventually return that id.

The #close() method must always be invoked when done using an generator (for this time). Failure to do will render the generator as "sticky" and unusable next time you try to initialize a generator using the same file. There can only be one id generator instance per id generator file.

In case of disk/file I/O failure an IOException is thrown.

Field Summary

static long

INTEGER_MINUS_ONE

Constructor Summary

IdGeneratorImpl(String fileName, int grabSize, long max, boolean aggressiveReuse)
Opens the id generator represented by fileName.

Method Summary

void	clearFreeIds()
void	close(boolean shutdown) Closes the id generator flushing defragged ids in memory to file.
static void	createGenerator(String fileName) Creates a new id generator.
void	delete()
void	dumpFreeIds() Utility method that will dump all defragged id's and the "high id" to console.
void	freeId(long id) Frees the id making it a defragged id that will be returned by next id before any new id (that hasn't been used yet) is returned.
long	getDefragCount()
String	getFileName() Returns the file associated with this id generator.
long	getHighId() Returns the next "high" id that will be returned if no defragged ids exist.
long	getNumberOfIdsInUse()
long	nextId() Returns the next "free" id.
IdRange	nextIdBatch(int size)
void	setHighId(long id) Sets the next free "high" id.

Methods inherited from class java.lang.Object

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

Field Detail

INTEGER_MINUS_ONE

public static final long INTEGER_MINUS_ONE

See Also:

Constant Field Values

Constructor Detail

IdGeneratorImpl

public IdGeneratorImpl(String fileName,
                       int grabSize,
                       long max,
                       boolean aggressiveReuse)

Opens the id generator represented by fileName. The grabSize means how many defragged ids we should keep in memory and is also the size (x4) of the two buffers used for reading and writing to the id generator file. The highest returned id will be read from file and if grabSize number of ids exist they will be read into memory (if less exist all defragged ids will be in memory).

If this id generator hasn't been closed properly since the previous session (sticky) an IOException will be thrown. When this happens one has to rebuild the id generator from the (node/rel/prop) store file.

Parameters:

fileName - The file name (and path if needed) for the id generator to be opened

grabSize - The number of defragged ids to keep in memory

max - is the highest possible id to be returned by this id generator from nextId().

aggressiveReuse - will reuse ids during the same session, not requiring a restart to be able reuse ids freed with freeId(long).

Throws:

UnderlyingStorageException - If no such file exist or if the id generator is sticky

Method Detail

nextId

public long nextId()

Returns the next "free" id. If a defragged id exist it will be returned else the next free id that hasn't been used yet is returned. If no id exist the capacity is exceeded (all values <= max are taken) and a UnderlyingStorageException will be thrown.

Specified by:

nextId in interface IdGenerator

Returns:

The next free id

Throws:

UnderlyingStorageException - If the capacity is exceeded

IllegalStateException - if this id generator has been closed

nextIdBatch

public IdRange nextIdBatch(int size)

Specified by:

nextIdBatch in interface IdGenerator

setHighId

public void setHighId(long id)

Sets the next free "high" id. This method should be called when an id generator has been rebuilt. id must not be higher than max.

Specified by:

setHighId in interface IdGenerator

Parameters:

id - The next free id

getHighId

public long getHighId()

Returns the next "high" id that will be returned if no defragged ids exist.

Specified by:

getHighId in interface IdGenerator

Returns:

The next free "high" id

freeId

public void freeId(long id)

Frees the id making it a defragged id that will be returned by next id before any new id (that hasn't been used yet) is returned.

This method will throw an IOException if id is negative or if id is greater than the highest returned id. However as stated in the class documentation above the id isn't validated to see if it really is free.

Specified by:

freeId in interface IdGenerator

Parameters:

id - The id to be made available again

Throws:

IOException - If id is negative or greater than the highest returned id

close

public void close(boolean shutdown)

Closes the id generator flushing defragged ids in memory to file. The file will be truncated to the minimal size required to hold all defragged ids and it will be marked as clean (not sticky).

An invoke to the nextId or freeId after this method has been invoked will result in an IOException since the highest returned id has been set to a negative value.

Specified by:

close in interface IdGenerator

Parameters:

shutdown - true if this is during shutdown of the database, false if it's an intermediary close, f.ex after rebuilding id generators at startup.

Throws:

IOException - If unable to close this id generator

getFileName

public String getFileName()

Returns the file associated with this id generator.

Returns:

The id generator's file name

createGenerator

public static void createGenerator(String fileName)

Creates a new id generator.

Parameters:

fileName - The name of the id generator

Throws:

IOException - If unable to create the id generator

dumpFreeIds

public void dumpFreeIds()

Utility method that will dump all defragged id's and the "high id" to console. Do not call while running store using this id generator since it could corrupt the id generator (not thread safe). This method will close the id generator after being invoked.

Throws:

IOException - If problem dumping free ids

getNumberOfIdsInUse

public long getNumberOfIdsInUse()

Specified by:

getNumberOfIdsInUse in interface IdGenerator

getDefragCount

public long getDefragCount()

Specified by:

getDefragCount in interface IdGenerator

clearFreeIds

public void clearFreeIds()

delete

public void delete()

Specified by:

delete in interface IdGenerator