
h1. Play Framework - Elastic Search Module

by *Felipe Oliveira*
"http://mashup.fm(http://mashup.fm)":http://mashup.fm
"http://geeks.aretotally.in(http://geeks.aretotally.in)":http://geeks.aretotally.in

Elastic Search is a Distributed Search Solution based on Apache Lucene. 

The main advantages are: 
- Schema-Free  (NoSQL)
- REST API Support - Easy Integration
- Reliable/No Single Point of Failure (you won't lose any data or have any outage if a node goes broke, huge point when considered the next point also)
- Near Real-Time (pretty self explanatory)
- Async Write Behind for Long Term Storage (store data on a separate data center for example without affecting the performance of your application)
- Geospatial Support (forget about highly complex packages such as PostGIS)


Integrate Elastic Search in a Play! Framework Application. This module uses JPA events to notify Elastic Search of events of their own. In Local Mode it embeds a running Elastic Search instance (port 9200 by default), a good choice for development. In Client Mode it connects to an external instance of Elastic Search, that might be your setup in production.



h2. Prerequisites

Play! 1.1



h2. Install the module

Install the elasticsearch module from the modules repository:

@play install elasticsearch@



h2. Enable the module

After installing the module, add the following to your application.conf to enable it:

@module.elasticsearch=${play.path}/modules/elasticsearch-0.0.6@



h2. Configure the module

You need to configure the module by setting these properties in your application.conf. There are two ways to run your Play! app with Elastic Search, local mode or client mode. Local mode works well for development purposes, an Elastic Search instance will run on the same JVM as your Play! application automatically. You won't need to setup another service, etc. The second option is client mode which fits better in a production environment. The default option is local mode.

				@# Option 1) Elastic Search (Local Model)
				elasticsearch.local=true@

				@# Option 2) Elastic Search (Client Model)
				elasticsearch.local=false
				elasticsearch.client=mynode1:9200,mynode2:9200@



h2. Usage

You basically need to add annotation "@ElasticSearchable" to your Model class. It only works for JPA so far. If a model has that annotation our module we'll watching for JPA events for instances of that class and route messages to Elastic Search to make sure Elastic Search index has the latest information available on the database.

Example:

				@ElasticSearchable
				@Entity
				public class Post extends Model {
				 
				    public String title;
				    
				
				    public Date postedAt;
				    
				}



h2. Searching

The biggest change on this release is a nicer search interface. We are providing a very simple way to get started, inspired by Play!'s CRUD module.
Basically you need to create a controller class and extend ElasticSearchController. Use annotation @ElasticSearchController.For(YOURMODELCLASS.class) to tell our module what model you want to search on, here's an example:

				@ElasticSearchController.For(ElasticSearchSampleModel.class)
				public class ElasticSearchExample extends ElasticSearchController {
				
				} 
			

You should be able to search on http://localhost:9000/elasticSearchExample/index. If you want to customize the views, just create a directory ELASTIC_SEARCH under views and change whatever you need to change.



h2. User Interface 

After you start your application (play run), you should have an admin interface automatically running on "http://localhost:9000/es-admin/(http://localhost:9000/es-admin/)":http://localhost:9000/es-admin/.




h2. Source Code

Fork it on Github "https://github.com/feliperazeek/playframework-elasticsearch(https://github.com/feliperazeek/playframework-elasticsearch)":https://github.com/feliperazeek/playframework-elasticsearch.

