[CONF] Apache Solr Reference Guide > Using SolrJ

["Steve Rowe (Confluence)" <co...@apache.org>]

Space: Apache Solr Reference Guide (https://cwiki.apache.org/confluence/display/solr)
Page: Using SolrJ (https://cwiki.apache.org/confluence/display/solr/Using+SolrJ)

Change Comment:
---------------------------------------------------------------------
remove mention of obsolete solr-common-3.x.jar

Edited by Steve Rowe:
---------------------------------------------------------------------
SolrJ (also sometimes known as SolJava) is an API that makes it easy for Java applications to talk to Solr. SolrJ hides a lot of the details of connecting to Solr and allows your application to interact with Solr with simple high-level methods.

The center of SolrJ is the {{org.apache.solr.client.solrj}} package, which contains just five main classes. Begin by creating a {{SolrServer}}, which represents the Solr instance you want to use. Then send SolrRequests or SolrQuerys and get back SolrResponses.

{{SolrServer}} is abstract, so to connect to a remote Solr instance, you'll actually create an instance of {{org.apache.solr.client.solrj.impl.HttpSolrServer}}, which knows how to use HTTP to talk to Solr.

{code:lang=java|borderStyle=solid|borderColor=#666666}
String urlString = "http://localhost:8983/solr";
SolrServer solr = new HttpSolrServer(urlString);
{code}

Creating a {{SolrServer}} does not make a network connection - that happens later when you perform a query or some other operation - but it will throw {{MalformedURLException}} if you give it a bad URL string.

Once you have a {{SolrServer}}, you can use it by calling methods like {{query()}}, {{add()}}, and {{commit()}}.

h2. Building and Running SolrJ Applications

The SolrJ API is included with Solr, so you do not have to download or install anything else. However, in order to build and run applications that use SolrJ, you have to add some libraries to the classpath.

At build time, the examples presented with this section require {{apache-solr-solrj-4.x.x.jar}} to be in the classpath.

At run time, the examples in this section require the libraries found in the 'dist/solrj-lib' directory.

The Ant script bundled with this sections' examples includes the libraries as appropriate when building and running.

You can sidestep a lot of the messing around with the JAR files by using Maven instead of Ant. All you will need to do to include SolrJ in your application is to put the following dependency in the project's {{pom.xml}}:

{code:lang=xml|borderStyle=solid|borderColor=#666666}
<dependency>
   <groupId>org.apache.solr</groupId>
   <artifactId>solr-solrj</artifactId>
   <version>3.x.0</version>
</dependency>
{code}

If you are worried about the SolrJ libraries expanding the size of your client application, you can use a code obfuscator like [ProGuard|http://proguard.sourceforge.net/] to remove APIs that you are not using. 

h2. Setting XMLResponseParser

SolrJ uses a binary format, rather than XML, as its default format. Users of earlier Solr releases who wish to continue working with XML must explicitly set the parser to the XMLResponseParser, like so:

{code:lang=java|borderStyle=solid|borderColor=#666666}
server.setParser(new XMLResponseParser());
{code}

h2. Performing Queries

Use {{query()}} to have Solr search for results. You have to pass a {{SolrQuery}} object that describes the query, and you will get back a QueryResponse (from the {{org.apache.solr.client.solrj.response}} package).

{{SolrQuery}} has methods that make it easy to add parameters to choose a request handler and send parameters to it. Here is a very simple example that uses the default request handler and sets the {{q}} parameter:

{code:lang=java|borderStyle=solid|borderColor=#666666}
SolrQuery parameters = new SolrQuery();
parameters.set("q", mQueryString);
{code}

To choose a different request handler, for example, just set the {{qt}} parameter like this:

{code:lang=java|borderStyle=solid|borderColor=#666666}
parameters.set("qt", "/spellCheckCompRH");
{code}

Once you have your {{SolrQuery}} set up, submit it with {{query()}}:

{code:lang=java|borderStyle=solid|borderColor=#666666}
QueryResponse response = solr.query(parameters);
{code}

The client makes a network connection and sends the query. Solr processes the query, and the response is sent and parsed into a {{QueryResponse}}.

The {{QueryResponse}} is a collection of documents that satisfy the query parameters. You can retrieve the documents directly with {{getResults()}} and you can call other methods to find out information about highlighting or facets.

{code:lang=java|borderStyle=solid|borderColor=#666666}
SolrDocumentList list = response.getResults();
{code}

h2. Indexing Documents

Other operations are just as simple. To index (add) a document, all you need to do is create a {{SolrInputDocument}} and pass it along to the {{SolrServer}}'s {{add()}} method.

{code:lang=java|borderStyle=solid|borderColor=#666666}
String urlString = "http://localhost:8983/solr";
SolrServer solr = new HttpSolrServer(urlString);
SolrInputDocument document = new SolrInputDocument();
document.addField("id", "552199");
document.addField("name", "Gouda cheese wheel");
document.addField("price", "49.99");
UpdateResponse response = solr.add(document);

Remember to commit your changes!

solr.commit();
{code}

h3. Uploading Content in XML or Binary Formats

SolrJ lets you upload content in XML and binary formats instead of the default XML format. Use the following to upload using binary format, which is the same format SolrJ uses to fetch results.

{code:lang=java|borderStyle=solid|borderColor=#666666}
server.setRequestWriter(new BinaryRequestWriter());
{code}

h2. EmbeddedSolrServer

The [{{EmbeddedSolrServer}}|http://lucene.apache.org/solr/4_0_0/solr-core/org/apache/solr/client/solrj/embedded/EmbeddedSolrServer.html] provides the Java interface described above without requiring an HTTP connection. This is the recommended approach if you need to use Solr in an embedded application. This approach enables you to work with the same Java interface whether or not you have access to HTTP.

{note}
{{EmbeddedSolrServer}} works only with handlers registered in {{solrconfig.xml}}. The Solr {{RequestHandler}} must be mapped to {{/update}} for a request to function. For more information about configuring handlers, see [Configuring solrconfig.xml].
{note}

Note that the following property could be set through JVM level arguments:

{code:lang=java|borderStyle=solid|borderColor=#666666}
System.setProperty("solr.solr.home", "/home/shalinsmangar/work/oss/branch-1.3/example/solr");
CoreContainer.Initializer initializer = new CoreContainer.Initializer();
CoreContainer coreContainer = initializer.initialize();
EmbeddedSolrServer server = new EmbeddedSolrServer(coreContainer, "");
{code}

If you want to use [MultiCore|http://wiki.apache.org/solr/MultiCore] features (which are described in [Solr Cores and solr.xml]), then you should use this:

{code:lang=java|borderStyle=solid|borderColor=#666666}
File home = new File( "/path/to/solr/home" );
File f = new File( home, "solr.xml" );
CoreContainer container = new CoreContainer();
container.load( "/path/to/solr/home", f );
EmbeddedSolrServer server = new EmbeddedSolrServer( container, "core name as defined in solr.xml" );
    ...
{code}

h2. Using the ConcurrentUpdateSolrServer

If you are working with Java, you can take advantage of the {{ConcurrentUpdateSolrServer}} to perform bulk updates at high speed. The {{ConcurrentHttpSolrServer}} buffers all added documents and writes them into open HTTP connections. This class is thread safe. Although any SolrServer request can be made with this implementation, it is only recommended to use the {{ConcurrrentUpdateSolrServer}} for {{/update}} requests.

You can learn more about the {{ConcurrentUpdateSolrServer}} at [http://lucene.apache.org/solr/4_0_0/solr-solrj/org/apache/solr/client/solrj/impl/ConcurrentUpdateSolrServer.html].

h2. Related Topics

* [SolrJ API documentation|http://lucene.apache.org/solr/4_0_0/solr-solrj/index.html]
* [Solr Wiki page on SolrJ|http://wiki.apache.org/solr/Solrj]
* [solr:Indexing and Basic Data Operations]

{scrollbar}


Stop watching space: https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=solr
Change email notification preferences: https://cwiki.apache.org/confluence/users/editmyemailsettings.action