@@ -193,7 +193,13 @@ class Author { \begin_layout Plain Layout - @OneToMany(){val mappedBy = "author", val targetEntity = classOf[Book]} + @OneToMany(){val mappedBy = "author", val targetEntity = classOf[Book], + +\end_layout + +\begin_layout Plain Layout + + val cascade = Array(CascadeType.REMOVE)} \end_layout \begin_layout Plain Layout apdx-code_listings.lyx @@ -110,8 +110,8 @@ JPA for short, is the evolution of a number of frameworks in Java to provide a simple database access layer for plain java objects (and, transitively, Scala objects). - JPA was developed as part of the EJB3 specification, with the goal of simplifyi -ng the persistence model. + JPA was developed as part of the Enterprise Java Beans 3 (EJB3) specification, + with the goal of simplifying the persistence model. Prior versions had used the Container Managed Persistence (CMP \begin_inset Index status collapsed @@ -124,8 +124,8 @@ CMP ) framework, which required many boilerplate artifacts in the form of interfaces and XML descriptors. - As part of the overarching theme of EJB3 to simplify and use configuration - by convention, JPA uses sensible defaults and annotations + As part of the overarching theme of EJB3 to simplify and use convention + over configuration, JPA uses sensible defaults and annotations \begin_inset Index status collapsed @@ -139,7 +139,7 @@ annotations JPA also does away with many of the interfaces used in CMP and provides a single \family typewriter -EntityManager +javax.persistence.EntityManager \family default \begin_inset Index @@ -151,7 +151,7 @@ EntityManager \end_inset - object for all persistence operations. + class for all persistence operations. An additional benefit is that JPA was designed so that it could be used both inside and outside of the Enterprise container, and several projects (Hibernate @@ -229,7 +229,7 @@ accessed objects in memory so that you avoid hitting the database entirely \end_layout \begin_layout Section -Introduction to JPA +Introducing JPA \end_layout \begin_layout Standard @@ -361,8 +361,47 @@ mvn archetype:generate \begin_layout Standard This will use the JPA archetype to create a new project for you with modules for the persistence and web portions of the project. - You will get a prompt asking you to confirm the settings we've chosen; - just hit +\end_layout + +\begin_layout Standard +\align center +\begin_inset Box Shadowbox +position "t" +hor_pos "c" +has_inner_box 1 +inner_pos "t" +use_parbox 0 +width "75col%" +special "none" +height "1in" +height_special "totalheight" +status open + +\begin_layout Plain Layout +Note: The reason we have split the module out into two projects is that + it aids deployment on Jave EE servers to have the Persistence module be + an independent JAR file. + If you don't need that, you can simply merge the contents of the two modules + into a single project and it will work standalone. + Note that you'll need to merge the pom.xml file's dependencies and plugin + configurations from all three POMs. + Lift comes with an archetype that handles this already, albeit without + the demo code we show here. + Simply use the lift-archetype-jpa-blank-single archetype and you'll get + a blank project (with minimal files for JPA and Lift) that you can use + for your app. + There's also a blank archetype that uses two modules if you want that, + called lift-archetype-jpa-blank. +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +You will get a prompt asking you to confirm the settings we've chosen; just + hit \family typewriter <enter> \family default @@ -413,47 +452,15 @@ JPADemo \begin_layout Standard If you look at the source directories, you'll see that our code is already - in place! If you were making your own application you could modify the - POMs and create/edit/replace the existing Scala code and templates to match + in place! If you're making your own application you can either use the + previously mentioned blank archetypes to start from scratch, or use the + basic archetype and modify the POMs, Scala code and templates to match your needs. - -\end_layout - -\begin_layout Standard -\align center -\begin_inset Box Shadowbox -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -width "75col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout -Note: The reason we have split the module out into two projects is that - it aids deployment on Jave EE servers to have the Persistence module be - an independent JAR file. - If you don't need that, you can simply merge the contents of the two modules - into a single project and it will work standalone. - Note that you'll need to merge the pom.xml file's dependencies and plugin - configurations from all three POMs. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -Now let's go over the contents of the project. + For now, let's go over the contents of the project. \end_layout \begin_layout Subsection -Entity Classes +Using Entity Classes \begin_inset Index status collapsed @@ -702,7 +709,14 @@ Author override \end_layout \begin_layout Subsection -Object attachment and detachment +Working with Attached and Detached Objects +\begin_inset CommandInset label +LatexCommand label +name "sub:Working-with-Attached" + +\end_inset + + \end_layout \begin_layout Standard @@ -735,7 +749,10 @@ getReference find \family default method. - As soon as the session ends, any formerly attached objects are now considered +\end_layout + +\begin_layout Standard +As soon as the session ends, any formerly attached objects are now considered detached. You can still operate on them as normal objects but any changes are not directly applied to the database. @@ -752,422 +769,228 @@ merge then make modifications and merge in a different cycle. \end_layout -\begin_layout Subsection -Support for user types -\end_layout - \begin_layout Standard -JPA can handle any Java primitive type, their corresponding Object versions - (java.lang.Long, java.lang.Integer, etc), and any entity classes comprised - of these types -\begin_inset Foot -status collapsed - -\begin_layout Plain Layout -It can technically handle more; see the JPA spec, section 2.1.1 for details -\end_layout - -\end_inset - -. - Occasionally, though, you may have a requirement for a type that doesn't - fit directly with those specifications. - One example in particular would be Scala's enumerations -\begin_inset Index -status collapsed - -\begin_layout Plain Layout -enumerations -\end_layout - -\end_inset - -. - Unfortunately, the JPA spec currently doesn't have a means to handle this - directly, although the various JPA providers such as Toplink and Hibernate - provide mechanisms for resolving custom user types. - JPA does provide direct support for -\emph on -Java -\emph default - enumerations, but that doesn't help us here since Scala enumerations aren't - an extension of Java enumerations. - In this example, we'll be using Hibernate's +As an example, our library application provides a summary listing of authors + on one page ( \family typewriter -UserType +src/main/webapp/authors/list.html \family default - to support an enumeration for the +) and allows editing of those entities on another ( \family typewriter -Genre +src/main/webapp/authors/add.html \family default - of a +). + We can use the \family typewriter -Book +SHtml.link \family default -. -\end_layout - -\begin_layout Standard -We begin by implementing a few helper classes besides the Genre enumeration - itself. - First, we define an + generator on our list page, combined with a \family typewriter -Enumv +RequestVar \family default - trait, shown in listing +, to pass the instance (detached once we return from the list snippet) to + our edit snippet. + Listing \begin_inset CommandInset ref -LatexCommand vref -reference "lst:Enumv-Trait" +LatexCommand ref +reference "lst:Passing-Detached-Instances" \end_inset -. - Its main purpose is to provide a + shows excerpts from our library application snippets demonstrating how + we hand off the instance and do a merge within our edit snippets submission + processing function ( \family typewriter -valueOf +doAdd \family default - method that we can use to resolve the enumerations database value to the - actual enumeration. - We also add some extra methods so that we can encapsulate a description - along with the database value. - Scala enumerations can use either -\family typewriter -Ints -\family default - or -\family typewriter -Strings -\family default - for the identity of the enumeration value (unique to each val), and in - this case we've chosen -\family typewriter -Strings -\family default -. - By adding a map for the description (since Scala enumeration values must - extend the -\family typewriter -Enumeration#Value -\family default - class and therefore can't carry the additional string) we allow for the - additional info. - We could extend this concept to make the -\family typewriter -Map -\family default - carry additional data, but for our purposes this is sufficient. - +). \end_layout \begin_layout Standard -In order to actually convert the -\family typewriter -Enumeration -\family default - class into the proper database type ( -\family typewriter -String -\family default -, -\family typewriter -Int -\family default -, etc), we need to implement the Hibernate -\family typewriter -UserType -\family default - interface, shown in listing -\begin_inset CommandInset ref -LatexCommand vref -reference "lst:EnumvType" +\begin_inset listings +inline false +status open -\end_inset +\begin_layout Plain Layout + +\begin_inset Caption + +\begin_layout Plain Layout + +Passing Detached Instances Around an Application +\begin_inset CommandInset label +LatexCommand label +name "lst:Passing-Detached-Instances" -. - We can see on line 18 that we will be using a -\family typewriter -varchar -\family default - column for the enumeration value. - Since this is based on the Scala -\family typewriter -Enumeration -\family default -'s -\family typewriter -Value -\family default - method, we could technically use either -\family typewriter -Integer -\family default - or character types here. - We override the -\family typewriter -sqlTypes -\family default - and -\family typewriter -returnedClass -\family default - methods to match our preferred type, and set the -\family typewriter -equals -\family default - and -\family typewriter -hashCode -\family default - methods accordingly. - Note that in Scala, the -\begin_inset Quotes eld \end_inset -== -\begin_inset Quotes erd + +\end_layout + \end_inset - operator on objects delegates to the -\family typewriter -equals -\family default - method, so we're not testing reference equality here. - The actual resolution of database column value to -\family typewriter -Enumeration -\family default - is done in the -\family typewriter -nullSafeGet -\family default - method; if we decided, for instance, that the null value should be returned - as unknown, we could do this here with some minor modifications to the - -\family typewriter -Enumv -\family default - class (defining the unknown value, for one).The rest of the methods are - set appropriately for an immutable object ( -\family typewriter -Enumeration -\family default -). - The great thing about the -\family typewriter -EnumvType -\family default - class, is that it can easily be used for a variety of types due to the + +\end_layout + +\begin_layout Plain Layout + +// in src/main/scala/net/liftweb/jpademo/snippets/Author.scala +\end_layout + +\begin_layout Plain Layout + +...package and imports ... -\begin_inset Quotes eld -\end_inset +\end_layout -et -\begin_inset Quotes erd -\end_inset +\begin_layout Plain Layout - constructor argument; as long as we mix in the -\family typewriter -Enumv -\family default - trait to our -\family typewriter -Enumeration -\family default - objects, we get persistence essentially for free. - If we determined instead that we want to use -\family typewriter -Integer -\family default - enumeration IDs, we need to make minor modifications to the -\family typewriter -EnumvType -\family default - to make sure arguments match and we're set. +class AuthorOps { \end_layout -\begin_layout Standard -\begin_inset listings -lstparams "breaklines=true,firstline=3,float,numbers=left,numberstyle={\tiny}" -inline false -status open +\begin_layout Plain Layout + + def list (xhtml : NodeSeq) : NodeSeq = { +\end_layout \begin_layout Plain Layout -\begin_inset Caption + val authors = ... +\end_layout \begin_layout Plain Layout -\begin_inset CommandInset label -LatexCommand label -name "lst:Genre-and-GenreType" -\end_inset + authors.flatMap(author => bind("author", xhtml, ... +\end_layout -Genre and GenreType +\begin_layout Plain Layout + + // use the link closure to capture the current \end_layout -\end_inset +\begin_layout Plain Layout -package com.foo.jpaweb.model + // instance for edit insertion \end_layout \begin_layout Plain Layout + "edit" -> SHtml.link("add.html", \end_layout \begin_layout Plain Layout -object Genre extends Enumeration with Enumv { + () => authorVar(author), Text(?("Edit"))))) \end_layout \begin_layout Plain Layout - val Mystery = Value("Mystery", "Mystery") + } \end_layout \begin_layout Plain Layout - val Science = Value("Science", "Science") + ... \end_layout \begin_layout Plain Layout - val Theater = Value("Theater", "Drama literature") + // Set up a requestVar to track the author object for edits and adds \end_layout \begin_layout Plain Layout - // more values here... + object authorVar extends RequestVar(new Author()) \end_layout \begin_layout Plain Layout -} + // helper def \end_layout \begin_layout Plain Layout + def author = authorVar.is \end_layout \begin_layout Plain Layout -class GenreType extends EnumvType(Genre) {} + def add (xhtml : NodeSeq) : NodeSeq = { \end_layout -\end_inset +\begin_layout Plain Layout + + def doAdd () = { +\end_layout +\begin_layout Plain Layout + ... \end_layout -\begin_layout Standard -Finally, the -\family typewriter -Genre -\family default - object and the associated -\family typewriter -GenreType -\family default - is shown in listing -\begin_inset CommandInset ref -LatexCommand ref -reference "lst:Genre-and-GenreType" +\begin_layout Plain Layout -\end_inset + // merge and save the detached instance +\end_layout -. - You can see that we create a singleton -\family typewriter -Genre -\family default - object with specific member values for each enumeration value. - The -\family typewriter -GenreType -\family default - class is trivial now that we have the -\family typewriter -EnumvType -\family default - class defined. - To use the -\family typewriter -Genre -\family default - type in our entity classes, we simply need to add the proper -\family typewriter -var -\family default - and annotate it with the -\family typewriter -@Type -\family default - annotation, as shown in listing -\begin_inset CommandInset ref -LatexCommand ref -reference "lst:Using-the-@Type" +\begin_layout Plain Layout -\end_inset + Model.mergeAndFlush(author) +\end_layout -. - We need to specify the type of the var due to the fact that the actual - enumeration values are of the type -\family typewriter -Enumeration.Val -\family default -, which doesn't match our -\family typewriter -valueOf -\family default - method in the -\family typewriter -Enumv -\family default - trait. - We also want to make sure we set the enumeration to some reasonable default; - in our example we have an -\emph on -unknown -\emph default - value to cover that case. +\begin_layout Plain Layout + + ... \end_layout -\begin_layout Standard -\begin_inset listings -lstparams "float" -inline false -status open +\begin_layout Plain Layout + + } +\end_layout \begin_layout Plain Layout -\begin_inset Caption + // Hold a val here so that the closure grabs it instead of the def +\end_layout \begin_layout Plain Layout -\begin_inset CommandInset label -LatexCommand label -name "lst:Using-the-@Type" -\end_inset + val current = author +\end_layout -Using the @Type annotation +\begin_layout Plain Layout + + // Use a hidden element to reinsert the instance on form submission \end_layout -\end_inset +\begin_layout Plain Layout - @Type{val `type` = "com.foo.jpaweb.model.GenreType"} + bind("author", xhtml, \end_layout \begin_layout Plain Layout - var genre : Genre.Value = Genre.unknown + "id" -> SHtml.hidden(() => authorVar(current)), ..., \end_layout -\end_inset +\begin_layout Plain Layout + + "submit" -> SHtml.submit(?("Save"), doAdd)) +\end_layout +\begin_layout Plain Layout + } \end_layout -\begin_layout Standard -Now that we have our objects defined, let's start using them. +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + \end_layout \begin_layout Section @@ -1193,7 +1016,7 @@ y when it comes to object lifecycle. What this means is that if we're working on a detached object and we attempt to access a collection contained in the instance, we're going to get an exception that the session that the object was loaded in is no longer live. - What we're really like to do is have some hooks into Lift's request cycle + What we'd really like to do is have some hooks into Lift's request cycle that allows us to set up a session when the request starts and properly close it down when the request ends. We still have to be careful with objects that have been passed into our @@ -1407,6 +1230,11 @@ Setting up an EntityManager via RequestVar \begin_layout Plain Layout +import _root_.org.scala_libs.jpa._ +\end_layout + +\begin_layout Plain Layout + object Model extends LocalEMF("jpaweb") with RequestVarEM \end_layout @@ -1427,8 +1255,8 @@ Model . \end_layout -\begin_layout Subsection -Transactions +\begin_layout Section +Handling Transactions \begin_inset Index status collapsed @@ -1463,7 +1291,8 @@ http://java.sun.com/developer/EJTechTips/2005/tt0125.html \end_inset - if you want to go into depth on how JTA or general transactions work. + if you want to go into depth on how the Java Transaction API (JTA) or general + transactions work. Essentially, a transaction is a set of operations that are performed atomically ; that is, they either all complete successfully or none of them do. The classic example is transferring funds between two bank accounts: you @@ -1488,6 +1317,15 @@ LocalEMF Similarly, JTA is what you use when you obtain your EM via JNDI. Technically it's also possible to use JTA with a locally managed EM, but that configuration is beyond the scope of this book. +\end_layout + +\begin_layout Standard +Generally, we would recommend using JTA where it’s free (i.e., when deploying + to a Java EE container) and using resource-local when you’re using a servlet + container such as Jetty or Tomcat. + If you will be accessing multiple databases or involving resources like + EJBs, it is much safer to use JTA so that you can utilize distributed transacti +ons. Choosing between the two is as simple as setting a property in your persistence. xml file (and changing the code to open and close the EM). Listing @@ -1569,7 +1407,11 @@ Setting the transaction type \begin_layout Standard You must make sure that your EM setup code matches what you have in your - persistence.xml. + +\family typewriter +persistence.xml +\family default +. Additionally, the database connection must match; with JTA, you \emph on must @@ -1640,9 +1482,9 @@ http://www.jpox.org/docs/1_2/persistence_unit.html If you'll be deploying into a JEE container, such as JBoss or GlassFish, then you get JTA support almost for free since JTA is part of the JEE spec. If you want to deploy your application on a lightweight container like - Jetty or Tomcat, the extra effort to set up JNDI and JTA in Jetty may or - may not exceed the effort involved in coding and testing your app. - + Jetty or Tomcat, we would recommend that you look into using an external + JTA coordinator such as JOTM, Atomikos, or JBoss Transaction Manager, since + embedding a JTA provider in your container is a nontrivial task. \end_layout \begin_layout Standard @@ -1843,7 +1685,7 @@ RequestVarEM Model \family default object. - The API ScalaDoc for + The API for \family typewriter ScalaEntityManager \family default @@ -1907,15 +1749,12 @@ name "sec:JPA-Examples" \end_inset -Examples and Tips +Operating on Entities \end_layout \begin_layout Standard -We find it helpful to solidify what we've discussed here with some concrete - examples. - We'll also cover some useful information that should help you when using - JPA from within Lift. - Let's start with some basic operations +In this section we'll demonstrate how to work with entities and cover some + important tips on using JPA effectively. \end_layout \begin_layout Subsection @@ -1925,7 +1764,7 @@ name "sub:Persisting,-merging-and-removing" \end_inset -Persisting, merging and removing +Persisting, Merging and Removing Entities \end_layout \begin_layout Standard @@ -1939,11 +1778,19 @@ persist \end_layout \begin_layout LyX-Code +val myNewAuthor = new Author; myNewAuthor.name = "Wilma" +\end_layout + +\begin_layout LyX-Code Model.persist(myNewAuthor) \end_layout \begin_layout Standard -This attaches the myNewAuthor object to the current persistence session. +This attaches the +\family typewriter +myNewAuthor +\family default + object to the current persistence session. Once the object is attached it should be visible in any subsequent queries, although it may not be written to the database just yet (see section \begin_inset CommandInset ref @@ -1953,11 +1800,25 @@ reference "sub:The-importance-of-flush" \end_inset ). - Note that the persist method is only intended for brand new objects. - If you have a detached object and you try to use persist you will most - likely get an EntityExistsException as the instance you're merging is technical -ly conflicting with itself. - Instead, you want to use the merge method to re-attach detached objects: + Note that the +\family typewriter +persist +\family default + method is only intended for brand new objects. + If you have a detached object and you try to use +\family typewriter +persist +\family default + you will most likely get an +\family typewriter +EntityExistsException +\family default + as the instance you're merging is technically conflicting with itself. + Instead, you want to use the +\family typewriter +merge +\family default + method to re-attach detached objects: \end_layout \begin_layout LyX-Code @@ -1965,8 +1826,12 @@ val author = Model.merge(myOldAuthor) \end_layout \begin_layout Standard -An important thing to note is that the merge method doesn't actually attach - the object passed to it; instead, it makes an attached +An important thing to note is that the +\family typewriter +merge +\family default + method doesn't actually attach the object passed to it; instead, it makes + an attached \emph on copy \emph default @@ -1993,14 +1858,32 @@ Fred \begin_layout Standard you'll find that subsequent changes to the object won't be written to the database. - One nice aspect of the merge method is that it intelligently detects whether - the entity you're merging is a new object or a detached object. - That means that you can use merge everywhere and let it sort out the semantics. - For example, in our library application, using merge allows us to combine - the add and edit functionality into a single snippet; if we want to edit - an existing Author we pass it into the method. - Otherwise, we pass a brand new Author instance into the method and the - merge takes care of either case appropriately. + One nice aspect of the +\family typewriter +merge +\family default + method is that it intelligently detects whether the entity you're merging + is a new object or a detached object. + That means that you can use +\family typewriter +merge +\family default + everywhere and let it sort out the semantics. + For example, in our library application, using +\family typewriter +merge +\family default + allows us to combine the adding and editing functionality into a single + snippet; if we want to edit an existing +\family typewriter +Author +\family default + we pass it into the method. + Otherwise, we pass a brand new +\family typewriter +Author +\family default + instance into the method and the merge takes care of either case appropriately. \end_layout \begin_layout Standard @@ -2020,7 +1903,11 @@ The passed entity is detached from the session immediately and will be removed from the database at the appropriate time. If the entity has any associations on it (to collections or other entities), they will be cascaded as indicated by the entity mapping. - An example of a cascade is shown in the Author listing on page + An example of a cascade is shown in the +\family typewriter +Author +\family default + listing on page \begin_inset CommandInset ref LatexCommand pageref reference "lst:Author.scala" @@ -2053,7 +1940,16 @@ Loading an Entity \end_layout \begin_layout Standard -There are actually three ways to load an entity object in your client code. +There are actually three ways to load an entity object in your client code: + using +\family typewriter +find +\family default +, +\family typewriter +getReference +\family default + or a query. The simplest is to use the \family typewriter find @@ -2083,14 +1979,35 @@ find \family default method takes two parameters: the class that you're trying to load and the value of the ID field of the entity. - In our example, the Book class uses the Long type for its ID, so we would - put a Long value here. + In our example, the +\family typewriter +Book +\family default + class uses the +\family typewriter +Long +\family default + type for its ID, so we would put a +\family typewriter +Long +\family default + value here. It returns either a \family typewriter Full \family default - Box (section ???) if the entity is found in the database, otherwise it - returns + +\family typewriter +Box +\family default + (section +\begin_inset CommandInset ref +LatexCommand vref +reference "sec:Box-(or-Scala's" + +\end_inset + +) if the entity is found in the database, otherwise it returns \family typewriter Empty \family default @@ -2101,7 +2018,11 @@ find \family default , the entity is loaded immediately from the database and can be used in both attached and detached states. - The next method you can use is the + +\end_layout + +\begin_layout Standard +The next method you can use is the \family typewriter getReference \family default @@ -2125,9 +2046,12 @@ find Because this is a lazy proxy, you usually don't want to use the returned object in a detached state unless you've accessed its fields while the session was open. - The normal use of getReference is when you want to set up a relationship - between two (or more) entities, since you don't need to query all of the - fields just to set a foreign key. + The normal use of +\family typewriter +getReference +\family default + is when you want to set up a relationship between two (or more) entities, + since you don't need to query all of the fields just to set a foreign key. For example: \end_layout @@ -2136,22 +2060,36 @@ myBook.author = Model.getReference(classOf[Author], authorId) \end_layout \begin_layout Standard -When myBook is flushed to the database the EM will correctly set up the - relationship. +When +\family typewriter +myBook +\family default + is flushed to the database the EM will correctly set up the relationship. The final difference is in how unknown entities are handled. Recall that the \family typewriter find \family default - method returns Empty if the entity cannot be found; with + method returns +\family typewriter +Empty +\family default + if the entity cannot be found; with \family typewriter getReference \family default , however, we don't query the database until the reference is used. - Because of this, the javax.persistence.EntityNotFoundException is thrown - when you try to access an undefined entity for the first time (this also - marks the transaction for rollback). - The third method for loading an entity would be to use a query (named or + Because of this, the +\family typewriter +javax.persistence.EntityNotFoundException +\family default + is thrown when you try to access an undefined entity for the first time + (this also marks the transaction for rollback). + +\end_layout + +\begin_layout Standard +The third method for loading an entity would be to use a query (named or otherwise) to fetch the entity. As an example, here's a query equivalent of the \family typewriter @@ -2165,35 +2103,22 @@ val myBook = \end_layout \begin_layout LyX-Code - Model.createQuery[Book]( -\begin_inset Quotes eld -\end_inset - -from Book bk where bk.id = :id -\begin_inset Quotes erd -\end_inset - -) + Model.createQuery[Book]("from Book bk where bk.id = :id") \end_layout \begin_layout LyX-Code - .setParams( -\begin_inset Quotes eld -\end_inset - -id -\begin_inset Quotes erd -\end_inset - - -> someId).findOne + .setParams("id" -> someId).findOne \end_layout \begin_layout Standard The advantage here is that we have more control over what is selected by using the query language to specify other properties. - One caveat is that when you use the findOne method you need to ensure that - the query will actually result in a unique entity; otherwise, the EM will - throw a + One caveat is that when you use the +\family typewriter +findOne +\family default + method you need to ensure that the query will actually result in a unique + entity; otherwise, the EM will throw a \family typewriter NonUniqueResultException \family default @@ -2201,34 +2126,36 @@ NonUniqueResultException \end_layout \begin_layout Subsection -Loading many entities +Loading Many Entities \end_layout \begin_layout Standard -Corresponding to the findOne method is the findAll method, which returns - all entities based on a query. - There are two ways to use findAll; the first is to use the convenience - findAll method defined in the ScalaEntityManager class: +Corresponding to the +\family typewriter +findOne +\family default + method is the +\family typewriter +findAll +\family default + method, which returns all entities based on a query. + There are two ways to use +\family typewriter +findAll +\family default +; the first is to use the convenience +\family typewriter +findAll +\family default + method defined in the +\family typewriter +ScalaEntityManager +\family default + class: \end_layout \begin_layout LyX-Code -val myBooks = Model.findAll( -\begin_inset Quotes eld -\end_inset - -booksByYear -\begin_inset Quotes erd -\end_inset - -, -\begin_inset Quotes eld -\end_inset - -year -\begin_inset Quotes erd -\end_inset - - -> myYear) +val myBooks = Model.findAll("booksByYear", "year" -> myYear) \end_layout \begin_layout Standard @@ -2279,11 +2206,21 @@ reference "sub:Using-the-orm.xml" \end_layout \begin_layout Standard -The second method is to create a ScalaQuery instance directly and then set - parameters and execute it. - In reality this is exactly what the Model.findAll method is doing. - The advantage here is that with the ScalaQuery instance you can do things - like set hinting, paging, etc. +The second method is to create a +\family typewriter +ScalaQuery +\family default + instance directly and then set parameters and execute it. + In reality this is exactly what the +\family typewriter +Model.findAll +\family default + method is doing. + The advantage here is that with the +\family typewriter +ScalaQuery +\family default + instance you can do things like set hinting, paging, and so on. For instance, if you wanted to do paging on the books query, you could do \end_layout @@ -2321,7 +2258,7 @@ year \end_layout \begin_layout Subsection -Tips for using queries +Using Queries Wisely \end_layout \begin_layout Standard @@ -2333,6 +2270,16 @@ In general we recommend that you use named queries throughout your code. Named parameters are just that: parameters that are inserted into your query by name, in contrast to positional parameters. As an example, here is the same query using named and positional parameters: +\begin_inset Note Note +status open + +\begin_layout Plain Layout +Split this into listings +\end_layout + +\end_inset + + \end_layout \begin_layout List @@ -2360,8 +2307,8 @@ s > ? \end_layout \begin_layout Standard -From this example we can show several advantages of named params over positional - params +This example shows several advantages of named parameters over positional + parameters: \end_layout \begin_layout Enumerate @@ -2400,16 +2347,28 @@ http://www.hibernate.org/hib_docs/entitymanager/reference/en/html/queryhql.html \end_layout \begin_layout Subsection -Converting collection properties +Converting Collection Properties \end_layout \begin_layout Standard -The ScalaEntityManager and ScalaQuery methods are already defined so that - they return Scala-friendly collections such as +The +\family typewriter +ScalaEntityManager +\family default + and +\family typewriter +ScalaQuery +\family default + methods are already defined so that they return Scala-friendly collections + such as \family typewriter scala.collection.jcl.BufferWrapper \family default - or SetWrapper. + or +\family typewriter +SetWrapper +\family default +. We have to use Java Collections \begin_inset Foot status collapsed @@ -2442,8 +2401,11 @@ under the hood For the same reason, collections in your entity classes must also use the Java Collections classes. Fortunately, Scala has a very nice framework for wrapping Java collections. - In particular, the scala.collection.jcl.Conversions class contains a number - of implicit conversions + In particular, the +\family typewriter +scala.collection.jcl.Conversions +\family default + class contains a number of implicit conversions \begin_inset Index status collapsed @@ -2699,7 +2661,8 @@ ity that it provides beyond being a simple ORM, we felt that we should discuss \begin_layout Standard JPA itself doesn't come with a built-in validation framework, although the - upcoming JPA 2.0 may use the JSR 303 Bean Validation framework as its default. + upcoming JPA 2.0 may use the JSR 303 (Bean Validation) framework as its + default. Currently, Hibernate Validator is one of the more popular libraries for validating JPA entities, and can be used with any JPA provider. More information is available at the project home page: @@ -2985,11 +2948,425 @@ class AuthorOps { \end_layout \begin_layout Section -Running the App +Supporting User Types +\end_layout + +\begin_layout Standard +JPA can handle any Java primitive type, their corresponding Object versions + (java.lang.Long, java.lang.Integer, etc), and any entity classes comprised + of these types +\begin_inset Foot +status collapsed + +\begin_layout Plain Layout +It can technically handle more; see the JPA spec, section 2.1.1 for details +\end_layout + +\end_inset + +. + Occasionally, though, you may have a requirement for a type that doesn't + fit directly with those specifications. + One example in particular would be Scala's enumerations +\begin_inset Index +status collapsed + +\begin_layout Plain Layout +enumerations +\end_layout + +\end_inset + +. + Unfortunately, the JPA spec currently doesn't have a means to handle this + directly, although the various JPA providers such as Toplink and Hibernate + provide mechanisms for resolving custom user types. + JPA does provide direct support for +\emph on +Java +\emph default + enumerations, but that doesn't help us here since Scala enumerations aren't + an extension of Java enumerations. + In this example, we'll be using Hibernate's +\family typewriter +UserType +\family default + to support an enumeration for the +\family typewriter +Genre +\family default + of a +\family typewriter +Book +\family default +. +\end_layout + +\begin_layout Standard +We begin by implementing a few helper classes besides the Genre enumeration + itself. + First, we define an +\family typewriter +Enumv +\family default + trait, shown in listing +\begin_inset CommandInset ref +LatexCommand vref +reference "lst:Enumv-Trait" + +\end_inset + +. + Its main purpose is to provide a +\family typewriter +valueOf +\family default + method that we can use to resolve the enumerations database value to the + actual enumeration. + We also add some extra methods so that we can encapsulate a description + along with the database value. + Scala enumerations can use either +\family typewriter +Ints +\family default + or +\family typewriter +Strings +\family default + for the identity of the enumeration value (unique to each val), and in + this case we've chosen +\family typewriter +Strings +\family default +. + By adding a map for the description (since Scala enumeration values must + extend the +\family typewriter +Enumeration#Value +\family default + class and therefore can't carry the additional string) we allow for the + additional info. + We could extend this concept to make the +\family typewriter +Map +\family default + carry additional data, but for our purposes this is sufficient. + +\end_layout + +\begin_layout Standard +In order to actually convert the +\family typewriter +Enumeration +\family default + class into the proper database type ( +\family typewriter +String +\family default +, +\family typewriter +Int +\family default +, etc), we need to implement the Hibernate +\family typewriter +UserType +\family default + interface, shown in listing +\begin_inset CommandInset ref +LatexCommand vref +reference "lst:EnumvType" + +\end_inset + +. + We can see on line 18 that we will be using a +\family typewriter +varchar +\family default + column for the enumeration value. + Since this is based on the Scala +\family typewriter +Enumeration +\family default +'s +\family typewriter +Value +\family default + method, we could technically use either +\family typewriter +Integer +\family default + or character types here. + We override the +\family typewriter +sqlTypes +\family default + and +\family typewriter +returnedClass +\family default + methods to match our preferred type, and set the +\family typewriter +equals +\family default + and +\family typewriter +hashCode +\family default + methods accordingly. + Note that in Scala, the +\begin_inset Quotes eld +\end_inset + +== +\begin_inset Quotes erd +\end_inset + + operator on objects delegates to the +\family typewriter +equals +\family default + method, so we're not testing reference equality here. + The actual resolution of database column value to +\family typewriter +Enumeration +\family default + is done in the +\family typewriter +nullSafeGet +\family default + method; if we decided, for instance, that the null value should be returned + as unknown, we could do this here with some minor modifications to the + +\family typewriter +Enumv +\family default + class (defining the unknown value, for one).The rest of the methods are + set appropriately for an immutable object ( +\family typewriter +Enumeration +\family default +). + The great thing about the +\family typewriter +EnumvType +\family default + class, is that it can easily be used for a variety of types due to the + +\begin_inset Quotes eld +\end_inset + +et +\begin_inset Quotes erd +\end_inset + + constructor argument; as long as we mix in the +\family typewriter +Enumv +\family default + trait to our +\family typewriter +Enumeration +\family default + objects, we get persistence essentially for free. + If we determined instead that we want to use +\family typewriter +Integer +\family default + enumeration IDs, we need to make minor modifications to the +\family typewriter +EnumvType +\family default + to make sure arguments match and we're set. +\end_layout + +\begin_layout Standard +\begin_inset listings +lstparams "breaklines=true,firstline=3,float,numbers=left,numberstyle={\tiny}" +inline false +status open + +\begin_layout Plain Layout + +\begin_inset Caption + +\begin_layout Plain Layout +\begin_inset CommandInset label +LatexCommand label +name "lst:Genre-and-GenreType" + +\end_inset + +Genre and GenreType +\end_layout + +\end_inset + +package com.foo.jpaweb.model +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +object Genre extends Enumeration with Enumv { +\end_layout + +\begin_layout Plain Layout + + val Mystery = Value("Mystery", "Mystery") +\end_layout + +\begin_layout Plain Layout + + val Science = Value("Science", "Science") +\end_layout + +\begin_layout Plain Layout + + val Theater = Value("Theater", "Drama literature") +\end_layout + +\begin_layout Plain Layout + + // more values here... +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +class GenreType extends EnumvType(Genre) {} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +Finally, the +\family typewriter +Genre +\family default + object and the associated +\family typewriter +GenreType +\family default + is shown in listing +\begin_inset CommandInset ref +LatexCommand ref +reference "lst:Genre-and-GenreType" + +\end_inset + +. + You can see that we create a singleton +\family typewriter +Genre +\family default + object with specific member values for each enumeration value. + The +\family typewriter +GenreType +\family default + class is trivial now that we have the +\family typewriter +EnumvType +\family default + class defined. + To use the +\family typewriter +Genre +\family default + type in our entity classes, we simply need to add the proper +\family typewriter +var +\family default + and annotate it with the +\family typewriter +@Type +\family default + annotation, as shown in listing +\begin_inset CommandInset ref +LatexCommand ref +reference "lst:Using-the-@Type" + +\end_inset + +. + We need to specify the type of the var due to the fact that the actual + enumeration values are of the type +\family typewriter +Enumeration.Val +\family default +, which doesn't match our +\family typewriter +valueOf +\family default + method in the +\family typewriter +Enumv +\family default + trait. + We also want to make sure we set the enumeration to some reasonable default; + in our example we have an +\emph on +unknown +\emph default + value to cover that case. +\end_layout + +\begin_layout Standard +\begin_inset listings +lstparams "float" +inline false +status open + +\begin_layout Plain Layout + +\begin_inset Caption + +\begin_layout Plain Layout +\begin_inset CommandInset label +LatexCommand label +name "lst:Using-the-@Type" + +\end_inset + +Using the @Type annotation +\end_layout + +\end_inset + + @Type{val `type` = "com.foo.jpaweb.model.GenreType"} +\end_layout + +\begin_layout Plain Layout + + var genre : Genre.Value = Genre.unknown +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Section +Running the Application \end_layout \begin_layout Standard -We just want to make a quick note on how to run the application. +Now that we've gone over everything, it's time to run the application. Because we've split up the app into separate SPA and WEB modules, we need to first run \end_layout chap-JPA.lyx @@ -2976,7 +2976,7 @@ reference "sec:Cookies" This can be useful if you have data that you want persisted across sessions. The down side is that you have to manage the cookie as well as deal with any security implications for the data in the cookie since it's stored - on the user's machine + on the user's machine. \end_layout \begin_layout Itemize @@ -2992,14 +2992,43 @@ reference "sec:Session-and-Request" adding and removing the session data if you don't want it around for the duration of the session. Like a cookie, it's also global, which means that it will be the same for - all snippet instances + all snippet instances. +\end_layout + +\begin_layout Itemize +Pass the state around in a RequestVar by setting +\begin_inset Quotes eld +\end_inset + +injector +\begin_inset Quotes erd +\end_inset + + functions in your page transition functions (e.g. + +\family typewriter +SHtml.link +\family default +, +\family typewriter +S.redirectTo +\family default +, etc). + We'll cover this technique in section +\begin_inset CommandInset ref +LatexCommand ref +reference "sec:Session-and-Request" + +\end_inset + +. \end_layout \begin_layout Itemize Use a StatefulSnippet subclass. This is ideal for small, conversational state, such as a form that spans multiple pages or for a page where you have multiple variables that you - want to be able to tweak individually + want to be able to tweak individually. \end_layout \begin_layout Standard @@ -4470,7 +4499,7 @@ name "lst:Defining-a-RequestVar" \begin_layout Plain Layout -class Ledger { +class AccountOps { \end_layout \begin_layout Plain Layout @@ -4533,7 +4562,7 @@ name "lst:Accessing-the-RequestVar" \begin_layout Plain Layout -query.setMaxResults(Ledger.pageSize.is) +query.setMaxResults(AccountOps.pageSize.is) \end_layout \begin_layout Plain Layout @@ -4543,7 +4572,7 @@ query.setMaxResults(Ledger.pageSize.is) \begin_layout Plain Layout -Ledger.pageSize(50) +AccountOps.pageSize(50) \end_layout \end_inset @@ -4569,7 +4598,8 @@ reference "lst:Defining-a-Cleanup" you access it then you'll need to use the registerCleanupFunc instead. Also remember that you're responsible for handling any exceptions that might be thrown during either default initialization or cleanup. - + The information we've covered here is equally applicable to SessionVars; + the only difference between them is the scope of their respective lifecycles. \end_layout \begin_layout Standard @@ -4626,8 +4656,272 @@ localhost:23 \end_layout \begin_layout Standard -The inormation we've covered here is equally applicable to SessionVars; - the only difference between them is the scope of their respective lifecycles. +Another common use of RequestVar is to pass state around between different + page views (requests). + We start by defining a RequestVar on an object so that it's accesible from + all of the snippet methods that will read and write to it. + It's also possible to define it on a class if all of the snippets that + will access it are in that class. + Then, in the parts of your code that will transition to a new page you + use the overloaded versions of SHtml.link or S.redirectTo that take a function + as a second argument to +\begin_inset Quotes eld +\end_inset + +inject +\begin_inset Quotes erd +\end_inset + + the value you want to pass via the RequestVar. + This is similar to using a query parameter on the URL to pass data, but + there are two important advantages: +\end_layout + +\begin_layout Enumerate +You can pass any type of data via a RequestVar, as opposed to just string + data in a query parameter. +\end_layout + +\begin_layout Enumerate +You're really only passing a reference to the injector function, as opposed + to the data itself. + This can be important if you don't want the user to be able to tamper with + the passed data. + One example would be passing the cost of an item from a +\begin_inset Quotes eld +\end_inset + +view item +\begin_inset Quotes erd +\end_inset + + page to an +\begin_inset Quotes eld +\end_inset + +add to cart +\begin_inset Quotes erd +\end_inset + + page. +\end_layout + +\begin_layout Standard +Listing +\begin_inset CommandInset ref +LatexCommand ref +reference "lst:Passing-an-Account" + +\end_inset + + shows how we pass an Account from a listing table to a specific Account + edit page using +\family typewriter +SHtml.link +\family default +, as well as how we could transition from an edit page to a view page using + +\family typewriter +S.redirectTo +\family default +. + Another example of passing is shown in listing +\begin_inset CommandInset ref +LatexCommand vref +reference "lst:Passing-Detached-Instances" + +\end_inset + +. +\end_layout + +\begin_layout Standard +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +\begin_inset Caption + +\begin_layout Plain Layout + +Passing an Account to View +\begin_inset CommandInset label +LatexCommand label +name "lst:Passing-an-Account" + +\end_inset + + +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Plain Layout + +class AccountOps { +\end_layout + +\begin_layout Plain Layout + + ... +\end_layout + +\begin_layout Plain Layout + + object currentAccountVar extends RequestVar[Account](null) +\end_layout + +\begin_layout Plain Layout + + ... +\end_layout + +\begin_layout Plain Layout + + def manage (xhtml : NodeSeq) ... + { +\end_layout + +\begin_layout Plain Layout + + ... +\end_layout + +\begin_layout Plain Layout + + User.currentUser.map({user => +\end_layout + +\begin_layout Plain Layout + + user.accounts.flatMap({acct => +\end_layout + +\begin_layout Plain Layout + + bind("acct", chooseTemplate("account", "entry", xhtml), +\end_layout + +\begin_layout Plain Layout + + ... +\end_layout + +\begin_layout Plain Layout + + // The second argument injects the "acct" val back +\end_layout + +\begin_layout Plain Layout + + // into the RequestVar +\end_layout + +\begin_layout Plain Layout + + link("/editAcct", () => currentAccountVar(acct), Text("Edit")) +\end_layout + +\begin_layout Plain Layout + + }) +\end_layout + +\begin_layout Plain Layout + + }) +\end_layout + +\begin_layout Plain Layout + + ... +\end_layout + +\begin_layout Plain Layout + + } +\end_layout + +\begin_layout Plain Layout + + def edit (xhtml : NodeSeq) : NodeSeq = { +\end_layout + +\begin_layout Plain Layout + + def doSave () { +\end_layout + +\begin_layout Plain Layout + + ... +\end_layout + +\begin_layout Plain Layout + + val acct = currentAccountVar.is +\end_layout + +\begin_layout Plain Layout + + S.redirectTo("/view", () => currentAccountVar(acct)) +\end_layout + +\begin_layout Plain Layout + + } +\end_layout + +\begin_layout Plain Layout + + ... +\end_layout + +\begin_layout Plain Layout + + } +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +One important thing to note is that the injector variable is called in the + scope of the following request. + That means that if you want the value returned by the function at the point + where you call the link or redirectTo, you'll need to capture it in a val. + Otherwise, the function will be called after the redirect or link, which + may result in a different value than you expect. + As you can see in listing +\begin_inset CommandInset ref +LatexCommand ref +reference "lst:Passing-an-Account" + +\end_inset + +, we set up an acct val in our doSave method prior to redirecting. + If we tried to do something like +\end_layout + +\begin_layout LyX-Code +S.redirectTo("/view", () => currentAccountVar(currentAccountVar.is)) +\end_layout + +\begin_layout Standard +instead, we would get the default value of our RequestVar (null in this + case). \end_layout \begin_layout Section chap-lift_architecture.lyx 5d8a3e3fb536c3ed54f7ed6be09e30c5a6641e0f Derek Chen-Becker github@chen-becker.org http://github.com/tjweir/liftbook/commit/a7b95c510cd0680c77927b63d099e3fc1f04989f a7b95c510cd0680c77927b63d099e3fc1f04989f 2009-04-19T07:15:37-07:00 2009-04-19T07:15:37-07:00 Changes to fundamentals and JPA chapters based on community feedback and backports from the APress book. f13a5780bed44414d44c4cddf7f4aa1a8ea511e3 Derek Chen-Becker github@chen-becker.org