uk.co.weft.dbutil
Class Context

java.lang.Object
  java.util.Dictionary
      java.util.Hashtable
          uk.co.weft.dbutil.Context

All Implemented Interfaces:

java.lang.Cloneable, java.util.Map, java.io.Serializable

public class Context

extends java.util.Hashtable

implements java.lang.Cloneable

A namespace in which to hold arbitrary values. Because so many databases mangle case, the namespace is deemed to be case-insensitive, which is to say both puts and gets are mapped to lower case. Note that this does not inherit from Properties, because the values are arbitrary objects. A load() method is provided similar to Properties.load(), and a store() method similat to Properties.store(). However, it is not guaranteed that a store followed by a load will restore a Context, because not everything that can be held in a Context can be recovered from it's printed form.

Version:

$Revision: 1.37.4.4 $ This revision:

Author:

Simon Brooke, $Author: simon $

See Also:

Serialized Form

Field Summary

static java.lang.String	endOfCommentMagicToken Deprecated. there should be no need to use this
static java.lang.String	startOfCommentMagicToken Deprecated. there should be no need to use this

Constructor Summary

Context()
the default constructor does nothing.

Method Summary

void	comment(java.lang.String message) Deprecated. don't use this. Write to your log instead if you have one; otherwise write to standard error (which is what this now does)
void	copyDBTokens(java.util.Dictionary donor) Copy into me the values of the the database magic tokens (URL, username and password) from this donor context
java.lang.Object	get(java.lang.String token) Get the value associated with this token in this context.
java.lang.Object	get(java.lang.String token, java.lang.Object dflt) Return the value associated with this token if not null else this default
java.sql.Connection	getConnection() Get a database connection using the following magic names in my own name-space: 'db_url', 'db_username', 'db_password'.
java.sql.Connection	getConnection(java.lang.String url, java.lang.String username, java.lang.String password) Deprecated. this is really horribly bad design. You should use ConnectionPool.getConnection() instead.
protected java.util.Enumeration	getKeys() Deprecated. probably better to use keys()
java.lang.Object	getValue(java.lang.String token) Deprecated. probably better to use get()
java.lang.Boolean	getValueAsBoolean(java.lang.String token) Coerce this value to a boolean and return it as a Boolean object, not as a bool.
java.util.Calendar	getValueAsCalendar(java.lang.String token) Extract the value associated with this token as a java.util.Calendar object
java.lang.Character	getValueAsCharacter(java.lang.String token) Coerce this value to a Character and return it.
java.awt.Color	getValueAsColor(java.lang.String token) Coerce this value to a java.awt.Color object and return it.
Currency	getValueAsCurrency(java.lang.String token) Coerce the value of this token to a Currency object and return it.
java.lang.Double	getValueAsDouble(java.lang.String token) Coerce this value to a double and return it as a Double object, not as a double.
java.io.File	getValueAsFile(java.lang.String token) Coerce this value to a File object (if this is possible) and return it.
java.lang.Float	getValueAsFloat(java.lang.String token) Coerce this value to a float and return it as a Float object, not as a float.
java.lang.Integer	getValueAsInteger(java.lang.String token) Coerce this value to an integer and return it as an Integer object, not as an int.
java.lang.String	getValueAsString(java.lang.String token) Coerce this value to a String and return it.
boolean	intersectMatch(Context compare) True iff for all the names which I have which compare also has, I have the same values for those names as compare has.
java.util.Enumeration	keys() Return my keys.
void	load(java.io.InputStream src) Load values into this context from this stream.
Context	merge(java.util.Dictionary other) Deprecated. the Dictionary class is obsolete; use merge(Map) instead.
Context	merge(java.util.Map other) Merge values from this context (or other Map) into me, preferring my own existing values where there are conflicts.
void	put(java.lang.String token, boolean value) A hack around the fact that Java isn't fully object oriented.
void	put(java.lang.String token, double value) A hack around the fact that Java isn't fully object oriented.
void	put(java.lang.String token, int value) A hack around the fact that Java isn't fully object oriented.
void	put(java.lang.String token, java.lang.Object value) Set the value associated with this token to this value.
void	putValue(java.lang.String token, java.lang.Object value) Deprecated. probably better to use put()
void	releaseConnection(java.sql.Connection c) Release this connection back into my free connections pool.
void	releaseConnection(java.sql.Connection c, boolean dontCloseStatements) Deprecated. setting dontCloseStatements to true may be associated with connection pool leaks: use with great caution.
void	store(java.io.OutputStream out, java.lang.String header) Write my keys and values to the output stream in a format which can be read by 'load'.
void	unwatch(java.lang.String token) remove this token from the list of tokens I am watching
void	watch(java.lang.String token) print a stack trace to standard error whenever the value of this token in this context changes

Methods inherited from class java.util.Hashtable

clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, rehash, remove, size, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

startOfCommentMagicToken

public static final java.lang.String startOfCommentMagicToken

Deprecated. there should be no need to use this

If contexts know how to print comments they must know comment syntax.

See Also:

Constant Field Values

endOfCommentMagicToken

public static final java.lang.String endOfCommentMagicToken

Deprecated. there should be no need to use this

If contexts know how to print comments they must know comment syntax.

See Also:

Constant Field Values

Constructor Detail

Context

public Context()

the default constructor does nothing.

Method Detail

getConnection

public java.sql.Connection getConnection(java.lang.String url,
                                         java.lang.String username,
                                         java.lang.String password)
                                  throws DataStoreException

Deprecated. this is really horribly bad design. You should use ConnectionPool.getConnection() instead.

Get a free database connection to my database URL from me using my username and password, creating the connection if necessary. A method which reserves a connection using getConnection() should subsequently release it into the free pool using releaseConnection(). If it does not, a memory leak will in effect occur.

Throws:

DataStoreException - throws a DataAuthException if an unambiguous authentication failure occurs, a DataStoreException if for some other reason no connection could be established.

See Also:

ConnectionPool.getConnection(java.lang.String, java.lang.String, java.lang.String)

getConnection

public java.sql.Connection getConnection()
                                  throws DataStoreException

Get a database connection using the following magic names in my own name-space: 'db_url', 'db_username', 'db_password'.

Throws:

throws - DataAuthException if a authorisation fails, DataStoreException if database connection cannot be established for some other reason

DataStoreException

See Also:

ConnectionPool.dbUrlMagicToken, ConnectionPool.dbUserMagicToken, ConnectionPool.dbPassMagicToken

getValue

public java.lang.Object getValue(java.lang.String token)

Deprecated. probably better to use get()

Get the value associated with this token in this context.

getValueAsBoolean

public java.lang.Boolean getValueAsBoolean(java.lang.String token)

Coerce this value to a boolean and return it as a Boolean object, not as a bool. If not already a bool, coerce to string and interpret the first letter: 't' or 'T' or '1' -> true, anything else -> false. This is not standard Java behaviour but is (in our opinion) a reasonable compromise between Java behaviour and SQL behaviour. Thanks to John Robinson for DataNull concept, Dave Orr for 't'/'f' concept.

Parameters:

token - the name against which the value to be returned is stored in this context

Returns:

Boolean.TRUE if there is a value which can be coerced to true, Boolean.FALSE if there is a value which can't, or null if no value or value is DataNull.

getValueAsCalendar

public java.util.Calendar getValueAsCalendar(java.lang.String token)
                                      throws DataFormatException

Extract the value associated with this token as a java.util.Calendar object

Throws:

DataFormatException

getValueAsCharacter

public java.lang.Character getValueAsCharacter(java.lang.String token)

Coerce this value to a Character and return it. If the underlying value has more than one character, return the first. Returns null if no value or value is DataNull.

getValueAsColor

public java.awt.Color getValueAsColor(java.lang.String token)
                               throws DataFormatException

Coerce this value to a java.awt.Color object and return it. If value is not natively a Color object try to parse it as a six-digit hex string. Returns null if no value or value is DataNull.

Throws:

throws - DataFormatException if value is not null and cannot be coerced to a colour

DataFormatException

getValueAsCurrency

public Currency getValueAsCurrency(java.lang.String token)
                            throws java.lang.NumberFormatException,
                                   DataFormatException

Coerce the value of this token to a Currency object and return it. Returns null if no value or value is DataNull.

Throws:

throws - NumberFormatException if value is not null and cannot be coerced to a float

java.lang.NumberFormatException

DataFormatException

getValueAsDouble

public java.lang.Double getValueAsDouble(java.lang.String token)
                                  throws java.lang.NumberFormatException

Coerce this value to a double and return it as a Double object, not as a double. Returns null if no value or value is DataNull.

Throws:

throws - NumberFormatException if value is not null and cannot be coerced to a double

java.lang.NumberFormatException

getValueAsFile

public java.io.File getValueAsFile(java.lang.String token)

Coerce this value to a File object (if this is possible) and return it.

Parameters:

token - the token which identified that value to be returned

Returns:

a File object if the value either is a File or is a valid path to a file which either exists or could be created, else null.

getValueAsFloat

public java.lang.Float getValueAsFloat(java.lang.String token)
                                throws java.lang.NumberFormatException

Coerce this value to a float and return it as a Float object, not as a float. Returns null if no value or value is DataNull.

Throws:

throws - NumberFormatException if value is not null and cannot be coerced to a float

java.lang.NumberFormatException

getValueAsInteger

public java.lang.Integer getValueAsInteger(java.lang.String token)
                                    throws java.lang.NumberFormatException

