org.starhope.appius.user
Class Nomenclator

java.lang.Object
  org.starhope.appius.user.Nomenclator

public class Nomenclator
extends Object

The Nomenclator is the universal factory and caché mechanism for all game objects derived from DataRecord, and provides facilities for caching of arbitrary objects as well. The most common way to obtain any game object is to call getDataRecord(Class, int) or getDataRecord(Class, String), which will check caché for an existing reference, or instantiate one from a data store (e.g. database) automatically.

Author:

brpocock@star-hope.org

Field Summary

private static ConcurrentSkipListSet<String>

allCaches an index of all cachés

Constructor Summary

Nomenclator()

Method Summary

static void	assertLoginAvailable(String userNameRequested) Make the assertion that the user name supplied is available to be requested or assigned to this user.
static <RecordClass extends DataRecord,StorageBaseClass extends DataRecordBacked<RecordClass>,InstanceClass extends StorageBaseClass> void	cache(Class<StorageBaseClass> klass, InstanceClass obj, RecordClass rec) Store an object into a caché in which the object is identified by a DataRecord instance object.
static <T extends DataRecord> void	cache(Class<T> klassGiven, int id, String ident, T o) Store an item into a caché, for which we've already extracted the object's identification string and integer values.
static <T extends DataRecord,S extends T> void	cache(T record) Store a DataRecord into the caché based upon its identifying string and integers.
static <T> void	cache(T o, String ident) Store an arbitrary object in a caché.
private static String	cacheInfoToString(com.whirlycott.cache.CacheDecorator<?,?> cache) put out caché info in string form
static void	clearCaches() clear all cachés (possibly causing severe consistency problems)
static AbstractUser	create(Date date, String string, String nick) Create a new user account
static <T extends DataRecord> T	findInCache(Class<T> klass, int id) Find an object in the caché, given its class and identifying integer.
static <S extends DataRecord,T extends DataRecordBacked<S>> T	findInCache(Class<T> klass, S rec) Find an object in the caché, given its base storage class and a DataRecord which uniquely identifies it.
static <T extends DataRecord> T	findInCache(Class<T> klass, String ident) Find an object in the caché based upon a class and a string identifier.
static <T> T	findInGenericCache(Class<T> klass, String ident) Find a generic object in a caché, without regards for the object's type.
static AbstractUser	get(org.json.JSONObject object) Pick up a user from a JSON object containing either the ID or login (user name) string.
static String	getAllCacheInfo() get information about all cachés
static <T extends DataRecord> T	getDataRecord(Class<T> klassGiven, int id) Obtain a data record (implementing DataRecord) of the given class, based upon its unique numeric identifier.
static <T extends DataRecord> T	getDataRecord(Class<T> klassGiven, String identifier) Get a data record by either searching the caché or loading it.
static <T extends DataRecord> T	getDataRecord(String klass, int id) get a data record given a string class name and an ID
static <T extends DataRecord> T	getDataRecord(String klass, String ident) get a data record given a specific class name string and identifier string
static <T extends Iterator<? extends DataRecord>> T	getDataRecordIterator(Class<T> klass, Object... constructorArgs) get a data record iterator
private static <T> com.whirlycott.cache.Cache<Integer,T>	getIDCache(Class<T> klassGiven) get the caché for ID (integer) records of a given class (or gens)
private static <T> com.whirlycott.cache.Cache<String,T>	getIdentCache(Class<T> klassGiven) get the caché for objects of some kind based on their string identifier
static int	getIDForLiveUserName(String name) Find the user name for a user who is currently signed on.
private static AbstractUser	getInstanceNPCByName(String instanceName) Find a cached NPC
static String	getLoginForID(int id)
private static <T> Class<T>	getNomenGentile(Class<? extends T> klassGiven) Get the nomen gentile of the class provided
static AbstractUser	getOnlineUserByLogin(String login) get a user by their login, but *only* if they are currently online; pull only from live user sources, and not from the database.
static Parent	getParentByApprovalCookie(String cookie)
static Parent	getParentByID(int id)
static Parent	getParentByMail(String mail)
private static <S extends DataRecord> String	getRecIDForBackedObject(S rec) get a record ID for something that is in turn backed by some kind of data record
private static <T> com.whirlycott.cache.Cache<String,T>	getRecordBackedCache(Class<T> klass) Get a caché backed by a type of record
private static <T,S> com.whirlycott.cache.Cache<S,T>	getSomeCache(Class<T> tClass, String s, Class<S> sClass) get a caché containing records of a given type, with keys of another given type, using a given suffix code
static AbstractUser	getSystemUser() Get the System user object (the user which represents the system program itself).
static AbstractUser	getUserByID(int id) Instantiate a user object from an existing user account ID
static AbstractUser	getUserByLogin(String login)
static AbstractUser	getUserByRequestedName(String userNameRequested) Get the user who has requested a certain name, if any.
static int	getUserIDForLogin(String name) Fetch the user ID number for a user name
static AbstractUser[]	getUsersByMail(String mail) Returns an array of all users associated with a given eMail address.
private static <S,T> com.whirlycott.cache.Cache<S,T>	initializeClassCache(Class<S> idClass, Class<T> klass, String ext) WRITEME: Document this method brpocock@star-hope.org
static <T extends DataRecordBacked<S>,S extends DataRecord> T	instantiate(Class<T> klass, S record) Instantiate an instance of an object which wraps a data record
(package private) static AbstractUser	instantiateUser(UserRecord rec) Instantiate a User (using the selected subclass) from the result set garnered from a SELECT *
static boolean	isLoginAvailable(String name) Determine whether the given name is potentially available for use.
static boolean	isLoginForbidden(String userNameRequested) Determine whether a name is forbidden
static <S extends DataRecord,T extends S> void	killCache(Class<S> klass, T o) Remove an arbitrary object from a caché.
static <T extends DataRecord> T	make(Class<T> klass, Object... more) WRITEME: Document this method brpocock@star-hope.org
static void	removeInstanceNPC(GeneralUser npc) Remove an instanced NPC from the caché on its destruction.

