← Back to branch summary

~ubuntu-branches/ubuntu/wily/libhibernate3-java/wily-proposed

« back to all changes in this revision

Viewing changes to src/org/hibernate/type/Type.java

  • Committer: Bazaar Package Importer
  • Author(s): Torsten Werner
  • Date: 2007-10-14 14:43:34 UTC
  • Revision ID: james.westby@ubuntu.com-20071014144334-eamc8i0q10gs1aro
Tags: upstream-3.2.5
Import upstream version 3.2.5

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/org/hibernate/type/Type.java
 
1
//$Id: Type.java 7793 2005-08-10 05:06:40Z oneovthafew $
 
2
package org.hibernate.type;
 
3
 
 
4
import java.io.Serializable;
 
5
import java.sql.PreparedStatement;
 
6
import java.sql.ResultSet;
 
7
import java.sql.SQLException;
 
8
import java.util.Map;
 
9
 
 
10
import org.dom4j.Node;
 
11
import org.hibernate.EntityMode;
 
12
import org.hibernate.HibernateException;
 
13
import org.hibernate.MappingException;
 
14
import org.hibernate.engine.Mapping;
 
15
import org.hibernate.engine.SessionFactoryImplementor;
 
16
import org.hibernate.engine.SessionImplementor;
 
17
 
 
18
/**
 
19
 * Defines a mapping from a Java type to an JDBC datatype. This interface is intended to
 
20
 * be implemented by applications that need custom types.<br>
 
21
 * <br>
 
22
 * Implementors should usually be immutable and <b>must</b> certainly be threadsafe.
 
23
 *
 
24
 * @author Gavin King
 
25
 */
 
26
public interface Type extends Serializable {
 
27
 
 
28
        /**
 
29
         * Return true if the implementation is castable to
 
30
         * <tt>AssociationType</tt>. This does not necessarily imply that
 
31
         * the type actually represents an association.
 
32
         * @see AssociationType
 
33
         * @return boolean
 
34
         */
 
35
        public boolean isAssociationType();
 
36
        /**
 
37
         * Is this type a collection type.
 
38
         */
 
39
        public boolean isCollectionType();
 
40
 
 
41
        /**
 
42
         * Is this type a component type. If so, the implementation
 
43
         * must be castable to <tt>AbstractComponentType</tt>. A component
 
44
         * type may own collections or associations and hence must provide
 
45
         * certain extra functionality.
 
46
         * @see AbstractComponentType
 
47
         * @return boolean
 
48
         */
 
49
        public boolean isComponentType();
 
50
 
 
51
        /**
 
52
         * Is this type an entity type?
 
53
         * @return boolean
 
54
         */
 
55
        public boolean isEntityType();
 
56
 
 
57
        /**
 
58
         * Is this an "any" type.
 
59
         *
 
60
         * i.e. a reference to a persistent entity
 
61
         * that is not modelled as a (foreign key) association.
 
62
         */
 
63
        public boolean isAnyType();
 
64
        
 
65
        public boolean isXMLElement();
 
66
 
 
67
        /**
 
68
         * Return the SQL type codes for the columns mapped by this type. The codes
 
69
         * are defined on <tt>java.sql.Types</tt>.
 
70
         * @see java.sql.Types
 
71
         * @return the typecodes
 
72
         * @throws MappingException
 
73
         */
 
74
        public int[] sqlTypes(Mapping mapping) throws MappingException;
 
75
 
 
76
        /**
 
77
         * How many columns are used to persist this type.
 
78
         */
 
79
        public int getColumnSpan(Mapping mapping) throws MappingException;
 
80
 
 
81
        /**
 
82
         * The class returned by <tt>nullSafeGet()</tt> methods. This is used to 
 
83
         * establish the class of an array of this type.
 
84
         *
 
85
         * @return Class
 
86
         */
 
87
        public Class getReturnedClass();
 
88
 
 
89
        /**
 
90
         * Compare two instances of the class mapped by this type for persistence
 
91
         * "equality" - equality of persistent state - taking a shortcut for
 
92
         * entity references.
 
93
         * @param x
 
94
         * @param y
 
95
         * @param entityMode
 
96
         *
 
97
         * @return boolean
 
98
         * @throws HibernateException
 
99
         */
 
100
        public boolean isSame(Object x, Object y, EntityMode entityMode) throws HibernateException;
 
101
 
 
102
        /**
 
103
         * Compare two instances of the class mapped by this type for persistence
 
104
         * "equality" - equality of persistent state.
 
105
         * @param x
 
106
         * @param y
 
107
         * @param entityMode 
 
108
         *
 
109
         * @return boolean
 
110
         * @throws HibernateException
 
111
         */
 
112
        public boolean isEqual(Object x, Object y, EntityMode entityMode) throws HibernateException;
 
113
 
 
114
        /**
 
115
         * Compare two instances of the class mapped by this type for persistence
 
116
         * "equality" - equality of persistent state.
 
117
         * @param x
 
118
         * @param y
 
119
         * @param entityMode 
 
120
         *
 
121
         * @return boolean
 
122
         * @throws HibernateException
 
123
         */
 
124
        public boolean isEqual(Object x, Object y, EntityMode entityMode, SessionFactoryImplementor factory) 
 
125
        throws HibernateException;
 
126
 
 
127
        /**
 
128
         * Get a hashcode, consistent with persistence "equality"
 
129
         * @param x
 
130
         * @param entityMode 
 
131
         */
 
132
        public int getHashCode(Object x, EntityMode entityMode) throws HibernateException;
 
133
 
 
134
        /**
 
135
         * Get a hashcode, consistent with persistence "equality"
 
136
         * @param x
 
137
         * @param entityMode 
 
138
         * @param factory
 
139
         */
 
140
        public int getHashCode(Object x, EntityMode entityMode, SessionFactoryImplementor factory) 
 
141
        throws HibernateException;
 
142
        
 
143
        /**
 
144
         * compare two instances of the type
 
145
         * @param entityMode 
 
146
         */
 
147
        public int compare(Object x, Object y, EntityMode entityMode);
 
148
 
 
149
        /**
 
150
         * Should the parent be considered dirty, given both the old and current field or 
 
151
         * element value?
 
152
         * 
 
153
         * @param old the old value
 
154
         * @param current the current value
 
155
         * @param session
 
156
         * @return true if the field is dirty
 
157
         */
 
158
        public boolean isDirty(Object old, Object current, SessionImplementor session)
 
159
        throws HibernateException;
 
160
        /**
 
161
         * Should the parent be considered dirty, given both the old and current field or 
 
162
         * element value?
 
163
         * 
 
164
         * @param old the old value
 
165
         * @param current the current value
 
166
         * @param checkable which columns are actually updatable
 
167
         * @param session
 
168
         * @return true if the field is dirty
 
169
         */
 
170
        public boolean isDirty(Object old, Object current, boolean[] checkable, SessionImplementor session)
 
171
        throws HibernateException;
 
172
 
 
173
        /**
 
174
         * Has the parent object been modified, compared to the current database state?
 
175
         * @param oldHydratedState the database state, in a "hydrated" form, with identifiers unresolved
 
176
         * @param currentState the current state of the object
 
177
         * @param checkable which columns are actually updatable
 
178
         * @param session
 
179
         * @return true if the field has been modified
 
180
         */
 
181
        public boolean isModified(Object oldHydratedState, Object currentState, boolean[] checkable, SessionImplementor session)
 
182
        throws HibernateException;
 
183
 
 
184
        /**
 
185
         * Retrieve an instance of the mapped class from a JDBC resultset. Implementors
 
186
         * should handle possibility of null values.
 
187
         *
 
188
         * @see Type#hydrate(ResultSet, String[], SessionImplementor, Object) alternative, 2-phase property initialization
 
189
         * @param rs
 
190
         * @param names the column names
 
191
         * @param session
 
192
         * @param owner the parent entity
 
193
         * @return Object
 
194
         * @throws HibernateException
 
195
         * @throws SQLException
 
196
         */
 
197
        public Object nullSafeGet(ResultSet rs, String[] names, SessionImplementor session, Object owner)
 
198
        throws HibernateException, SQLException;
 
199
 
 
200
        /**
 
201
         * Retrieve an instance of the mapped class from a JDBC resultset. Implementations
 
202
         * should handle possibility of null values. This method might be called if the
 
203
         * type is known to be a single-column type.
 
204
         *
 
205
         * @param rs
 
206
         * @param name the column name
 
207
         * @param session
 
208
         * @param owner the parent entity
 
209
         * @return Object
 
210
         * @throws HibernateException
 
211
         * @throws SQLException
 
212
         */
 
213
        public Object nullSafeGet(ResultSet rs, String name, SessionImplementor session, Object owner)
 
214
        throws HibernateException, SQLException;
 
215
 
 
216
        /**
 
217
         * Write an instance of the mapped class to a prepared statement, ignoring some columns. 
 
218
         * Implementors should handle possibility of null values. A multi-column type should be 
 
219
         * written to parameters starting from <tt>index</tt>.
 
220
         * @param st
 
221
         * @param value the object to write
 
222
         * @param index statement parameter index
 
223
         * @param settable an array indicating which columns to ignore
 
224
         * @param session
 
225
         *
 
226
         * @throws HibernateException
 
227
         * @throws SQLException
 
228
         */
 
229
        public void nullSafeSet(PreparedStatement st, Object value, int index, boolean[] settable, SessionImplementor session)
 
230
        throws HibernateException, SQLException;
 
231
 
 
232
        /**
 
233
         * Write an instance of the mapped class to a prepared statement. Implementors
 
234
         * should handle possibility of null values. A multi-column type should be written
 
235
         * to parameters starting from <tt>index</tt>.
 
236
         * @param st
 
237
         * @param value the object to write
 
238
         * @param index statement parameter index
 
239
         * @param session
 
240
         *
 
241
         * @throws HibernateException
 
242
         * @throws SQLException
 
243
         */
 
244
        public void nullSafeSet(PreparedStatement st, Object value, int index, SessionImplementor session)
 
245
        throws HibernateException, SQLException;
 
246
 
 
247
        /**
 
248
         * A representation of the value to be embedded in an XML element.
 
249
         *
 
250
         * @param value
 
251
         * @param factory
 
252
         * @return String
 
253
         * @throws HibernateException
 
254
         */
 
255
        public void setToXMLNode(Node node, Object value, SessionFactoryImplementor factory)
 
256
        throws HibernateException;
 
257
 
 
258
        /**
 
259
         * A representation of the value to be embedded in a log file.
 
260
         *
 
261
         * @param value
 
262
         * @param factory
 
263
         * @return String
 
264
         * @throws HibernateException
 
265
         */
 
266
        public String toLoggableString(Object value, SessionFactoryImplementor factory)
 
267
        throws HibernateException;
 
268
 
 
269
        /**
 
270
         * Parse the XML representation of an instance.
 
271
         * @param xml
 
272
         * @param factory
 
273
         *
 
274
         * @return an instance of the type
 
275
         * @throws HibernateException
 
276
         */
 
277
        public Object fromXMLNode(Node xml, Mapping factory) throws HibernateException;
 
278
 
 
279
        /**
 
280
         * Returns the abbreviated name of the type.
 
281
         *
 
282
         * @return String the Hibernate type name
 
283
         */
 
284
        public String getName();
 
285
 
 
286
        /**
 
287
         * Return a deep copy of the persistent state, stopping at entities and at
 
288
         * collections.
 
289
         * @param value generally a collection element or entity field
 
290
         * @param entityMode 
 
291
         * @param factory
 
292
         * @return Object a copy
 
293
         */
 
294
        public Object deepCopy(Object value, EntityMode entityMode, SessionFactoryImplementor factory) 
 
295
        throws HibernateException;
 
296
 
 
297
        /**
 
298
         * Are objects of this type mutable. (With respect to the referencing object ...
 
299
         * entities and collections are considered immutable because they manage their
 
300
         * own internal state.)
 
301
         *
 
302
         * @return boolean
 
303
         */
 
304
        public boolean isMutable();
 
305
 
 
306
        /**
 
307
         * Return a cacheable "disassembled" representation of the object.
 
308
         * @param value the value to cache
 
309
         * @param session the session
 
310
         * @param owner optional parent entity object (needed for collections)
 
311
         * @return the disassembled, deep cloned state
 
312
         */
 
313
        public Serializable disassemble(Object value, SessionImplementor session, Object owner) throws HibernateException;
 
314
 
 
315
        /**
 
316
         * Reconstruct the object from its cached "disassembled" state.
 
317
         * @param cached the disassembled state from the cache
 
318
         * @param session the session
 
319
         * @param owner the parent entity object
 
320
         * @return the the object
 
321
         */
 
322
        public Object assemble(Serializable cached, SessionImplementor session, Object owner)
 
323
        throws HibernateException;
 
324
        
 
325
        /**
 
326
         * Called before assembling a query result set from the query cache, to allow batch fetching
 
327
         * of entities missing from the second-level cache.
 
328
         */
 
329
        public void beforeAssemble(Serializable cached, SessionImplementor session);
 
330
 
 
331
        /**
 
332
         * Retrieve an instance of the mapped class, or the identifier of an entity or collection, 
 
333
         * from a JDBC resultset. This is useful for 2-phase property initialization - the second 
 
334
         * phase is a call to <tt>resolveIdentifier()</tt>.
 
335
         * 
 
336
         * @see Type#resolve(Object, SessionImplementor, Object)
 
337
         * @param rs
 
338
         * @param names the column names
 
339
         * @param session the session
 
340
         * @param owner the parent entity
 
341
         * @return Object an identifier or actual value
 
342
         * @throws HibernateException
 
343
         * @throws SQLException
 
344
         */
 
345
        public Object hydrate(ResultSet rs, String[] names, SessionImplementor session, Object owner)
 
346
        throws HibernateException, SQLException;
 
347
 
 
348
        /**
 
349
         * Map identifiers to entities or collections. This is the second phase of 2-phase property 
 
350
         * initialization.
 
351
         * 
 
352
         * @see Type#hydrate(ResultSet, String[], SessionImplementor, Object)
 
353
         * @param value an identifier or value returned by <tt>hydrate()</tt>
 
354
         * @param owner the parent entity
 
355
         * @param session the session
 
356
         * @return the given value, or the value associated with the identifier
 
357
         * @throws HibernateException
 
358
         */
 
359
        public Object resolve(Object value, SessionImplementor session, Object owner)
 
360
        throws HibernateException;
 
361
        
 
362
        /**
 
363
         * Given a hydrated, but unresolved value, return a value that may be used to
 
364
         * reconstruct property-ref associations.
 
365
         */
 
366
        public Object semiResolve(Object value, SessionImplementor session, Object owner)
 
367
        throws HibernateException;
 
368
        
 
369
        /**
 
370
         * Get the type of a semi-resolved value.
 
371
         */
 
372
        public Type getSemiResolvedType(SessionFactoryImplementor factory);
 
373
 
 
374
        /**
 
375
         * During merge, replace the existing (target) value in the entity we are merging to
 
376
         * with a new (original) value from the detached entity we are merging. For immutable
 
377
         * objects, or null values, it is safe to simply return the first parameter. For
 
378
         * mutable objects, it is safe to return a copy of the first parameter. For objects
 
379
         * with component values, it might make sense to recursively replace component values.
 
380
         *
 
381
         * @param original the value from the detached entity being merged
 
382
         * @param target the value in the managed entity
 
383
         * @return the value to be merged
 
384
         */
 
385
        public Object replace(
 
386
                        Object original, 
 
387
                        Object target, 
 
388
                        SessionImplementor session, 
 
389
                        Object owner, 
 
390
                        Map copyCache)
 
391
        throws HibernateException;
 
392
        
 
393
        /**
 
394
         * During merge, replace the existing (target) value in the entity we are merging to
 
395
         * with a new (original) value from the detached entity we are merging. For immutable
 
396
         * objects, or null values, it is safe to simply return the first parameter. For
 
397
         * mutable objects, it is safe to return a copy of the first parameter. For objects
 
398
         * with component values, it might make sense to recursively replace component values.
 
399
         *
 
400
         * @param original the value from the detached entity being merged
 
401
         * @param target the value in the managed entity
 
402
         * @return the value to be merged
 
403
         */
 
404
        public Object replace(
 
405
                        Object original, 
 
406
                        Object target, 
 
407
                        SessionImplementor session, 
 
408
                        Object owner, 
 
409
                        Map copyCache, 
 
410
                        ForeignKeyDirection foreignKeyDirection)
 
411
        throws HibernateException;
 
412
        
 
413
        /**
 
414
         * Given an instance of the type, return an array of boolean, indicating
 
415
         * which mapped columns would be null.
 
416
         * 
 
417
         * @param value an instance of the type
 
418
         */
 
419
        public boolean[] toColumnNullness(Object value, Mapping mapping);
 
420
        
 
421
}
 
422
 
 
423
 
 
424
 
 
425
 
 
426
 
 
427