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  ;
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 TODO
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     /**
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   oldHydratedState, Object   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   nullSafeGet(ResultSet   rs, String  [] names, SessionImplementor session, Object   owner)
185     throws HibernateException, SQLException  ;
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   nullSafeGet(ResultSet   rs, String   name, SessionImplementor session, Object   owner)
201     throws HibernateException, SQLException  ;
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   st, Object   value, int index, boolean[] settable, SessionImplementor session)
217     throws HibernateException, SQLException  ;
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   st, Object   value, int index, SessionImplementor session)
232     throws HibernateException, SQLException  ;
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   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   toLoggableString(Object   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   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   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   deepCopy(Object   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   disassemble(Object   value, SessionImplementor session, Object   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   assemble(Serializable   cached, SessionImplementor session, Object   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   hydrate(ResultSet   rs, String  [] names, SessionImplementor session, Object   owner)
327     throws HibernateException, SQLException  ;
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   resolve(Object   value, SessionImplementor session, Object   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   semiResolve(Object   value, SessionImplementor session, Object   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   replace(
367             Object   original, 
368             Object   target, 
369             SessionImplementor session, 
370             Object   owner, 
371             Map   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   replace(
386             Object   original, 
387             Object   target, 
388             SessionImplementor session, 
389             Object   owner, 
390             Map   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   value, Mapping mapping);
401     
402 }
403 
404 
405 
406 
407 
408 
409
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags