Updates to Chapter 5 (part 1)

spec/src/main/asciidoc/annotations.adoc

@@ -14,7 +14,7 @@
 
 === Models Annotation
 
-As mentioned previously, the Mapping API has annotations that make the Java developer's life easier; these annotations have two categories:
+As previously mentioned, the Mapping API has annotations that make the Java developer's life easier; these annotations have two categories:
 
 * Annotation Models
 * Qualifier annotation
@@ -52,7 +52,7 @@ public class Person {
 }
 ----
 
-An entity that is a field be will incorporated as a sub-entity. For example, in a Document, the entity field will be converted to a subdocument.
+An entity that is a field will be incorporated as a sub-entity. For example, in a Document, the entity field will be converted to a sub-document.
 
 
 [source,java]
@@ -96,7 +96,7 @@ public class Address {
 ----
 ===== @Column
 
-This annotation defines which fields that belong an Entity will be persisted. There is a single attribute that specifies that name in Database. It is default value that is the field name as declared in the class. This annotation is mandatory for non-Key-Value database types. In Key-Value types, only the Key needs to be identified with `@Key` - all other fields are stored as a single blob. 
+This annotation defines which fields that belong to an Entity will be persisted. There is a single attribute that specifies that name in Database. It is default value that is the field name as declared in the class. This annotation is mandatory for non-Key-Value database types. In Key-Value types, only the Key needs to be identified with `@Key` - all other fields are stored as a single blob.
 
 [source,java]
 ----
@@ -111,16 +111,16 @@ public class Person {
     @Column
     private List<String> phones;
 
-    //ignored
+    // ignored
     private String address;
 }
 ----
 
 ===== @MappedSuperclass
 
-The class with the MapperSuperclass annotation will have all attributes considered as an extension of his subclass with Entity annotation. In this case, all attributes are going to be stored, even the attributes inside the Super Class.
+The class with the `@MapperSuperclass` annotation will have all attributes considered as an extension of this subclass with an `@Entity` annotation. In this case, all attributes are going to be stored, even the attributes inside the super class.
 
-This means, that This annotation causes fields annotated with `@Column` in a parent class to be persisted together with the child class' fields. 
+This means, that this annotation causes fields annotated with `@Column` in a parent class to be persisted together with the child class' fields.
 
 
 [source,java]
@@ -148,7 +148,7 @@ On the example above, when saving a Dog instance, Animal class' fields are saved
 
 ===== @Id
 
-Defines which attribute is the entity's id, or the Key in Key-Value databases. In such case, the Value is the remaining information. It has a single attribute (like `@Column`) to define the native name. Unlike `@Column`, the default value is `_id`. 
+This annotation defines which attribute is the entity's ID, or the Key in Key-Value databases. In such a case, the Value is the remaining information. It has a single attribute (like `@Column`) to define the native name. Unlike `@Column`, the default value is `_id`.
 
 [source,java]
 ----
@@ -169,7 +169,7 @@ public class User implements Serializable {
 
 ===== @Embeddable
 
-Defines a class whose instances are stored as an intrinsic part of an owning entity and share the identity of that object. The behaviour is similar to `@MappedSuperclass`, but this is used on composition instead of inheritance.
+This annotation defines a class whose instances are stored as an intrinsic part of an owning entity and share the identity of that object. The behaviour is similar to `@MappedSuperclass`, but this is used on composition instead of inheritance.
 
 [source,java]
 ----
@@ -195,11 +195,11 @@ public class Author {
 
 ----
 
-In this example, there is a single Instance in the database with columns `title`, `author` and `age`.
+In this example, there is a single instance in the database with columns `title`, `author` and `age`.
 
 ===== @Convert
 
-This annotation allows value convertions when mapping the value that came from the Communication API. This is useful for cases such as to cipher a field (String to String conversion), or to convert to a custom type. The Converter annotation has a single, mandatory parameter: a Class that inherits from AttributeConverter that will be used to perform the convertion. The example below shows how to create a converter to a custom Money class.
+This annotation allows value conversions when mapping the value that came from the Communication API. This is useful for cases such as to cipher a field (String to String conversion), or to convert to a custom type. The Converter annotation has a single, mandatory parameter: a class that inherits from `AttributeConverter` that will be used to perform the conversion. The example below shows how to create a converter to a custom `Money` class.
 
 [source,java]
 ----
@@ -214,40 +214,40 @@ public class Employee {
 
     @Column("money")
     @Convert(MoneyConverter.class)
-    private MonetaryAmmount salary;
+    private MonetaryAmount salary;
 }
 
-public class MoneyConverter implements AttributeConverter<MonetaryAmmount, String> {
+public class MoneyConverter implements AttributeConverter<MonetaryAmount, String> {
     
     @Override
-    public String convertToDatabaseColumn(MonetaryAmmount appValue) {
+    public String convertToDatabaseColumn(MonetaryAmount appValue) {
         return appValue.toString();
     }
     
     @Override
-    public MonetaryAmmount convertToEntityAttribute(String dbValue) {
-        return MonetaryAmmount.parse(dbValue);
+    public MonetaryAmount convertToEntityAttribute(String dbValue) {
+        return MonetaryAmount.parse(dbValue);
     }
 }
 
-public class MonetaryAmmount {
+public class MonetaryAmount {
     private final String currency;
 
     private final BigDecimal value;
 
     public String toString() {
-        //specific implementation
+        // specific implementation
     }
 
-    public static MonetaryAmmount parse(String string) {
-        //specific implementation
+    public static MonetaryAmount parse(String string) {
+        // specific implementation
     }
 }
 ----
 
 ===== Collections
 
-The Mapping layer supports `java.util.Collection` (and subclasses, as defined below) mapping to simple elements such as `String` and `Integer` (that will be sent to the communication API as-is), and mapping to `Entity` or `Embedded` entities. 
+The Mapping layer supports `java.util.Collection` (and subclasses as defined below) mapping to simple elements such as `String` and `Integer` (that will be sent to the communication API as-is), and mapping to `Entity` or `Embedded` entities.
 
 The following collections are supported:
 
@@ -316,7 +316,7 @@ The above classes are mapped to:
 
 This annotation allows programmers to specialize `@Inject` annotations to choose which specific resource should be injected.
 
-For example, when working with multiple DocumentRepositories, the following is ambiguous:
+For example, when working with multiple `DocumentRepositories`, the following statement are ambiguous:
 
 [source,java]
 ----
@@ -337,11 +337,11 @@ Applying the annotation to the example above, the result is:
 [source,java]
 ----
 @Inject
-@Database(value = DatabaseType.DOCUMENT, provider = “databaseA”)
+@Database(value = DatabaseType.DOCUMENT, provider = "databaseA")
 private DocumentRepository repositoryA;
 
 @Inject
-@Database(value = DatabaseType.DOCUMENT, provider = “databaseB”)
+@Database(value = DatabaseType.DOCUMENT, provider = "databaseB")
 private DocumentRepository repositoryB;
 ----
 

spec/src/main/asciidoc/mapping.adoc

@@ -12,11 +12,11 @@
 //
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 
-== Mapping API Introduction
+== Introduction to the Mapping API
 
-The mapping level, to put it differently, has the same goals as either the JPA or ORM. In NoSQL world, the *OxM* then converts the entity object to a communication model.
+The mapping level, to put it differently, has the same goals as either the JPA or ORM. In the NoSQL world, the *OxM* then converts the entity object to a communication model.
 
-This level is in charge to do integration among technologies such as Bean Validation. The Mapping API has annotations that make the Java developer’s life easier. As a communication project, it must be extensible and configurable to keep the diversity of NoSQL database.
+This level is in charge to perform integration among technologies such as Bean Validation. The Mapping API has annotations that make the Java developer’s life easier. As a communication project, it must be extensible and configurable to keep the diversity of NoSQL database.
 
 To go straight and cover the four NoSQL types, this API has four domains:
 
@@ -39,14 +39,14 @@ The mapping API has five parts:
 
 TIP: Each module works separately as a Communication API.
 
-IMPORTANT: Like communication API, there is a support for database diversity. This project has extensions for each database types on the database mapping level.
+IMPORTANT: Similar to the communication API, there is a support for database diversity. This project has extensions for each database types on the database mapping level.
 
 include::annotations.adoc[]
 
 
 === Template classes
 
-The template offers convenient operations to create, update, delete, query, and provides a mapping between your domain objects and communication API. The templates classes have the goal to persist an Entity Model through a communication API. It has three components:
+The template offers convenient operations to create, update, delete, query, and provides a mapping among your domain objects and communication API. The templates classes have a goal to persist an Entity Model through a communication API. It has three components:
 
 * *Converter*: That converts the Entity to a communication level API.
 * *EntityManager*: The EntityManager for communication.

spec/src/main/asciidoc/template_column.adoc

@@ -14,19 +14,19 @@
 
 ==== ColumnTemplate
 
-This template has the duty to be a bridge between the entity model and the communication to a column family. 
+This template has the responsibility to serve as a bridge between the entity model and the communication to a column family NoSQL database type.
 
 The `ColumnTemplate` is the column template for the synchronous tasks. It has three components:
 
-* *ColumnEntityConverter*: That converts an entity to communication API, e.g., The Person to ColumnFamilyEntity.
+* *ColumnEntityConverter*: Converts an entity to communication API, e.g., the `Person` to `ColumnFamilyEntity`.
 
 * *ColumnCollectionManager*: The communication column family entity manager.
 
 * *ColumnWorkflow*: The workflow to update and insert methods.
 
 [source,java]
 ----
-ColumnTemplate template = //instance;
+ColumnTemplate template = // instance;
 
 Person person = new Person();
 person.setAddress("Olympus");
@@ -44,7 +44,7 @@ template.update(person);
 template.update(people);
 ----
 
-For information removal and retrieval, there are *ColumnQuery* and *ColumnDeleteQuery* respectively; also, the callback method can be used.
+For information removal and retrieval, there are `ColumnQuery` and `ColumnDeleteQuery` classes, respectively. Also, the callback method may be used.
 
 [source,java]
 ----
@@ -60,7 +60,7 @@ template.delete(deleteQuery);
 ----
 
 
-Both *ColumnQuery* and *ColumnDeleteQuery* won't convert the Object to native fields. However, there is *ColumnQueryMapperBuilder* that creates both query types, reading the Class then switching to the native fields through annotations.
+Both `ColumnQuery` and `ColumnDeleteQuery` won't convert the object to native fields. However, `ColumnQueryMapperBuilder` creates both query types, reads the class, then switches to the native fields through annotations.
 
 [source,java]
 ----
@@ -85,36 +85,36 @@ private ColumnQueryMapperBuilder mapperBuilder;
 
 public void mapper() {
   ColumnQuery query = mapperBuilder.selectFrom(Person.class).where("id").gte(10).build();
-  //translating: select().from("Person").where("native_id").gte(10L).build();
+  // translating: select().from("Person").where("native_id").gte(10L).build();
   ColumnDeleteQuery deleteQuery = mapperBuilder.deleteFrom(Person.class)
                                                .where("id").eq("20").build();
-  //translating: delete().from("Person").where("native_id").gte(10L).build();
+  // translating: delete().from("Person").where("native_id").gte(10L).build();
 }
 ----
 
 
-To use a column template, just follow the CDI style and put an `@Inject` on the field.
+To use a column template, just follow the CDI style and precede the field with the `@Inject` annotation.
 
 [source,java]
 ----
 @Inject
 private ColumnTemplate template;
 ----
 
-The next step is to produce a **ColumnFamilyManager**:
+The next step is to produce a `ColumnFamilyManager`:
 
 [source,java]
 ----
 @Produces
 public ColumnFamilyManager getManager() {
-    ColumnFamilyManager manager = //instance;
+    ColumnFamilyManager manager = // instance;
     return manager;
 }
 ----
 
-To work with more than one Column Template, there are two approaches:
+To work with more than one column template, there are two approaches:
 
-1) Using qualifiers:
+1) Use qualifiers:
 
 [source,java]
 ----
@@ -126,31 +126,31 @@ private ColumnTemplate templateA;
 @Database(value = DatabaseType.COLUMN, provider = "databaseB")
 private ColumnTemplate templateB;
 
-//producers methods
+// producers methods
 @Produces
 @Database(value = DatabaseType.COLUMN, provider = "databaseA")
 public ColumnFamilyManager getManagerA() {
-    ColumnFamilyManager manager =//instance;
+    ColumnFamilyManager manager =// instance;
     return manager;
 }
 
 @Produces
 @Database(value = DatabaseType.COLUMN, provider = "databaseB")
 public ColumnFamilyManager getManagerB() {
-    ColumnFamilyManager manager = //instance;
+    ColumnFamilyManager manager = // instance;
     return manager;
 }
 ----
 
-2)  Using the **ColumnTemplateProducer** class:
+2) Use the `ColumnTemplateProducer` class:
 
 ```java
 @Inject
 private ColumnTemplateProducer producer;
 
 public void sample() {
-   ColumnFamilyManager managerA = //instance;
-   ColumnFamilyManager managerB = //instance;
+   ColumnFamilyManager managerA = // instance;
+   ColumnFamilyManager managerB = // instance;
    ColumnTemplate templateA = producer.get(managerA);
    ColumnTemplate templateB = producer.get(managerB);
 }