mongo.html

<!DOCTYPE html>
<html>
<head>
  <meta charset='utf-8'>
  <meta http-equiv="X-UA-Compatible" content="chrome=1">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <!--link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css"-->
  <link rel="stylesheet" href="/gfx/bootstrap.min.css">
  <link rel="stylesheet" href="/gfx/main.css">
  <link rel="stylesheet" href="/gfx/code.css">
  <title>MongoDB repositories</title>
</head>
<body class="page">
<!-- Google Tag Manager -->
<noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-PMJSKV"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-PMJSKV');</script>
<!-- End Google Tag Manager -->

<header>
  <div class="container">
    <a href="/">Immutables</a> &larr;

    <h1>MongoDB repositories <iframe src="https://ghbtns.com/github-btn.html?user=immutables&repo=immutables&type=star&count=true&size=large" frameborder="0" scrolling="0" width="160px" height="30px"></iframe>
</h1>
  </div>
</header>
<aside id="toc"></aside>
<section class="documentation">
  
<h2 id="overview">Overview</h2>
<div class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> <b>Important:</b> While we don’t yet deprecate mongo repositories, new and existing users are encouraged to consider <a href="criteria.html">criteria API</a> as a better alternative</div>

<p>There are already a lot of tools to access MongoDB collections <a href="http://docs.mongodb.org/ecosystem/drivers/java/">using Java</a>.
Each driver or wrapper has it’s own distinct features and advantages. The focus of <em>Immutables</em> repository generation
is to provide the best possible API that matches well for storing documents expressed as immutable objects.</p>

<ul>
  <li>Expressive type safe API
    <ul>
      <li>Document field names are expressed as method names, not strings. Works nicely with auto-completion in IDE.</li>
      <li>Operations and types should match.</li>
    </ul>
  </li>
  <li>Asynchronous operations returning <code class="language-plaintext highlighter-rouge">Future</code>
    <ul>
      <li>Compose async operations.</li>
      <li>IO is still synchronous underneath with dedicated thread pool.</li>
    </ul>
  </li>
</ul>

<p>One of the side goals of this module was to demonstrate that Java DSLs and APIs could be actually a lot less ugly than they usually are.</p>

<p>Generated repositories wrap the infrastructure of the official <a href="https://mongodb.github.io/mongo-java-driver/">Java driver</a> and <a href="http://mongodb.github.io/mongo-java-driver/3.8/bson/">BSON serialization</a>.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Define repository for collection "items".</span>
<span class="nd">@Value</span><span class="o">.</span><span class="na">Immutable</span>
<span class="nd">@Mongo</span><span class="o">.</span><span class="na">Repository</span><span class="o">(</span><span class="s">"items"</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">abstract</span> <span class="kd">class</span> <span class="nc">Item</span> <span class="o">{</span>
  <span class="nd">@Mongo</span><span class="o">.</span><span class="na">Id</span>
  <span class="kd">public</span> <span class="kd">abstract</span> <span class="kt">long</span> <span class="nf">id</span><span class="o">();</span>
  <span class="kd">public</span> <span class="kd">abstract</span> <span class="nc">String</span> <span class="nf">name</span><span class="o">();</span>
  <span class="kd">public</span> <span class="kd">abstract</span> <span class="nc">Set</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="nf">values</span><span class="o">();</span>
  <span class="kd">public</span> <span class="kd">abstract</span> <span class="nc">Optional</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="nf">comment</span><span class="o">();</span>
<span class="o">}</span>

<span class="c1">// Instantiate generated repository</span>
<span class="nc">ItemRepository</span> <span class="n">items</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">ItemRepository</span><span class="o">(</span>
    <span class="nc">RepositorySetup</span><span class="o">.</span><span class="na">forUri</span><span class="o">(</span><span class="s">"mongodb://localhost/test"</span><span class="o">));</span>

<span class="c1">// Create item</span>
<span class="nc">Item</span> <span class="n">item</span> <span class="o">=</span> <span class="nc">ImmutableItem</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
    <span class="o">.</span><span class="na">id</span><span class="o">(</span><span class="mi">1</span><span class="o">)</span>
    <span class="o">.</span><span class="na">name</span><span class="o">(</span><span class="s">"one"</span><span class="o">)</span>
    <span class="o">.</span><span class="na">addValues</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="mi">2</span><span class="o">)</span>
    <span class="o">.</span><span class="na">build</span><span class="o">();</span>

<span class="c1">// Insert async</span>
<span class="n">items</span><span class="o">.</span><span class="na">insert</span><span class="o">(</span><span class="n">item</span><span class="o">);</span> <span class="c1">// returns future</span>

