Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
JNoSQL/Artemis/Start
Contents
Getting Start with Artemis
The Artemis project is the abstraction level, to put it differently, it has the same goals of the either JPA or ORM to NoSQL world, which converts the entity object to Diana model.
Using Artemis in a Maven project
To use Artemis in a Maven project just need to add the following dependency. As the communication layer, it has modules and a project to each NoSQL kind database.
<dependency> <groupId>org.jnosql.artemis</groupId> <artifactId>artemis-key-value</artifactId> <version>version</version> </dependency> <dependency> <groupId>org.jnosql.artemis</groupId> <artifactId>artemis-column</artifactId> <version>version</version> </dependency> <dependency> <groupId>org.jnosql.artemis</groupId> <artifactId>artemis-document</artifactId> <version>version</version> </dependency>
To graph database:
<dependency> <groupId>org.jnosql.artemis</groupId> <artifactId>graph-extension</artifactId> <version>version</version> </dependency>
The Eclipse JNoSQL graph API went to the extension because the communication layer is the Apache TinkerPop project instead of an Eclipse JNoSQL API.
Artemis need a CDI implementation once it is CDI driven.
Annotations
The annotation Models is to convert the entity model to the entity on communication, the Diana entity:
- Entity
- Column
- MappedSuperclass
- Id
- Embeddable
- Subentity
- Convert
- ConfigurationUnit
E.g:
@Entity("Person")
public class Person {
@Column
private long id;
@Column
private String name;
@Column
private List<String> phones;
//getter and setters
}
The JNoSQL Artemis does not require the getter and setter methods to the fields, however, the Entity class must have a non-private constructor with no parameters.
Column Template
This template has the duty to be a bridge between the entity model and Diana to a column family. It has two classes ColumnTemplate and ColumnTemplateAsync to synchronous and asynchronous works.
Sync
To use it, the developer just needs to produce a ColumnFamilyManager and make it available to CDI.
@Produces
public ColumnFamilyManager getManager() {
ColumnFamilyManager manager = //instance
return manager;
}
Artemis will handle to you some instances such as ColumnTemplate and Repository.
@Inject
private ColumnTemplate template;
public void sample() {
Person person = new Person();
person.setAddress("Olympus");
person.setName("Artemis Good");
person.setPhones(Arrays.asList("55 11 94320121", "55 11 94320121"));
person.setNickname("artemis");
List<Person> people = Collections.singletonList(person);
Person personUpdated = template.insert(person);
template.insert(people);
template.insert(person, Duration.ofHours(1L));
template.update(person);
template.update(people);
}
Async
To use it, the developer just needs to produce a ColumnFamilyManagerAsync and make it available to CDI.
@Produces
public ColumnFamilyManagerAsync getManager() {
ColumnFamilyManagerAsync managerAsync = //instance
return manager;
}
Artemis will handle to you some instances such as ColumnTemplate.
@Inject
private ColumnTemplateAsync templateAsync;
public void sample() {
Person person = new Person();
person.setAddress("Olympus");
person.setName("Artemis Good");
person.setPhones(Arrays.asList("55 11 94320121", "55 11 94320121"));
person.setNickname("artemis");
List<Person> people = Collections.singletonList(person);
Consumer<Person> callback = p -> {};
templateAsync.insert(person);
templateAsync.insert(person, Duration.ofHours(1L));
templateAsync.insert(person, callback);
templateAsync.insert(people);
templateAsync.update(person);
templateAsync.update(person, callback);
templateAsync.update(people);
Consumer<List<Person>> callBackPeople = p -> {};
Consumer<Void> voidCallBack = v ->{};
templateAsync.select(query, callBackPeople);
templateAsync.delete(deleteQuery);
templateAsync.delete(deleteQuery, voidCallBack);
}
Document Template
This template has the duty to be a bridge between the entity model and Diana to a document family. It has two classes DocumentTemplate and DocumentTemplateAsync to synchronous and asynchronous works.
Sync
To use it, the developer just needs to produce a DocumentCollectionManager and make it available to CDI.
@Produces
public DocumentCollectionManager getManager() {
DocumentCollectionManager manager = //instance
return manager;
}
Artemis will handle to you some instances such as ColumnTemplate and Repository.
@Inject
private DocumentTemplate template;
public void sample() {
Person person = new Person();
person.setAddress("Olympus");
person.setName("Artemis Good");
person.setPhones(Arrays.asList("55 11 94320121", "55 11 94320121"));
person.setNickname("artemis");
List<Person> people = Collections.singletonList(person);
Person personUpdated = template.insert(person);
template.insert(people);
template.insert(person, Duration.ofHours(1L));
template.update(person);
template.update(people);
}
Async
To use it, the developer just needs to produce a DocumentCollectionManagerAsync and make it available to CDI.
@Produces
public DocumentCollectionManagerAsync getManager() {
DocumentCollectionManagerAsync managerAsync = //instance
return manager;
}
Artemis will handle you some instances such as ColumnTemplate.
@Inject
private DocumentTemplateAsync template;
public void sample() {
Person person = new Person();
person.setAddress("Olympus");
person.setName("Artemis Good");
person.setPhones(Arrays.asList("55 11 94320121", "55 11 94320121"));
person.setNickname("artemis");
List<Person> people = Collections.singletonList(person);
Consumer<Person> callback = p -> {};
templateAsync.insert(person);
templateAsync.insert(person, Duration.ofHours(1L));
templateAsync.insert(person, callback);
templateAsync.insert(people);
templateAsync.update(person);
templateAsync.update(person, callback);
templateAsync.update(people);
Consumer<List<Person>> callBackPeople = p -> {};
Consumer<Void> voidCallBack = v ->{};
templateAsync.select(query, callBackPeople);
templateAsync.delete(deleteQuery);
templateAsync.delete(deleteQuery, voidCallBack);
}
Key-value Template
The key value is a bridge between the entity and the key-value database.
Sync
To use it, the developer just needs to produce a BucketManager and make it available to CDI.
@Produces
public BucketManager getManager() {
BucketManager manager = //instance
return manager;
}
Artemis will handle to you some instances such as KeyValueTemplate.
@Inject
private KeyValueTemplate template;
public void demo() {
User user = new User();
user.setNickname("ada");
user.setAge(10);
user.setName("Ada Lovelace");
List<User> users = Collections.singletonList(user);
template.put(user);
template.put(users);
Optional<Person> ada = template.get("ada", Person.class);
Iterable<Person> usersFound = template.get(Collections.singletonList("ada"), Person.class);
}
ConfigurationUnit
The storage a database in a different place, Artemis has the ConfigurationUnit annotation. that reads the configuration from a file such as XML and JSON file and inject to create a factory. The default configuration structure is within either META-INF or WEB-INF folder.
JSON file structure
[
{
"description":"that is the description",
"name":"name",
"provider":"class",
"settings":{
"key":"value"
}
},
{
"description":"that is the description",
"name":"name-2",
"provider":"class",
"settings":{
"key":"value"
}
}
]
XML file structure
<?xml version="1.0" encoding="UTF-8"?>
<configurations>
<configuration>
<description>that is the description</description>
<name>name</name>
<provider>class</provider>
<settings>
<entry>
<key>key2</key>
<value>value2</value>
</entry>
<entry>
<key>key</key>
<value>value</value>
</entry>
</settings>
</configuration>
</configurations>
Injection the code
With the configuration file, the next step is to inject the dependency in the application. The default behavior supports the following classes:
- BucketManagerFactory
- DocumentCollectionManagerAsyncFactory
- DocumentCollectionManagerAsyncFactory
- ColumnFamilyManagerAsyncFactory
- ColumnFamilyManagerAsyncFactory
@Inject
@ConfigurationUnit(fileName = "column.xml", name = "name")
private ColumnFamilyManagerFactory<?> factoryA;
@Inject
@ConfigurationUnit(fileName = "document.json", name = "name-2")
private DocumentCollectionManagerFactory factoryB;
@Inject
@ConfigurationUnit
private BucketManagerFactory factoryB;
ConfigurationUnit Dependency
To configuration unit annotations needs the JNoSQL Artemis configuration dependency.
<dependency>
<groupId>org.jnosql.artemis</groupId>
<artifactId>artemis-configuration</artifactId>
<version>0.0.4-SNAPSHOT</version>
</<dependency>
Links
- Demo code: https://github.com/JNOSQL/artemis-demo
- Extensions: https://github.com/JNOSQL/artemis-extension
- Documentation: https://www.gitbook.com/book/jnosql/jnosql-book/details
- Qualifier
- Repository
- Bean Validation with Artemis
- Cassandra Extension
- Couchbase Extension
- Elasticsearch Extension
- OrientDB Extension
- Graph Extension