Coerce this value to an integer and return it as an Integer object, not as an int. Returns null if no value or value is DataNull.

Throws:

throws - NumberFormatException if value is not null and cannot be coerced to an integer

java.lang.NumberFormatException

getValueAsString

public java.lang.String getValueAsString(java.lang.String token)

Coerce this value to a String and return it. Returns null if no value or value is DataNull.

comment

public void comment(java.lang.String message)

Deprecated. don't use this. Write to your log instead if you have one; otherwise write to standard error (which is what this now does)

Print a debugging message, or, actually, don't. At the level of dbutil, this method actually shouldn't do anything because there isn't anywhere for the message to go. Furthermore, the name of the method is wrong. Needs more thought.

copyDBTokens

public void copyDBTokens(java.util.Dictionary donor)

Copy into me the values of the the database magic tokens (URL, username and password) from this donor context

Parameters:

donor - the dictionary (usually a context) which is providing the token values

get

public java.lang.Object get(java.lang.String token)

Get the value associated with this token in this context.

Parameters:

token - the (non-case-sensitive) name whose value is sought

Returns:

the value of that name in this namespace

get

public java.lang.Object get(java.lang.String token,
                            java.lang.Object dflt)

Return the value associated with this token if not null else this default

intersectMatch

public boolean intersectMatch(Context compare)

True iff for all the names which I have which compare also has, I have the same values for those names as compare has.

keys

public java.util.Enumeration keys()

Return my keys. Specialisation: return them in serial order, according to when they were added.

Returns:

an enumeration of my keys in serial order by age

Since:

Jacquard 1.10 (prior to that, order of keys was undetermined)

load

public void load(java.io.InputStream src)
          throws java.io.IOException

Load values into this context from this stream. Lines in the stream should be token/value pairs, separated by any of '=',':',' ' .

Throws:

java.io.IOException

merge

public Context merge(java.util.Dictionary other)

Deprecated. the Dictionary class is obsolete; use merge(Map) instead.

Merge values from this context (or other Dictionary) into me, preferring my own existing values where there are conflicts. Force all keys to lower-case strings, because that's what Contexts allow (when merging other Dictionary classes, keys might include other things).

Parameters:

other - the context to merge in.

Returns:

myself.

merge

public Context merge(java.util.Map other)

Merge values from this context (or other Map) into me, preferring my own existing values where there are conflicts. Force all keys to lower-case strings, because that's what Contexts allow (when merging other Map classes, keys might include other things).

Parameters:

other - the context to merge in.

Returns:

myself.

Since:

Jacquard 1.10.8

put

public void put(java.lang.String token,
                java.lang.Object value)

Set the value associated with this token to this value. Puts and gets are case insensitive, because so many SQL engines mangle case. It is not an error for the value put to be null.

put

public void put(java.lang.String token,
                int value)

A hack around the fact that Java isn't fully object oriented. You ought to be able to put() any sort of value...

put

public void put(java.lang.String token,
                double value)

A hack around the fact that Java isn't fully object oriented. You ought to be able to put() any sort of value...

put

public void put(java.lang.String token,
                boolean value)

A hack around the fact that Java isn't fully object oriented. You ought to be able to put() any sort of value...

putValue

public void putValue(java.lang.String token,
                     java.lang.Object value)

Deprecated. probably better to use put()

Set the value associated with this token to this value. Puts and gets are case insensitive, because so many SQL engines mangle case.

releaseConnection

public void releaseConnection(java.sql.Connection c)
                       throws DataStoreException

Release this connection back into my free connections pool. A method which reserves a connection using getConnection() should subsequently release it using releaseConnection().

Throws:

DataStoreException

releaseConnection

public void releaseConnection(java.sql.Connection c,
                              boolean dontCloseStatements)
                       throws DataStoreException

Deprecated. setting dontCloseStatements to true may be associated with connection pool leaks: use with great caution.

Release this connection back into my free connections pool. A method which reserves a connection using getConnection() should subsequently release it using releaseConnection().

Throws:

DataStoreException

store

public void store(java.io.OutputStream out,
                  java.lang.String header)
           throws java.io.IOException

Write my keys and values to the output stream in a format which can be read by 'load'. Note that this does not imply a context can be recreated by store() followed by load() - there are many things which may be stored in Contexts for which this might not work safely. This method deliberately shares the signature of Properties.store()

Throws:

java.io.IOException

unwatch

public void unwatch(java.lang.String token)

remove this token from the list of tokens I am watching

Parameters:

token - the token which no longer needs to be watched

See Also:

watch(String)

watch

public void watch(java.lang.String token)

print a stack trace to standard error whenever the value of this token in this context changes

Parameters:

token - the token to watch

getKeys

protected java.util.Enumeration getKeys()

Deprecated. probably better to use keys()

Return an enumeration of all my hash keys