<span class="nc">Optional</span><span class="o">&lt;</span><span class="nc">Item</span><span class="o">&gt;</span> <span class="n">modifiedItem</span> <span class="o">=</span> <span class="n">items</span><span class="o">.</span><span class="na">findById</span><span class="o">(</span><span class="mi">1</span><span class="o">)</span>
    <span class="o">.</span><span class="na">andModifyFirst</span><span class="o">()</span> <span class="c1">// findAndModify</span>
    <span class="o">.</span><span class="na">addValues</span><span class="o">(</span><span class="mi">1</span><span class="o">)</span> <span class="c1">// $addToSet</span>
    <span class="o">.</span><span class="na">setComment</span><span class="o">(</span><span class="s">"present"</span><span class="o">)</span> <span class="c1">// $set</span>
    <span class="o">.</span><span class="na">returningNew</span><span class="o">()</span>
    <span class="o">.</span><span class="na">update</span><span class="o">()</span> <span class="c1">// returns future</span>
    <span class="o">.</span><span class="na">getUnchecked</span><span class="o">();</span>

<span class="c1">// Update all matching documents</span>
<span class="n">items</span><span class="o">.</span><span class="na">update</span><span class="o">(</span>
    <span class="nc">ItemRepository</span><span class="o">.</span><span class="na">criteria</span><span class="o">()</span>
        <span class="o">.</span><span class="na">idIn</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="mi">2</span><span class="o">,</span> <span class="mi">3</span><span class="o">)</span>
        <span class="o">.</span><span class="na">nameNot</span><span class="o">(</span><span class="s">"Nameless"</span><span class="o">)</span>
        <span class="o">.</span><span class="na">valuesNonEmpty</span><span class="o">())</span>
    <span class="o">.</span><span class="na">clearComment</span><span class="o">()</span>
    <span class="o">.</span><span class="na">updateAll</span><span class="o">();</span>

</code></pre></div></div>

<h2 id="usage">Usage</h2>

<h3 id="dependencies">Dependencies</h3>

<p>In addition to code annotation-processor, it’s necessary to add the <code class="language-plaintext highlighter-rouge">mongo</code> annotation module and runtime library, including some required transitive dependencies.</p>

<p><a name="dependencies"></a></p>

<ul>
  <li><a href="https://search.maven.org/artifact/org.immutables/mongo/2.10.1/jar">org.immutables:mongo:2.10.1</a>
    <ul>
      <li>Compile and runtime utilities used during marshaling</li>
    </ul>
  </li>
</ul>

<p><em>Mongo</em> artifact required to be used for compilation as well be available at runtime.
By default, <em>Mongo</em> adapter works with <a href="/json.html#gson">Gson</a> module, however there are ways to register external <a href="http://mongodb.github.io/mongo-java-driver/3.8/bson/codecs/">CodecRegistry</a> to allow custom serialization and deserialization using other libraries (eg. Jackson).</p>

<p>Snippet of Maven dependencies:</p>

<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;dependency&gt;</span>
  <span class="nt">&lt;groupId&gt;</span>org.immutables<span class="nt">&lt;/groupId&gt;</span>
  <span class="nt">&lt;artifactId&gt;</span>value<span class="nt">&lt;/artifactId&gt;</span>
  <span class="nt">&lt;version&gt;</span>2.10.1<span class="nt">&lt;/version&gt;</span>
  <span class="nt">&lt;scope&gt;</span>provided<span class="nt">&lt;/scope&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
<span class="nt">&lt;dependency&gt;</span>
  <span class="nt">&lt;groupId&gt;</span>org.immutables<span class="nt">&lt;/groupId&gt;</span>
  <span class="nt">&lt;artifactId&gt;</span>mongo<span class="nt">&lt;/artifactId&gt;</span>
  <span class="nt">&lt;version&gt;</span>2.10.1<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
</code></pre></div></div>

<h3 id="enable-repository-generation">Enable repository generation</h3>

<p>In order to enable repository generation, put an <code class="language-plaintext highlighter-rouge">org.immutables.mongo.Mongo.Repository</code>
annotation on a abstract value class alongside an <code class="language-plaintext highlighter-rouge">org.immutables.value.Value.Immutable</code> annotation.
A repository which accesses a collection of documents will be generated
as a class with a <code class="language-plaintext highlighter-rouge">Repository</code> suffix in the same package.</p>

<p>By default, the mapped collection name is derived from abstract value class name: For a
<code class="language-plaintext highlighter-rouge">UserDocument</code> class, the collection name will be <code class="language-plaintext highlighter-rouge">userDocument</code>. However, the name is customizable
using a <code class="language-plaintext highlighter-rouge">value</code> annotation attribute:</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">org.immutables.mongo.Mongo</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.immutables.value.Value</span><span class="o">;</span>

<span class="nd">@Value</span><span class="o">.</span><span class="na">Immutable</span>
<span class="nd">@Gson</span><span class="o">.</span><span class="na">TypeAdapters</span> <span class="c1">// you can put TypeAdapters on a package instead</span>
<span class="nd">@Mongo</span><span class="o">.</span><span class="na">Repository</span><span class="o">(</span><span class="s">"user"</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">abstract</span> <span class="kd">class</span> <span class="nc">UserDocument</span> <span class="o">{</span>
  <span class="o">...</span>
<span class="o">}</span>
</code></pre></div></div>

<h3 id="creating-repositories">Creating repositories</h3>

<p>Once the repository class is generated, it’s possible to instantiate this class using the <code class="language-plaintext highlighter-rouge">new</code>
operator. You need to supply a <code class="language-plaintext highlighter-rouge">org.immutables.common.repository.RepositorySetup</code> as a
constructor argument. Setup can be shared by all repositories for a single MongoDB
database. <code class="language-plaintext highlighter-rouge">RepositorySetup</code> combines the definition of a thread pool, MongoDB database,
and a configured <code class="language-plaintext highlighter-rouge">com.google.gson.Gson</code> instance.</p>

<p>Luckily, to get started (and for simpler applications), there’s an easy way to create a setup
using <code class="language-plaintext highlighter-rouge">RepositorySetup.forUri</code> factory method. Pass a MongoDB connection string and a setup
will be created with default settings.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nc">RepositorySetup</span> <span class="n">setup</span> <span class="o">=</span> <span class="nc">RepositorySetup</span><span class="o">.</span><span class="na">forUri</span><span class="o">(</span><span class="s">"mongodb://localhost/test"</span><span class="o">);</span>
</code></pre></div></div>

<p>To get a test database running on the default port on a local machine, just launch <code class="language-plaintext highlighter-rouge">mongod</code>.</p>

<p>To fully customize setting use <code class="language-plaintext highlighter-rouge">RepositorySetup</code> builder:</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nc">MongoClient</span> <span class="n">mongoClient</span> <span class="o">=</span> <span class="o">...</span>
<span class="nc">ListeningExecutorService</span> <span class="n">executor</span> <span class="o">=</span> <span class="o">...</span>
<span class="nc">GsonBuilder</span> <span class="n">gsonBuilder</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">GsonBuilder</span><span class="o">();</span>
<span class="o">...</span>

<span class="nc">RepositorySetup</span> <span class="n">setup</span> <span class="o">=</span> <span class="nc">RepositorySetup</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
  <span class="o">.</span><span class="na">database</span><span class="o">(</span><span class="n">mongoClient</span><span class="o">.</span><span class="na">getDB</span><span class="o">(</span><span class="s">"test"</span><span class="o">))</span>
  <span class="o">.</span><span class="na">executor</span><span class="o">(</span><span class="n">executor</span><span class="o">)</span>
  <span class="o">.</span><span class="na">gson</span><span class="o">(</span><span class="n">gsonBuilder</span><span class="o">.</span><span class="na">create</span><span class="o">())</span>
  <span class="o">.</span><span class="na">build</span><span class="o">();</span>
</code></pre></div></div>

<p>See <a href="http://docs.mongodb.org/ecosystem/tutorial/getting-started-with-java-driver/">getting started with java driver</a> for an explanation how to create a <code class="language-plaintext highlighter-rouge">MongoClient</code>.</p>

<h3 id="id-attribute">Id attribute</h3>

<p>It is highly recommended to have explicit <code class="language-plaintext highlighter-rouge">_id</code> field for MongoDB documents. Use the <code class="language-plaintext highlighter-rouge">@Mongo.Id</code>
annotation to declare an <code class="language-plaintext highlighter-rouge">id</code> attribute. The <code class="language-plaintext highlighter-rouge">@Mongo.Id</code> annotation acts as an alias to
<code class="language-plaintext highlighter-rouge">@Gson.Named("_id")</code>, which can also be used.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nd">@Value</span><span class="o">.</span><span class="na">Immutable</span>
<span class="nd">@Gson</span><span class="o">.</span><span class="na">TypeAdapters</span>
<span class="nd">@Mongo</span><span class="o">.</span><span class="na">Repository</span><span class="o">(</span><span class="s">"user"</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">abstract</span> <span class="kd">class</span> <span class="nc">UserDocument</span> <span class="o">{</span>
  <span class="nd">@Mongo</span><span class="o">.</span><span class="na">Id</span>
  <span class="kd">public</span> <span class="kd">abstract</span> <span class="kt">int</span> <span class="nf">id</span><span class="o">();</span>
  <span class="o">...</span>
<span class="o">}</span>
</code></pre></div></div>

<p>An identifier attribute can be of any type that is marshaled to a valid BSON type that can
be used as <code class="language-plaintext highlighter-rouge">_id</code> field in MongoDB. The Java attribute name is irrelevant as long as it will be
generated marshaled as <code class="language-plaintext highlighter-rouge">_id</code> (annotated with <code class="language-plaintext highlighter-rouge">@Gson.Named("_id")</code> or <code class="language-plaintext highlighter-rouge">@Mongo.Id</code>).</p>

<p>In some cases you may need to use special type <code class="language-plaintext highlighter-rouge">ObjectID</code> for <code class="language-plaintext highlighter-rouge">_id</code> or other fields. In order to
do this, <em>Immutables</em> provides the wrapper type <code class="language-plaintext highlighter-rouge">org.immutables.mongo.types.Id</code>. Use the static
factory methods of <code class="language-plaintext highlighter-rouge">org.immutables.mongo.types.Id</code> class to construct instances that correspond
to MongoDB’ <code class="language-plaintext highlighter-rouge">ObjectID</code>. Here’s example of an auto-generated identifier:</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">org.immutables.value.Value</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.immutables.gson.Gson</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.immutables.mongo.Mongo</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.immutables.mongo.types.Id</span><span class="o">;</span>

<span class="nd">@Value</span><span class="o">.</span><span class="na">Immutable</span>
<span class="nd">@Gson</span><span class="o">.</span><span class="na">TypeAdapters</span>
<span class="nd">@Mongo</span><span class="o">.</span><span class="na">Repository</span><span class="o">(</span><span class="s">"events"</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">abstract</span> <span class="kd">class</span> <span class="nc">EventRecord</span> <span class="o">{</span>
  <span class="nd">@Mongo</span><span class="o">.</span><span class="na">Id</span>
  <span class="nd">@Value</span><span class="o">.</span><span class="na">Default</span>
  <span class="kd">public</span> <span class="nc">Id</span> <span class="nf">id</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="nc">Id</span><span class="o">.</span><span class="na">generate</span><span class="o">();</span>
  <span class="o">}</span>
  <span class="o">...</span>
<span class="o">}</span>
</code></pre></div></div>

<hr />
<p>BSON/JSON documents
—-</p>

<p>Reading and writing mongo documents requries conversion into <a href="http://bson.org">BSON format</a>. 
Immutables provides BSON adapters for common JSON libraries like <a href="#jackson">Jackson</a> (experimental) and <a href="#gson">GSON</a> so users can
reuse their mapping API while persisting objects in binary (BSON) format.</p>

<p>For historical reasons, GSON is used by default for mongo repositories. 
However, it is possible to register any CodecRegistry 
(even <a href="http://mongodb.github.io/mongo-java-driver/3.8/bson/pojos/">PojoCodec</a>). 
Internally, Jackson and Gson have their own CodecRegistry implementations.</p>

<p><a name="gson"></a></p>
<h4 id="gson">GSON</h4>

<p>All values used to model documents should have GSON type adapters registered. Use
<code class="language-plaintext highlighter-rouge">@Gson.TypeAdapters</code> on types or packages to generate type adapters for enclosed value types. When
using <code class="language-plaintext highlighter-rouge">RepositorySetup.forUri</code>, all type adapters will be auto-registered from the classpath. When
using custom <code class="language-plaintext highlighter-rouge">RepositorySetup</code>, register type adapters on a <code class="language-plaintext highlighter-rouge">Gson</code> instance using <code class="language-plaintext highlighter-rouge">GsonBuilder</code>
as shown in <a href="json.html#adapter-registration">GSON guide</a>.</p>

<p>A large portion of the things you need to know to create MongoDB mapped documents with GSON is described in
<a href="json.html#gson">GSON guide</a></p>

<p><a name="jackson"></a></p>
<h4 id="jackson-experimental">Jackson (experimental)</h4>

<p>Since release <a href="https://github.com/immutables/immutables#272-2018-11-05">2.7.2</a> immutables has added 
<strong>experimental support</strong> for jackson. You can use provided helper classes to bridge between <a href="https://fasterxml.github.io/jackson-databind/javadoc/2.8/com/fasterxml/jackson/databind/ObjectMapper.html">ObjectMapper</a> and <a href="http://mongodb.github.io/mongo-java-driver/3.8/bson/codecs/">CodecRegistry</a> as shown below:</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nc">ObjectMapper</span> <span class="n">mapper</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">ObjectMapper</span><span class="o">()</span>
       <span class="c1">// support for mongo driver (bson) specific types like Document, DBObject etc.</span>
      <span class="o">.</span><span class="na">registerModule</span><span class="o">(</span><span class="nc">JacksonCodecs</span><span class="o">.</span><span class="na">module</span><span class="o">(</span><span class="nc">MongoClient</span><span class="o">.</span><span class="na">getDefaultCodecRegistry</span><span class="o">()))</span>
      <span class="o">.</span><span class="na">registerModule</span><span class="o">(</span><span class="k">new</span> <span class="nc">GuavaModule</span><span class="o">());</span>

<span class="nc">RepositorySetup</span> <span class="n">setup</span> <span class="o">=</span> <span class="nc">RepositorySetup</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
      <span class="o">.</span><span class="na">database</span><span class="o">(</span><span class="n">database</span><span class="o">)</span>
      <span class="o">.</span><span class="na">codecRegistry</span><span class="o">(</span><span class="nc">JacksonCodecs</span><span class="o">.</span><span class="na">registryFromMapper</span><span class="o">(</span><span class="n">mapper</span><span class="o">))</span>
      <span class="c1">// ...</span>
      <span class="o">.</span><span class="na">build</span><span class="o">();</span>
</code></pre></div></div>

<p>Jackson adapter for CodecRegistry will delegate all calls to native <a href="http://mongodb.github.io/mongo-java-driver/3.9/bson/readers-and-writers/">BsonReader and BsonWriter</a> without intermediate object reprsentation (eg. String or byte[]) thus avoiding extra parsing and memory allocation.</p>

<p>Please note that jackson support is marked as <a href="https://google.github.io/guava/releases/21.0/api/docs/com/google/common/annotations/Beta.html">@Beta</a> so API is subject to change or even removal.</p>

<hr />
<p>Operations
———-</p>

<h4 id="sample-document-repository">Sample document repository</h4>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nd">@Value</span><span class="o">.</span><span class="na">Immutable</span>
<span class="nd">@Gson</span><span class="o">.</span><span class="na">TypeAdapters</span>
<span class="nd">@Mongo</span><span class="o">.</span><span class="na">Repository</span><span class="o">(</span><span class="s">"posts"</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">abstract</span> <span class="kd">class</span> <span class="nc">PostDocument</span> <span class="o">{</span>
  <span class="nd">@Mongo</span><span class="o">.</span><span class="na">Id</span>
  <span class="kd">public</span> <span class="kd">abstract</span> <span class="kt">long</span> <span class="nf">id</span><span class="o">();</span>
  <span class="kd">public</span> <span class="kd">abstract</span> <span class="nc">String</span> <span class="nf">content</span><span class="o">();</span>
  <span class="kd">public</span> <span class="kd">abstract</span> <span class="nc">List</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">&gt;</span> <span class="nf">ratings</span><span class="o">();</span>
  <span class="nd">@Value</span><span class="o">.</span><span class="na">Default</span>
  <span class="kd">public</span> <span class="kt">int</span> <span class="nf">version</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="mi">0</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">}</span>

<span class="c1">// Instantiate generated repository</span>
<span class="nc">PostDocumentRepository</span> <span class="n">posts</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">PostDocumentRepository</span><span class="o">(</span>
    <span class="nc">RepositorySetup</span><span class="o">.</span><span class="na">forUri</span><span class="o">(</span><span class="s">"mongodb://localhost/test"</span><span class="o">));</span>

</code></pre></div></div>

<h3 id="insert-documents">Insert documents</h3>
<p>Insert single or iterable of documents using <code class="language-plaintext highlighter-rouge">insert</code> methods.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">posts</span><span class="o">.</span><span class="na">insert</span><span class="o">(</span>
    <span class="nc">ImmutablePostDocument</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
        <span class="o">.</span><span class="na">id</span><span class="o">(</span><span class="mi">1</span><span class="o">)</span>
        <span class="o">.</span><span class="na">content</span><span class="o">(</span><span class="s">"a"</span><span class="o">)</span>
        <span class="o">.</span><span class="na">build</span><span class="o">());</span>

<span class="n">posts</span><span class="o">.</span><span class="na">insert</span><span class="o">(</span>
    <span class="nc">ImmutableList</span><span class="o">.</span><span class="na">of</span><span class="o">(</span>
        <span class="nc">ImmutablePostDocument</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
            <span class="o">.</span><span class="na">id</span><span class="o">(</span><span class="mi">2</span><span class="o">)</span>
            <span class="o">.</span><span class="na">content</span><span class="o">(</span><span class="s">"b"</span><span class="o">)</span>
            <span class="o">.</span><span class="na">build</span><span class="o">(),</span>
        <span class="nc">ImmutablePostDocument</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
            <span class="o">.</span><span class="na">id</span><span class="o">(</span><span class="mi">3</span><span class="o">)</span>
            <span class="o">.</span><span class="na">content</span><span class="o">(</span><span class="s">"c"</span><span class="o">)</span>
            <span class="o">.</span><span class="na">build</span><span class="o">(),</span>
        <span class="nc">ImmutablePostDocument</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
            <span class="o">.</span><span class="na">id</span><span class="o">(</span><span class="mi">4</span><span class="o">)</span>
            <span class="o">.</span><span class="na">content</span><span class="o">(</span><span class="s">"d"</span><span class="o">)</span>
            <span class="o">.</span><span class="na">build</span><span class="o">()));</span>
</code></pre></div></div>

<h3 id="upsert-document">Upsert document</h3>

<p>Update or insert full document content by <code class="language-plaintext highlighter-rouge">_id</code> using the <code class="language-plaintext highlighter-rouge">upsert</code> method:</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">posts</span><span class="o">.</span><span class="na">upsert</span><span class="o">(</span>
    <span class="nc">ImmutablePostDocument</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
        <span class="o">.</span><span class="na">id</span><span class="o">(</span><span class="mi">1</span><span class="o">)</span>
        <span class="o">.</span><span class="na">content</span><span class="o">(</span><span class="s">"a1"</span><span class="o">)</span>
        <span class="o">.</span><span class="na">build</span><span class="o">());</span>

<span class="n">posts</span><span class="o">.</span><span class="na">upsert</span><span class="o">(</span>
    <span class="nc">ImmutablePostDocument</span><span class="o">.</span><span class="na">builder</span><span class="o">()</span>
        <span class="o">.</span><span class="na">id</span><span class="o">(</span><span class="mi">10</span><span class="o">)</span>
        <span class="o">.</span><span class="na">content</span><span class="o">(</span><span class="s">"!!!"</span><span class="o">)</span>
        <span class="o">.</span><span class="na">addRatings</span><span class="o">(</span><span class="mi">2</span><span class="o">)</span>
        <span class="o">.</span><span class="na">build</span><span class="o">());</span>

