001: //$Id: Hibernate.java 10009 2006-06-10 03:24:05Z epbernard $
002: package org.hibernate;
003:
004: import java.io.IOException;
005: import java.io.InputStream;
006: import java.io.Reader;
007: import java.io.Serializable;
008: import java.sql.Blob;
009: import java.sql.Clob;
010: import java.util.Iterator;
011: import java.util.Properties;
012:
013: import org.hibernate.collection.PersistentCollection;
014: import org.hibernate.engine.HibernateIterator;
015: import org.hibernate.intercept.FieldInterceptionHelper;
016: import org.hibernate.intercept.FieldInterceptor;
017: import org.hibernate.lob.BlobImpl;
018: import org.hibernate.lob.ClobImpl;
019: import org.hibernate.lob.SerializableBlob;
020: import org.hibernate.lob.SerializableClob;
021: import org.hibernate.proxy.HibernateProxy;
022: import org.hibernate.proxy.LazyInitializer;
023: import org.hibernate.type.AnyType;
024: import org.hibernate.type.BigDecimalType;
025: import org.hibernate.type.BigIntegerType;
026: import org.hibernate.type.BinaryType;
027: import org.hibernate.type.BlobType;
028: import org.hibernate.type.BooleanType;
029: import org.hibernate.type.ByteType;
030: import org.hibernate.type.CalendarDateType;
031: import org.hibernate.type.CalendarType;
032: import org.hibernate.type.CharacterType;
033: import org.hibernate.type.ClassType;
034: import org.hibernate.type.ClobType;
035: import org.hibernate.type.CompositeCustomType;
036: import org.hibernate.type.CurrencyType;
037: import org.hibernate.type.CustomType;
038: import org.hibernate.type.DateType;
039: import org.hibernate.type.DoubleType;
040: import org.hibernate.type.FloatType;
041: import org.hibernate.type.IntegerType;
042: import org.hibernate.type.LocaleType;
043: import org.hibernate.type.LongType;
044: import org.hibernate.type.ManyToOneType;
045: import org.hibernate.type.NullableType;
046: import org.hibernate.type.SerializableType;
047: import org.hibernate.type.ShortType;
048: import org.hibernate.type.StringType;
049: import org.hibernate.type.TextType;
050: import org.hibernate.type.TimeType;
051: import org.hibernate.type.TimeZoneType;
052: import org.hibernate.type.TimestampType;
053: import org.hibernate.type.TrueFalseType;
054: import org.hibernate.type.Type;
055: import org.hibernate.type.YesNoType;
056: import org.hibernate.type.CharArrayType;
057: import org.hibernate.type.WrapperBinaryType;
058: import org.hibernate.type.CharacterArrayType;
059: import org.hibernate.usertype.CompositeUserType;
060:
061: /**
062: * <ul>
063: * <li>Provides access to the full range of Hibernate built-in types. <tt>Type</tt>
064: * instances may be used to bind values to query parameters.
065: * <li>A factory for new <tt>Blob</tt>s and <tt>Clob</tt>s.
066: * <li>Defines static methods for manipulation of proxies.
067: * </ul>
068: *
069: * @author Gavin King
070: * @see java.sql.Clob
071: * @see java.sql.Blob
072: * @see org.hibernate.type.Type
073: */
074:
075: public final class Hibernate {
076:
077: /**
078: * Hibernate <tt>long</tt> type.
079: */
080: public static final NullableType LONG = new LongType();
081: /**
082: * Hibernate <tt>short</tt> type.
083: */
084: public static final NullableType SHORT = new ShortType();
085: /**
086: * Hibernate <tt>integer</tt> type.
087: */
088: public static final NullableType INTEGER = new IntegerType();
089: /**
090: * Hibernate <tt>byte</tt> type.
091: */
092: public static final NullableType BYTE = new ByteType();
093: /**
094: * Hibernate <tt>float</tt> type.
095: */
096: public static final NullableType FLOAT = new FloatType();
097: /**
098: * Hibernate <tt>double</tt> type.
099: */
100: public static final NullableType DOUBLE = new DoubleType();
101: /**
102: * Hibernate <tt>character</tt> type.
103: */
104: public static final NullableType CHARACTER = new CharacterType();
105: /**
106: * Hibernate <tt>string</tt> type.
107: */
108: public static final NullableType STRING = new StringType();
109: /**
110: * Hibernate <tt>time</tt> type.
111: */
112: public static final NullableType TIME = new TimeType();
113: /**
114: * Hibernate <tt>date</tt> type.
115: */
116: public static final NullableType DATE = new DateType();
117: /**
118: * Hibernate <tt>timestamp</tt> type.
119: */
120: public static final NullableType TIMESTAMP = new TimestampType();
121: /**
122: * Hibernate <tt>boolean</tt> type.
123: */
124: public static final NullableType BOOLEAN = new BooleanType();
125: /**
126: * Hibernate <tt>true_false</tt> type.
127: */
128: public static final NullableType TRUE_FALSE = new TrueFalseType();
129: /**
130: * Hibernate <tt>yes_no</tt> type.
131: */
132: public static final NullableType YES_NO = new YesNoType();
133: /**
134: * Hibernate <tt>big_decimal</tt> type.
135: */
136: public static final NullableType BIG_DECIMAL = new BigDecimalType();
137: /**
138: * Hibernate <tt>big_integer</tt> type.
139: */
140: public static final NullableType BIG_INTEGER = new BigIntegerType();
141: /**
142: * Hibernate <tt>binary</tt> type.
143: */
144: public static final NullableType BINARY = new BinaryType();
145: /**
146: * Hibernate <tt>wrapper-binary</tt> type.
147: */
148: public static final NullableType WRAPPER_BINARY = new WrapperBinaryType();
149: /**
150: * Hibernate char[] type.
151: */
152: public static final NullableType CHAR_ARRAY = new CharArrayType();
153: /**
154: * Hibernate Character[] type.
155: */
156: public static final NullableType CHARACTER_ARRAY = new CharacterArrayType();
157: /**
158: * Hibernate <tt>text</tt> type.
159: */
160: public static final NullableType TEXT = new TextType();
161: /**
162: * Hibernate <tt>blob</tt> type.
163: */
164: public static final Type BLOB = new BlobType();
165: /**
166: * Hibernate <tt>clob</tt> type.
167: */
168: public static final Type CLOB = new ClobType();
169: /**
170: * Hibernate <tt>calendar</tt> type.
171: */
172: public static final NullableType CALENDAR = new CalendarType();
173: /**
174: * Hibernate <tt>calendar_date</tt> type.
175: */
176: public static final NullableType CALENDAR_DATE = new CalendarDateType();
177: /**
178: * Hibernate <tt>locale</tt> type.
179: */
180: public static final NullableType LOCALE = new LocaleType();
181: /**
182: * Hibernate <tt>currency</tt> type.
183: */
184: public static final NullableType CURRENCY = new CurrencyType();
185: /**
186: * Hibernate <tt>timezone</tt> type.
187: */
188: public static final NullableType TIMEZONE = new TimeZoneType();
189: /**
190: * Hibernate <tt>class</tt> type.
191: */
192: public static final NullableType CLASS = new ClassType();
193: /**
194: * Hibernate <tt>serializable</tt> type.
195: */
196: public static final NullableType SERIALIZABLE = new SerializableType(
197: Serializable.class);
198: /**
199: * Hibernate <tt>object</tt> type.
200: */
201: public static final Type OBJECT = new AnyType();
202:
203: /**
204: * Cannot be instantiated.
205: */
206: private Hibernate() {
207: throw new UnsupportedOperationException();
208: }
209:
210: /**
211: * A Hibernate <tt>serializable</tt> type.
212: */
213: public static Type serializable(Class serializableClass) {
214: return new SerializableType(serializableClass);
215: }
216:
217: /**
218: * A Hibernate <tt>any</tt> type.
219: *
220: * @param metaType a type mapping <tt>java.lang.Class</tt> to a single column
221: * @param identifierType the entity identifier type
222: * @return the Type
223: */
224: public static Type any(Type metaType, Type identifierType) {
225: return new AnyType(metaType, identifierType);
226: }
227:
228: /**
229: * A Hibernate persistent object (entity) type.
230: *
231: * @param persistentClass a mapped entity class
232: */
233: public static Type entity(Class persistentClass) {
234: // not really a many-to-one association *necessarily*
235: return new ManyToOneType(persistentClass.getName());
236: }
237:
238: /**
239: * A Hibernate persistent object (entity) type.
240: *
241: * @param entityName a mapped entity class
242: */
243: public static Type entity(String entityName) {
244: // not really a many-to-one association *necessarily*
245: return new ManyToOneType(entityName);
246: }
247:
248: /**
249: * A Hibernate custom type.
250: *
251: * @param userTypeClass a class that implements <tt>UserType</tt>
252: */
253: public static Type custom(Class userTypeClass)
254: throws HibernateException {
255: return custom(userTypeClass, null);
256: }
257:
258: /**
259: * A Hibernate parameterizable custom type.
260: *
261: * @param userTypeClass a class that implements <tt>UserType and ParameterizableType</tt>
262: * @param parameterNames the names of the parameters passed to the type
263: * @param parameterValues the values of the parameters passed to the type. They must match
264: * up with the order and length of the parameterNames array.
265: */
266: public static Type custom(Class userTypeClass,
267: String[] parameterNames, String[] parameterValues)
268: throws HibernateException {
269: Properties parameters = new Properties();
270: for (int i = 0; i < parameterNames.length; i++) {
271: parameters.setProperty(parameterNames[i],
272: parameterValues[i]);
273: }
274: return custom(userTypeClass, parameters);
275: }
276:
277: /**
278: * A Hibernate parameterizable custom type.
279: *
280: * @param userTypeClass a class that implements <tt>UserType and ParameterizableType</tt>
281: * @param parameters the parameters as a collection of name/value pairs
282: */
283: public static Type custom(Class userTypeClass, Properties parameters)
284: throws HibernateException {
285: if (CompositeUserType.class.isAssignableFrom(userTypeClass)) {
286: CompositeCustomType type = new CompositeCustomType(
287: userTypeClass, parameters);
288: return type;
289: } else {
290: CustomType type = new CustomType(userTypeClass, parameters);
291: return type;
292: }
293: }
294:
295: /**
296: * Force initialization of a proxy or persistent collection.
297: * <p/>
298: * Note: This only ensures intialization of a proxy object or collection;
299: * it is not guaranteed that the elements INSIDE the collection will be initialized/materialized.
300: *
301: * @param proxy a persistable object, proxy, persistent collection or <tt>null</tt>
302: * @throws HibernateException if we can't initialize the proxy at this time, eg. the <tt>Session</tt> was closed
303: */
304: public static void initialize(Object proxy)
305: throws HibernateException {
306: if (proxy == null) {
307: return;
308: } else if (proxy instanceof HibernateProxy) {
309: ((HibernateProxy) proxy).getHibernateLazyInitializer()
310: .initialize();
311: } else if (proxy instanceof PersistentCollection) {
312: ((PersistentCollection) proxy).forceInitialization();
313: }
314: }
315:
316: /**
317: * Check if the proxy or persistent collection is initialized.
318: *
319: * @param proxy a persistable object, proxy, persistent collection or <tt>null</tt>
320: * @return true if the argument is already initialized, or is not a proxy or collection
321: */
322: public static boolean isInitialized(Object proxy) {
323: if (proxy instanceof HibernateProxy) {
324: return !((HibernateProxy) proxy)
325: .getHibernateLazyInitializer().isUninitialized();
326: } else if (proxy instanceof PersistentCollection) {
327: return ((PersistentCollection) proxy).wasInitialized();
328: } else {
329: return true;
330: }
331: }
332:
333: /**
334: * Get the true, underlying class of a proxied persistent class. This operation
335: * will initialize a proxy by side-effect.
336: *
337: * @param proxy a persistable object or proxy
338: * @return the true class of the instance
339: * @throws HibernateException
340: */
341: public static Class getClass(Object proxy) {
342: if (proxy instanceof HibernateProxy) {
343: return ((HibernateProxy) proxy)
344: .getHibernateLazyInitializer().getImplementation()
345: .getClass();
346: } else {
347: return proxy.getClass();
348: }
349: }
350:
351: /**
352: * Create a new <tt>Blob</tt>. The returned object will be initially immutable.
353: *
354: * @param bytes a byte array
355: * @return the Blob
356: */
357: public static Blob createBlob(byte[] bytes) {
358: return new SerializableBlob(new BlobImpl(bytes));
359: }
360:
361: /**
362: * Create a new <tt>Blob</tt>. The returned object will be initially immutable.
363: *
364: * @param stream a binary stream
365: * @param length the number of bytes in the stream
366: * @return the Blob
367: */
368: public static Blob createBlob(InputStream stream, int length) {
369: return new SerializableBlob(new BlobImpl(stream, length));
370: }
371:
372: /**
373: * Create a new <tt>Blob</tt>. The returned object will be initially immutable.
374: *
375: * @param stream a binary stream
376: * @return the Blob
377: * @throws IOException
378: */
379: public static Blob createBlob(InputStream stream)
380: throws IOException {
381: return new SerializableBlob(new BlobImpl(stream, stream
382: .available()));
383: }
384:
385: /**
386: * Create a new <tt>Clob</tt>. The returned object will be initially immutable.
387: *
388: * @param string a <tt>String</tt>
389: */
390: public static Clob createClob(String string) {
391: return new SerializableClob(new ClobImpl(string));
392: }
393:
394: /**
395: * Create a new <tt>Clob</tt>. The returned object will be initially immutable.
396: *
397: * @param reader a character stream
398: * @param length the number of characters in the stream
399: */
400: public static Clob createClob(Reader reader, int length) {
401: return new SerializableClob(new ClobImpl(reader, length));
402: }
403:
404: /**
405: * Close an <tt>Iterator</tt> created by <tt>iterate()</tt> immediately,
406: * instead of waiting until the session is closed or disconnected.
407: *
408: * @param iterator an <tt>Iterator</tt> created by <tt>iterate()</tt>
409: * @throws HibernateException
410: * @see org.hibernate.Query#iterate
411: * @see Query#iterate()
412: */
413: public static void close(Iterator iterator)
414: throws HibernateException {
415: if (iterator instanceof HibernateIterator) {
416: ((HibernateIterator) iterator).close();
417: } else {
418: throw new IllegalArgumentException(
419: "not a Hibernate iterator");
420: }
421: }
422:
423: /**
424: * Check if the property is initialized. If the named property does not exist
425: * or is not persistent, this method always returns <tt>true</tt>.
426: *
427: * @param proxy The potential proxy
428: * @param propertyName the name of a persistent attribute of the object
429: * @return true if the named property of the object is not listed as uninitialized
430: * @return false if the object is an uninitialized proxy, or the named property is uninitialized
431: */
432: public static boolean isPropertyInitialized(Object proxy,
433: String propertyName) {
434:
435: Object entity;
436: if (proxy instanceof HibernateProxy) {
437: LazyInitializer li = ((HibernateProxy) proxy)
438: .getHibernateLazyInitializer();
439: if (li.isUninitialized()) {
440: return false;
441: } else {
442: entity = li.getImplementation();
443: }
444: } else {
445: entity = proxy;
446: }
447:
448: if (FieldInterceptionHelper.isInstrumented(entity)) {
449: FieldInterceptor interceptor = FieldInterceptionHelper
450: .extractFieldInterceptor(entity);
451: return interceptor == null
452: || interceptor.isInitialized(propertyName);
453: } else {
454: return true;
455: }
456:
457: }
458:
459: }
|