From 4e3dfdfd02f973cd90c1b6bff33f644cf34b0af9 Mon Sep 17 00:00:00 2001 From: Oliver Gierke Date: Wed, 16 May 2012 16:21:44 +0200 Subject: [PATCH] DATAJPA-211 - Documented CDI integration. Added brief section on how to use the CDI extension. Poslished documentation in general: updated copyright year, removed revision history, fixed links to Maven repositories, added missing section ids to create stable links, improved CSS for HTML rendering, improved PDF rendering. --- src/docbkx/index.xml | 17 +- src/docbkx/preface.xml | 6 +- src/docbkx/reference/jpa.xml | 90 ++++++-- src/docbkx/resources/css/html.css | 317 ++++++----------------------- src/docbkx/resources/xsl/fopdf.xsl | 7 +- 5 files changed, 135 insertions(+), 302 deletions(-) diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index b01bad45f..80c1fd0a9 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -33,24 +33,11 @@ - 2008-2011 + 2008-2012 The original authors - - - - 09.02.2011 - - - Oliver - - Gierke - - - Initial port from Hades documentation - - + diff --git a/src/docbkx/preface.xml b/src/docbkx/preface.xml index 3cffa1701..c626e09df 100644 --- a/src/docbkx/preface.xml +++ b/src/docbkx/preface.xml @@ -20,17 +20,17 @@ Release repository - http://maven.springframework.org/release + url="http://repo.springsource.org/libs-release">http://repo.springsource.org/libs-release Milestone repository - http://maven.springframework.org/milestone + url="http://repo.springsource.org/libs-milestone">http://repo.springsource.org/libs-milestone Snapshot repository - http://maven.springframework.org/snapshot + url="http://repo.springsource.org/libs-snapshot">http://repo.springsource.org/libs-snapshot diff --git a/src/docbkx/reference/jpa.xml b/src/docbkx/reference/jpa.xml index 25c503433..bbfb65264 100644 --- a/src/docbkx/reference/jpa.xml +++ b/src/docbkx/reference/jpa.xml @@ -39,7 +39,7 @@ Using this element looks up Spring Data repositories as described - in . Beyond that it + in . Beyond that it activates persistence exception translation for all beans annotated with @Repository to let exceptions being thrown by the JPA presistence providers be converted into Spring's @@ -111,10 +111,10 @@ name parser does not support the keyword one wants to use or the method name would get unnecessarily ugly. So you can either use JPA named queries through a naming convention (see for more information) or + linkend="jpa.query-methods.named-queries"/> for more information) or rather annotate your query method with @Query (see for details). + linkend="jpa.query-methods.at-query"/> for details). @@ -122,7 +122,7 @@ Query creation Generally the query creation mechanism for JPA works as described - in . Here's a short example + in . Here's a short example of what a JPA query method translates into: Query creation from method names @@ -136,7 +136,7 @@ Spring Data JPA will do a property check and traverse nested properties as described in . Here's + linkend="repositories.query-methods.property-expressions"/>. Here's an overview of the keywords supported for JPA and what a method containing that keyword essentially translates to. @@ -145,11 +145,11 @@ Supported keywords inside method names - + - + - + @@ -337,7 +337,7 @@ of Collection as parameter as well as arrays or varargs. For other syntactical versions of the very same logical operator check . + linkend="repository-query-keywords"/>. @@ -489,10 +489,10 @@ public class User { All the sections above describe how to declare queries to access a given entity or collection of entities. Of course you can add custom modifying behaviour by using facilities described in . As this approach is feasible for - comprehensive custom functionality, you can achieve the execution of - modifying queries that actually only need parameter binding by - annotating the query method with @Modifying: + linkend="repositories.custom-implementations"/>. As this approach is + feasible for comprehensive custom functionality, you can achieve the + execution of modifying queries that actually only need parameter binding + by annotating the query method with @Modifying: Declaring manipulating queries @@ -569,11 +569,8 @@ int setFixedFirstnameFor(String firstname, String lastname); The additional interface carries methods that allow you to execute Specifications in a variety of ways. - For example, the - - readAll - - method will return all entities that match the specification: + For example, the readAll method will return all + entities that match the specification: List<T> readAll(Specification<T> spec); @@ -779,8 +776,8 @@ public interface UserRepository extends JpaRepository<User, Long> { -
- Locking +
+ Locking To specify the lock mode to be used the @Lock annotation can be used on query @@ -915,7 +912,7 @@ public interface UserRepository extends JpaRepository<User, Long> {
Miscellaneous -
+
Merging persistence units Spring supports having multiple persistence units out of the box. @@ -936,7 +933,7 @@ public interface UserRepository extends JpaRepository<User, Long> {
-
+
Classpath scanning for @Entity classes and JPA mapping files @@ -975,5 +972,54 @@ public interface UserRepository extends JpaRepository<User, Long> { for details.
+ +
+ CDI integration + + Instances of the repository interfaces are usually created by a + container, which Spring is the most natural choice when working with + Spring Data. There's sophisticated support to easily set up Spring to + create bean instances documented in . As of version 1.1.0 Spring + Data JPA ships with a custom CDI extension that allows using the + repository abstraction in CDI environments. The extension is part of the + JAR so all you need to do to activate it is dropping the Spring Data JPA + JAR into your classpath. + + You can now set up the infrastructure by implementing a CDI + Producer for the + EntityManagerFactory: + + class EntityManagerFactoryProducer { + + @Produces + @ApplicationScoped + public EntityManagerFactory createEntityManagerFactory() { + return Persistence.createEntityManagerFactory("my-presistence-unit"); + } + + public void close(@Disposes EntityManagerFactory entityManagerFactory) { + entityManagerFactory.close(); + } +} + + The Spring Data JPA CDI extension will pick up all + EntityManagers availables as CDI beans + and create a proxy for a Spring Data repository whenever an bean of a + repository type is requested by the container. Thus obtaining an + instance of a Spring Data repository is a matter of declaring an + @Injected property: + + class RepositoryClient { + + @Inject + PersonRepository repository; + + public void businessMethod() { + + List<Person> people = repository.findAll(); + } +} +
diff --git a/src/docbkx/resources/css/html.css b/src/docbkx/resources/css/html.css index dd2ab6941..f3d48690f 100644 --- a/src/docbkx/resources/css/html.css +++ b/src/docbkx/resources/css/html.css @@ -1,246 +1,68 @@ @IMPORT url("highlight.css"); -body { - text-align: justify; - margin-right: 2em; - margin-left: 2em; -} - -a, -a[accesskey^="h"], -a[accesskey^="n"], -a[accesskey^="u"], -a[accesskey^="p"] { - font-family: Verdana, Arial, helvetica, sans-serif; - font-size: 12px; - color: #003399; +html { + padding: 0pt; + margin: 0pt; } -a:active { - color: #003399; +body { + margin-left: 15%; + margin-right: 15%; + font-family: "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif; } -a:visited { - color: #888888; +div { + margin: 0pt; } p { - font-family: Verdana, Arial, sans-serif; -} - -dt { - font-family: Verdana, Arial, sans-serif; - font-size: 12px; -} - -p, dl, dt, dd, blockquote { - color: #000000; - margin-bottom: 3px; - margin-top: 3px; - padding-top: 0; -} - -ol, ul, p { - margin-top: 6px; - margin-bottom: 6px; -} - -p, blockquote { - font-size: 90%; -} - -p.releaseinfo { - font-size: 100%; - font-weight: bold; - font-family: Verdana, Arial, helvetica, sans-serif; - padding-top: 10px; -} - -p.pubdate { - font-size: 120%; - font-weight: bold; - font-family: Verdana, Arial, helvetica, sans-serif; -} - -td { - font-size: 80%; -} - -td, th, span { - color: #000000; + text-align: justify; + line-height: 1.3em; } -td[width^="40%"] { - font-family: Verdana, Arial, helvetica, sans-serif; - font-size: 12px; - color: #003399; -} - -table[summary^="Navigation header"] tbody tr th[colspan^="3"] { - font-family: Verdana, Arial, helvetica, sans-serif; -} - -blockquote { - margin-right: 0; -} - -h1, h2, h3, h4, h6 { - color: #000000; - font-weight: 500; - margin-top: 0; - padding-top: 14px; - font-family: Verdana, Arial, helvetica, sans-serif; - margin-bottom: 0; -} - -h2.title { - font-weight: 800; - margin-bottom: 8px; -} - -h2.subtitle { - font-weight: 800; - margin-bottom: 20px; -} - -.firstname, .surname { - font-size: 12px; - font-family: Verdana, Arial, helvetica, sans-serif; -} - -table { - border-collapse: collapse; - border-spacing: 0; - border: 1px black; - empty-cells: hide; - margin: 10px 0 30px 50px; - width: 90%; -} - -div.table { - margin: 30px 0 10px 0; - border: 1px dashed gray; - padding: 10px; -} - -div .table-contents table { - border: 1px solid black; -} - -div.table > p.title { - padding-left: 10px; -} - -table[summary^="Navigation footer"] { - border-collapse: collapse; - border-spacing: 0; - border: 1px black; - empty-cells: hide; - margin: 0px; - width: 100%; -} - -table[summary^="Note"], -table[summary^="Warning"], -table[summary^="Tip"] { - border-collapse: collapse; - border-spacing: 0; - border: 1px black; - empty-cells: hide; - margin: 10px 0px 10px -20px; - width: 100%; -} - -td { - padding: 4pt; - font-family: Verdana, Arial, helvetica, sans-serif; -} - -div.warning TD { - text-align: justify; -} - -h1 { - font-size: 150%; -} - -h2 { - font-size: 110%; -} - -h3 { - font-size: 100%; font-weight: bold; -} - -h4 { - font-size: 90%; font-weight: bold; -} - -h5 { - font-size: 90%; font-style: italic; -} - -h6 { - font-size: 100%; font-style: italic; -} - -tt { - font-size: 110%; - font-family: "Courier New", Courier, monospace; - color: #000000; -} - -.navheader, .navfooter { - border: none; +hr { + border: 1px solid gray; + background: gray; } -div.navfooter table { - border-style: dashed; - border-color: gray; - border-width: 1px 1px 1px 1px; - background-color: #cde48d; +h1,h2,h3,h4,h5 { + color: #234623; + font-weight: "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif; + margin-bottom: 0em; + margin-top: 2em; } pre { - font-size: 110%; - padding: 5px; - border-style: solid; - border-width: 1px; - border-color: #CCCCCC; - background-color: #f3f5e9; + line-height: 1.0; + color: black; } -ul, ol, li { - list-style: disc; +table code { + font-size: 110%; } -hr { - width: 100%; - height: 1px; - background-color: #CCCCCC; - border-width: 0; - padding: 0; +pre.programlisting { + font-size: 1em; + padding: 3pt 3pt; + border: 1pt solid black; + background: #eeeeee; + clear: both; } -.variablelist { - padding-top: 10px; - padding-bottom: 10px; - margin: 0; -} - -.term { - font-weight:bold; +div.table { + margin: 1em; + padding: 0.5em; + text-align: center; } -.mediaobject { - padding-top: 30px; - padding-bottom: 30px; +div.table table { + display: table; + width: 100%; } -.legalnotice { - font-family: Verdana, Arial, helvetica, sans-serif; - font-size: 12px; - font-style: italic; +div.table td { + padding-left: 7px; + padding-right: 7px; } .sidebar { @@ -253,53 +75,36 @@ hr { font-size: 14px; } -.property { - font-family: "Courier New", Courier, monospace; -} - -a code { - font-family: Verdana, Arial, monospace; - font-size: 12px; -} - -td code { - font-size: 110%; -} - -div.note * td, -div.tip * td, -div.warning * td, -div.calloutlist * td { - text-align: justify; - font-size: 100%; -} - -.programlisting { - clear: both; +.mediaobject { + padding-top: 30px; + padding-bottom: 30px; } -.programlisting .interfacename, -.programlisting .literal, -.programlisting .classname { - font-size: 95%; +.legalnotice { + font-family: "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif; + font-size: 12px; + font-style: italic; } -.title .interfacename, -.title .literal, -.title .classname { - font-size: 130%; +p.releaseinfo { + font-size: 100%; + font-weight: bold; + font-family: "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif; + padding-top: 10px; } -/* everything in a is displayed in a coloured, comment-like font */ -.programlisting * .lineannotation, -.programlisting * .lineannotation * { - color: green; +p.pubdate { + font-size: 120%; + font-weight: bold; + font-family: "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif; } -.question * p { - font-size: 100%; +span.productname { + font-size: 200%; + font-weight: bold; + font-family: "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif; } -.answer * p { - font-size: 100%; +code { + font-size: 125%; } \ No newline at end of file diff --git a/src/docbkx/resources/xsl/fopdf.xsl b/src/docbkx/resources/xsl/fopdf.xsl index bc973f305..d05645d0b 100644 --- a/src/docbkx/resources/xsl/fopdf.xsl +++ b/src/docbkx/resources/xsl/fopdf.xsl @@ -23,11 +23,6 @@ - @@ -62,7 +57,7 @@ - Copyright © 2011 + Copyright © 2012