</code></pre></div></div>

<p>If document with <code class="language-plaintext highlighter-rouge">_id</code> 10 is not found, then it will be created, otherwise updated.</p>

<h3 id="find-documents">Find documents</h3>

<p>To find a document, you need to provide criteria object. Search criteria objects are generated to reflect fields of
the document. Empty criteria objects are obtained by using the <code class="language-plaintext highlighter-rouge">criteria()</code> static factory method on a generated repository.
Criteria objects are immutable and can be stored as constants or otherwise safely passed around.
Criteria objects have methods corresponding to document attributes and relevant constraints.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nc">Criteria</span> <span class="n">where</span> <span class="o">=</span> <span class="n">posts</span><span class="o">.</span><span class="na">criteria</span><span class="o">();</span>

<span class="nc">List</span><span class="o">&lt;</span><span class="nc">PostDocument</span><span class="o">&gt;</span> <span class="n">documents</span> <span class="o">=</span>
    <span class="n">posts</span><span class="o">.</span><span class="na">find</span><span class="o">(</span><span class="n">where</span><span class="o">.</span><span class="na">contentStartsWith</span><span class="o">(</span><span class="s">"a"</span><span class="o">))</span>
        <span class="o">.</span><span class="na">fetchAll</span><span class="o">()</span>
        <span class="o">.</span><span class="na">getUnchecked</span><span class="o">();</span>

<span class="nc">Optional</span><span class="o">&lt;</span><span class="nc">PostDocument</span><span class="o">&gt;</span> <span class="n">document</span> <span class="o">=</span>
    <span class="n">posts</span><span class="o">.</span><span class="na">find</span><span class="o">(</span>
        <span class="n">where</span><span class="o">.</span><span class="na">content</span><span class="o">(</span><span class="s">"!!!"</span><span class="o">)</span>
            <span class="o">.</span><span class="na">ratingsNonEmpty</span><span class="o">())</span>
        <span class="o">.</span><span class="na">fetchFirst</span><span class="o">()</span>
        <span class="o">.</span><span class="na">getUnchecked</span><span class="o">();</span>

<span class="nc">List</span><span class="o">&lt;</span><span class="nc">PostDocument</span><span class="o">&gt;</span> <span class="n">limited</span> <span class="o">=</span>
    <span class="n">posts</span><span class="o">.</span><span class="na">find</span><span class="o">(</span>
        <span class="n">where</span><span class="o">.</span><span class="na">contentStartsWith</span><span class="o">(</span><span class="s">"a"</span><span class="o">)</span>
            <span class="o">.</span><span class="na">or</span><span class="o">()</span>
            <span class="o">.</span><span class="na">contentStartsWith</span><span class="o">(</span><span class="s">"b"</span><span class="o">))</span>
        <span class="o">.</span><span class="na">orderById</span><span class="o">()</span>
        <span class="o">.</span><span class="na">skip</span><span class="o">(</span><span class="mi">5</span><span class="o">)</span>
        <span class="o">.</span><span class="na">fetchWithLimit</span><span class="o">(</span><span class="mi">10</span><span class="o">)</span>
        <span class="o">.</span><span class="na">getUnchecked</span><span class="o">();</span>
</code></pre></div></div>

<p>With each constraint, a new immutable criteria is returned which composes constraints with the <em>and</em> logic. Constraints
can be composed with <em>or</em> logic by explicitly delimiting with <code class="language-plaintext highlighter-rouge">.or()</code> method,
effectively forming <a href="http://en.wikipedia.org/wiki/Disjunctive_normal_form">DNF</a> consisting of constraints.</p>

<p>The <code class="language-plaintext highlighter-rouge">find</code> method returns an uncompleted operation, which is subject to configuration via <code class="language-plaintext highlighter-rouge">Finder</code> object methods,
discover these configuration methods, use them as needed, then invoke finalizing operation which returns <em>future</em>
of result.</p>

<h4 id="simple-find-methods">Simple find methods</h4>

<p>For convenience, there are methods to lookup by <code class="language-plaintext highlighter-rouge">_id</code> and to find all documents. These methods do not need criteria objects.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">posts</span><span class="o">.</span><span class="na">findById</span><span class="o">(</span><span class="mi">10</span><span class="o">).</span><span class="na">fetchFirst</span><span class="o">();</span>

<span class="c1">// Fetch all? Ok</span>
<span class="n">posts</span><span class="o">.</span><span class="na">findAll</span><span class="o">().</span><span class="na">fetchAll</span><span class="o">();</span>
</code></pre></div></div>

<p>Note that <code class="language-plaintext highlighter-rouge">findById</code> method might be named differently if your document has its attribute with a name other than <code class="language-plaintext highlighter-rouge">id</code>
in Java.</p>

<h3 id="excluding-output-fields">Excluding output fields</h3>

<p>MongoDB has a feature to return a subset of fields in results. In order to preserve the consistency of immutable
document objects created during unmarshaling, a repository only allows the exclusion of optional fields such
as <a href="immutable.html#collection">collection attributes</a> and <a href="immutable.html#optional">optional attributes</a>.
Use <code class="language-plaintext highlighter-rouge">exclude*</code> methods on <code class="language-plaintext highlighter-rouge">Finder</code> objects to configure attribute exclusion.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">boolean</span> <span class="n">isTrue</span> <span class="o">=</span>
    <span class="n">posts</span><span class="o">.</span><span class="na">findById</span><span class="o">(</span><span class="mi">10</span><span class="o">)</span>
        <span class="o">.</span><span class="na">excludeRatings</span><span class="o">()</span>
        <span class="o">.</span><span class="na">fetchFirst</span><span class="o">()</span>
        <span class="o">.</span><span class="na">getUnchecked</span><span class="o">()</span>
        <span class="o">.</span><span class="na">ratings</span><span class="o">()</span>
        <span class="o">.</span><span class="na">isEmpty</span><span class="o">();</span>
</code></pre></div></div>

<h3 id="sorting-result">Sorting result</h3>

<p>Use <code class="language-plaintext highlighter-rouge">Finder</code> to specify ordering by attributes and direction. Ordering is used for fetching results as well
as finding the first matching object to modify.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">posts</span><span class="o">.</span><span class="na">find</span><span class="o">(</span><span class="n">where</span><span class="o">.</span><span class="na">contentNot</span><span class="o">(</span><span class="s">"b"</span><span class="o">))</span>
    <span class="o">.</span><span class="na">orderByContent</span><span class="o">()</span>
    <span class="o">.</span><span class="na">orderByIdDesceding</span><span class="o">()</span>
    <span class="o">.</span><span class="na">deleteFirst</span><span class="o">();</span>

<span class="n">posts</span><span class="o">.</span><span class="na">findAll</span><span class="o">()</span>
    <span class="o">.</span><span class="na">orderByContent</span><span class="o">()</span>
    <span class="o">.</span><span class="na">fetchWithLimit</span><span class="o">(</span><span class="mi">10</span><span class="o">);</span>
</code></pre></div></div>

<h3 id="delete-documents">Delete documents</h3>

<p>Looking for delete operations? Well, we found good place for them, but probably not a very obvious one!</p>

<p>Delete operations are defined on the same <code class="language-plaintext highlighter-rouge">Finder</code> object:</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">posts</span><span class="o">.</span><span class="na">findById</span><span class="o">(</span><span class="mi">1</span><span class="o">).</span><span class="na">deleteFirst</span><span class="o">();</span>

<span class="kt">int</span> <span class="n">deletedDocumentsCount</span> <span class="o">=</span> <span class="n">posts</span><span class="o">.</span><span class="na">find</span><span class="o">(</span><span class="n">where</span><span class="o">.</span><span class="na">content</span><span class="o">(</span><span class="s">""</span><span class="o">))</span>
    <span class="o">.</span><span class="na">deleteAll</span><span class="o">()</span>
    <span class="o">.</span><span class="na">getUnchecked</span><span class="o">();</span>

<span class="c1">// Delete all? Ok</span>
<span class="n">posts</span><span class="o">.</span><span class="na">findAll</span><span class="o">().</span><span class="na">deleteAll</span><span class="o">();</span>
</code></pre></div></div>

<h3 id="update-and-findandmodify">Update and FindAndModify</h3>

<p>Update, find, and modify operations support incremental updates of the documents matching a criteria.
Incremental update operations are used to update particular fields. Some fields may need to be initialized
if a document is to be created via upsert operation.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nc">Optional</span><span class="o">&lt;</span><span class="nc">PostDocument</span><span class="o">&gt;</span> <span class="n">updatedDocument</span> <span class="o">=</span>
    <span class="n">posts</span><span class="o">.</span><span class="na">findById</span><span class="o">(</span><span class="mi">2</span><span class="o">)</span>
        <span class="o">.</span><span class="na">andModifyFirst</span><span class="o">()</span>
        <span class="o">.</span><span class="na">addRatings</span><span class="o">(</span><span class="mi">5</span><span class="o">)</span>
        <span class="o">.</span><span class="na">setContent</span><span class="o">(</span><span class="s">"bbb"</span><span class="o">)</span>
        <span class="o">.</span><span class="na">returningNew</span><span class="o">()</span>
        <span class="o">.</span><span class="na">update</span><span class="o">()</span>
        <span class="o">.</span><span class="na">getUnchecked</span><span class="o">();</span>

<span class="n">posts</span><span class="o">.</span><span class="na">update</span><span class="o">(</span><span class="n">where</span><span class="o">.</span><span class="na">ratingsEmpty</span><span class="o">())</span>
    <span class="o">.</span><span class="na">addRatings</span><span class="o">(</span><span class="mi">3</span><span class="o">)</span>
    <span class="o">.</span><span class="na">updateAll</span><span class="o">();</span>