Methods inherited from class java.lang.Object

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

Field Detail

allCaches

private static ConcurrentSkipListSet<String> allCaches

an index of all cachés

Constructor Detail

Nomenclator

public Nomenclator()

Method Detail

assertLoginAvailable

public static void assertLoginAvailable(String userNameRequested)
                                 throws AlreadyUsedException,
                                        ForbiddenUserException

Make the assertion that the user name supplied is available to be requested or assigned to this user.

Note that having another user request the name, which has not been either permitted or denied, will still throw an AlreadyUsedException.

This routine returns void, because it throws exceptions if the name is forbidden or already used. For a boolean version, see (String)

Parameters:

userNameRequested - The name which is being requested

Throws:

AlreadyUsedException - if the user name has been requested or accepted already

ForbiddenUserException - if the user name is forbidden from use (obscene, gives away personal information, or so forth). See (String)

cache

public static <RecordClass extends DataRecord,StorageBaseClass extends DataRecordBacked<RecordClass>,InstanceClass extends StorageBaseClass> void cache(Class<StorageBaseClass> klass,
                                                                                                                                                        InstanceClass obj,
                                                                                                                                                        RecordClass rec)

Store an object into a caché in which the object is identified by a DataRecord instance object. For this method to function, the object must implement the DataRecordBacked interface. The representative class of the object must also be specified, allowing “comparable” implementations of a common base class to be stored in the same caché.

Type Parameters:

RecordClass - The DataRecord identifying this object must be a member of a class which extends DataRecord, of course.

StorageBaseClass - The base class of which the object being stored is either a member of, or a member of an extending/implementing class thereof.

InstanceClass - The class of which the object is actually an instance, which extends StorageBaseClass (or is StorageBaseClass)

Parameters:

klass - The class identifier of the caché in which the object is to be stored.

obj - The object to be stored in the caché

