001: //$Id: UserType.java 6133 2005-03-21 16:53:58Z turin42 $
002: package org.hibernate.usertype;
003:
004: import java.io.Serializable;
005: import java.sql.PreparedStatement;
006: import java.sql.ResultSet;
007: import java.sql.SQLException;
008:
009: import org.hibernate.HibernateException;
010:
011: /**
012: * This interface should be implemented by user-defined "types".
013: * A "type" class is <em>not</em> the actual property type - it
014: * is a class that knows how to serialize instances of another
015: * class to and from JDBC.<br>
016: * <br>
017: * This interface
018: * <ul>
019: * <li>abstracts user code from future changes to the <tt>Type</tt>
020: * interface,</li>
021: * <li>simplifies the implementation of custom types and</li>
022: * <li>hides certain "internal" interfaces from user code.</li>
023: * </ul>
024: * <br>
025: * Implementors must be immutable and must declare a public
026: * default constructor.<br>
027: * <br>
028: * The actual class mapped by a <tt>UserType</tt> may be just
029: * about anything.<br>
030: * <br>
031: * <tt>CompositeUserType</tt> provides an extended version of
032: * this interface that is useful for more complex cases.<br>
033: * <br>
034: * Alternatively, custom types could implement <tt>Type</tt>
035: * directly or extend one of the abstract classes in
036: * <tt>org.hibernate.type</tt>. This approach risks future
037: * incompatible changes to classes or interfaces in that
038: * package.
039: *
040: * @see CompositeUserType for more complex cases
041: * @see org.hibernate.type.Type
042: * @author Gavin King
043: */
044: public interface UserType {
045:
046: /**
047: * Return the SQL type codes for the columns mapped by this type. The
048: * codes are defined on <tt>java.sql.Types</tt>.
049: * @see java.sql.Types
050: * @return int[] the typecodes
051: */
052: public int[] sqlTypes();
053:
054: /**
055: * The class returned by <tt>nullSafeGet()</tt>.
056: *
057: * @return Class
058: */
059: public Class returnedClass();
060:
061: /**
062: * Compare two instances of the class mapped by this type for persistence "equality".
063: * Equality of the persistent state.
064: *
065: * @param x
066: * @param y
067: * @return boolean
068: */
069: public boolean equals(Object x, Object y) throws HibernateException;
070:
071: /**
072: * Get a hashcode for the instance, consistent with persistence "equality"
073: */
074: public int hashCode(Object x) throws HibernateException;
075:
076: /**
077: * Retrieve an instance of the mapped class from a JDBC resultset. Implementors
078: * should handle possibility of null values.
079: *
080: * @param rs a JDBC result set
081: * @param names the column names
082: * @param owner the containing entity
083: * @return Object
084: * @throws HibernateException
085: * @throws SQLException
086: */
087: public Object nullSafeGet(ResultSet rs, String[] names, Object owner)
088: throws HibernateException, SQLException;
089:
090: /**
091: * Write an instance of the mapped class to a prepared statement. Implementors
092: * should handle possibility of null values. A multi-column type should be written
093: * to parameters starting from <tt>index</tt>.
094: *
095: * @param st a JDBC prepared statement
096: * @param value the object to write
097: * @param index statement parameter index
098: * @throws HibernateException
099: * @throws SQLException
100: */
101: public void nullSafeSet(PreparedStatement st, Object value,
102: int index) throws HibernateException, SQLException;
103:
104: /**
105: * Return a deep copy of the persistent state, stopping at entities and at
106: * collections. It is not necessary to copy immutable objects, or null
107: * values, in which case it is safe to simply return the argument.
108: *
109: * @param value the object to be cloned, which may be null
110: * @return Object a copy
111: */
112: public Object deepCopy(Object value) throws HibernateException;
113:
114: /**
115: * Are objects of this type mutable?
116: *
117: * @return boolean
118: */
119: public boolean isMutable();
120:
121: /**
122: * Transform the object into its cacheable representation. At the very least this
123: * method should perform a deep copy if the type is mutable. That may not be enough
124: * for some implementations, however; for example, associations must be cached as
125: * identifier values. (optional operation)
126: *
127: * @param value the object to be cached
128: * @return a cachable representation of the object
129: * @throws HibernateException
130: */
131: public Serializable disassemble(Object value)
132: throws HibernateException;
133:
134: /**
135: * Reconstruct an object from the cacheable representation. At the very least this
136: * method should perform a deep copy if the type is mutable. (optional operation)
137: *
138: * @param cached the object to be cached
139: * @param owner the owner of the cached object
140: * @return a reconstructed object from the cachable representation
141: * @throws HibernateException
142: */
143: public Object assemble(Serializable cached, Object owner)
144: throws HibernateException;
145:
146: /**
147: * During merge, replace the existing (target) value in the entity we are merging to
148: * with a new (original) value from the detached entity we are merging. For immutable
149: * objects, or null values, it is safe to simply return the first parameter. For
150: * mutable objects, it is safe to return a copy of the first parameter. For objects
151: * with component values, it might make sense to recursively replace component values.
152: *
153: * @param original the value from the detached entity being merged
154: * @param target the value in the managed entity
155: * @return the value to be merged
156: */
157: public Object replace(Object original, Object target, Object owner)
158: throws HibernateException;
159: }
|