Руководство по Eclipse JNoSQL

1. обзор

EclipseJNoSQL - это набор API и реализаций, которыеsimplify the interaction of Java applications with NoSQL databases.

В этой статье мы узнаем, как установить и настроить JNoSQL для взаимодействия с базой данных NoSQL. Мы будем работать как со слоем коммуникации, так и со слоем картографии.

2. Коммуникационный уровень Eclipse JNoSQL

Технически говоря, коммуникационный уровень состоит из двух модулей:Diana API and a driver.

While the API defines an abstraction to NoSQL database types, the driver provides implementations for most known databases.

Мы можем сравнить это с JDBC API и драйвером JDBC в реляционных базах данных.

2.1. Eclipse JNoSQL Diana API

Проще говоря, существует четыре основных типа баз данных NoSQL: Key-Value, Column, Document и Graph.

И API Eclipse JNoSQL Diana определяет три модуля:

диана-ключ-значение
диана-колонки
диана-документ

Тип графа NoSQL не покрывается API, потому что он уже охваченApache ThinkerPop.

API основан на базовом модуле diana-core и определяет абстракцию для общих понятий, таких как конфигурация, фабрика, менеджер, сущность и значение.

Для работы с API нам необходимо обеспечить зависимость соответствующего модуля от типа нашей базы данных NoSQL.

Таким образом, для документно-ориентированной базы данных нам понадобится зависимостьdiana-document:


    org.jnosql.diana
    diana-document
    0.0.5

Точно так же мы должны использовать модульdiana-key-value, если рабочая база данных NoSQL ориентирована на ключ-значение:


    org.jnosql.diana
    diana-key-value
    0.0.5

И, наконец, модульdiana-column, если он ориентирован на столбцы:


    org.jnosql.diana
    diana-column
    0.0.5

Самые последние версии можно найти наMaven Central.

2.2. Драйвер Eclipse JNoSQL Diana

The driver is a set of implementations of the API for the most common NoSQL databases.

Для каждой базы данных NoSQL существует одна реализация. If the database is multi-model, the driver should implement all supported APIs.

Например,couchbase-driver реализует какdiana-document, так иdiana-key-value, потому чтоCouchbase ориентирован как на документ, так и на ключ-значение.

В отличие от реляционных баз данных, где драйвер обычно предоставляется поставщиком базы данных, здесьthe driver is provided by Eclipse JNoSQL. В большинстве случаев этот драйвер является оберткой вокруг официальной библиотеки поставщика.

Чтобы начать работу с драйвером, мы должны включить API и соответствующую реализацию для выбранной базы данных NoSQL.

Например, для MongoDB нам необходимо включить следующие зависимости:


    org.jnosql.diana
    diana-document
    0.0.5


    org.jnosql.diana
    mongodb-driver
    0.0.5

Процесс работы с драйвером прост.

Во-первых, нам нужен bean-компонентConfiguration. Читая файл конфигурации из пути к классам или значений жесткого кодирования,Configuration может создатьFactory.. Затем мы используем его для созданияManager.

Finally, The Manager is responsible for pushing and retrieving the Entity to and from the NoSQL database.

В следующих подразделах мы объясним этот процесс для каждого типа базы данных NoSQL.

2.3. Работа с документно-ориентированной базой данных

В этом примереwe’ll be using an embedded MongoDB, поскольку это просто начать работу и не требует установки. Он ориентирован на документы, и следующие инструкции применимы к любой другой документно-ориентированной базе данных NoSQL.

В самом начале мы должны предоставить все необходимые настройки, необходимые приложению для правильного взаимодействия с базой данных. В самом простом виде мы должны предоставитьhost иport для запущенный экземпляр MongoDB.

Мы можем предоставить эти настройки либо вmongodb-driver.properties, расположенном в пути к классам:

#Define Host and Port
mongodb-server-host-1=localhost:27017

Или в виде жестко закодированных значений:

Map map = new HashMap<>();
map.put("mongodb-server-host-1", "localhost:27017");

Затем мы создаем bean-компонентConfiguration для типа документа:

DocumentConfiguration configuration = new MongoDBDocumentConfiguration();

Из этого bean-компонентаConfiguration мы можем создатьManagerFactory:

DocumentCollectionManagerFactory managerFactory = configuration.get();

Неявно методget() бинаConfiguration использует настройки из файла свойств. Мы также можем получить эту фабрику из жестко закодированных значений:

DocumentCollectionManagerFactory managerFactory
  = configuration.get(Settings.of(map));

ManagerFactory имеет простой методget(),, который принимает имя базы данных в качестве параметра и создаетManager:

DocumentCollectionManager manager = managerFactory.get("my-db");

И наконец, мы готовы. Manager предоставляет все необходимые методы для взаимодействия с базовой базой данных NoSQL черезDocumentEntity.

Таким образом, мы могли бы, например, вставить документ:

DocumentEntity documentEntity = DocumentEntity.of("books");
documentEntity.add(Document.of("_id", "100"));
documentEntity.add(Document.of("name", "JNoSQL in Action"));
documentEntity.add(Document.of("pages", "620"));
DocumentEntity saved = manager.insert(documentEntity);

Мы также могли бы искать документы:

DocumentQuery query = select().from("books").where("_id").eq(100).build();
List entities = manager.select(query);

Аналогичным образом мы могли бы обновить существующий документ:

saved.add(Document.of("author", "example"));
DocumentEntity updated = manager.update(saved);

И, наконец, мы можем удалить сохраненный документ:

DocumentDeleteQuery deleteQuery = delete().from("books").where("_id").eq("100").build();
manager.delete(deleteQuery);

Чтобы запустить образец, нам просто нужно получить доступ к модулюjnosql-diana и запустить приложениеDocumentApp.

Мы должны увидеть вывод в консоли:

DefaultDocumentEntity{documents={pages=620, name=JNoSQL in Action, _id=100}, name='books'}
DefaultDocumentEntity{documents={pages=620, author=example, name=JNoSQL in Action, _id=100}, name='books'}
[]

2.4. Работа с колоночной базой данных

В целях этого разделаwe’ll use an embedded version of the Cassandra database, поэтому установка не требуется.

Процесс работы с базой данных, ориентированной на столбцы, очень похож. Прежде всего, мы добавляем драйвер Cassandra и API-интерфейс столбцов в pom:


    org.jnosql.diana
    diana-column
    0.0.5


    org.jnosql.diana
    cassandra-driver
    0.0.5

Далее нам понадобятся параметры конфигурации, указанные в файле конфигурацииdiana-cassandra.properties, и пути к классам. В качестве альтернативы, мы могли бы также использовать жестко закодированные значения конфигурации.

Затем, используя аналогичный подход, мы создадимColumnFamilyManager и начнем управлятьColumnEntity:

ColumnConfiguration configuration = new CassandraConfiguration();
ColumnFamilyManagerFactory managerFactory = configuration.get();
ColumnFamilyManager entityManager = managerFactory.get("my-keySpace");

Итак, чтобы создать новую сущность, давайте вызовем методinsert():

ColumnEntity columnEntity = ColumnEntity.of("books");
Column key = Columns.of("id", 10L);
Column name = Columns.of("name", "JNoSQL in Action");
columnEntity.add(key);
columnEntity.add(name);
ColumnEntity saved = entityManager.insert(columnEntity);

Чтобы запустить образец и увидеть результат в консоли, запустите приложениеColumnFamilyApp.

2.5. Работа с базой данных, ориентированной на ключ-значение

В этом разделе мы будем использовать Hazelcast. Hazelcast is a key-value oriented NoSQL database. Для получения дополнительной информации о базе данных Hazelcast вы можете проверить этотlink.

