UserType


1   //$Id: UserType.java,v 1.6 2005/03/21 16:53:58 turin42 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  
11  /**
12   * This interface should be implemented by user-defined "types".
13   * A "type" class is <em>not</em> the actual property type - it
14   * is a class that knows how to serialize instances of another
15   * class to and from JDBC.<br>
16   * <br>
17   * This interface
18   * <ul>
19   * <li>abstracts user code from future changes to the <tt>Type</tt>
20   * interface,</li>
21   * <li>simplifies the implementation of custom types and</li>
22   * <li>hides certain "internal" interfaces from user code.</li>
23   * </ul>
24   * <br>
25   * Implementors must be immutable and must declare a public
26   * default constructor.<br>
27   * <br>
28   * The actual class mapped by a <tt>UserType</tt> may be just
29   * about anything.<br>
30   * <br>
31   * <tt>CompositeUserType</tt> provides an extended version of
32   * this interface that is useful for more complex cases.<br>
33   * <br>
34   * Alternatively, custom types could implement <tt>Type</tt>
35   * directly or extend one of the abstract classes in
36   * <tt>org.hibernate.type</tt>. This approach risks future
37   * incompatible changes to classes or interfaces in that
38   * package.
39   *
40   * @see CompositeUserType for more complex cases
41   * @see org.hibernate.type.Type
42   * @author Gavin King
43   */
44  public interface UserType {
45  
46      /**
47       * Return the SQL type codes for the columns mapped by this type. The
48       * codes are defined on <tt>java.sql.Types</tt>.
49       * @see java.sql.Types
50       * @return int[] the typecodes
51       */
52      public int[] sqlTypes();
53  
54      /**
55       * The class returned by <tt>nullSafeGet()</tt>.
56       *
57       * @return Class
58       */
59      public Class   returnedClass();
60  
61      /**
62       * Compare two instances of the class mapped by this type for persistence "equality".
63       * Equality of the persistent state.
64       *
65       * @param x
66       * @param y
67       * @return boolean
68       */
69      public boolean equals(Object   x, Object   y) throws HibernateException;
70  
71      /**
72       * Get a hashcode for the instance, consistent with persistence "equality"
73       */
74      public int hashCode(Object   x) throws HibernateException;
75  
76      /**
77       * Retrieve an instance of the mapped class from a JDBC resultset. Implementors
78       * should handle possibility of null values.
79       *
80       * @param rs a JDBC result set
81       * @param names the column names
82       * @param owner the containing entity
83       * @return Object
84       * @throws HibernateException
85       * @throws SQLException
86       */
87      public Object   nullSafeGet(ResultSet   rs, String  [] names, Object   owner) throws HibernateException, SQLException  ;
88  
89      /**
90       * Write an instance of the mapped class to a prepared statement. Implementors
91       * should handle possibility of null values. A multi-column type should be written
92       * to parameters starting from <tt>index</tt>.
93       *
94       * @param st a JDBC prepared statement
95       * @param value the object to write
96       * @param index statement parameter index
97       * @throws HibernateException
98       * @throws SQLException
99       */
100     public void nullSafeSet(PreparedStatement   st, Object   value, int index) throws HibernateException, SQLException  ;
101 
102     /**
103      * Return a deep copy of the persistent state, stopping at entities and at
104      * collections. It is not necessary to copy immutable objects, or null
105      * values, in which case it is safe to simply return the argument.
106      *
107      * @param value the object to be cloned, which may be null
108      * @return Object a copy
109      */
110     public Object   deepCopy(Object   value) throws HibernateException;
111 
112     /**
113      * Are objects of this type mutable?
114      *
115      * @return boolean
116      */
117     public boolean isMutable();
118 
119     /**
120      * Transform the object into its cacheable representation. At the very least this
121      * method should perform a deep copy if the type is mutable. That may not be enough
122      * for some implementations, however; for example, associations must be cached as
123      * identifier values. (optional operation)
124      *
125      * @param value the object to be cached
126      * @return a cachable representation of the object
127      * @throws HibernateException
128      */
129     public Serializable   disassemble(Object   value) throws HibernateException;
130 
131     /**
132      * Reconstruct an object from the cacheable representation. At the very least this
133      * method should perform a deep copy if the type is mutable. (optional operation)
134      *
135      * @param cached the object to be cached
136      * @param owner the owner of the cached object
137      * @return a reconstructed object from the cachable representation
138      * @throws HibernateException
139      */
140     public Object   assemble(Serializable   cached, Object   owner) throws HibernateException;
141 
142     /**
143      * During merge, replace the existing (target) value in the entity we are merging to
144      * with a new (original) value from the detached entity we are merging. For immutable
145      * objects, or null values, it is safe to simply return the first parameter. For
146      * mutable objects, it is safe to return a copy of the first parameter. For objects
147      * with component values, it might make sense to recursively replace component values.
148      *
149      * @param original the value from the detached entity being merged
150      * @param target the value in the managed entity
151      * @return the value to be merged
152      */
153     public Object   replace(Object   original, Object   target, Object   owner) throws HibernateException;
154 }
155 
156 
157 
158 
159 
160 
161
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags