Spring/spring-data-commons
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DATACMNS-551 - Move to Asciidoctor for reference documentation.

Browse Source
This commit is contained in:
Oliver Gierke
2014-07-31 07:15:28 +02:00
parent 85157b6644
commit 62e66ab305
14 changed files with 1172 additions and 2102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
pom.xml
View File

@@ -234,6 +234,10 @@
<groupId>org.codehaus.mojo</groupId>
<artifactId>wagon-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
</plugin>
</plugins>
</build>

107
src/docbkx/auditing.xml
View File

@@ -1,107 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section id="auditing.basics">
<title>Basics</title>
<para>Spring Data provides sophisticated support to transparently keep track
of who created or changed an entity and the point in time this happened. To
benefit from that functionality you have to equip your entity classes with
auditing metadata that can be defined either using annotations or by
implementing an interface.</para>
<section id="auditing.annotations">
<title>Annotation based auditing metadata</title>
<para>We provide <interfacename>@CreatedBy</interfacename>,
<interfacename>@LastModifiedBy</interfacename> to capture the user who
created or modified the entity as well as
<interfacename>@CreatedDate</interfacename> and
<interfacename>@LastModifiedDate</interfacename> to capture the point in
time this happened.</para>
<example>
<title>An audited entity</title>
<programlisting language="java">class Customer {
@CreatedBy
private User user;
@CreatedDate
private DateTime createdDate;
// … further properties omitted
}</programlisting>
</example>
<para>As you can see, the annotations can be applied selectively,
depending on which information you'd like to capture. For the annotations
capturing the points in time can be used on properties of type
<classname>org.joda.time.DateTime</classname>,
<classname>java.util.Date</classname> as well as
<code>long</code>/<classname>Long</classname>. </para>
</section>
<section id="auditing.interfaces">
<title>Interface-based auditing metadata</title>
<para>In case you don't want to use annotations to define auditing
metadata you can let your domain class implement the
<interfacename>Auditable</interfacename> interface. It exposes setter
methods for all of the auditing properties. </para>
<para>There's also a convenience base class
<interfacename>AbstractAuditable</interfacename> which you can extend to
avoid the need to manually implement the interface methods. Be aware that
this increases the coupling of your domain classes to Spring Data which
might be something you want to avoid. Usually the annotation based way of
defining auditing metadata is preferred as it is less invasive and more
flexible.</para>
</section>
<section id="auditing.auditor-aware">
<title>AuditorAware</title>
<para>In case you use either <interfacename>@CreatedBy</interfacename> or
<interfacename>@LastModifiedBy</interfacename>, the auditing
infrastructure somehow needs to become aware of the current principal. To
do so, we provide an <interfacename>AuditorAware&lt;T&gt;</interfacename>
SPI interface that you have to implement to tell the infrastructure who
the current user or system interacting with the application is. The
generic type <code>T</code> defines of what type the properties annotated
with <interfacename>@CreatedBy</interfacename> or
<interfacename>@LastModifiedBy</interfacename> have to be. </para>
<para>Here's an example implementation of the interface using Spring
Security's <interfacename>Authentication</interfacename> object:</para>
<example>
<title>Implementation of AuditorAware based on Spring Security</title>
<programlisting language="java">class SpringSecurityAuditorAware implements AuditorAware&lt;User&gt; {
public User getCurrentAuditor() {
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
if (authentication == null || !authentication.isAuthenticated()) {
return null;
}
return ((MyUserDetails) authentication.getPrincipal()).getUser();
}
}</programlisting>
</example>
<para>The implementation is accessing the
<interfacename>Authentication</interfacename> object provided by Spring
Security and looks up the custom
<interfacename>UserDetails</interfacename> instance from it that you have
created in your <interfacename>UserDetailsService</interfacename>
implementation. We're assuming here that you are exposing the domain user
through that <interfacename>UserDetails</interfacename> implementation but
you could also look it up from anywhere based on the
<interfacename>Authentication</interfacename> found.</para>
</section>
</section>

55
src/docbkx/index.xml
View File

@@ -1,55 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo>
<title>Spring Data Commons - Reference Documentation</title>
<releaseinfo>&version;</releaseinfo>
<authorgroup>
<author>
<firstname>Mark</firstname>
<surname>Pollack</surname>
</author>
<author>
<firstname>Thomas</firstname>
<surname>Risberg</surname>
</author>
<author>
<firstname>Oliver</firstname>
<surname>Gierke</surname>
</author>
<author>
<firstname>Thomas</firstname>
<surname>Darimont</surname>
</author>
<author>
<firstname>Christoph</firstname>
<surname>Strobl</surname>
</author>
</authorgroup>
<legalnotice>
<para>
Copies of this document may be made for your own use and for distribution
to others, provided that you do not charge any fee for such copies and
further provided that each copy contains this Copyright Notice, whether
distributed in print or electronically.
</para>
</legalnotice>
</bookinfo>
<toc/>
<xi:include href="preface.xml"/>
<part>
<title>Reference</title>
<partintro>
<para>
This part of the reference documentation details the ...
</para>
</partintro>
<xi:include href="repositories.xml" />
</part>
</book>

10
src/docbkx/preface.xml
View File

@@ -1,10 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<preface id="preface">
<title>Preface</title>
<para>The Spring Data Commons project applies core Spring concepts to the
development of solutions using many relational and non-relational data
stores.</para>
</preface>

1594
src/docbkx/repositories.xml
View File

File diff suppressed because it is too large Load Diff

81
src/docbkx/repository-namespace-reference.xml
View File

@@ -1,81 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<appendix id="namespace-reference">
<title>Namespace reference</title>
<section id="namespace-dao-config">
<title>The <code>&lt;repositories /&gt;</code> element</title>
<para>The <code>&lt;repositories /&gt;</code> element triggers the setup
of the Spring Data repository infrastructure. The most important attribute
is <code>base-package</code> which defines the package to scan for Spring
Data repository interfaces.<footnote>
<para>see <xref
linkend="repositories.create-instances.spring"/></para>
</footnote></para>
<table>
<title>Attributes</title>
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>base-package</code></entry>
<entry>Defines the package to be used to be scanned for repository
interfaces extending <interfacename>*Repository</interfacename>
(actual interface is determined by specific Spring Data module) in
auto detection mode. All packages below the configured package
will be scanned, too. Wildcards are allowed.</entry>
</row>
<row>
<entry><code>repository-impl-postfix</code></entry>
<entry>Defines the postfix to autodetect custom repository
implementations. Classes whose names end with the configured
postfix will be considered as candidates. Defaults to
<code>Impl</code>.</entry>
</row>
<row>
<entry><code>query-lookup-strategy</code></entry>
<entry>Determines the strategy to be used to create finder
queries. See <xref
linkend="repositories.query-methods.query-lookup-strategies"/> for
details. Defaults to <code>create-if-not-found</code>.</entry>
</row>
<row>
<entry><code>named-queries-location</code></entry>
<entry>Defines the location to look for a Properties file
containing externally defined queries.</entry>
</row>
<row>
<entry><code>consider-nested-repositories</code></entry>
<entry>Controls whether nested repository interface definitions
should be considered. Defaults to
<literal>false</literal>.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</appendix>

43
src/docbkx/repository-populator-namespace-reference.xml
View File

@@ -1,43 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<appendix id="namespace-reference">
<title>Populators namespace reference</title>
<section id="namespace-dao-config">
<title>The <code>&lt;populator /&gt;</code> element</title>
<para>The <code>&lt;populator /&gt;</code> element allows to populate the
a data store via the Spring Data repository infrastructure.<footnote>
<para>see <xref
linkend="repositories.create-instances.spring"/></para>
</footnote></para>
<table>
<title>Attributes</title>
<tgroup cols="2">
<colspec colwidth="1*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>locations</code></entry>
<entry>Where to find the files to read the objects from the
repository shall be populated with.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</appendix>

212
src/docbkx/repository-query-keywords-reference.xml
View File

@@ -1,212 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<appendix id="repository-query-keywords">
<title>Repository query keywords</title>
<section>
<title>Supported query keywords</title>
<para>The following table lists the keywords generally supported by the
Spring Data repository query derivation mechanism. However, consult the
store-specific documentation for the exact list of supported keywords,
because some listed here might not be supported in a particular
store.</para>
<table>
<title>Query keywords</title>
<tgroup cols="2">
<colspec colwidth="1*" />
<colspec colwidth="4*" />
<thead>
<row>
<entry>Logical keyword</entry>
<entry>Keyword expressions</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>AND</code></entry>
<entry><literal>And</literal></entry>
</row>
<row>
<entry><code>OR</code></entry>
<entry><literal>Or</literal></entry>
</row>
<row>
<entry><code>AFTER</code></entry>
<entry><literal>After</literal>,
<literal>IsAfter</literal></entry>
</row>
<row>
<entry><code>BEFORE</code></entry>
<entry><literal>Before</literal>,
<literal>IsBefore</literal></entry>
</row>
<row>
<entry><code>CONTAINING</code></entry>
<entry><literal>Containing</literal>,
<literal>IsContaining</literal>,
<literal>Contains</literal></entry>
</row>
<row>
<entry><code>BETWEEN</code></entry>
<entry><literal>Between</literal>,
<literal>IsBetween</literal></entry>
</row>
<row>
<entry><code>ENDING_WITH</code></entry>
<entry><literal>EndingWith</literal>,
<literal>IsEndingWith</literal>,
<literal>EndsWith</literal></entry>
</row>
<row>
<entry><code>EXISTS</code></entry>
<entry><literal>Exists</literal></entry>
</row>
<row>
<entry><code>FALSE</code></entry>
<entry><literal>False</literal>,
<literal>IsFalse</literal></entry>
</row>
<row>
<entry><code>GREATER_THAN</code></entry>
<entry><literal>GreaterThan</literal>,
<literal>IsGreaterThan</literal></entry>
</row>
<row>
<entry><code>GREATER_THAN_EQUALS</code></entry>
<entry><literal>GreaterThanEqual</literal>,
<literal>IsGreaterThanEqual</literal></entry>
</row>
<row>
<entry><code>IN</code></entry>
<entry><literal>In</literal>, <literal>IsIn</literal></entry>
</row>
<row>
<entry><code>IS</code></entry>
<entry><literal>Is</literal>, <literal>Equals</literal>, (or no
keyword)</entry>
</row>
<row>
<entry><code>IS_NOT_NULL</code></entry>
<entry><literal>NotNull</literal>,
<literal>IsNotNull</literal></entry>
</row>
<row>
<entry><code>IS_NULL</code></entry>
<entry><literal>Null</literal>, <literal>IsNull</literal></entry>
</row>
<row>
<entry><code>LESS_THAN</code></entry>
<entry><literal>LessThan</literal>,
<literal>IsLessThan</literal></entry>
</row>
<row>
<entry><code>LESS_THAN_EQUAL</code></entry>
<entry><literal>LessThanEqual</literal>,
<literal>IsLessThanEqual</literal></entry>
</row>
<row>
<entry><code>LIKE</code></entry>
<entry><literal>Like</literal>, <literal>IsLike</literal></entry>
</row>
<row>
<entry><code>NEAR</code></entry>
<entry><literal>Near</literal>, <literal>IsNear</literal></entry>
</row>
<row>
<entry><code>NOT</code></entry>
<entry><literal>Not</literal>, <literal>IsNot</literal></entry>
</row>
<row>
<entry><code>NOT_IN</code></entry>
<entry><literal>NotIn</literal>,
<literal>IsNotIn</literal></entry>
</row>
<row>
<entry><code>NOT_LIKE</code></entry>
<entry><literal>NotLike</literal>,
<literal>IsNotLike</literal></entry>
</row>
<row>
<entry><code>REGEX</code></entry>
<entry><literal>Regex</literal>, <literal>MatchesRegex</literal>,
<literal>Matches</literal></entry>
</row>
<row>
<entry><code>STARTING_WITH</code></entry>
<entry><literal>StartingWith</literal>,
<literal>IsStartingWith</literal>,
<literal>StartsWith</literal></entry>
</row>
<row>
<entry><code>TRUE</code></entry>
<entry><literal>True</literal>, <literal>IsTrue</literal></entry>
</row>
<row>
<entry><code>WITHIN</code></entry>
<entry><literal>Within</literal>,
<literal>IsWithin</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</appendix>