Процесс работы с типом, ориентированным на ключ-значение, также аналогичен. Начнем с добавления этих зависимостей в pom:


    org.jnosql.diana
    diana-key-value
    0.0.5


    org.jnosql.diana
    hazelcast-driver
    0.0.5

Затем нам нужно предоставить настройки конфигурации. Затем мы можем получитьBucketManager, а затем манипулироватьKeyValueEntity:

KeyValueConfiguration configuration = new HazelcastKeyValueConfiguration();
BucketManagerFactory managerFactory = configuration.get();
BucketManager entityManager = managerFactory.getBucketManager("books");

Допустим, мы хотим сохранить следующую модельBook:

public class Book implements Serializable {

    private String isbn;
    private String name;
    private String author;
    private int pages;

    // standard constructor
    // standard getters and setters
}

Итак, мы создаем экземплярBook, а затем сохраняем его, вызывая методput();

Book book = new Book(
  "12345", "JNoSQL in Action",
  "example", 420);
KeyValueEntity keyValueEntity = KeyValueEntity.of(
  book.getIsbn(), book);
entityManager.put(keyValueEntity);

Затем, чтобы получить сохраненный экземплярBook:

Optional optionalValue = manager.get("12345");
Value value = optionalValue.get(); // or any other adequate Optional handling
Book savedBook = value.get(Book.class);

Чтобы запустить образец и увидеть результат в консоли, запустите приложениеKeyValueApp.

3. Уровень отображения Eclipse JNoSQL

The mapping layer, Artemis API, is a set of APIs that help map java annotated Objects to NoSQL databases. Он основан на API Diana и CDI (внедрение контекста и зависимостей).

We can consider this API as JPA or ORM like for the NoSQL world. Этот уровень также предоставляет API для каждого типа NoSQL и один базовый API для общих функций.

В этом разделе мы собираемся работать с документно-ориентированной базой данных MongoDB.

3.1. Требуемые зависимости

Чтобы включить Artemis в приложении, нам нужно добавить зависимостьartemis-configuration. Поскольку MongoDB ориентирована на документы, также необходима зависимостьartemis-document.

Для других типов баз данных NoSQL мы будем использоватьartemis-column, artemis-key-value иartemis-graph.

Драйвер Diana для MongoDB также необходим:


    org.jnosql.artemis
    artemis-configuration
    0.0.5


    org.jnosql.artemis
    artemis-document
    0.0.5


    org.jnosql.diana
    mongodb-driver
    0.0.5

Артемида основана на CDI, поэтому нам также необходимо обеспечить эту зависимость Maven:


    javax
    javaee-web-api
    8.0
    provided

3.2. Файл конфигурации документа

Конфигурация - это набор свойств для данной базы данных, который позволяет нам устанавливать параметры вне кода. По умолчанию нам нужно предоставить файлjnosql.json под ресурсом META-INF.

Это пример файла конфигурации:

[
    {
        "description": "The mongodb document configuration",
        "name": "document",
        "provider": "org.jnosql.diana.mongodb.document.MongoDBDocumentConfiguration",
        "settings": {
            "mongodb-server-host-1":"localhost:27019"
        }
    }
]

Нам нужно будет указать имя конфигурации выше, установив атрибутname в нашемConfigurationUnit.. Если конфигурация находится в другом файле, ее можно указать с помощью атрибутаfileName.

Учитывая эту конфигурацию, мы создаем фабрику:

@Inject
@ConfigurationUnit(name = "document")
private DocumentCollectionManagerFactory managerFactory;

И из этой фабрики мы можем создатьDocumentCollectionManager:

@Produces
public MongoDBDocumentCollectionManager getEntityManager() {
    return managerFactory.get("todos");
}

DocumentCollectionManager - это компонент с поддержкой CDI, и он используется как вTemplate, так и вRepository..

3.3. картографирование

Отображение - это управляемый аннотациями процесс, с помощью которого модельEntity преобразуется в модель DianaEntityValue..

Начнем с определения моделиTodo:

