From hibernate-commits at lists.jboss.org Tue May 25 15:07:44 2010 Content-Type: multipart/mixed; boundary="===============3190483948387845125==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r19607 - core/trunk/documentation/manual/src/main/docbook/en-US/content. Date: Tue, 25 May 2010 15:07:44 -0400 Message-ID: <201005251907.o4PJ7iiu004820@svn01.web.mwc.hst.phx2.redhat.com> --===============3190483948387845125== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: steve.ebersole(a)jboss.com Date: 2010-05-25 15:07:43 -0400 (Tue, 25 May 2010) New Revision: 19607 Added: core/trunk/documentation/manual/src/main/docbook/en-US/content/type.xml Log: Added: core/trunk/documentation/manual/src/main/docbook/en-US/content/type.= xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- core/trunk/documentation/manual/src/main/docbook/en-US/content/type.xml= (rev 0) +++ core/trunk/documentation/manual/src/main/docbook/en-US/content/type.xml= 2010-05-25 19:07:43 UTC (rev 19607) @@ -0,0 +1,990 @@ + + + = + + Types + + + As an Object/Relational Mapping solution, Hibernate deals with bot= h the Java and JDBC representations of + application data. An online catalog application, for example, mos= t likely has Product + object with a number of attributes such as a sku, name, etc. For these + individual attributes, Hibernate must be able to read the values o= ut of the database and write them back. This + 'marshalling' is the function of a Hibernate type, which is an implementation of the + org.hibernate.type.Type interface. = In addition, a + Hibernate type describes various aspects of b= ehavior of the Java type such as "how is + equality checked?" or "how are values cloned?". + + + + + A Hibernate type is neither a Java type nor a SQL datatype; it= provides a information about both. + + + When you encounter the term type in regar= ds to Hibernate be aware that usage might + refer to the Java type, the SQL/JDBC type or the Hibernate typ= e. + + + + + Hibernate categorizes types into two high-level groups: value type= s (see ) and + entity types (see ). + + +
+ Value types + + + The main distinguishing characteristic of a value type is the = fact that they do not define their own + lifecycle. We say that they are "owned" by something else (sp= ecifically an entity, as we will see later) + which defines their lifecycle. Value types are further classi= fied into 3 sub-categories: basic types (see + ), composite types (see <= xref linkend=3D"types.value.composite"/>) + amd collection types (see ). + + +
+ Basic value types + + The norm for basic value types is that they map a single d= atabase value (column) to a single, = + non-aggregated Java type. Hibernate provides a number of = built-in basic types, which we will present + in the following sections by the Java type. Mainly these = follow the natural mappings recommended in the + JDBC specification. We will later cover how to override t= hese mapping and how to provide and use + alternative type mappings. + +
+ java.lang.String + + + org.hibernate.type.StringType + + + Maps a string to the JDBC VARCHAR type. T= his is the standard mapping for a string if = + no Hibernate type is specified. + + + Registered under string= and java.lang.String + in the type registry (see ). + + + + + org.hibernate.type.MaterializedCl= ob + + + Maps a string to a JDBC CLOB type + + + Registered under materialized_clo= b in the type registry (see + ). + + + + + org.hibernate.type.TextType + + + Maps a string to a JDBC LONGVARCHAR type + + + Registered under text i= n the type registry (see + ). + + + + +
+
+ <classname>java.lang.Character</classname> (or char= primitive) + + + org.hibernate.type.CharacterType<= /classname> + + + Maps a char or java.lang.Charac= ter to a JDBC CHAR + + + Registered under char a= nd java.lang.Character in the + type registry (see ). + + + + +
+
+ <classname>java.lang.Boolean</classname> (or boolea= n primitive) + + + org.hibernate.type.BooleanType + + + Maps a boolean to a JDBC BIT type + + + Registered under boolean and java.lang.Boolean in + the type registry (see ). + + + + + org.hibernate.type.NumericBoolean= Type + + + Maps a boolean to a JDBC INTEGER type as 0= =3D false, 1 =3D true + + + Registered under numeric_boolean<= /literal> in the type registry (see + ). + + + + + org.hibernate.type.YesNoType + + + Maps a boolean to a JDBC CHAR type as ('N'= | 'n') =3D false, ( 'Y' | 'y' ) =3D true + + + Registered under yes_no= in the type registry (see + ). + + + + + org.hibernate.type.TrueFalseType<= /classname> + + + Maps a boolean to a JDBC CHAR type as ('F'= | 'f') =3D false, ( 'T' | 't' ) =3D true + + + Registered under true_false in the type registry (see + ). + + + + +
+
+ <classname>java.lang.Byte</classname> (or byte prim= itive) + + + org.hibernate.type.ByteType + + + Maps a byte or java.lang.Byte to a JDBC TINYINT + + + Registered under byte a= nd java.lang.Byte in the + type registry (see ). + + + + +
+
+ <classname>java.lang.Short</classname> (or short pr= imitive) + + + org.hibernate.type.ShortType + + + Maps a short or java.lang.Short= to a JDBC SMALLINT + + + Registered under short = and java.lang.Short in the + type registry (see ). + + + + +
+
+ <classname>java.lang.Integer</classname> (or int pr= imitive) + + + org.hibernate.type.IntegerTypes + + + Maps an int or java.lang.Intege= r to a JDBC INTEGER + + + Registered under int an= d java.lang.Integerin the + type registry (see ). + + + + +
+
+ <classname>java.lang.Long</classname> (or long prim= itive) + + + org.hibernate.type.LongType + + + Maps a long or java.lang.Long to a JDBC BIGINT + + + Registered under long a= nd java.lang.Long in the + type registry (see ). + + + + +
+
+ <classname>java.lang.Float</classname> (or float pr= imitive) + + + org.hibernate.type.FloatType + + + Maps a float or java.lang.Float= to a JDBC FLOAT + + + Registered under float = and java.lang.Float in the + type registry (see ). + + + + +
+
+ <classname>java.lang.Double</classname> (or double = primitive) + + + org.hibernate.type.DoubleType + + + Maps a double or java.lang.Doub= le to a JDBC DOUBLE + + + Registered under double= and java.lang.Double in the + type registry (see ). + + + + +
+
+ <classname>java.math.BigInteger</classname> + + + org.hibernate.type.BigIntegerType= + + + Maps a java.math.BigInteger to a JDBC NUMERIC + + + Registered under big_integer and java.math.BigInteger in the + type registry (see ). + + + + +
+
+ <classname>java.math.BigDecimal</classname> + + + org.hibernate.type.BigDecimalType= + + + Maps a java.math.BigDecimal to a JDBC NUMERIC + + + Registered under big_decimal and java.math.BigDecimal in the + type registry (see ). + + + + +
+
+ <classname>java.util.Date</classname> or <classname= >java.sql.Timestamp</classname> + + + org.hibernate.type.TimestampType<= /classname> + + + Maps a java.sql.Timestamp to a JDBC TIMESTAMP + + + Registered under timestamp, java.sql.Timestamp and + java.util.Date in the t= ype registry (see ). + + + + +
+
+ <classname>java.sql.Time</classname> + + + org.hibernate.type.TimeType + + + Maps a java.sql.Time to a JDBC TIME + + + Registered under time a= nd java.sql.Time in the + type registry (see ). + + + + +
+
+ <classname>java.sql.Date</classname> + + + org.hibernate.type.DateType + + + Maps a java.sql.Date to a JDBC DATE + + + Registered under date a= nd java.sql.Date in the + type registry (see ). + + + + +
+
+ <classname>java.util.Calendar</classname> + + + org.hibernate.type.CalendarType + + + Maps a java.util.Calendar to a JDBC TIMESTAMP + + + Registered under calendar, java.util.Calendar and + java.util.GregorianCalendar in the type registry (see + ). + + + + + org.hibernate.type.CalendarDateTy= pe + + + Maps a java.util.Calendar to a JDBC DATE + + + Registered under calendar_date in the type registry (see + ). + + + + +
+
+ <classname>java.util.Currency</classname> + + + org.hibernate.type.CurrencyType + + + Maps a java.util.Currency to a JDBC VARCHAR (using the Currency code) + + + Registered under currency and java.util.Currency in the + type registry (see ). + + + + +
+
+ <classname>java.util.Locale</classname> + + + org.hibernate.type.LocaleType + + + Maps a java.util.Locale to a JDBC VARCHAR (using the Locale code) + + + Registered under locale= and java.util.Locale in the + type registry (see ). + + + + +
+
+ <classname>java.util.TimeZone</classname> + + + org.hibernate.type.TimeZoneType + + + Maps a java.util.TimeZone to a JDBC VARCHAR (using the TimeZone ID) + + + Registered under timezone and java.util.TimeZone in the + type registry (see ). + + + + +
+
+ <classname>java.lang.Class</classname> + + + org.hibernate.type.ClassType + + + Maps a java.lang.Class to a JDBC VARCHAR (using the Class name) + + + Registered under class = and java.lang.Class in the + type registry (see ). + + + + +
+
+ <classname>java.sql.Blob</classname> + + + org.hibernate.type.BlobType + + + Maps a java.sql.Blob to a JDBC BLOB + + + Registered under blob a= nd java.sql.Blob in the + type registry (see ). + + + + +
+
+ <classname>java.sql.Clob</classname> + + + org.hibernate.type.ClobType + + + Maps a java.sql.Clob to a JDBC CLOB + + + Registered under clob a= nd java.sql.Clob in the + type registry (see ). + + + + +
+
+ byte[] + + + org.hibernate.type.BinaryType + + + Maps a primitive byte[] to a JDBC VARBINARY + + + Registered under binary= and byte[] in the + type registry (see ). + + + + + org.hibernate.type.MaterializedBl= obType + + + Maps a primitive byte[] to a JDBC BLOB + + + Registered under materialized_blo= b in the type registry (see + ). + + + + +
+
+ byte[] + + + org.hibernate.type.BinaryType + + + Maps a java.lang.Byte[] to a JDBC VARBINARY + + + Registered under wrapper-binary, Byte[] and + java.lang.Byte[] in the= type registry (see ). + + + + +
+
+ char[] + + + org.hibernate.type.CharArrayType<= /classname> + + + Maps a char[] to a JDBC VARCHAR + + + Registered under characters and char[] + in the type registry (see ). + + + + +
+
+ char[] + + + org.hibernate.type.CharacterArray= Type + + + Maps a java.lang.Character[] to a JDBC VAR= CHAR + + + Registered under wrapper-characte= rs, Character[] + and java.lang.Character[] in the type registry (see ). + + + + +
+
+ java.io.Serializable + + + org.hibernate.type.SerializableTy= pe + + + Maps implementors of java.lang.Serializabl= e to a JDBC VARBINARY + + + Unlike the other value types, there are mu= ltiple instances of this type. It + gets registered once under java.i= o.Serializable. Additionally it + gets registered under the specific java.io.Serializable + implementation class names. + + + + +
+
+ +
+ Composite types + + + The Java Persistence API calls these embedded types, w= hile Hibernate traditionally called them + components. Just be aware that both terms are used an= d mean the same thing in the scope of + discussing Hibernate. + + + + Components represent aggregations of values into a single = Java type. For example, you might have + an Address class that aggregates street, city, state, etc = information or a Name class that + aggregates the parts of a person's Name. In many ways a c= omponent looks exactly like an entity. They + are both (generally speaking) classes written specifically= for the application. They both might have + references to other application-specific classes, as well = as to collections and simple JDK types. As + discussed before, the only distinguishing factory is the f= act that a component does not own its own + lifecycle. + +
+ +
+ Collection types + + + It is critical understand that we mean the collection = itself, not its contents. + The contents of the collection can in turn be basic, c= omponent or entity types (though not + collections), but the collection itself is owned. + + + + Collections are covered in . + +
+ +
+ +
+ Entity types + + The definition of entities is covered in detail in . For the purpose of + this discussion, it is enough to say that entities are (genera= lly application-specific) classes which + correlate to rows in a table. Specifically they correlate to = the row by means of a unique identifier. + Because of this unique identifier, entities exist independentl= y and define their own lifecycle. As an example, + when we delete a Membership, both the <= classname>User and + Group entities remain. + + + This notion of entity independence can be modified by = the application developer using the concept of + cascades. Cascades allow certain operations to contin= ue (or "cascade") across an association from + one entity to another. Cascades are covered in detail= in . + + + +
+ +
+ Significance of type categories + + Why do we spend so much time categorizing the various types of= types? What is the significance of the + distinction? + + + The main categorization was between entity types and value typ= es. To review we said that entities, by + nature of their unique identifier, exist independently of othe= r objects whereas values do not. An + application cannot "delete" a Product sku; instead, the sku is= removed when the Product itself is + deleted (obviously you can update the sku= of that Product to null to maker it + "go away", but even there the access is done through the Produ= ct). + + + Nor can you define an association to that= Product sku. You can + define an association to Product based on= its sku, assuming sku is unique but that + is totally different. + + + entity types define + data that maintains its own lifecycle, while value types defin= e data that only exists dependently. Essentially it defines it own unique = identifier. In turn that means + that it can be used to share references to that data from othe= r entities (or components or collections). + This dependence/independence has a few important ramifications: + + + + First, entities can be looked up and referenced (a= s in foreign keys). The same is not true of + a value type. For example, a Product entity can be looked up by its + unique identifier. The sku of that Product + + + + +
+ +
+ Custom types + + Hibernate makes it relatively easy for developers to create th= eir own value types. For + example, you might want to persist properties of type java.lang.BigInteger to + VARCHAR columns. Custom types are not limi= ted to mapping values to a single table + column. So, for example, you might want to concatenate togeth= er FIRST_NAME, + INITIAL and SURNAME colu= msn into a java,lang.String. + + + + There are 3 approaches to developing a custom Hibernate type. = As a means of illustrating the different + approaches, lets consider a use case where we need to compose = a java.math.BigDecimal + and java.util.Currency together into a = custom Money class. + + +
+ Custom types using <interfacename>org.hibernate.type.Ty= pe</interfacename> + + The first approach is to directly implement the org.hibernate.type.Type + interface (or one of its derivatives). Probably, you will= be more interested in the more specific + org.hibernate.type.BasicType contract which would allow registration of + the type (see ). The be= nefit of this registration is that whenever + the metadata for a particular property does not specify th= e Hibernate type to use, Hibernate will + consult the registry for the exposed property type. In ou= r example, the property type would be + Money, which is the key we would us= e to register our type in the registry: + + Defining and registering the custom Type + + + Configuration cfg =3D new Configuration(); + cfg.registerTypeOverride( new MoneyType() ); + cfg...; + + + + + It is important that we registered the type before adding mappings. + + + +
+ +
+ Custom types using <interfacename>org.hibernate.usertyp= e.UserType</interfacename> + + + Both org.hibernate.usertype.UserType and + org.hibernate.usertype.CompositeUserTyp= e were originally + added to isolate user code from internal changes to th= e org.hibernate.type.Type + interfaces. + + + + The second approach is the use the org.hibe= rnate.usertype.UserType + interface, which presents a somewhat simplified view of th= e org.hibernate.type.Type + interface. Using a org.hibernate.usertype.= UserType, our + Money custom type would look as fol= lows: + + + Defining the custom UserType + + + + There is not much difference between the or= g.hibernate.type.Type example + and the org.hibernate.usertype.UserType example, but that is only because + of the snippets shown. If you choose the o= rg.hibernate.type.Type approach + there are quite a few more methods you would need to imple= ment as compared to the + org.hibernate.usertype.UserType. + +
+ +
+ Custom types using <interfacename>org.hibernate.usertyp= e.CompositeUserType</interfacename> + + The third and final approach is the use the org.hibernate.usertype.CompositeUserType + interface, which differs from org.hibernate= .usertype.UserType in that it + gives us the ability to provide Hibernate the information = to handle the composition within the + Money class (specifically the 2 att= ributes). THis would give us the capability, + for example, to reference the amount at= tribute in an HQL query. Using a + org.hibernate.usertype.UserType, our Money custom + type would look as follows: + + + + Defining the custom CompositeUserType + + +
+ +
+ +
+ Type registry + + Internally Hibernate uses a registry of basic types (see ) when + it needs to resolve the specific org.hibernate.= type.Type to use in certain + situations. It also provides a way for applications to add ex= tra basic type registrations as well as + override the standard basic type registrations. + + + To register a new type or to override an existing type registr= ation, applications would make use of the + registerTypeOverride method of the org.hibernate.cfg.Configuration + class when bootstrapping Hibernate. For example, lets say you= want Hibernate to use your custom + SuperDuperStringType; during bootstrap = you would call: + + Overriding the standard <classname>StringType</clas= sname> + + + + + The argument to registerTypeOverride = is a org.hibernate.type.BasicType + which is a specialization of the org.hibernate.= type.Type we saw before. It + adds a single method: + + Snippet from BasicType.java + + /** + * Get the names under which this type should be registered in the type r= egistry. + * + * @return The keys under which to register this type. + */ + public String[] getRegistrationKeys(); + + + One approach is to use inheritance (SuperDuperStrin= gType extends = + org.hibernate.typeStringType). Another= approach is to use delegation. + + + + Currently UserType and CompositeUserType cannot be registe= red with the registry. See + for details. + + +
+ + --===============3190483948387845125==--