001: //$Id: EntityTuplizer.java 7516 2005-07-16 22:20:48Z oneovthafew $
002: package org.hibernate.tuple.entity;
003:
004: import java.io.Serializable;
005: import java.util.Map;
006:
007: import org.hibernate.HibernateException;
008: import org.hibernate.tuple.Tuplizer;
009: import org.hibernate.engine.SessionImplementor;
010:
011: /**
012: * Defines further responsibilities reagarding tuplization based on
013: * a mapped entity.
014: * <p/>
015: * EntityTuplizer implementations should have the following constructor signature:
016: * (org.hibernate.tuple.entity.EntityMetamodel, org.hibernate.mapping.PersistentClass)
017: *
018: * @author Gavin King
019: * @author Steve Ebersole
020: */
021: public interface EntityTuplizer extends Tuplizer {
022:
023: /**
024: * Create an entity instance initialized with the given identifier.
025: *
026: * @param id The identifier value for the entity to be instantiated.
027: * @return The instantiated entity.
028: * @throws HibernateException
029: */
030: public Object instantiate(Serializable id)
031: throws HibernateException;
032:
033: /**
034: * Extract the identifier value from the given entity.
035: *
036: * @param entity The entity from which to extract the identifier value.
037: * @return The identifier value.
038: * @throws HibernateException If the entity does not define an identifier property, or an
039: * error occurrs accessing its value.
040: */
041: public Serializable getIdentifier(Object entity)
042: throws HibernateException;
043:
044: /**
045: * Inject the identifier value into the given entity.
046: * </p>
047: * Has no effect if the entity does not define an identifier property
048: *
049: * @param entity The entity to inject with the identifier value.
050: * @param id The value to be injected as the identifier.
051: * @throws HibernateException
052: */
053: public void setIdentifier(Object entity, Serializable id)
054: throws HibernateException;
055:
056: /**
057: * Inject the given identifier and version into the entity, in order to
058: * "roll back" to their original values.
059: *
060: * @param currentId The identifier value to inject into the entity.
061: * @param currentVersion The version value to inject into the entity.
062: */
063: public void resetIdentifier(Object entity, Serializable currentId,
064: Object currentVersion);
065:
066: /**
067: * Extract the value of the version property from the given entity.
068: *
069: * @param entity The entity from which to extract the version value.
070: * @return The value of the version property, or null if not versioned.
071: * @throws HibernateException
072: */
073: public Object getVersion(Object entity) throws HibernateException;
074:
075: /**
076: * Inject the value of a particular property.
077: *
078: * @param entity The entity into which to inject the value.
079: * @param i The property's index.
080: * @param value The property value to inject.
081: * @throws HibernateException
082: */
083: public void setPropertyValue(Object entity, int i, Object value)
084: throws HibernateException;
085:
086: /**
087: * Inject the value of a particular property.
088: *
089: * @param entity The entity into which to inject the value.
090: * @param propertyName The name of the property.
091: * @param value The property value to inject.
092: * @throws HibernateException
093: */
094: public void setPropertyValue(Object entity, String propertyName,
095: Object value) throws HibernateException;
096:
097: /**
098: * Extract the values of the insertable properties of the entity (including backrefs)
099: *
100: * @param entity The entity from which to extract.
101: * @param mergeMap a map of instances being merged to merged instances
102: * @param session The session in which the resuest is being made.
103: * @return The insertable property values.
104: * @throws HibernateException
105: */
106: public Object[] getPropertyValuesToInsert(Object entity,
107: Map mergeMap, SessionImplementor session)
108: throws HibernateException;
109:
110: /**
111: * Extract the value of a particular property from the given entity.
112: *
113: * @param entity The entity from which to extract the property value.
114: * @param propertyName The name of the property for which to extract the value.
115: * @return The current value of the given property on the given entity.
116: * @throws HibernateException
117: */
118: public Object getPropertyValue(Object entity, String propertyName)
119: throws HibernateException;
120:
121: /**
122: * Called just after the entities properties have been initialized.
123: *
124: * @param entity The entity being initialized.
125: * @param lazyPropertiesAreUnfetched Are defined lazy properties currently unfecthed
126: * @param session The session initializing this entity.
127: */
128: public void afterInitialize(Object entity,
129: boolean lazyPropertiesAreUnfetched,
130: SessionImplementor session);
131:
132: /**
133: * Does this entity, for this mode, present a possibility for proxying?
134: *
135: * @return True if this tuplizer can generate proxies for this entity.
136: */
137: public boolean hasProxy();
138:
139: /**
140: * Generates an appropriate proxy representation of this entity for this
141: * entity-mode.
142: *
143: * @param id The id of the instance for which to generate a proxy.
144: * @param session The session to which the proxy should be bound.
145: * @return The generate proxies.
146: * @throws HibernateException Indicates an error generating the proxy.
147: */
148: public Object createProxy(Serializable id,
149: SessionImplementor session) throws HibernateException;
150:
151: /**
152: * Does the {@link #getMappedClass() class} managed by this tuplizer implement
153: * the {@link org.hibernate.classic.Lifecycle} interface.
154: *
155: * @return True if the Lifecycle interface is implemented; false otherwise.
156: */
157: public boolean isLifecycleImplementor();
158:
159: /**
160: * Does the {@link #getMappedClass() class} managed by this tuplizer implement
161: * the {@link org.hibernate.classic.Validatable} interface.
162: *
163: * @return True if the Validatable interface is implemented; false otherwise.
164: */
165: public boolean isValidatableImplementor();
166:
167: // TODO: getConcreteProxyClass() is solely used (externally) to perform narrowProxy()
168: // would be great to fully encapsulate that narrowProxy() functionality within the
169: // Tuplizer, itself, with a Tuplizer.narrowProxy(..., PersistentContext) method
170: /**
171: * Returns the java class to which generated proxies will be typed.
172: *
173: * @return The java class to which generated proxies will be typed
174: */
175: public Class getConcreteProxyClass();
176:
177: /**
178: * Does the given entity instance have any currently uninitialized lazy properties?
179: *
180: * @param entity The entity to be check for uninitialized lazy properties.
181: * @return True if uninitialized lazy properties were found; false otherwise.
182: */
183: public boolean hasUninitializedLazyProperties(Object entity);
184:
185: /**
186: * Is it an instrumented POJO?
187: */
188: public boolean isInstrumented();
189: }
|