01: // $Id: Tuplizer.java 10119 2006-07-14 00:09:19Z steve.ebersole@jboss.com $
02: package org.hibernate.tuple;
03:
04: import org.hibernate.HibernateException;
05:
06: /**
07: * A tuplizer defines the contract for things which know how to manage
08: * a particular representation of a piece of data, given that
09: * representation's {@link org.hibernate.EntityMode} (the entity-mode
10: * essentially defining which representation).
11: * </p>
12: * If that given piece of data is thought of as a data structure, then a tuplizer
13: * is the thing which knows how to<ul>
14: * <li>create such a data structure appropriately
15: * <li>extract values from and inject values into such a data structure
16: * </ul>
17: * </p>
18: * For example, a given piece of data might be represented as a POJO class.
19: * Here, it's representation and entity-mode is POJO. Well a tuplizer for POJO
20: * entity-modes would know how to<ul>
21: * <li>create the data structure by calling the POJO's constructor
22: * <li>extract and inject values through getters/setter, or by direct field access, etc
23: * </ul>
24: * </p>
25: * That same piece of data might also be represented as a DOM structure, using
26: * the tuplizer associated with the DOM4J entity-mode, which would generate instances
27: * of {@link org.dom4j.Element} as the data structure and know how to access the
28: * values as either nested {@link org.dom4j.Element}s or as {@link org.dom4j.Attribute}s.
29: *
30: * @see org.hibernate.tuple.entity.EntityTuplizer
31: * @see org.hibernate.tuple.component.ComponentTuplizer
32: *
33: * @author Steve Ebersole
34: */
35: public interface Tuplizer {
36:
37: /**
38: * Extract the current values contained on the given entity.
39: *
40: * @param entity The entity from which to extract values.
41: * @return The current property values.
42: * @throws HibernateException
43: */
44: public Object[] getPropertyValues(Object entity)
45: throws HibernateException;
46:
47: /**
48: * Inject the given values into the given entity.
49: *
50: * @param entity The entity.
51: * @param values The values to be injected.
52: * @throws HibernateException
53: */
54: public void setPropertyValues(Object entity, Object[] values)
55: throws HibernateException;
56:
57: /**
58: * Extract the value of a particular property from the given entity.
59: *
60: * @param entity The entity from which to extract the property value.
61: * @param i The index of the property for which to extract the value.
62: * @return The current value of the given property on the given entity.
63: * @throws HibernateException
64: */
65: public Object getPropertyValue(Object entity, int i)
66: throws HibernateException;
67:
68: /**
69: * Generate a new, empty entity.
70: *
71: * @return The new, empty entity instance.
72: * @throws HibernateException
73: */
74: public Object instantiate() throws HibernateException;
75:
76: /**
77: * Is the given object considered an instance of the the entity (acconting
78: * for entity-mode) managed by this tuplizer.
79: *
80: * @param object The object to be checked.
81: * @return True if the object is considered as an instance of this entity
82: * within the given mode.
83: */
84: public boolean isInstance(Object object);
85:
86: /**
87: * Return the pojo class managed by this tuplizer.
88: * </p>
89: * Need to determine how to best handle this for the Tuplizers for EntityModes
90: * other than POJO.
91: * </p>
92: * todo : be really nice to not have this here since it is essentially pojo specific...
93: *
94: * @return The persistent class.
95: */
96: public Class getMappedClass();
97:
98: }
|