Holger's Java API

## com.antelmann.db
Class SessionIdGenerator

    java.lang.Object
      com.antelmann.db.SessionIdGenerator

All Implemented Interfaces:
  IDFactory, Converter<Integer,String>

Direct Known Subclasses:
  GIDFactory

    public abstract class SessionIdGenerator

extends Object
implements IDFactory, Converter<Integer,String>

This class provides efficient unique String-based IDs for different clients. The implementation uses one abstract method to generate (and store) an ID for a client session. This session-ID is then used as a prefix for the actual IDs that are given out by the method `generateNewID()`, which is to be used to create new IDs from this class. Each ID given out is unique, as the ID concatenates the session-prefix with a counter, that is incremented on each call. This way, this implementation creates new IDs quite efficiently, as a call to the database only needs to occur once for the initialization of the prefix. After initialization, every call to generate a new ID for the client only requires local access of this class where a simple counter is used to guarantee that each call for generating a new ID is unique.

Since:
  27. August 2007, 21:56
Author:
  Holger Antelmann
See Also:
  `DBClassStore.generateNewID()`

Nested Class Summary

Nested classes/interfaces inherited from interface com.antelmann.util.Converter
`Converter.Adapter<T1,T2>`

Constructor Summary
`SessionIdGenerator(Database<?> db)`
`SessionIdGenerator(Database<?> db, int radix)` before any IDs can be retrieved, the instance must be initialized before use.

Method Summary
`String` `convert(Integer i)`
`Integer` `convertBack(String str)`
`String` `generateNewID()`
`Object` `generateNewID(Class<? extends DBEntry> entryClass)` this implementation doesn't do anything but returning generateNewID(), thus disregarding the given parameter
`protected abstract String` `generateSessionPrefix()` this method is to access the database to generate a new session prefix on every call and also store it into the database, so that it is guaranteed that no other call ever re-uses this prefix again.
`protected String` `generateSQLSessionPrefix(Connection con, String table, String idColumn, String sessionKey, String valueColumn, String separator)`
`int` `getCounter()` returns the current value of the session counter
`Database<?>` `getDatabase()`
`int` `getRadix()` unless changed, the default value is 10.
`String` `getSessionPrefix()` returns the prefix for the current session; if this instance is not initialized, this method return s null;
`void` `initNewSession()` this method must be called at least once after instanciation to init a new session for providing unique IDs.
`void` `setRadix(int radix)` allows to adjust the radix for generating the number string to compress the length of a generated ID.
`void` `setSessionDataManually(String sessionPrefix, int counter, boolean yesIKnowWhatIAmDoing)` allows to manually override the session prefix - use with caution - if at all

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### SessionIdGenerator

    public SessionIdGenerator(Database<?> db)

### SessionIdGenerator

    public SessionIdGenerator(Database<?> db,
                              int radix)

  before any IDs can be retrieved, the instance must be initialized before use.

  See Also:
    `initNewSession()`

Method Detail

### getRadix

    public int getRadix()

  unless changed, the default value is 10.

  See Also:
    `setRadix(int)`

### setRadix

    public void setRadix(int radix)

  allows to adjust the radix for generating the number string to compress the length of a generated ID.

  See Also:
    `Integer.toString(int, int)`

### generateSessionPrefix

    protected abstract String generateSessionPrefix()
                                             throws DatabaseException

  this method is to access the database to generate a new session prefix on every call and also store it into the database, so that it is guaranteed that no other call ever re-uses this prefix again. Note that this method must not manage the transaction, as this method is called by `initNewSession()`, which begins and commits its own transaction; i.e. this method can be savely assumed to run within a synchronized transaction.

  Returns:
    a new unique session-ID from the database to be used as a prefix for this session
  Throws:
    `DatabaseException`
  See Also:
    `initNewSession()`

### setSessionDataManually

    @Warning(value="using this method may result in non-unique IDs - YOU BETTER KNOW WHAT YOU\'RE DOING HERE")
    public void setSessionDataManually(String sessionPrefix,
                                                    int counter,
                                                    boolean yesIKnowWhatIAmDoing)

  allows to manually override the session prefix - use with caution - if at all

### initNewSession

    public void initNewSession()
                        throws DatabaseException

  this method must be called at least once after instanciation to init a new session for providing unique IDs. On each call, this method (synchronized on the transaction object) begins a transaction, calls `generateSessionPrefix()` and then commits the transaction, so that it is guaranteed that every call from any client at any time will initialize a new and unique session.

  Throws:
    `DatabaseException`
  See Also:
    `generateSessionPrefix()`

### getSessionPrefix

    public String getSessionPrefix()

  returns the prefix for the current session; if this instance is not initialized, this method return s null;

### getCounter

    public int getCounter()

  returns the current value of the session counter

### generateNewID

    public Object generateNewID(Class<? extends DBEntry> entryClass)
                         throws DatabaseException,
                                IllegalArgumentException

  this implementation doesn't do anything but returning generateNewID(), thus disregarding the given parameter

  Specified by:
    `generateNewID` in interface `IDFactory`
  Returns:
    an Object for use as an ID for the given DBEntry class.
  Throws:
    `DatabaseException`
    `IllegalArgumentException`

### convert

    public String convert(Integer i)

  Specified by:
    `convert` in interface `Converter<Integer,String>`

### convertBack

    public Integer convertBack(String str)
                        throws IllegalArgumentException

  Specified by:
    `convertBack` in interface `Converter<Integer,String>`
  Throws:
    `IllegalArgumentException`

### generateNewID

    public String generateNewID()
                         throws IllegalStateException

  Returns:
    a unique ID on every call that can be used as a String-based ID for DBEntry objects.
  Throws:
    `IllegalStateException` - if no session has been initialized, yet
  See Also:
    `initNewSession()`, `DBEntry`, `DBClassStore.generateNewID()`

### getDatabase

    public Database<?> getDatabase()

### generateSQLSessionPrefix

    protected String generateSQLSessionPrefix(Connection con,
                                              String table,
                                              String idColumn,
                                              String sessionKey,
                                              String valueColumn,
                                              String separator)
                                       throws DatabaseException

  Throws:
    `DatabaseException`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads