Author: steve.ebersole(a)jboss.com Date: 2007-01-16 10:26:09 -0500 (Tue, 16 Jan 2007) New Revision: 11047 Modified: trunk/Hibernate3/src/org/hibernate/type/NullableType.java Log: HHH-2356 : NullableType.toString + nulls; javadocs; formatting Modified: trunk/Hibernate3/src/org/hibernate/type/NullableType.java =================================================================== --- trunk/Hibernate3/src/org/hibernate/type/NullableType.java 2007-01-16 15:25:54 UTC (rev 11046) +++ trunk/Hibernate3/src/org/hibernate/type/NullableType.java 2007-01-16 15:26:09 UTC (rev 11047) @@ -20,32 +20,80 @@ /** * Superclass of single-column nullable types. + * * @author Gavin King */ public abstract class NullableType extends AbstractType { - private static final boolean IS_TRACE_ENABLED; - static { - //cache this, because it was a significant performance cost; is - // trace logging enabled on the type package... - IS_TRACE_ENABLED = LogFactory.getLog( StringHelper.qualifier( Type.class.getName() ) ).isTraceEnabled(); + /** + * This is the old scheme where logging of parameter bindings and value extractions + * was controlled by the trace level enablement on the 'org.hibernate.type' package... + * <p/> + * Originally was cached such because of performance of looking up the logger each time + * in order to check the trace-enablement. Driving this via a central Log-specific class + * would alleviate that performance hit, and yet still allow more "normal" logging usage/config. + */ + private static final boolean IS_VALUE_TRACING_ENABLED = LogFactory.getLog( StringHelper.qualifier( Type.class.getName() ) ).isTraceEnabled(); + private transient Log log; + + private Log log() { + if ( log == null ) { + log = LogFactory.getLog( getClass() ); + } + return log; } /** * Get a column value from a result set, without worrying about the - * possibility of null values + * possibility of null values. Called from {@link #nullSafeGet} after + * nullness checks have been performed. + * + * @param rs The result set from which to extract the value. + * @param name The name of the value to extract. + * + * @return The extracted value. + * + * @throws org.hibernate.HibernateException Generally some form of mismatch error. + * @throws java.sql.SQLException Indicates problem making the JDBC call(s). */ - public abstract Object get(ResultSet rs, String name) - throws HibernateException, SQLException; + public abstract Object get(ResultSet rs, String name) throws HibernateException, SQLException; /** - * Get a parameter value without worrying about the possibility of null values + * Set a parameter value without worrying about the possibility of null + * values. Called from {@link #nullSafeSet} after nullness checks have + * been performed. + * + * @param st The statement into which to bind the parameter value. + * @param value The parameter value to bind. + * @param index The position or index at which to bind the param value. + * + * @throws org.hibernate.HibernateException Generally some form of mismatch error. + * @throws java.sql.SQLException Indicates problem making the JDBC call(s). */ - public abstract void set(PreparedStatement st, Object value, int index) - throws HibernateException, SQLException; + public abstract void set(PreparedStatement st, Object value, int index) throws HibernateException, SQLException; + /** + * A convenience form of {@link #sqlTypes(org.hibernate.engine.Mapping)}, returning + * just a single type value since these are explicitly dealing with single column + * mappings. + * + * @return The {@link java.sql.Types} mapping value. + */ public abstract int sqlType(); + /** + * A null-safe version of {@link #toString(Object)}. Specifically we are + * worried about null safeness in regards to the incoming value parameter, + * not the return. + * + * @param value The value to convert to a string representation; may be null. + * @return The string representation; may be null. + * @throws HibernateException Thrown by {@link #toString(Object)}, which this calls. + */ + public String nullSafeToString(Object value) throws HibernateException { + return value == null ? null : toString( value ); + } + public abstract String toString(Object value) throws HibernateException; public abstract Object fromStringValue(String xml) throws HibernateException; @@ -69,14 +117,14 @@ throws HibernateException, SQLException { try { if ( value == null ) { - if ( IS_TRACE_ENABLED ) { + if ( IS_VALUE_TRACING_ENABLED ) { log().trace( "binding null to parameter: " + index ); } st.setNull( index, sqlType() ); } else { - if ( IS_TRACE_ENABLED ) { + if ( IS_VALUE_TRACING_ENABLED ) { log().trace( "binding '" + toString( value ) + "' to parameter: " + index ); } @@ -84,11 +132,11 @@ } } catch ( RuntimeException re ) { - log().info( "could not bind value '" + toString( value ) + "' to parameter: " + index + "; " + re.getMessage() ); + log().info( "could not bind value '" + nullSafeToString( value ) + "' to parameter: " + index + "; " + re.getMessage() ); throw re; } catch ( SQLException se ) { - log().info( "could not bind value '" + toString( value ) + "' to parameter: " + index + "; " + se.getMessage() ); + log().info( "could not bind value '" + nullSafeToString( value ) + "' to parameter: " + index + "; " + se.getMessage() ); throw se; } } @@ -112,13 +160,13 @@ try { Object value = get(rs, name); if ( value == null || rs.wasNull() ) { - if ( IS_TRACE_ENABLED ) { + if ( IS_VALUE_TRACING_ENABLED ) { log().trace( "returning null as column: " + name ); } return null; } else { - if (IS_TRACE_ENABLED) { + if ( IS_VALUE_TRACING_ENABLED ) { log().trace( "returning '" + toString( value ) + "' as column: " + name ); } return value; @@ -165,7 +213,7 @@ } public String toLoggableString(Object value, SessionFactoryImplementor factory) { - return value==null ? "null" : toString(value); + return value == null ? "null" : toString(value); } public Object fromXMLNode(Node xml, Mapping factory) throws HibernateException { @@ -185,8 +233,4 @@ throws HibernateException { return checkable[0] && isDirty(old, current, session); } - - private Log log() { - return LogFactory.getLog( getClass() ); - } }