@Entity
public class Todo implements Serializable {

    @Id("id")
    public long id;

    @Column
    public String name;

    @Column
    public String description;

    // standard constructor
    // standard getters and setters
}

Как показано выше, у нас есть основные аннотации отображения:@Entity, @Id, и@Column.

Теперь, чтобы управлять этой моделью, нам понадобится либо классTemplate, либо интерфейсRepository.

3.4. Работа с шаблоном

The template is thebridge between the entity model and the Diana API. Для документно-ориентированной базы данных мы начинаем с внедрения bean-компонентаDocumentTemplate:

@Inject
DocumentTemplate documentTemplate;

А затем мы можем управлять объектомTodo. Например, мы можем создатьTodo:

public Todo add(Todo todo) {
    return documentTemplate.insert(todo);
}

Или мы можем получитьTodo поid:

public Todo get(String id) {
    Optional todo = documentTemplate
      .find(Todo.class, id);
    return todo.get(); // or any other proper Optional handling
}

Чтобы выбрать все объекты, мы создаемDocumentQuery, а затем вызываем методselect():

public List getAll() {
    DocumentQuery query = select().from("Todo").build();
    return documentTemplate.select(query);
}

И, наконец, мы можем удалить объектTodo с помощьюid:

public void delete(String id) {
    documentTemplate.delete(Todo.class, id);
}

3.5. Работа с репозиторием

Помимо классаTemplate, мы также можем управлять сущностями с помощью информацииthe Repository interface which has methods for creating, updating, deleting and retrieving.

Чтобы использовать интерфейсRepository, мы просто предоставляем подинтерфейсRepository:

public interface TodoRepository extends Repository {
    List findByName(String name);
    List findAll();
}

В соответствии со следующими соглашениями об именах и методах реализация этого интерфейса предоставляется во время выполнения в виде компонента CDI.

В этом примере все объектыTodo с совпадающимname извлекаются методомfindByName().

Теперь мы можем использовать это:

@Inject
TodoRepository todoRepository;

КвалификаторDatabase позволяет нам работать с более чем одной базой данных NoSQL в одном приложении. Он поставляется с двумя атрибутами, типом и поставщиком.

Если база данных мультимодельная, то нам нужно указать, с какой моделью мы работаем:

@Inject
@Database(value = DatabaseType.DOCUMENT)
TodoRepository todoRepository;

Кроме того, если у нас более одной базы данных одной модели, нам нужно указать провайдера:

@Inject
@Database(value = DatabaseType.DOCUMENT, provider="org.jnosql.diana.mongodb.document.MongoDBDocumentConfiguration")
TodoRepository todoRepository;

Чтобы запустить пример, просто зайдите в модуль jnosql-artemis и вызовите эту команду:

mvn package liberty:run

Эта команда создает, развертывает и запускает серверOpen Liberty благодаряliberty-maven-plugin.

3.6. Тестирование приложения

Поскольку приложение предоставляет конечную точку REST, мы можем использовать любой клиент REST для наших тестов. Здесь мы использовали инструмент curl.

Итак, чтобы сохранить класс Todo:

curl -d '{"id":"120", "name":"task120", "description":"Description 120"}' -H "Content-Type: application/json" -X POST http://localhost:9080/jnosql-artemis/todos

и чтобы получить все Todo:

curl -H "Accept: application/json" -X GET http://localhost:9080/jnosql-artemis/todos

Или получить только одну Todo:

curl -H "Accept: application/json" -X GET http://localhost:9080/jnosql-artemis/todos/120

4. Заключение

В этом руководстве мы рассмотрели, как JNoSQL может абстрагировать взаимодействие с базой данных NoSQL.

First, we have used JNoSQL Diana API to interact with the database with low-level code. Then, we used the JNoSQL Artemis API to work with friendly Java annotated Models.

Как обычно, мы можем найти код, использованный в этой статьеover on Github.

TOC

Руководство по Eclipse JNoSQL