Apache Ignite Documentation

GridGain Developer Hub - Apache Ignitetm

Welcome to the Apache Ignite developer hub run by GridGain. Here you'll find comprehensive guides and documentation to help you start working with Apache Ignite as quickly as possible, as well as support if you get stuck.

 

GridGain also provides Community Edition which is a distribution of Apache Ignite made available by GridGain. It is the fastest and easiest way to get started with Apache Ignite. The Community Edition is generally more stable than the Apache Ignite release available from the Apache Ignite website and may contain extra bug fixes and features that have not made it yet into the release on the Apache website.

 

Let's jump right in!

 

Documentation     Ask a Question     Download

 

Javadoc     Scaladoc     Examples

Automatic Persistence

Automatically read-through and write-through your domain model to and from database.

Ignite ships with its own database schema mapping wizard which provides automatic support for integrating with persistence stores. This utility automatically connects to the underlying database and generates all the required XML OR-mapping configuration and Java domain model POJOs.

Ignite also ships with org.apache.ignite.cache.store.jdbc.CacheJdbcPojoStore, which is out-of-the-box JDBC implementation of the IgniteCacheStore interface, and automatically handles all the write-through and read-through logic.

Database Schema Import

To start the wizard for generating database schema mapping, execute bin/ignite-schema-import.sh script:

$ bin/ignite-schema-import.sh

This command will bring up a UI wizard which will take you through a couple of screens.

Connect To Database

The first screen will ask you for database connectivity settings. Note that JDBC drivers are not supplied with the utility and should be provided separately.

Generate XML Configuration and POJOs

The second screen allows to map database tables to domain model classes and automatically generates XML configurations and POJOs.

Generated Artifacts

The utility generates the following artifacts:

  • Java POJO key and value classes.
  • XML CacheTypeMetadata configuration.
  • ConfigurationSnippet.java (alternative to XML).

After you exit from the wizard, you should

  1. Copy generated POJO java classes to you project source folder.
  2. Copy XML declaration of CacheTypeMetadata to your Ignite XML configuration file under appropriate CacheConfiguration root.
  3. Use ConfigurationSnippet.java in your Ignite initialization logic.
/**
 * PersonKey definition.
 *
 * Code generated by Apache Ignite Schema Import utility: 03/03/2015.
 */
public class PersonKey implements Serializable {
    /** */
    private static final long serialVersionUID = 0L;

    /** Value for id. */
    private int id;

    /**
     * Gets id.
     *
     * @return Value for id.
     */
    public int getId() {
        return id;
    }

    /**
     * Sets id.
     *
     * @param id New value for id.
     */
    public void setId(int id) {
        this.id = id;
    }

    /** {@inheritDoc} */
    @Override public boolean equals(Object o) {
        if (this == o)
            return true;

        if (!(o instanceof PersonKey))
            return false;

        PersonKey that = (PersonKey)o;

        if (id != that.id)
            return false;

        return true;
    }

    /** {@inheritDoc} */
    @Override public int hashCode() {
        int res = id;

        return res;
    }

    /** {@inheritDoc} */
    @Override public String toString() {
        return "PersonKey [id=" + id +
            "]";
    }
}
/**
 * Person definition.
 *
 * Code generated by Apache Ignite Schema Import utility: 03/03/2015.
 */
public class Person implements Serializable {
    /** */
    private static final long serialVersionUID = 0L;

    /** Value for id. */
    private int id;

    /** Value for orgId. */
    private Integer orgId;

    /** Value for name. */
    private String name;

    /**
     * Gets id.
     *
     * @return Value for id.
     */
    public int getId() {
        return id;
    }

    /**
     * Sets id.
     *
     * @param id New value for id.
     */
    public void setId(int id) {
        this.id = id;
    }

    /**
     * Gets orgId.
     *
     * @return Value for orgId.
     */
    public Integer getOrgId() {
        return orgId;
    }

    /**
     * Sets orgId.
     *
     * @param orgId New value for orgId.
     */
    public void setOrgId(Integer orgId) {
        this.orgId = orgId;
    }

    /**
     * Gets name.
     *
     * @return Value for name.
     */
    public String getName() {
        return name;
    }

    /**
     * Sets name.
     *
     * @param name New value for name.
     */
    public void setName(String name) {
        this.name = name;
    }

    /** {@inheritDoc} */
    @Override public boolean equals(Object o) {
        if (this == o)
            return true;

        if (!(o instanceof Person))
            return false;

        Person that = (Person)o;

        if (id != that.id)
            return false;

        if (orgId != null ? !orgId.equals(that.orgId) : that.orgId != null)
            return false;

        if (name != null ? !name.equals(that.name) : that.name != null)
            return false;

        return true;
    }

    /** {@inheritDoc} */
    @Override public int hashCode() {
        int res = id;

        res = 31 * res + (orgId != null ? orgId.hashCode() : 0);

        res = 31 * res + (name != null ? name.hashCode() : 0);

        return res;
    }

    /** {@inheritDoc} */
    @Override public String toString() {
        return "Person [id=" + id +
            ", orgId=" + orgId +
            ", name=" + name +
            "]";
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:util="http://www.springframework.org/schema/util"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
                           http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/util
                           http://www.springframework.org/schema/util/spring-util.xsd">
    <bean class="org.apache.ignite.cache.CacheTypeMetadata">
        <property name="databaseSchema" value="PUBLIC"/>
        <property name="databaseTable" value="PERSON"/>
        <property name="keyType" value="org.apache.ignite.examples.datagrid.store.model.PersonKey"/>
        <property name="valueType" value="org.apache.ignite.examples.datagrid.store.model.Person"/>
        <property name="keyFields">
            <list>
                <bean class="org.apache.ignite.cache.CacheTypeFieldMetadata">
                    <property name="databaseName" value="ID"/>
                    <property name="databaseType">
                        <util:constant static-field="java.sql.Types.INTEGER"/>
                    </property>
                    <property name="javaName" value="id"/>
                    <property name="javaType" value="int"/>
                </bean>
            </list>
        </property>
        <property name="valueFields">
            <list>
                <bean class="org.apache.ignite.cache.CacheTypeFieldMetadata">
                    <property name="databaseName" value="ID"/>
                    <property name="databaseType">
                        <util:constant static-field="java.sql.Types.INTEGER"/>
                    </property>
                    <property name="javaName" value="id"/>
                    <property name="javaType" value="int"/>
                </bean>
                <bean class="org.apache.ignite.cache.CacheTypeFieldMetadata">
                    <property name="databaseName" value="ORG_ID"/>
                    <property name="databaseType">
                        <util:constant static-field="java.sql.Types.INTEGER"/>
                    </property>
                    <property name="javaName" value="orgId"/>
                    <property name="javaType" value="java.lang.Integer"/>
                </bean>
                <bean class="org.apache.ignite.cache.CacheTypeFieldMetadata">
                    <property name="databaseName" value="NAME"/>
                    <property name="databaseType">
                        <util:constant static-field="java.sql.Types.VARCHAR"/>
                    </property>
                    <property name="javaName" value="name"/>
                    <property name="javaType" value="java.lang.String"/>
                </bean>
            </list>
        </property>
    </bean>
</beans>
/**
 * ConfigurationSnippet definition.
 *
 * Code generated by Apache Ignite Schema Import utility: 03/22/2015.
 */
public class ConfigurationSnippet {
  /** Configure cache store. */
  public static CacheStore store() {
    DataSource dataSource = null; // TODO create data source.

    CacheJdbcPojoStore store = new CacheJdbcPojoStore();
    store.setDataSource(dataSource);

    return store;
  }

  /** Configure cache types metadata. */
  public static Collection<CacheTypeMetadata> typeMetadata() {
    // Configure cache types. 
    Collection<CacheTypeMetadata> meta = new ArrayList<>();

    // PERSON.
    CacheTypeMetadata type = new CacheTypeMetadata();
    type.setDatabaseSchema("PUBLIC");
    type.setDatabaseTable("PERSON");
    type.setKeyType("org.apache.ignite.PersonKey");
    type.setValueType("org.apache.ignite.Person");

    meta.add(type);

    // Key fields for PERSON.
    Collection<CacheTypeFieldMetadata> keys = new ArrayList<>();
    keys.add(new CacheTypeFieldMetadata("ID", Types.INTEGER, "id", int.class));
    type.setKeyFields(keys);

    // Value fields for PERSON.
    Collection<CacheTypeFieldMetadata> vals = new ArrayList<>();
    vals.add(new CacheTypeFieldMetadata("ID", Types.INTEGER, "id", int.class));
    vals.add(new CacheTypeFieldMetadata("FIRST_NAME", Types.VARCHAR, "firstName", String.class));
    vals.add(new CacheTypeFieldMetadata("LAST_NAME", Types.VARCHAR, "lastName", String.class));
    type.setValueFields(vals);


    return meta;
  }
}

CacheJdbcPojoStore

After you generate XML and POJOs in wizard and copy all necessary stuff into your project you could use CacheJdbcPojoStore to load data from database into cache and write data from cache into database.

First you need to properly declare store in configuration:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
...
 <!-- Cache configuration. -->
 <property name="cacheConfiguration">
  <list>
   <bean class="org.apache.ignite.configuration.CacheConfiguration">
    ...
    <!-- Cache store. -->
    <property name="cacheStoreFactory">
     <bean class="javax.cache.configuration.FactoryBuilder$SingletonFactory">
      <constructor-arg>
       <bean class="org.apache.ignite.cache.store.jdbc.CacheJdbcPojoStore">
        <property name="dataSource">
         <!-- Sample datasource: in-memory H2 database -->
         <property name="dataSource">
          <bean class="org.h2.jdbcx.JdbcConnectionPool" factory-method="create">
           <constructor-arg value="jdbc:h2:tcp://localhost/mem:ExampleDb"/>
           <constructor-arg value="sa"/>
           <constructor-arg value=""/>
          </bean>
         </property>
        </property>
       </bean>
      </constructor-arg>
     </bean>
    </property>

     <!-- Cache types metadata. -->
    <property name="typeMetadata">
     <list>
     ... Copy here types generated by wizard...
     </list>
    </property>
    
    <!-- Enable store usage. --> 
    <!-- Sets flag indicating whether read from database is enabled. -->
    <property name="readThrough" value="true"/>
     
    <!-- Sets flag indicating whether write to database is enabled. -->
    <property name="writeThrough" value="true"/>
     
    <!-- Enable database batching. --> 
    <!-- Sets flag indicating whether write-behind is enabled. -->
    <property name="writeBehindEnabled" value="true/>
  </list>
 </property>
...
</bean>
IgniteConfiguration cfg = new IgniteConfiguration();
...
CacheConfiguration ccfg = new CacheConfiguration<>();

// Create data source for your database.
// For example: in-memory H2 database.
DataSource dataSource = org.h2.jdbcx.JdbcConnectionPool.create("jdbc:h2:tcp://localhost/mem:ExampleDb", "sa", "");

// Create store. 
CacheJdbcPojoStore store = new CacheJdbcPojoStore();
store.setDataSource(dataSource);

// Create store factory. 
ccfg.setCacheStoreFactory(new FactoryBuilder.SingletonFactory<>(store));

// Configure cache to use store. 
ccfg.setReadThrough(true);
ccfg.setWriteThrough(true);

// Enable database batching.
ccfg.setWriteBehindEnabled(true);

cfg.setCacheConfiguration(ccfg);

// Configure cache types. 
Collection<CacheTypeMetadata> meta = new ArrayList<>();
... Paste here code generated by wizard ...
...
// Start Ignite node.
Ignition.start(cfg);

All operations defined in Persistent Store are available in CacheJdbcPojoStore.

CacheJdbcPojoStore can effectively load data. To load all data from database for all types registered in cache configuration - just call IgniteCache.loadCache(null) method. To load data with custom conditions you should pass key types and SQL queries to IgniteCache.loadCache() method. For example:

IgniteCache<Long, Person> c = node.jcache(CACHE_NAME);
c.loadCache(null, "java.lang.Integer", "select * from Person where id > 100");

Example

Example org.apache.ignite.examples.datagrid.store.CacheStoreExample demonstrates usage of cache store.

In order to run example for automatic persistence you need to set CacheNodeWithStoreStartup.STORE = AUTO and run CacheStoreExample.

Demo

Lets do step-by-step demo. You can find demo sources in examples/schema-import folder.

We will use H2 database.

  • Start H2 server with following script:
$  examples/schema-import/bin/h2-server.sh

H2 Console will be started in your default browser.

  • Connect to H2 with following settings:

    • Select Generic H2 (Server) settings.
    • Specify JDBC URL as jdbc:h2:tcp://localhost/~/schema-import/demo.
  • Click Connect.

  • Paste content of examples/schema-import/bin/db-init.sql into H2 Console and execute.

  • Start Schema Import Wizard with properties configured for demo:

 bin/ignite-schema-import.sh examples/schema-import/bin/schema-import.properties
  • Click Next.
  • Click Generate. Answer Yes for override warnings.

POJO files and java snippets will be generated in examples/schema-import/src/main/java/org/apache/ignite/schema folder.

  • Import in your favorite IDE examples/schema-import/pom.xml.

  • Run Demo.java.

Automatic Persistence


Automatically read-through and write-through your domain model to and from database.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.