rec - The DataRecord uniquely identifying the object. The identifiers of this DataRecord will be used as keys to the caché.

cache

public static <T extends DataRecord> void cache(Class<T> klassGiven,
                                                int id,
                                                String ident,
                                                T o)

Store an item into a caché, for which we've already extracted the object's identification string and integer values.

Type Parameters:

T - The class of object (descended of DataRecord)

Parameters:

klassGiven - The class of object (descended of DataRecord )

id - The numeric ID under which to caché the reference

ident - The string ID under which to caché the reference

o - The object to be cached

cache

public static <T extends DataRecord,S extends T> void cache(T record)

Store a DataRecord into the caché based upon its identifying string and integers.

Type Parameters:

T - the class of the record to be stored in the caché

S - the class of the record to be stored in the caché

Parameters:

record - the record to be stored in the caché

cache

public static <T> void cache(T o,
                             String ident)

Store an arbitrary object in a caché. Note that this is not recommended for any class that is either a DataRecord nor an implementation of DataRecordBacked.

Type Parameters:

T - The class of the arbitrary object

Parameters:

o - An arbitrary object to be stored in the caché.

ident - A globally unique identifier, which should include enough information to uniquely identify it among all objects which might be stored.

cacheInfoToString

private static String cacheInfoToString(com.whirlycott.cache.CacheDecorator<?,?> cache)
                                 throws com.whirlycott.cache.CacheException

put out caché info in string form

Parameters:

cache - the caché to be interrogated

Returns:

a string telling useful things about it

Throws:

com.whirlycott.cache.CacheException - if something goes awry

clearCaches

public static void clearCaches()
                        throws com.whirlycott.cache.CacheException

clear all cachés (possibly causing severe consistency problems)

Throws:

com.whirlycott.cache.CacheException - if something goes wrong

create

public static AbstractUser create(Date date,
                                  String string,
                                  String nick)
                           throws AlreadyUsedException,
                                  ForbiddenUserException

Create a new user account

Parameters:

date - User's date of birth

string - Character class or type designator

nick - User's requested nickname

Returns:

the new user object

Throws:

AlreadyUsedException - if the nickname is not available

ForbiddenUserException - if the user account is not permitted to be created, e.g. for having an obscene user ID

findInCache

public static <T extends DataRecord> T findInCache(Class<T> klass,
                                                   int id)
                                        throws NotFoundException

Find an object in the caché, given its class and identifying integer.

Type Parameters:

T - The class of object being returned

Parameters:

klass - The class of object to be returned, descended from DataRecord

id - The numeric ID under which to locate the object

Returns:

The object, if found. This routine will never return null.

Throws:

NotFoundException - If the object is not found in the caché.

findInCache

public static <S extends DataRecord,T extends DataRecordBacked<S>> T findInCache(Class<T> klass,
                                                                                 S rec)
                                                 throws NotFoundException

Find an object in the caché, given its base storage class and a DataRecord which uniquely identifies it. Note that the object itself will be guaranteed only to be a member of the specified class or an extension or implementor thereof.

Type Parameters:

S - The class of which the data record is an isstance or an instance of a subclass thereof

T - The class of the object in the caché, which is backed by and identified by the data record

Parameters:

klass - The class of which the data record is an instance or instance of a subclass thereof

rec - The data record to be used to identify the object cached

Returns:

The object found in the caché. This method will never return null.

Throws:

NotFoundException - If no such object can be found in the caché.

findInCache

public static <T extends DataRecord> T findInCache(Class<T> klass,
                                                   String ident)
                                        throws NotFoundException

Find an object in the caché based upon a class and a string identifier.

Type Parameters:

T - The class of objects to be searched

Parameters:

klass - The class of objects to be searched

ident - The string identifier for the object to be found (or not)

Returns:

The object (if found); will not return null (throws NotFoundException)

Throws:

NotFoundException - if the object was not found in the caché

findInGenericCache

public static <T> T findInGenericCache(Class<T> klass,
                                       String ident)
                            throws NotFoundException

