Skip to content

Commit 2194096

Browse files
sothawosothawo
authored
DATAES-589 - Improve readme file.
Original PR: spring-projects#285, contains change from spring-projects#268
1 parent 42803eb commit 2194096

File tree

1 file changed

+65
-42
lines changed

1 file changed

+65
-42
lines changed

‎README.adoc

Lines changed: 65 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@ image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-elasticsearch%2
22
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-elasticsearch%2F3.1.x&subject=Lovelace%20(3.1.x)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-elasticsearch/]
33
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-elasticsearch%2F2.1.x&subject=Ingalls%20(2.1.x)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-elasticsearch/]
44

5-
65
= Spring Data Elasticsearch
76

87
Spring Data implementation for ElasticSearch
@@ -13,17 +12,31 @@ The Spring Data Elasticsearch project provides integration with the https://www.
1312

1413
== Guide
1514

16-
* https://docs.spring.io/spring-data/elasticsearch/docs/current/reference/html/[Reference Documentation]
15+
* https://spring.io/projects/spring-data-elasticsearch#learn[Reference Documentation]
1716
* https://docs.spring.io/spring-data/elasticsearch/docs/current/api/[API Documentation]
18-
* https://projects.spring.io/spring-data[Spring Data Project]
17+
* https://spring.io/projects/spring-data[Spring Data Project]
18+
* https://jira.springsource.org/browse/DATAES[Issues (Spring Jira)]
19+
* https://stackoverflow.com/questions/tagged/spring-data-elasticsearch[Questions (Stack Overflow)]
1920
* https://github.com/BioMedCentralLtd/spring-data-elasticsearch-sample-application[Sample Test Application]
20-
* https://jira.springsource.org/browse/DATAES[Issues]
21-
* https://groups.google.com/d/forum/spring-data-elasticsearch-devs[Spring Data Elasticsearch Google Group]
22-
* https://stackoverflow.com/questions/tagged/spring-data-elasticsearch[Questions]
2321

2422
== Quick Start
2523

26-
Wiki page for https://github.com/spring-projects/spring-data-elasticsearch/wiki/How-to-start-with-spring-data-elasticsearch[Getting Started]
24+
This section is just short introduction, for more information refer to the https://spring.io/projects/spring-data-elasticsearch#learn[reference documentation].
25+
26+
=== Versions
27+
28+
The following table shows the Elasticsearch versions that are used by Spring Data Elasticsearch:
29+
[cols="^,^"]
30+
|===
31+
|Spring Data Elasticsearch |Elasticsearch
32+
33+
|3.2.x |6.7.2
34+
|3.1.x |6.2.2
35+
|3.0.x |5.5.0
36+
|2.1.x |2.4.0
37+
|2.0.x |2.2.0
38+
|1.3.x |1.5.2
39+
|===
2740

2841
=== Maven configuration
2942

@@ -56,35 +69,42 @@ the appropriate dependency version.
5669
</repository>
5770
----
5871

59-
[cols="^,^"]
60-
|===
61-
|spring data elasticsearch |elasticsearch
62-
63-
|3.2.x |6.5.0
64-
|3.1.x |6.2.2
65-
|3.0.x |5.5.0
66-
|2.1.x |2.4.0
67-
|2.0.x |2.2.0
68-
|1.3.x |1.5.2
69-
|===
7072

7173
=== ElasticsearchRepository
7274

73-
A default implementation of ElasticsearchRepository, aligning to the generic Repository Interfaces, is provided. Spring can do the Repository implementation for you depending on method names in the interface definition.
74-
75-
The ElasticsearchCrudRepository extends PagingAndSortingRepository
75+
A default implementation of `ElasticsearchRepository`, aligning to the generic `Repository` Interfaces, is provided. Spring can do the `Repository` implementation for you depending on method names in the interface definition.
76+
For a detailed information about Spring Data, repositories and the supported query methods check the https://spring.io/projects/spring-data-elasticsearch#learn[reference documentation].
7677

