Skip to content

Commit e560ca6

Browse files
mp911deschauder
mp911de
authored and
schauder
committed
DATAJDBC-555 - Add common reference documentation sections.
Original pull request: #225.
1 parent 66c6c8e commit e560ca6

File tree

2 files changed

+113
-4
lines changed

2 files changed

+113
-4
lines changed

‎src/main/asciidoc/jdbc.adoc‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,58 @@ WARNING: In the current implementation, entities referenced from an aggregate ro
6161

6262
You can overwrite the repository methods with implementations that match your style of working and designing your database.
6363

64+
[[jdbc.getting-started]]
65+
== Getting Started
66+
67+
An easy way to bootstrap setting up a working environment is to create a Spring-based project in https://spring.io/tools/sts[STS] or from https://start.spring.io[Spring Initializr].
68+
69+
First, you need to set up a running database server. Refer to your vendor documentation on how to configure your database for JDBC access.
70+
71+
To create a Spring project in STS:
72+
73+
. Go to File -> New -> Spring Template Project -> Simple Spring Utility Project, and press Yes when prompted. Then enter a project and a package name, such as `org.spring.jdbc.example`.
74+
.Add the following to the pom.xml files `dependencies` element:
75+
+
76+
[source,xml,subs="+attributes"]
77+
----
78+
<dependencies>
79+
80+
<!-- other dependency elements omitted -->
81+
82+
<dependency>
83+
<groupId>org.springframework.data</groupId>
84+
<artifactId>spring-data-jdbc</artifactId>
85+
<version>{version}</version>
86+
</dependency>
87+
88+
</dependencies>
89+
----
90+
. Change the version of Spring in the pom.xml to be
91+
+
92+
[source,xml,subs="+attributes"]
93+
----
94+
<spring.framework.version>{springVersion}</spring.framework.version>
95+
----
96+
. Add the following location of the Spring Milestone repository for Maven to your `pom.xml` such that it is at the same level of your `<dependencies/>` element:
97+
+
98+
[source,xml]
99+
----
100+
<repositories>
101+
<repository>
102+
<id>spring-milestone</id>
103+
<name>Spring Maven MILESTONE Repository</name>
104+
<url>https://repo.spring.io/libs-milestone</url>
105+
</repository>
106+
</repositories>
107+
----
108+
109+
The repository is also https://repo.spring.io/milestone/org/springframework/data/[browseable here].
110+
111+
[[jdbc.examples-repo]]
112+
== Examples Repository
113+
114+
There is a https://github.com/spring-projects/spring-data-examples[GitHub repository with several examples] that you can download and play around with to get a feel for how the library works.
115+
64116
[[jdbc.java-config]]
65117
== Annotation-based Configuration
66118

@@ -113,6 +165,9 @@ Everything else is done by Spring Boot.
113165

114166
There are a couple of things one might want to customize in this setup.
115167

168+
[[jdbc.dialects]]
169+
=== Dialects
170+
116171
Spring Data JDBC uses implementations of the interface `Dialect` to encapsulate behavior that is specific to a database or its JDBC driver.
117172
By default the `AbstractJdbcConfiguration` tries to determine the database in use an register the correct `Dialect`.
118173
This behavior can be changed by overwriting `jdbcDialect(NamedParameterJdbcOperations)`.

‎src/main/asciidoc/preface.adoc‎

Lines changed: 58 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,68 @@
11
[[preface]]
22
= Preface
33

4-
Spring Data JDBC offers a repository abstraction based on JDBC.
4+
The Spring Data JDBC project applies core Spring concepts to the development of solutions that use JDBC databases aligned with <<jdbc.domain-driven-design,Domain-driven design principles>>.
5+
We provide a "`template`" as a high-level abstraction for storing and querying aggregates.
6+
7+
This document is the reference guide for Spring Data JDBC Support.
8+
It explains the concepts and semantics and syntax..
9+
10+
This section provides some basic introduction.
11+
The rest of the document refers only to Spring Data JDBC features and assumes the user is familiar with SQL and Spring concepts.
12+
13+
[[get-started:first-steps:spring]]
14+
== Learning Spring
15+
16+
Spring Data uses Spring framework's https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html[core] functionality, including:
17+
18+
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#beans[IoC] container
19+
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#validation[type conversion system]
20+
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/core.html#expressions[expression language]
21+
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/integration.html#jmx[JMX integration]
22+
* https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/data-access.html#dao-exceptions[DAO exception hierarchy].
23+
24+
While you need not know the Spring APIs, understanding the concepts behind them is important.
25+
At a minimum, the idea behind Inversion of Control (IoC) should be familiar, and you should be familiar with whatever IoC container you choose to use.
26+
27+
The core functionality of the JDBC Aggregate support can be used directly, with no need to invoke the IoC services of the Spring Container.
28+
This is much like `JdbcTemplate`, which can be used "'standalone'" without any other services of the Spring container.
29+
To leverage all the features of Spring Data JDBC, such as the repository support, you need to configure some parts of the library to use Spring.
30+
31+
To learn more about Spring, you can refer to the comprehensive documentation that explains the Spring Framework in detail.
32+
There are a lot of articles, blog entries, and books on the subject.
33+
See the Spring framework https://spring.io/docs[home page] for more information.
34+
35+
[[requirements]]
36+
== Requirements
37+
38+
The Spring Data JDBC binaries require JDK level 8.0 and above and https://spring.io/docs[Spring Framework] {springVersion} and above.
39+
40+
[[get-started:help]]
41+
== Additional Help Resources
42+
43+
Learning a new framework is not always straightforward.
44+
In this section, we try to provide what we think is an easy-to-follow guide for starting with the Spring Data JDBC module.
45+
However, if you encounter issues or you need advice, feel free to use one of the following links:
46+
47+
[[get-started:help:community]]
48+
Community Forum :: Spring Data on https://stackoverflow.com/questions/tagged/spring-data[Stack Overflow] is a tag for all Spring Data (not just Document) users to share information and help each other.
49+
Note that registration is needed only for posting.
50+
51+
[[get-started:help:professional]]
52+
Professional Support :: Professional, from-the-source support, with guaranteed response time, is available from https://pivotal.io/[Pivotal Sofware, Inc.], the company behind Spring Data and Spring.
53+
54+
[[get-started:up-to-date]]
55+
== Following Development
56+
57+
For information on the Spring Data JDBC source code repository, nightly builds, and snapshot artifacts, see the Spring Data JDBC https://spring.io/projects/spring-data-jdbc/[homepage].
58+
You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Community on https://stackoverflow.com/questions/tagged/spring-data[Stack Overflow].
59+
If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue https://jira.spring.io/browse/DATAJDBC[tracker].
60+
To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community https://spring.io[Portal].
61+
You can also follow the Spring https://spring.io/blog[blog] or the project team on Twitter (https://twitter.com/SpringData[SpringData]).
562

663
[[project]]
7-
[preface]
864
== Project Metadata
965

10-
* Version control: https://github.com/spring-projects/spring-data-jdbc
11-
* Bugtracker: https://jira.spring.io/browse/DATAJDBC
1266
* Release repository: https://repo.spring.io/libs-release
1367
* Milestone repository: https://repo.spring.io/libs-milestone
1468
* Snapshot repository: https://repo.spring.io/libs-snapshot

0 commit comments

Comments
 (0)