Find a generic object in a caché, without regards for the object's type. Note that the objects stored in the generic (default) caché share a single namespace, so it's possible to have objects of a totally incorrect class returned as a result of a search if the identifier is not globally unique. This method provides a minimum guarantee of correctness by catching class cast exceptions and throwing a somewhat more useful/informative NotFoundException rather than forcing the caller to perform a blind cast and try to catch runtime exceptions.

Type Parameters:

T - The class of object expected to be found

Parameters:

klass - The class of object expected to be found

ident - The (globally unique) identifier of the object

Returns:

The object, if found. Will not return null; throws a NotFoundException instead

Throws:

NotFoundException - If the object is not in the caché; or, if there is an object in the caché identified by (parameter) “ident” which is not of the class “klass” or a subclass or implementor thereof.

get

public static AbstractUser get(org.json.JSONObject object)

Pick up a user from a JSON object containing either the ID or login (user name) string.

Parameters:

object - A JSON object with either an { id: userID } or { login: userName }

Returns:

the User thusly fetched, or null if not found.

getAllCacheInfo

public static String getAllCacheInfo()
                              throws com.whirlycott.cache.CacheException

get information about all cachés

Returns:

a string explaining things

Throws:

com.whirlycott.cache.CacheException - if something goes awry

getDataRecord

public static <T extends DataRecord> T getDataRecord(Class<T> klassGiven,
                                                     int id)
                                          throws NotFoundException

Obtain a data record (implementing DataRecord) of the given class, based upon its unique numeric identifier.

This method will attempt to locate a copy of the object in an in-core caché prior to resorting to other factory methods, e.g. RecordLoader or so forth.

The ID value given is expected to be globally unique for all data records of the given class. Note that this is most often an SQL-backed DataRecord, and the ID is generally an SQL row identification. Also, typically, these ID's are expected to be positive numbers. However, this method will cheerfully accept negative ID's and attempt to locate the records.

Type Parameters:

T - The class of which the data record is an instance (or a subclass thereof)

Parameters:

klassGiven - The class of which the data record is an instance (or a subclass thereof)

id - The unique identifier for the data record in question

Returns:

The object of class “klass” identified by “id.” Will not return null; throws NotFoundException.

Throws:

NotFoundException - If the various factory methods available cannot produce the data record requested

getDataRecord

public static <T extends DataRecord> T getDataRecord(Class<T> klassGiven,
                                                     String identifier)
                                          throws NotFoundException

Get a data record by either searching the caché or loading it. See getDataRecord(Class, int) for contractual details.

Type Parameters:

T - the class of the record (as per klass)

Parameters:

klassGiven - the class of the record to be loaded

identifier - the name or something that uniquely identifies the record to be found

Returns:

The data record of class “klass” identified by “identifier.” Will not return null; throws a NotFoundException

Throws:

NotFoundException - If the record in question cannot be found

getDataRecord

public static <T extends DataRecord> T getDataRecord(String klass,
                                                     int id)
                                          throws NotFoundException,
                                                 ClassNotFoundException

get a data record given a string class name and an ID

Type Parameters:

T - the resultant class represented by “klass”

Parameters:

klass - string class name

id - integer ID

Returns:

the object in question

Throws:

NotFoundException - if the object is not found

ClassNotFoundException - if the class is not found

getDataRecord

public static <T extends DataRecord> T getDataRecord(String klass,
                                                     String ident)
                                          throws NotFoundException,
                                                 ClassNotFoundException

get a data record given a specific class name string and identifier string

Type Parameters:

T - class thing to make compiler happy

Parameters:

klass - class name string

ident - identifier string

Returns:

object described thereby

Throws:

NotFoundException - if the object can't be found

ClassNotFoundException - if the class name isn't found

getDataRecordIterator

public static <T extends Iterator<? extends DataRecord>> T getDataRecordIterator(Class<T> klass,
                                                                                 Object... constructorArgs)

get a data record iterator

