001: //$Id: CompositeUserType.java 6471 2005-04-19 20:36:59Z oneovthafew $
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: import org.hibernate.engine.SessionImplementor;
011: import org.hibernate.type.Type;
012:
013: /**
014: * A <tt>UserType</tt> that may be dereferenced in a query.
015: * This interface allows a custom type to define "properties".
016: * These need not necessarily correspond to physical JavaBeans
017: * style properties.<br>
018: * <br>
019: * A <tt>CompositeUserType</tt> may be used in almost every way
020: * that a component may be used. It may even contain many-to-one
021: * associations.<br>
022: * <br>
023: * Implementors must be immutable and must declare a public
024: * default constructor.<br>
025: * <br>
026: * Unlike <tt>UserType</tt>, cacheability does not depend upon
027: * serializability. Instead, <tt>assemble()</tt> and
028: * <tt>disassemble</tt> provide conversion to/from a cacheable
029: * representation.
030: *
031: * @see UserType for more simple cases
032: * @see org.hibernate.type.Type
033: * @author Gavin King
034: */
035: public interface CompositeUserType {
036:
037: /**
038: * Get the "property names" that may be used in a
039: * query.
040: *
041: * @return an array of "property names"
042: */
043: public String[] getPropertyNames();
044:
045: /**
046: * Get the corresponding "property types".
047: *
048: * @return an array of Hibernate types
049: */
050: public Type[] getPropertyTypes();
051:
052: /**
053: * Get the value of a property.
054: *
055: * @param component an instance of class mapped by this "type"
056: * @param property
057: * @return the property value
058: * @throws HibernateException
059: */
060: public Object getPropertyValue(Object component, int property)
061: throws HibernateException;
062:
063: /**
064: * Set the value of a property.
065: *
066: * @param component an instance of class mapped by this "type"
067: * @param property
068: * @param value the value to set
069: * @throws HibernateException
070: */
071: public void setPropertyValue(Object component, int property,
072: Object value) throws HibernateException;
073:
074: /**
075: * The class returned by <tt>nullSafeGet()</tt>.
076: *
077: * @return Class
078: */
079: public Class returnedClass();
080:
081: /**
082: * Compare two instances of the class mapped by this type for persistence "equality".
083: * Equality of the persistent state.
084: *
085: * @param x
086: * @param y
087: * @return boolean
088: * @throws HibernateException
089: */
090: public boolean equals(Object x, Object y) throws HibernateException;
091:
092: /**
093: * Get a hashcode for the instance, consistent with persistence "equality"
094: */
095: public int hashCode(Object x) throws HibernateException;
096:
097: /**
098: * Retrieve an instance of the mapped class from a JDBC resultset. Implementors
099: * should handle possibility of null values.
100: *
101: * @param rs a JDBC result set
102: * @param names the column names
103: * @param session
104: * @param owner the containing entity
105: * @return Object
106: * @throws HibernateException
107: * @throws SQLException
108: */
109: public Object nullSafeGet(ResultSet rs, String[] names,
110: SessionImplementor session, Object owner)
111: throws HibernateException, SQLException;
112:
113: /**
114: * Write an instance of the mapped class to a prepared statement. Implementors
115: * should handle possibility of null values. A multi-column type should be written
116: * to parameters starting from <tt>index</tt>.
117: *
118: * @param st a JDBC prepared statement
119: * @param value the object to write
120: * @param index statement parameter index
121: * @param session
122: * @throws HibernateException
123: * @throws SQLException
124: */
125: public void nullSafeSet(PreparedStatement st, Object value,
126: int index, SessionImplementor session)
127: throws HibernateException, SQLException;
128:
129: /**
130: * Return a deep copy of the persistent state, stopping at entities and at collections.
131: *
132: * @param value generally a collection element or entity field
133: * @return Object a copy
134: * @throws HibernateException
135: */
136: public Object deepCopy(Object value) throws HibernateException;
137:
138: /**
139: * Check if objects of this type mutable.
140: *
141: * @return boolean
142: */
143: public boolean isMutable();
144:
145: /**
146: * Transform the object into its cacheable representation. At the very least this
147: * method should perform a deep copy. That may not be enough for some implementations,
148: * however; for example, associations must be cached as identifier values. (optional
149: * operation)
150: *
151: * @param value the object to be cached
152: * @param session
153: * @return a cachable representation of the object
154: * @throws HibernateException
155: */
156: public Serializable disassemble(Object value,
157: SessionImplementor session) throws HibernateException;
158:
159: /**
160: * Reconstruct an object from the cacheable representation. At the very least this
161: * method should perform a deep copy. (optional operation)
162: *
163: * @param cached the object to be cached
164: * @param session
165: * @param owner the owner of the cached object
166: * @return a reconstructed object from the cachable representation
167: * @throws HibernateException
168: */
169: public Object assemble(Serializable cached,
170: SessionImplementor session, Object owner)
171: throws HibernateException;
172:
173: /**
174: * During merge, replace the existing (target) value in the entity we are merging to
175: * with a new (original) value from the detached entity we are merging. For immutable
176: * objects, or null values, it is safe to simply return the first parameter. For
177: * mutable objects, it is safe to return a copy of the first parameter. However, since
178: * composite user types often define component values, it might make sense to recursively
179: * replace component values in the target object.
180: *
181: * @param original
182: * @param target
183: * @param session
184: * @param owner
185: * @return
186: * @throws HibernateException
187: */
188: public Object replace(Object original, Object target,
189: SessionImplementor session, Object owner)
190: throws HibernateException;
191: }
|