64
src/main/asciidoc/auditing.adoc Normal file
View File

@@ -0,0 +1,64 @@
[[auditing]]
= Auditing
[[auditing.basics]]
== Basics
Spring Data provides sophisticated support to transparently keep track of who created or changed an entity and the point in time this happened. To benefit from that functionality you have to equip your entity classes with auditing metadata that can be defined either using annotations or by implementing an interface.
[[auditing.annotations]]
=== Annotation based auditing metadata
We provide `@CreatedBy`, `@LastModifiedBy` to capture the user who created or modified the entity as well as `@CreatedDate` and `@LastModifiedDate` to capture the point in time this happened.
.An audited entity
====
[source, java]
----
class Customer {
@CreatedBy
private User user;
@CreatedDate
private DateTime createdDate;
// … further properties omitted
}
----
====
As you can see, the annotations can be applied selectively, depending on which information you'd like to capture. For the annotations capturing the points in time can be used on properties of type `org.joda.time.DateTime`, `java.util.Date` as well as `long`/`Long`.
[[auditing.interfaces]]
=== Interface-based auditing metadata
In case you don't want to use annotations to define auditing metadata you can let your domain class implement the Auditable interface. It exposes setter methods for all of the auditing properties.
There's also a convenience base class `AbstractAuditable` which you can extend to avoid the need to manually implement the interface methods. Be aware that this increases the coupling of your domain classes to Spring Data which might be something you want to avoid. Usually the annotation based way of defining auditing metadata is preferred as it is less invasive and more flexible.
[[auditing.auditor-aware]]
=== AuditorAware
In case you use either `@CreatedBy` or `@LastModifiedBy`, the auditing infrastructure somehow needs to become aware of the current principal. To do so, we provide an `AuditorAware<T>` SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is. The generic type `T` defines of what type the properties annotated with `@CreatedBy` or `@LastModifiedBy` have to be.
Here's an example implementation of the interface using Spring Security's `Authentication` object:
.Implementation of `AuditorAware` based on Spring Security
====
[source, java]
----
class SpringSecurityAuditorAware implements AuditorAware<User> {
public User getCurrentAuditor() {
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
if (authentication == null || !authentication.isAuthenticated()) {
return null;
}
return ((MyUserDetails) authentication.getPrincipal()).getUser();
}
}
----
====
The implementation is accessing the `Authentication` object provided by Spring Security and looks up the custom `UserDetails` instance from it that you have created in your `UserDetailsService` implementation. We're assuming here that you are exposing the domain user through that `UserDetails` implementation but you could also look it up from anywhere based on the `Authentication found.

29
src/main/asciidoc/index.adoc Normal file
View File

@@ -0,0 +1,29 @@
= Spring Data Commons - Reference Documentation
Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Pollack; Thomas Risberg;
{version}
:toc:
:spring-framework-docs: http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html
NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
[[preface]]
[preface]
= Preface
The Spring Data Commons project applies core Spring concepts to the development of solutions using many relational and non-relational data stores.
[[reference-documentation]]
= Reference documentation
:leveloffset: 1
include::repositories.adoc[]
include::auditing.adoc[]
:leveloffset: 0
[[appendix]]
= Appendix
:leveloffset: 1
:numbered!:
include::repository-namespace-reference.adoc[]
include::repository-populator-namespace-reference.adoc[]
include::repository-query-keywords-reference.adoc[]
:leveloffset: 0

1005
src/main/asciidoc/repositories.adoc Normal file
View File

File diff suppressed because it is too large Load Diff