Type Parameters:

T - the class of iterator to be summoned

Parameters:

klass - the class of iterator to be summoned

constructorArgs - arguments to be passed to the constructor (which must accept the nomen gentile of the parameter classes)

Returns:

the required iterator

getIDCache

private static <T> com.whirlycott.cache.Cache<Integer,T> getIDCache(Class<T> klassGiven)

get the caché for ID (integer) records of a given class (or gens)

Type Parameters:

T - class (or gens)

Parameters:

klassGiven - class

Returns:

the ID cache for class “klassGiven”

getIdentCache

private static <T> com.whirlycott.cache.Cache<String,T> getIdentCache(Class<T> klassGiven)

get the caché for objects of some kind based on their string identifier

Type Parameters:

T - the class or gens

Parameters:

klassGiven - the class

Returns:

the caché

getIDForLiveUserName

public static int getIDForLiveUserName(String name)

Find the user name for a user who is currently signed on.

Parameters:

name - User name to look up

Returns:

The user ID number, if the user is online; else -1

getInstanceNPCByName

private static AbstractUser getInstanceNPCByName(String instanceName)

Find a cached NPC

Parameters:

instanceName - Name with login$instanceID

Returns:

the NPC, if found, else Null.

getLoginForID

public static String getLoginForID(int id)

Parameters:

id - The user ID value

Returns:

The user's login name

getNomenGentile

private static <T> Class<T> getNomenGentile(Class<? extends T> klassGiven)

Get the nomen gentile of the class provided

Type Parameters:

T - type parameter to try to quiesce the compiler a bit

Parameters:

klassGiven - the specific class

Returns:

the class of the gens

getOnlineUserByLogin

public static AbstractUser getOnlineUserByLogin(String login)

get a user by their login, but *only* if they are currently online; pull only from live user sources, and not from the database.

Parameters:

login - user's login

Returns:

the user object, if the user exists, and is online; else null.

getParentByApprovalCookie

public static Parent getParentByApprovalCookie(String cookie)
                                        throws NotFoundException,
                                               IOException

Parameters:

cookie - the approval cookie uniquely identifying the desired Parent

Returns:

the Parent uniquely identified by the given approval cookie

Throws:

NotFoundException - if the cookie does not uniquely identify any Parent

IOException - if the contents of the approval cookie can't be decoded

getParentByID

public static Parent getParentByID(int id)

Parameters:

id - database ID number

Returns:

the relevant Parent record (if it exists)

getParentByMail

public static Parent getParentByMail(String mail)

Parameters:

mail - The parent's eMail address

Returns:

the relevant Parent record

getRecIDForBackedObject

private static <S extends DataRecord> String getRecIDForBackedObject(S rec)

get a record ID for something that is in turn backed by some kind of data record

Type Parameters:

S - type of the record

Parameters:

rec - the record whose ID is to be extracted

Returns:

a string that can be used to identify the record

getRecordBackedCache

private static <T> com.whirlycott.cache.Cache<String,T> getRecordBackedCache(Class<T> klass)

Get a caché backed by a type of record

Type Parameters:

T - the record type contained in the caché

Parameters:

klass - the record type contained in the caché

Returns:

the caché containing such records

getSomeCache

private static <T,S> com.whirlycott.cache.Cache<S,T> getSomeCache(Class<T> tClass,
                                                                  String s,
                                                                  Class<S> sClass)

get a caché containing records of a given type, with keys of another given type, using a given suffix code

Type Parameters:

T - the type contained within the caché

S - the type of keys

Parameters:

tClass - the type contained within the caché

s - the suffix code appended to 's class name

sClass - the type of keys

Returns:

the caché (new or existing) used to contain objects keyed on

getSystemUser

public static AbstractUser getSystemUser()

Get the System user object (the user which represents the system program itself). In particular, the System object's eMail address and givenName are used to address mail to users.

Returns:

the System user object

getUserByID

public static AbstractUser getUserByID(int id)

Instantiate a user object from an existing user account ID

