DATAES-65 - Overhaul README.md

Author: mohsinh

README.md

@@ -15,24 +15,47 @@ Guide
 * [API Documentation](http://docs.spring.io/spring-data/elasticsearch/docs/1.0.0.M1/api/)
 * [Spring Data Project](http://www.springsource.org/spring-data)
 * [Sample Test Application](https://github.com/BioMedCentralLtd/spring-data-elasticsearch-sample-application)
+* for more detailed questions, use the [forum](http://forum.springsource.org/forumdisplay.php?f=80).
 
 
 Quick Start
 -----------
 Wiki page for [Getting Started] (https://github.com/spring-projects/spring-data-elasticsearch/wiki/How-to-start-with-spring-data-elasticsearch)
 
-### Dependency
-```java
+### Maven configuration
+
+Add the Maven dependency:
+
+```xml
 <dependency>
     <groupId>org.springframework.data</groupId>
     <artifactId>spring-data-elasticsearch</artifactId>
     <version>1.0.0.M1</version>
-</dependency> 
+</dependency>
+
+<repository>
+  <id>spring-libs-milestone</id>
+  <name>Spring Milestone Repository</name>
+  <url>http://repo.springsource.org/libs-milestone</url>
+</repository>
 ```
 
-### ElasticsearchTemplate
-ElasticsearchTemplate is the central support class for elasticsearch operations.
+If you'd rather like the latest snapshots of the upcoming major version, use our Maven snapshot repository and declare
+the appropriate dependency version.
 
+```xml
+<dependency>
+  <groupId>org.springframework.data</groupId>
+  <artifactId>spring-data-elasticsearch</artifactId>
+  <version>1.0.0.BUILD-SNAPSHOT</version>
+</dependency>
+
+<repository>
+  <id>spring-libs-snapshot</id>
+  <name>Spring Snapshot Repository</name>
+  <url>http://repo.springsource.org/libs-snapshot</url>
+</repository>
+```
 
 ### ElasticsearchRepository
 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.
@@ -49,87 +72,22 @@ Extending ElasticsearchRepository for custom methods
 ```java
     public interface BookRepository extends Repository<Book, String> {
 
-	//Equivalent Json Query will be "{ "bool" : { "must" :[{ "field" : {"name" : "?"} },{ "field" : {"price" : "?"} }]} }"
         List<Book> findByNameAndPrice(String name, Integer price);
 
-        //Equivalent Json Query will be "{"bool" : {"should" : [ {"field" : "name" : "?"}}, {"field" : {"price" : "?"}} ]}}"
         List<Book> findByNameOrPrice(String name, Integer price);
 
-        //Equivalent Json Query will be "{"bool" : {"must" : {"field" : {"name" : "?"}}}}"
         Page<Book> findByName(String name,Pageable page);
 
-        //Equivalent Json Query will be "{"bool" : {"must_not" : {"field" : {"name" : "?"}}}}"
         Page<Book> findByNameNot(String name,Pageable page);
 
-        //Equivalent Json Query will be "{"bool" : {"must" : {"range" : {"price" : {"from" : ?,"to" : ?,"include_lower" : true,"include_upper" : true}}}}}"
         Page<Book> findByPriceBetween(int price,Pageable page);
 
-
-        //Equivalent Json Query will be "{"bool" : {"must" : {"field" : {"name" : {"query" : "?*","analyze_wildcard" : true}}}}"
         Page<Book> findByNameLike(String name,Pageable page);
 
-
-        @Query("{\"bool\" : {\"must\" : {\"field\" : {\"message\" : \"?0\"}}}}")
+        @Query("{\"bool\" : {\"must\" : {\"term\" : {\"message\" : \"?0\"}}}}")
         Page<Book> findByMessage(String message, Pageable pageable);
     }
 ```
-
-Indexing a single document using Elasticsearch Template
-
-```java
-        String documentId = "123456";
-        SampleEntity sampleEntity = new SampleEntity();
-        sampleEntity.setId(documentId);
-        sampleEntity.setMessage("some message");
-        IndexQuery indexQuery = new IndexQuery();
-        indexQuery.setId(documentId);
-        indexQuery.setObject(sampleEntity);
-        elasticsearchTemplate.index(indexQuery);
-```
-
-Indexing multiple Document(bulk index) using Elasticsearch Template
-
-```java
-        @Autowired
-        private ElasticsearchTemplate elasticsearchTemplate;
-
-        List<IndexQuery> indexQueries = new ArrayList<IndexQuery>();
-        //first document
-        String documentId = "123456";
-        SampleEntity sampleEntity1 = new SampleEntity();
-        sampleEntity1.setId(documentId);
-        sampleEntity1.setMessage("some message");
-
-        IndexQuery indexQuery1 = new IndexQuery();
-        indexQuery1.setId(documentId);
-        indexQuery1.setObject(sampleEntity1);
-        indexQueries.add(indexQuery1);
-
-        //second document
-        String documentId2 = "123457";
-        SampleEntity sampleEntity2 = new SampleEntity();
-        sampleEntity2.setId(documentId2);
-        sampleEntity2.setMessage("some message");
-        IndexQuery indexQuery2 = new IndexQuery();
-        indexQuery2.setId(documentId2);
-        indexQuery2.setObject(sampleEntity2);
-        indexQueries.add(indexQuery2);
-        //bulk index
-        elasticsearchTemplate.bulkIndex(indexQueries);
-```
-
-Searching entities using Elasticsearch Template
-
-```java
-        @Autowired
-        private ElasticsearchTemplate elasticsearchTemplate;
-
-        SearchQuery searchQuery = new NativeSearchQueryBuilder()
-        .withQuery(fieldQuery("id", documentId))
-        .build();
-        Page<SampleEntity> sampleEntities = elasticsearchTemplate.queryForPage(searchQuery,SampleEntity.class);
-```
-
 Indexing a single document with Repository
 
 ```java
@@ -166,156 +124,63 @@ Indexing multiple Document(bulk index) using Repository
         repository.save(sampleEntities);
 ```
 
-### Adding custom behaviors to ResultMapper - CustomResultMapper
-
-Define new class implementing ResultMapper
-
-```java
-public class CustomResultMapper implements ResultsMapper{
-
-    private EntityMapper entityMapper;
-
-    public CustomResultMapper(EntityMapper entityMapper) {
-        this.entityMapper = entityMapper;
-    }
-
-    @Override
-    public EntityMapper getEntityMapper() {
-        return entityMapper;
-    }
-
-    @Override
-    public <T> T mapResult(GetResponse response, Class<T> clazz) {
-        return null;  //Your implementation
-    }
-
-    @Override
-    public <T> FacetedPage<T> mapResults(SearchResponse response, Class<T> clazz, Pageable pageable) {
-        return null;  //Your implementation
-    }
-}
-
-```
-
-Inject your custom implementation to template
-
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<beans xmlns="http://www.springframework.org/schema/beans"
-       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-       xmlns:elasticsearch="http://www.springframework.org/schema/data/elasticsearch"
-       xsi:schemaLocation="http://www.springframework.org/schema/data/elasticsearch http://www.springframework.org/schema/data/elasticsearch/spring-elasticsearch-1.0.xsd
-		http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsd">
-
-    <elasticsearch:repositories base-package="com.xyz.acme"/>
-
-    <elasticsearch:transport-client id="client" cluster-nodes="localhost:9300,someip:9300" />
 
-    <bean name="elasticsearchTemplate"
-          class="org.springframework.data.elasticsearch.core.ElasticsearchTemplate">
-        <constructor-arg name="client" ref="client"/>
-        <constructor-arg name="resultsMapper" ref="resultMapper"/>
-    </bean>
+### ElasticsearchTemplate
 
-    <bean name="entityMapper" class="org.springframework.data.elasticsearch.core.DefaultEntityMapper"/>
+ElasticsearchTemplate is the central support class for elasticsearch operations.
 
-    <bean name="resultMapper" class="org.springframework.data.elasticsearch.core.CustomResultMapper">
-        <constructor-arg ref="entityMapper"/>
-    </bean>
+Indexing a single document using Elasticsearch Template
 
-</beans>
+```java
+        String documentId = "123456";
+        SampleEntity sampleEntity = new SampleEntity();
+        sampleEntity.setId(documentId);
+        sampleEntity.setMessage("some message");
+        IndexQuery indexQuery = new IndexQueryBuilder().withId(sampleEntity.getId()).withObject(sampleEntity).build();
+        elasticsearchTemplate.index(indexQuery);
 ```
 
-### Geo indexing and request
-
-You can make request using geo_distance filter. This can be done using GeoPoint object.
-
-First, here is a sample of an entity with a GeoPoint field (location)
+Indexing multiple Document(bulk index) using Elasticsearch Template
 
 ```java
-@Document(indexName = "test-geo-index", type = "geo-class-point-type")
-public class AuthorMarkerEntity {
-
-    @Id
-    private String id;
-    private String name;
-
-    private GeoPoint location;
-
-    private AuthorMarkerEntity(){
-    }
-
-    public AuthorMarkerEntity(String id){
-        this.id = id;
-    }
-
-    public String getId() {
-        return id;
-    }
-
-    public void setId(String id) {
-        this.id = id;
-    }
+        @Autowired
+        private ElasticsearchTemplate elasticsearchTemplate;
 
-    public String getName() {
-        return name;
-    }
+        List<IndexQuery> indexQueries = new ArrayList<IndexQuery>();
+        //first document
+        String documentId = "123456";
+        SampleEntity sampleEntity1 = new SampleEntity();
+        sampleEntity1.setId(documentId);
+        sampleEntity1.setMessage("some message");
 
-    public void setName(String name) {
-        this.name = name;
-    }
+        IndexQuery indexQuery1 = new IndexQueryBuilder().withId(sampleEntity1.getId()).withObject(sampleEntity1).build();
+        indexQueries.add(indexQuery1);
 
-    public GeoPoint getLocation() {
-        return location;
-    }
+        //second document
+        String documentId2 = "123457";
+        SampleEntity sampleEntity2 = new SampleEntity();
+        sampleEntity2.setId(documentId2);
+        sampleEntity2.setMessage("some message");
 
-    public void setLocation(GeoPoint location) {
-        this.location = location;
-    }
-}
-```
+        IndexQuery indexQuery2 = new IndexQueryBuilder().withId(sampleEntity2.getId()).withObject(sampleEntity2).build()
+        indexQueries.add(indexQuery2);
 
-Indexing your entity with a geo-point : 
-```java
-elasticsearchTemplate.createIndex(AuthorMarkerEntity.class);
-elasticsearchTemplate.refresh(AuthorMarkerEntity.class, true);
-elasticsearchTemplate.putMapping(AuthorMarkerEntity.class);
-
-List<IndexQuery> indexQueries = new ArrayList<IndexQuery>();
-indexQueries.add(new AuthorMarkerEntityBuilder("1").name("Franck Marchand").location(45.7806d, 3.0875d).buildIndex());
-indexQueries.add(new AuthorMarkerEntityBuilder("2").name("Mohsin Husen").location(51.5171d, 0.1062d).buildIndex());
-indexQueries.add(new AuthorMarkerEntityBuilder("3").name("Rizwan Idrees").location(51.5171d, 0.1062d).buildIndex());
-elasticsearchTemplate.bulkIndex(indexQueries);
+        //bulk index
+        elasticsearchTemplate.bulkIndex(indexQueries);
 ```
 
-For your information : 
-- Clermont-Ferrand : 45.7806, 3.0875
-- London : 51.5171, 0.1062
-
-So, if you want to search for authors who are located within 20 kilometers around Clermont-Ferrand, here is the way to build your query :
+Searching entities using Elasticsearch Template
 
 ```java
-CriteriaQuery geoLocationCriteriaQuery = new CriteriaQuery(
-                new Criteria("location").within(new GeoPoint(45.7806d, 3.0875d), "20km"));
-List<AuthorMarkerEntity> geoAuthorsForGeoCriteria = elasticsearchTemplate.queryForList(geoLocationCriteriaQuery, AuthorMarkerEntity.class);
-```
-
-This example should only return one author named "Franck Marchand".
-
-You can even combine with other criteria (e.g. author name) :
-
-Here, we're looking for authors located within 20 kilometers around London AND named "Mohsin Husen" : 
+        @Autowired
+        private ElasticsearchTemplate elasticsearchTemplate;
 
-```java
-CriteriaQuery geoLocationCriteriaQuery2 = new CriteriaQuery(
-                new Criteria("name").is("Mohsin Husen").and("location").within(new GeoPoint(51.5171d, 0.1062d), "20km"));
-List<AuthorMarkerEntity> geoAuthorsForGeoCriteria2 = elasticsearchTemplate.queryForList(geoLocationCriteriaQuery2, AuthorMarkerEntity.class);
+        SearchQuery searchQuery = new NativeSearchQueryBuilder()
+        .withQuery(queryString(documentId).field("id"))
+        .build();
+        Page<SampleEntity> sampleEntities = elasticsearchTemplate.queryForPage(searchQuery,SampleEntity.class);
 ```
 
-This example should only return one author named "Mohsin Husen".
-
-
 ### XML Namespace
 
 You can set up repository scanning via xml configuration, which will happily create your repositories.
@@ -351,14 +216,19 @@ Using Transport Client
 
     <elasticsearch:repositories base-package="com.xyz.acme"/>
 
-    <elasticsearch:transport-client id="client" cluster-nodes="localhost:9300,someip:9300" />
+    <elasticsearch:transport-client id="client" cluster-nodes="ip:9300,ip:9300" cluster-name="elasticsearch" />
 
     <bean name="elasticsearchTemplate" class="org.springframework.data.elasticsearch.core.ElasticsearchTemplate">
         <constructor-arg name="client" ref="client"/>
     </bean>
 
 </beans>
-```    
+```
+
+## Help Pages
+
+* [Geo distance and location search](https://github.com/spring-projects/spring-data-elasticsearch/wiki/Geo-indexing-and-request)
+* [Custom object mapper](https://github.com/spring-projects/spring-data-elasticsearch/wiki/Custom-ObjectMapper)
 
 ## Contributing to Spring Data
 
@@ -381,4 +251,4 @@ Code formatting for [Eclipse and Intellij](https://github.com/spring-projects/sp
 * Rizwan Idrees ([email protected])
 * Abdul Waheed ([email protected])
 * Mohsin Husen ([email protected])
-* Artur Konczak([email protected])
+* Artur Konczak([email protected])