<span class="n">posts</span><span class="o">.</span><span class="na">findById</span><span class="o">(</span><span class="mi">111</span><span class="o">)</span>
    <span class="o">.</span><span class="na">andModifyFirst</span><span class="o">()</span>
    <span class="o">.</span><span class="na">incrementVersion</span><span class="o">(</span><span class="mi">1</span><span class="o">)</span>
    <span class="o">.</span><span class="na">initContent</span><span class="o">(</span><span class="s">"2"</span><span class="o">)</span>
    <span class="o">.</span><span class="na">addRatings</span><span class="o">(</span><span class="mi">5</span><span class="o">)</span>
    <span class="o">.</span><span class="na">upsert</span><span class="o">();</span>
</code></pre></div></div>

<h3 id="read-only-repositories">Read-only repositories</h3>
<p>For usecases when only read operations are required one can customize repository generation with <code class="language-plaintext highlighter-rouge">readonly</code> annotation parameter.
When set to <code class="language-plaintext highlighter-rouge">true</code> (it is <code class="language-plaintext highlighter-rouge">false</code> by default) write, delete and update methods will not be available:</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nd">@Value</span><span class="o">.</span><span class="na">Immutable</span>
<span class="nd">@Mongo</span><span class="o">.</span><span class="na">Repository</span><span class="o">(</span><span class="n">readonly</span> <span class="o">=</span> <span class="kc">true</span><span class="o">)</span> <span class="c1">// don't generate any write / delete / update methods</span>
<span class="kd">public</span> <span class="kd">abstract</span> <span class="kd">class</span> <span class="nc">Item</span> <span class="o">{</span>
  <span class="c1">// ...</span>
<span class="o">}</span>
</code></pre></div></div>

<p>To omit indexing operations use <code class="language-plaintext highlighter-rouge">index = false</code> parameter (indexing is enabled by default).</p>

<h3 id="ensure-index">Ensure Index</h3>

<p>If you want to ensure indices using code rather than the administrative tools,
you can use an <code class="language-plaintext highlighter-rouge">Indexer</code> object, which ensures indexing with particular fields.
See the methods of <code class="language-plaintext highlighter-rouge">Indexer</code> object.</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
<span class="c1">// Compound index on content and ratings</span>
<span class="n">posts</span><span class="o">.</span><span class="na">index</span><span class="o">()</span>
    <span class="o">.</span><span class="na">withContent</span><span class="o">()</span>
    <span class="o">.</span><span class="na">withRatings</span><span class="o">()</span>
    <span class="o">.</span><span class="na">ensure</span><span class="o">();</span>

<span class="c1">// Reversed index on content</span>
<span class="n">posts</span><span class="o">.</span><span class="na">index</span><span class="o">()</span>
    <span class="o">.</span><span class="na">withContentDesceding</span><span class="o">()</span>
    <span class="o">.</span><span class="na">ensure</span><span class="o">();</span>
</code></pre></div></div>

</section>
<footer class="jumbotron">
  <div class="container">
    <h2 id="guides">Guides</h2>

<ul>
  <li><a href="/getstarted.html">Get started!</a></li>
  <li><a href="/intro.html">Inception</a></li>
  <li><a href="/immutable.html">Immutable objects</a></li>
  <li><a href="/factory.html">Factory builders</a></li>
  <li><a href="/functional.html">Functions and Predicates (for Java 7)</a></li>
  <li><a href="/style.html">Style customization</a></li>
  <li><a href="/json.html">JSON serialization</a></li>
  <li><a href="/criteria.html">Criteria</a></li>
  <li><a href="/mongo.html">MongoDB repositories</a></li>
  <li><a href="/dynamodb.html">DynamoDB integration</a></li>
  <li><a href="/encoding.html">Encoding: Customizing attributes and builders (experimental)</a></li>
  <li><a href="/apt.html">Using annotation processor in IDE</a></li>
</ul>

<h2 id="get-involved">Get involved</h2>

<ul>
  <li>Clone source repository, contribute bug reports and fixes on <a href="https://github.com/immutables/immutables">GitHub immutables/immutables</a></li>
  <li>Issue reports, questions and feedback is welcome on issue tracker <a href="https://github.com/immutables/immutables/issues">GitHub immutables/immutables/issues</a></li>
  <li>News and announcements on twitter <a href="https://twitter.com/ImmutablesOrg">@ImmutablesOrg</a></li>
</ul>

<p><a href="/license.html">Apache License 2.0</a></p>

    <!--<div><h2>Posts</h2>
      <ul>
        
      </ul>
    </div>-->
  </div>
</footer>
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
<script defer src="/gfx/jquery.toc.min.js"></script>
<script>
$(function() {
  $('#toc').toc({
    container: '.documentation',
    selectors: 'h1,h2,h3,h4',
    anchorName: function(i, heading, prefix) {
      heading = $(heading).text();
      if (heading.trim) heading = heading.trim();
      return heading.toLowerCase().replace(/ /g, '-').replace(/[^a-z^\-]+/g, '');
    },
  })
})
</script>
</body>
</html>