Parameters:

id - The user ID to instantiate

Returns:

the instantiated user record, or null if the user ID doesn't represent a user record (too high, or the record was destroyed somehow) — not returned for deleted or banned accounts, though.

getUserByLogin

public static AbstractUser getUserByLogin(String login)

Parameters:

login - the user login name

Returns:

the User record, or null if no user currently has that login name

getUserByRequestedName

public static AbstractUser getUserByRequestedName(String userNameRequested)

Get the user who has requested a certain name, if any.

Parameters:

userNameRequested - the user name for which we're searching

Returns:

null, if no user has requested the name; otherwise, the user who requested it. (Note that the name might have been approved, or might not have been.)

getUserIDForLogin

public static int getUserIDForLogin(String name)

Fetch the user ID number for a user name

Parameters:

name - The user name (login)

Returns:

the user ID

getUsersByMail

public static AbstractUser[] getUsersByMail(String mail)

Returns an array of all users associated with a given eMail address. This includes all users who report it as being their own eMail address, as well as the children of any parents using it.

Parameters:

mail - The eMail address for which we are searching

Returns:

An array of any/all such users. If the array consists only of one element, which is the value "null," then there are too many results and special effort is required to recall the list.

initializeClassCache

private static <S,T> com.whirlycott.cache.Cache<S,T> initializeClassCache(Class<S> idClass,
                                                                          Class<T> klass,
                                                                          String ext)

WRITEME: Document this method brpocock@star-hope.org

Type Parameters:

S - class of ID

T - WRITEME

Parameters:

idClass - class of ID

klass - WRITEME

ext - WRITEME

Returns:

WRITEME

instantiate

public static <T extends DataRecordBacked<S>,S extends DataRecord> T instantiate(Class<T> klass,
                                                                                 S record)

Instantiate an instance of an object which wraps a data record

Type Parameters:

T - the type of object which is backed by the given record. An object of this type, or possible an extension subclass specified in the configuration file, will be returned.

S - the type of data record which is passed in

Parameters:

klass - The class of T, to be instantiated

record - The record to be used to instantiate the new object

Returns:

the object of type T

instantiateUser

static AbstractUser instantiateUser(UserRecord rec)

Instantiate a User (using the selected subclass) from the result set garnered from a SELECT *

Parameters:

rec - The given database record

Returns:

The User (subclass) representing that database record

isLoginAvailable

public static boolean isLoginAvailable(String name)

Determine whether the given name is potentially available for use. Returns false if the name has already been forbidden (by virtue of matching a negative filter rule, or having been previously denied to another user), or if the name is currently either in use or requested by another user.

Parameters:

name - The user name being checked

Returns:

true, if the name can potentially be tried.

isLoginForbidden

public static boolean isLoginForbidden(String userNameRequested)

Determine whether a name is forbidden

... A user name is “forbidden” if it matches a negative filter (if it contains forbidden word(s) or phrase(s)), or if it has previously been banned for some reason

Parameters:

userNameRequested - The name to be checked

Returns:

True, if the requested name is forbidden

killCache

public static <S extends DataRecord,T extends S> void killCache(Class<S> klass,
                                                                T o)

Remove an arbitrary object from a caché.

FIXME: Does not work!

Type Parameters:

S - WRITEME

T - The class of the arbitrary object

Parameters:

klass - WRITEME

o - An arbitrary object to be stored in the caché.

make

public static <T extends DataRecord> T make(Class<T> klass,
                                            Object... more)
                                 throws NotReadyException

WRITEME: Document this method brpocock@star-hope.org

Type Parameters:

T - WRITEME

Parameters:

klass - WRITEME

more - WRITEME

Returns:

WRITEME

Throws:

NotReadyException - WRITEME

removeInstanceNPC

public static void removeInstanceNPC(GeneralUser npc)

Remove an instanced NPC from the caché on its destruction. Only should be called by AbstractNonPlayerCharacter.destroy()

Parameters:

npc - the character to be destroyed