18
src/main/asciidoc/repository-namespace-reference.adoc Normal file
View File

@@ -0,0 +1,18 @@
[[repositories.namespace-reference]]
[appendix]
= Namespace reference
[[populator.namespace-dao-config]]
== The <repositories /> element
The `<repositories />` element triggers the setup of the Spring Data repository infrastructure. The most important attribute is `base-package` which defines the package to scan for Spring Data repository interfaces.footnote:[see <<repositories.create-instances.spring>>]
.Attributes
[options="header", cols="1,3"]
|===============
|Name|Description
|`base-package`|Defines the package to be used to be scanned for repository interfaces extending *Repository (actual interface is determined by specific Spring Data module) in auto detection mode. All packages below the configured package will be scanned, too. Wildcards are allowed.
|`repository-impl-postfix`|Defines the postfix to autodetect custom repository implementations. Classes whose names end with the configured postfix will be considered as candidates. Defaults to `Impl`.
|`query-lookup-strategy`|Determines the strategy to be used to create finder queries. See <<repositories.query-methods.query-lookup-strategies>> for details. Defaults to `create-if-not-found`.
|`named-queries-location`|Defines the location to look for a Properties file containing externally defined queries.
|`consider-nested-repositories`|Controls whether nested repository interface definitions should be considered. Defaults to `false`.
|===============

14
src/main/asciidoc/repository-populator-namespace-reference.adoc Normal file
View File

@@ -0,0 +1,14 @@
[[populator.namespace-reference]]
[appendix]
= Populators namespace reference
[[namespace-dao-config]]
== The <populator /> element
The `<populator />` element allows to populate the a data store via the Spring Data repository infrastructure.footnote:[see <<repositories.create-instances.spring>>]
.Attributes
[options="header", cols="1,3"]
|===============
|Name|Description
|`locations`|Where to find the files to read the objects from the repository shall be populated with.
|===============

38
src/main/asciidoc/repository-query-keywords-reference.adoc Normal file
View File

@@ -0,0 +1,38 @@
[[repository-query-keywords]]
[appendix]
= Repository query keywords
== Supported query keywords
The following table lists the keywords generally supported by the Spring Data repository query derivation mechanism. However, consult the store-specific documentation for the exact list of supported keywords, because some listed here might not be supported in a particular store.
.Query keywords
[options="header", cols="1,3"]
|===============
|Logical keyword|Keyword expressions
|`AND`|`And`
|`OR`|`Or`
|`AFTER`|`After`, `IsAfter`
|`BEFORE`|`Before`, `IsBefore`
|`CONTAINING`|`Containing`, `IsContaining`, `Contains`
|`BETWEEN`|`Between`, `IsBetween`
|`ENDING_WITH`|`EndingWith`, `IsEndingWith`, `EndsWith`
|`EXISTS`|`Exists`
|`FALSE`|`False`, `IsFalse`
|`GREATER_THAN`|`GreaterThan`, `IsGreaterThan`
|`GREATER_THAN_EQUALS`|`GreaterThanEqual`, `IsGreaterThanEqual`
|`IN`|`In`, `IsIn`
|`IS`|`Is`, `Equals`, (or no keyword)
|`IS_NOT_NULL`|`NotNull`, `IsNotNull`
|`IS_NULL`|`Null`, `IsNull`
|`LESS_THAN`|`LessThan`, `IsLessThan`
|`LESS_THAN_EQUAL`|`LessThanEqual`, `IsLessThanEqual`
|`LIKE`|`Like`, `IsLike`
|`NEAR`|`Near`, `IsNear`
|`NOT`|`Not`, `IsNot`
|`NOT_IN`|`NotIn`, `IsNotIn`
|`NOT_LIKE`|`NotLike`, `IsNotLike`
|`REGEX`|`Regex`, `MatchesRegex`, `Matches`
|`STARTING_WITH`|`StartingWith`, `IsStartingWith`, `StartsWith`
|`TRUE`|`True`, `IsTrue`
|`WITHIN`|`Within`, `IsWithin`
|===============