7778
[source,java]
7879
----
79-
public interface ElasticsearchCrudRepository<T, ID extends Serializable> extends ElasticsearchRepository<T, ID>, PagingAndSortingRepository<T, ID> {
80+
@NoRepositoryBean
81+
public interface ElasticsearchRepository<T, ID> extends ElasticsearchCrudRepository<T, ID> {
82+
83+
<S extends T> S index(S entity);
84+
85+
Iterable<T> search(QueryBuilder query);
86+
87+
Page<T> search(QueryBuilder query, Pageable pageable);
88+
89+
Page<T> search(SearchQuery searchQuery);
90+
91+
Page<T> searchSimilar(T entity, String[] fields, Pageable pageable);
92+
93+
void refresh();
94+
95+
Class<T> getEntityClass();
96+
}
97+
98+
@NoRepositoryBean
99+
public interface ElasticsearchCrudRepository<T, ID> extends PagingAndSortingRepository<T, ID> {
80100
}
81101
----
82102

83-
Extending ElasticsearchRepository for custom methods
103+
.Extending `ElasticsearchRepository` with custom methods:
84104

85105
[source,java]
86106
----
87-
public interface BookRepository extends Repository<Book, String> {
107+
public interface BookRepository extends ElasticsearchRepository<Book, String> {
88108
89109
List<Book> findByNameAndPrice(String name, Integer price);
90110
@@ -103,7 +123,7 @@ Extending ElasticsearchRepository for custom methods
103123
}
104124
----
105125

106-
Indexing a single document with Repository
126+
.Indexing a single document using a `Repository`:
107127

108128
[source,java]
109129
----
@@ -118,7 +138,7 @@ Indexing a single document with Repository
118138
repository.save(sampleEntity);
119139
----
120140

121-
Indexing multiple Document(bulk index) using Repository
141+
.Indexing multiple documents (bulk index) using a `Repository`:
122142

123143
[source,java]
124144
----
@@ -141,11 +161,13 @@ Indexing multiple Document(bulk index) using Repository
141161
repository.save(sampleEntities);
142162
----
143163

144-
=== ElasticsearchTemplate
164+
=== ElasticsearchTemplate and ElasticsearchRestTemplate
165+
166+
`ElasticsearchTemplate` and `ElasticsearchRestTemplate` are the central support classes for Elasticsearch operations, both implement the `ElasticsearchOperations` interface that defines the methods to operate on an Elasticsearch cluster.
145167

146-
ElasticsearchTemplate is the central support class for elasticsearch operations.
168+
`ElasticsearchTemplate` uses a `TransportClient`, whereas `ElasticsearchRestTemplate` uses the `RestHighLevelClient`. The `TransportClient` is deprecated in Elasticsearch 7, but until it is removed from Elasticsearch, the `ElasticsearchTemplate` will be supported as well.
147169

148-
Indexing a single document using Elasticsearch Template
170+
.Indexing a single document using `ElasticsearchTemplate`:
149171

150172
[source,java]
151173
----
@@ -157,7 +179,7 @@ Indexing a single document using Elasticsearch Template
157179
elasticsearchTemplate.index(indexQuery);
158180
----
159181

160-
Indexing multiple Document(bulk index) using Elasticsearch Template
182+
.Indexing multiple documents (bulk index) using `ElasticsearchTemplate`:
161183

162184
[source,java]
163185
----
@@ -187,7 +209,7 @@ Indexing multiple Document(bulk index) using Elasticsearch Template
187209
elasticsearchTemplate.bulkIndex(indexQueries);
188210
----
189211

190-
Searching entities using Elasticsearch Template
212+
.Searching entities using `ElasticsearchTemplate`:
191213

192214
[source,java]
193215
----
@@ -202,7 +224,7 @@ Searching entities using Elasticsearch Template
202224

203225
=== Reactive Elasticsearch
204226

205-
The `ReactiveElasticsearchClient` is a non official driver based on `WebClient`.
227+
The `ReactiveElasticsearchClient`, introduced in Spring Data Elasticsearch 3.2, is a non official driver based on `WebClient`.
206228
It uses the request/response objects provided by the Elasticsearch core project.
207229

208230
[source,java]
@@ -280,8 +302,7 @@ The above outputs the following sequence on the console.
280302

281303
You can set up repository scanning via xml configuration, which will happily create your repositories.
282304

283-
Using Node Client
284-
305+
.Using TransportClient
285306
[source,xml]
286307
----
287308
<?xml version="1.0" encoding="UTF-8"?>
@@ -291,7 +312,9 @@ Using Node Client
291312
xsi:schemaLocation="http://www.springframework.org/schema/data/elasticsearch https://www.springframework.org/schema/data/elasticsearch/spring-elasticsearch.xsd
292313
http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd">
293314
294-
<elasticsearch:node-client id="client" local="true"/>
315+
<elasticsearch:repositories base-package="com.xyz.acme"/>
316+
317+
<elasticsearch:transport-client id="client" cluster-nodes="ip:9300,ip:9300" cluster-name="elasticsearch" />
295318
296319
<bean name="elasticsearchTemplate" class="org.springframework.data.elasticsearch.core.ElasticsearchTemplate">
297320
<constructor-arg name="client" ref="client"/>
@@ -300,8 +323,7 @@ Using Node Client
300323
</beans>
301324
----
302325

303-
Using Transport Client
304-
326+
.Using RestClient
305327
[source,xml]
306328
----
307329
<?xml version="1.0" encoding="UTF-8"?>
@@ -313,15 +335,16 @@ Using Transport Client
313335
314336
<elasticsearch:repositories base-package="com.xyz.acme"/>
315337
316-
<elasticsearch:transport-client id="client" cluster-nodes="ip:9300,ip:9300" cluster-name="elasticsearch" />
338+
<elasticsearch:rest-client id="restClient" hosts="http://localhost:9200/"/>
317339
318-
<bean name="elasticsearchTemplate" class="org.springframework.data.elasticsearch.core.ElasticsearchTemplate">
319-
<constructor-arg name="client" ref="client"/>
340+
<bean name="elasticsearchTemplate"
341+
class="org.springframework.data.elasticsearch.core.ElasticsearchRestTemplate">
342+
<constructor-arg name="client" ref="restClient"/>
320343
</bean>
321344
345+
322346
</beans>
323347
----
324-
325348
== Help Pages
326349

327350
* https://github.com/spring-projects/spring-data-elasticsearch/wiki/Geo-indexing-and-request[Geo distance and location search]
@@ -336,7 +359,7 @@ Here are some ways for you to get involved in the community:
336359
* Github is for social coding: if you want to write code, we encourage contributions through pull requests from https://help.github.com/forking/[forks of this repository]. If you want to contribute code this way, please reference a JIRA ticket as well covering the specific issue you are addressing.
337360
* Watch for upcoming articles on Spring by https://www.springsource.org/node/feed[subscribing] to springframework.org
338361

339-
Before we accept a non-trivial patch or pull request we will need you to https://cla.pivotal.io/sign/spring[sign the Contributor License Agreement]. Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. If you forget to do so, you'll be reminded when you submit a pull request. Active contributors might be asked to join the core team, and given the ability to merge pull requests.
362+
Before we accept a pull request we will need you to https://cla.pivotal.io/sign/spring[sign the Contributor License Agreement]. Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. If you forget to do so, you'll be reminded when you submit a pull request. Active contributors might be asked to join the core team, and given the ability to merge pull requests.
340363

341364
Code formatting for https://github.com/spring-projects/spring-data-build/tree/master/etc/ide[Eclipse and Intellij]
342365

0 commit comments

Comments
 (0)