CompositeUserType


1   //$Id: CompositeUserType.java,v 1.8 2005/04/19 20:36:59 oneovthafew Exp $
2   package org.hibernate.usertype;
3   
4   import java.io.Serializable  ;
5   import java.sql.PreparedStatement  ;
6   import java.sql.ResultSet  ;
7   import java.sql.SQLException  ;
8   
9   import org.hibernate.HibernateException;
10  import org.hibernate.engine.SessionImplementor;
11  import org.hibernate.type.Type;
12  
13  /**
14   * A <tt>UserType</tt> that may be dereferenced in a query.
15   * This interface allows a custom type to define "properties".
16   * These need not necessarily correspond to physical JavaBeans
17   * style properties.<br>
18   * <br>
19   * A <tt>CompositeUserType</tt> may be used in almost every way
20   * that a component may be used. It may even contain many-to-one
21   * associations.<br>
22   * <br>
23   * Implementors must be immutable and must declare a public
24   * default constructor.<br>
25   * <br>
26   * Unlike <tt>UserType</tt>, cacheability does not depend upon
27   * serializability. Instead, <tt>assemble()</tt> and
28   * <tt>disassemble</tt> provide conversion to/from a cacheable
29   * representation.
30   *
31   * @see UserType for more simple cases
32   * @see org.hibernate.type.Type
33   * @author Gavin King
34   */
35  public interface CompositeUserType {
36  
37      /**
38       * Get the "property names" that may be used in a
39       * query.
40       *
41       * @return an array of "property names"
42       */
43      public String  [] getPropertyNames();
44  
45      /**
46       * Get the corresponding "property types".
47       *
48       * @return an array of Hibernate types
49       */
50      public Type[] getPropertyTypes();
51  
52      /**
53       * Get the value of a property.
54       *
55       * @param component an instance of class mapped by this "type"
56       * @param property
57       * @return the property value
58       * @throws HibernateException
59       */
60      public Object   getPropertyValue(Object   component, int property) throws HibernateException;
61  
62      /**
63       * Set the value of a property.
64       *
65       * @param component an instance of class mapped by this "type"
66       * @param property
67       * @param value the value to set
68       * @throws HibernateException
69       */
70      public void setPropertyValue(Object   component, int property, Object   value) throws HibernateException;
71  
72      /**
73       * The class returned by <tt>nullSafeGet()</tt>.
74       *
75       * @return Class
76       */
77      public Class   returnedClass();
78  
79      /**
80       * Compare two instances of the class mapped by this type for persistence "equality".
81       * Equality of the persistent state.
82       *
83       * @param x
84       * @param y
85       * @return boolean
86       * @throws HibernateException
87       */
88      public boolean equals(Object   x, Object   y) throws HibernateException;
89      
90      /**
91       * Get a hashcode for the instance, consistent with persistence "equality"
92       */
93      public int hashCode(Object   x) throws HibernateException;
94  
95      /**
96       * Retrieve an instance of the mapped class from a JDBC resultset. Implementors
97       * should handle possibility of null values.
98       *
99       * @param rs a JDBC result set
100      * @param names the column names
101      * @param session
102      * @param owner the containing entity
103      * @return Object
104      * @throws HibernateException
105      * @throws SQLException
106      */
107     public Object   nullSafeGet(ResultSet   rs, String  [] names, SessionImplementor session, Object   owner) 
108     throws HibernateException, SQLException  ;
109 
110     /**
111      * Write an instance of the mapped class to a prepared statement. Implementors
112      * should handle possibility of null values. A multi-column type should be written
113      * to parameters starting from <tt>index</tt>.
114      *
115      * @param st a JDBC prepared statement
116      * @param value the object to write
117      * @param index statement parameter index
118      * @param session
119      * @throws HibernateException
120      * @throws SQLException
121      */
122     public void nullSafeSet(PreparedStatement   st, Object   value, int index, SessionImplementor session) 
123     throws HibernateException, SQLException  ;
124 
125     /**
126      * Return a deep copy of the persistent state, stopping at entities and at collections.
127      *
128      * @param value generally a collection element or entity field
129      * @return Object a copy
130      * @throws HibernateException
131      */
132     public Object   deepCopy(Object   value) throws HibernateException;
133 
134     /**
135      * Check if objects of this type mutable.
136      *
137      * @return boolean
138      */
139     public boolean isMutable();
140 
141     /**
142      * Transform the object into its cacheable representation. At the very least this
143      * method should perform a deep copy. That may not be enough for some implementations,
144      * however; for example, associations must be cached as identifier values. (optional
145      * operation)
146      *
147      * @param value the object to be cached
148      * @param session
149      * @return a cachable representation of the object
150      * @throws HibernateException
151      */
152     public Serializable   disassemble(Object   value, SessionImplementor session) throws HibernateException;
153 
154     /**
155      * Reconstruct an object from the cacheable representation. At the very least this
156      * method should perform a deep copy. (optional operation)
157      *
158      * @param cached the object to be cached
159      * @param session
160      * @param owner the owner of the cached object
161      * @return a reconstructed object from the cachable representation
162      * @throws HibernateException
163      */
164     public Object   assemble(Serializable   cached, SessionImplementor session, Object   owner) 
165     throws HibernateException;
166 
167     /**
168      * During merge, replace the existing (target) value in the entity we are merging to
169      * with a new (original) value from the detached entity we are merging. For immutable
170      * objects, or null values, it is safe to simply return the first parameter. For
171      * mutable objects, it is safe to return a copy of the first parameter. However, since
172      * composite user types often define component values, it might make sense to recursively 
173      * replace component values in the target object.
174      * 
175      * @param original
176      * @param target
177      * @param session
178      * @param owner
179      * @return
180      * @throws HibernateException
181      */
182     public Object   replace(Object   original, Object   target, SessionImplementor session, Object   owner) 
183     throws HibernateException;
184 }
185
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags