KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > hibernate > type > Type


1 //$Id: Type.java,v 1.23 2005/07/19 18:17:14 oneovthafew Exp $
2
package org.hibernate.type;
3
4 import java.io.Serializable JavaDoc;
5 import java.sql.PreparedStatement JavaDoc;
6 import java.sql.ResultSet JavaDoc;
7 import java.sql.SQLException JavaDoc;
8 import java.util.Map JavaDoc;
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 JavaDoc {
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 JavaDoc 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 TODO
96      *
97      * @return boolean
98      * @throws HibernateException
99      */

100     public boolean isSame(Object JavaDoc x, Object JavaDoc 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 JavaDoc x, Object JavaDoc 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 JavaDoc x, Object JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc x, Object JavaDoc 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 JavaDoc old, Object JavaDoc current, SessionImplementor session)
159     throws HibernateException;
160
161     /**
162      * Has the parent object been modified, compared to the current database state?
163      * @param oldHydratedState the database state, in a "hydrated" form, with identifiers unresolved
164      * @param currentState the current state of the object
165      * @param session
166      * @return true if the field has been modified
167      */

168     public boolean isModified(Object JavaDoc oldHydratedState, Object JavaDoc currentState, SessionImplementor session)
169     throws HibernateException;
170
171     /**
172      * Retrieve an instance of the mapped class from a JDBC resultset. Implementors
173      * should handle possibility of null values.
174      *
175      * @see Type#hydrate(ResultSet, String[], SessionImplementor, Object) alternative, 2-phase property initialization
176      * @param rs
177      * @param names the column names
178      * @param session
179      * @param owner the parent entity
180      * @return Object
181      * @throws HibernateException
182      * @throws SQLException
183      */

184     public Object JavaDoc nullSafeGet(ResultSet JavaDoc rs, String JavaDoc[] names, SessionImplementor session, Object JavaDoc owner)
185     throws HibernateException, SQLException JavaDoc;
186
187     /**
188      * Retrieve an instance of the mapped class from a JDBC resultset. Implementations
189      * should handle possibility of null values. This method might be called if the
190      * type is known to be a single-column type.
191      *
192      * @param rs
193      * @param name the column name
194      * @param session
195      * @param owner the parent entity
196      * @return Object
197      * @throws HibernateException
198      * @throws SQLException
199      */

200     public Object JavaDoc nullSafeGet(ResultSet JavaDoc rs, String JavaDoc name, SessionImplementor session, Object JavaDoc owner)
201     throws HibernateException, SQLException JavaDoc;
202
203     /**
204      * Write an instance of the mapped class to a prepared statement, ignoring some columns.
205      * Implementors should handle possibility of null values. A multi-column type should be
206      * written to parameters starting from <tt>index</tt>.
207      * @param st
208      * @param value the object to write
209      * @param index statement parameter index
210      * @param settable an array indicating which columns to ignore
211      * @param session
212      *
213      * @throws HibernateException
214      * @throws SQLException
215      */

216     public void nullSafeSet(PreparedStatement JavaDoc st, Object JavaDoc value, int index, boolean[] settable, SessionImplementor session)
217     throws HibernateException, SQLException JavaDoc;
218
219     /**
220      * Write an instance of the mapped class to a prepared statement. Implementors
221      * should handle possibility of null values. A multi-column type should be written
222      * to parameters starting from <tt>index</tt>.
223      * @param st
224      * @param value the object to write
225      * @param index statement parameter index
226      * @param session
227      *
228      * @throws HibernateException
229      * @throws SQLException
230      */

231     public void nullSafeSet(PreparedStatement JavaDoc st, Object JavaDoc value, int index, SessionImplementor session)
232     throws HibernateException, SQLException JavaDoc;
233
234     /**
235      * A representation of the value to be embedded in an XML element.
236      *
237      * @param value
238      * @param factory
239      * @return String
240      * @throws HibernateException
241      */

242     public void setToXMLNode(Node node, Object JavaDoc value, SessionFactoryImplementor factory)
243     throws HibernateException;
244
245     /**
246      * A representation of the value to be embedded in a log file.
247      *
248      * @param value
249      * @param factory
250      * @return String
251      * @throws HibernateException
252      */

253     public String JavaDoc toLoggableString(Object JavaDoc value, SessionFactoryImplementor factory)
254     throws HibernateException;
255
256     /**
257      * Parse the XML representation of an instance.
258      * @param xml
259      * @param factory
260      *
261      * @return an instance of the type
262      * @throws HibernateException
263      */

264     public Object JavaDoc fromXMLNode(Node xml, Mapping factory) throws HibernateException;
265
266     /**
267      * Returns the abbreviated name of the type.
268      *
269      * @return String the Hibernate type name
270      */

271     public String JavaDoc getName();
272
273     /**
274      * Return a deep copy of the persistent state, stopping at entities and at
275      * collections.
276      * @param value generally a collection element or entity field
277      * @param entityMode
278      * @param factory
279      * @return Object a copy
280      */

281     public Object JavaDoc deepCopy(Object JavaDoc value, EntityMode entityMode, SessionFactoryImplementor factory)
282     throws HibernateException;
283
284     /**
285      * Are objects of this type mutable. (With respect to the referencing object ...
286      * entities and collections are considered immutable because they manage their
287      * own internal state.)
288      *
289      * @return boolean
290      */

291     public boolean isMutable();
292
293     /**
294      * Return a cacheable "disassembled" representation of the object.
295      * @param value the value to cache
296      * @param session the session
297      * @param owner optional parent entity object (needed for collections)
298      * @return the disassembled, deep cloned state
299      */

300     public Serializable JavaDoc disassemble(Object JavaDoc value, SessionImplementor session, Object JavaDoc owner) throws HibernateException;
301
302     /**
303      * Reconstruct the object from its cached "disassembled" state.
304      * @param cached the disassembled state from the cache
305      * @param session the session
306      * @param owner the parent entity object
307      * @return the the object
308      */

309     public Object JavaDoc assemble(Serializable JavaDoc cached, SessionImplementor session, Object JavaDoc owner)
310     throws HibernateException;
311
312     /**
313      * Retrieve an instance of the mapped class, or the identifier of an entity or collection,
314      * from a JDBC resultset. This is useful for 2-phase property initialization - the second
315      * phase is a call to <tt>resolveIdentifier()</tt>.
316      *
317      * @see Type#resolve(Object, SessionImplementor, Object)
318      * @param rs
319      * @param names the column names
320      * @param session the session
321      * @param owner the parent entity
322      * @return Object an identifier or actual value
323      * @throws HibernateException
324      * @throws SQLException
325      */

326     public Object JavaDoc hydrate(ResultSet JavaDoc rs, String JavaDoc[] names, SessionImplementor session, Object JavaDoc owner)
327     throws HibernateException, SQLException JavaDoc;
328
329     /**
330      * Map identifiers to entities or collections. This is the second phase of 2-phase property
331      * initialization.
332      *
333      * @see Type#hydrate(ResultSet, String[], SessionImplementor, Object)
334      * @param value an identifier or value returned by <tt>hydrate()</tt>
335      * @param owner the parent entity
336      * @param session the session
337      * @return the given value, or the value associated with the identifier
338      * @throws HibernateException
339      */

340     public Object JavaDoc resolve(Object JavaDoc value, SessionImplementor session, Object JavaDoc owner)
341     throws HibernateException;
342     
343     /**
344      * Given a hydrated, but unresolved value, return a value that may be used to
345      * reconstruct property-ref associations.
346      */

347     public Object JavaDoc semiResolve(Object JavaDoc value, SessionImplementor session, Object JavaDoc owner)
348     throws HibernateException;
349     
350     /**
351      * Get the type of a semi-resolved value.
352      */

353     public Type getSemiResolvedType(SessionFactoryImplementor factory);
354
355     /**
356      * During merge, replace the existing (target) value in the entity we are merging to
357      * with a new (original) value from the detached entity we are merging. For immutable
358      * objects, or null values, it is safe to simply return the first parameter. For
359      * mutable objects, it is safe to return a copy of the first parameter. For objects
360      * with component values, it might make sense to recursively replace component values.
361      *
362      * @param original the value from the detached entity being merged
363      * @param target the value in the managed entity
364      * @return the value to be merged
365      */

366     public Object JavaDoc replace(
367             Object JavaDoc original,
368             Object JavaDoc target,
369             SessionImplementor session,
370             Object JavaDoc owner,
371             Map JavaDoc copyCache)
372     throws HibernateException;
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 JavaDoc replace(
386             Object JavaDoc original,
387             Object JavaDoc target,
388             SessionImplementor session,
389             Object JavaDoc owner,
390             Map JavaDoc copyCache,
391             ForeignKeyDirection foreignKeyDirection)
392     throws HibernateException;
393     
394     /**
395      * Given an instance of the type, return an array of boolean, indicating
396      * which mapped columns would be null.
397      *
398      * @param value an instance of the type
399      */

400     public boolean[] toColumnNullness(Object JavaDoc value, Mapping mapping);
401     
402 }
403
404
405
406
407
408
409
Popular Tags