Merge pull request #342 from njr-11/228-review-of-introduction-and-go…

…als-section

review of introduction and goals section

spec/src/main/asciidoc/chapters/introduction/introduction.asciidoc

@@ -14,48 +14,47 @@
 
 == Introduction
 
-The Jakarta Data specification provides an API for easier data access. A
-Java developer can split the persistence from the model with several features,
-such as the ability to compose custom query methods on a Repository interface where the framework
-will implement it.
+The Jakarta Data specification provides an API to simplify data access. It enables the
+Java developer to focus on the data model, while delegating away the complexities of data persistence.
+To make this possible, Jakarta Data includes a variety of features such as
+pre-built interfaces for data access, offset and cursor based pagination strategies,
+and the ability to compose custom query methods that the framework implements.
 
-There is no doubt about the importance of data within the context of an application. We often discuss the concept of a stateless application, where we delegate the management of the application's state to the database.
+Data is a primary concern of most applications, and dealing with a database presents one of the most significant challenges within software architecture. Beyond selecting from the various database options available in the market, it is necessary to consider the intricacies of persistence integrations. Jakarta Data simplifies the lives of Java developers by providing a solution that streamlines data access and manipulation.
 
-Dealing with a database presents one of the most significant challenges within software architecture. Beyond selecting from the various database options available in the market, it's essential to consider the intricacies of persistence integrations. Jakarta Data simplifies the lives of Java developers by providing a solution that streamlines data access and manipulation.
-
-In this context, a "domain-centric" approach refers to designing the application's architecture primarily focusing on the domain model. It means that the application's data and logic structure and organization revolve around the core domain concepts and business rules, ensuring that the domain model plays a central role in shaping the application's structure.
+In this context, a domain-centric approach refers to designing the application's architecture primarily focusing on the domain model. It means that the application's data and logic structure and organization revolve around the core domain concepts and business rules, ensuring that the domain model plays a central role in shaping the application's structure.
 
 === Goals
 
-Jakarta Data is a pivotal solution that addresses a fundamental challenge in Java application development: the seamless integration of diverse data sources. This integration is crucial for applications with many databases and storage technologies.
+Jakarta Data is addresses a fundamental challenge in Java application development: the seamless integration of diverse data sources amid the dissimilarities in their respective programming models. Offering the Java developer a common, familiar starting point for data access is helpful for solutions involving multiple databases and storage technologies.
 
-The primary problem Jakarta Data sets out to solve is the complexity and inconsistency that arises when Java applications encounter various database systems—some relational, some NoSQL, and others unique. Managing these diverse data sources can be daunting, often requiring developers to write specialized code for each storage technology.
+The primary problem Jakarta Data sets out to solve is the complexity and inconsistency that arises when Java applications encounter various database systems—relational, document, column, key-value, graph, and others. Managing these diverse data sources can be daunting, often requiring developers to write specialized code for each storage technology.
 
 Jakarta Data combines the concept of a persistence agnostic API with a domain-centric approach. This approach enables developers to work with different databases and storage engines while aligning their data access strategies with the core principles of a domain-centric architecture, where the domain model plays a central role in shaping the application's structure.
 
 Jakarta Data is guided by a set of clear and well-defined objectives to simplify data integration and enhance data access for Java developers. These objectives serve as the pillars of its design philosophy, ensuring that it addresses real-world challenges and provides concrete advantages to developers:
 
 * **Jakarta Data is engineered to tackle a fundamental problem:** simplifying data access and manipulation within Java applications that interact with diverse databases and storage sources.
 
-* **Jakarta Data is designed to be persistence agnostic.** In this context, agnostic does not mean that you can switch the underlying persistence without changes but implies that Jakarta Data is not tied to a specific database technology. It offers a flexible, adaptable framework that allows you to work with the databases and storage sources that best suit your project's needs. This agnostic approach ensures that Jakarta Data can cater to various use cases.
+* **Jakarta Data is designed to be persistence agnostic:** In this context, agnostic does not mean that you can switch the underlying persistence without changes but implies that Jakarta Data is not tied to a specific database technology. It offers a flexible, adaptable framework that allows you to work with the databases and storage sources that best suit your project's needs. This agnostic approach ensures that Jakarta Data can cater to various use cases.
 
-* **Enhancing a Domain-Centric Approach:** Jakarta Data enhances the concept of a "persistence agnostic API" by incorporating a domain-centric approach. It enables developers to align their data access strategies with the core principles of a domain-centric architecture, where the domain model plays a central role in shaping the application's structure.
+* **Enhancing a Domain-Centric Approach:** Jakarta Data enhances the concept of a persistence agnostic API by incorporating a domain-centric approach. It enables developers to align their data access strategies with the core principles of a domain-centric architecture, where the domain model plays a central role in shaping the application's structure.
 
 * **Unified API:** Jakarta Data provides a unified and standardized API for interacting with various data sources. This consistency simplifies development by allowing developers to use the same tools and practices regardless of the underlying database technology.
 
 * **Pluggable and Extensible:** Jakarta Data is designed to be pluggable and extensible. Even in cases where the API doesn't directly support a specific behavior of a storage engine, Jakarta Data aims to provide an extensible API to enable developers to customize and adapt as needed.
 
-* **Simplified and Domain-Centric Querying and Database Operations:** Jakarta Data strongly emphasizes simplifying and aligning querying and database operations with your application's domain model. By offering domain-centric query capabilities through annotations, a driver, or query-by-method, Jakarta Data strives to be compatible with multiple databases and inherently closer to your application's domain logic. This approach ensures that your queries and operations are more versatile among various persistence engines, making working with different data sources easier while maintaining a cohesive and domain-focused codebase.
+* **Simplified and Domain-Centric Querying and Database Operations:** Jakarta Data strongly emphasizes simplifying and aligning querying and database operations with your application's domain model. By offering domain-centric query capabilities through annotations, built-in repository interfaces, or query-by-method, Jakarta Data strives to be compatible with multiple databases and inherently closer to your application's domain logic. This approach ensures that your queries and operations are more versatile across various persistence engines, making working with different data sources easier while maintaining a cohesive and domain-focused codebase.
 
 * **Seamless Integration:** Jakarta Data enables seamless integration between Java applications and various persistence layers, making it easier for developers to work with different databases and storage sources without extensive customization.
 
 === Non-Goals
 
-In the development of any software component, important decisions are made to strike a balance between various considerations. It's equally important to define what Jakarta Data does not aim to achieve—its non-goals:
+In the development of any software component, important decisions are made to strike a balance between various considerations. It iss equally important to define what Jakarta Data does not aim to achieve—its non-goals:
 
-1. **Specific Features of Jakarta Persistence, Jakarta NoSQL, etc., and Specializations:** Jakarta Data does not intend to replicate or replace the specific features provided by other Jakarta specifications, such as Jakarta Persistence and Jakarta NoSQL, along with their associated specializations and extensions. These specifications have well-defined scopes and functionalities that cater to specific use cases. Jakarta Data operates with the understanding that it complements these specifications by providing a higher-level, agnostic API. It does not seek to duplicate its capabilities but aims to simplify data access and integration across diverse data sources. The specialized features, specializations, and extensions that address particular behaviors and use cases are crucial within the Jakarta ecosystem but distinct from Jakarta Data's core API. Jakarta Data's core primarily provides a persistence-agnostic data access and integration framework. It establishes a consistent foundation that abstracts the complexities of data sources and storage engines, offering developers a unified approach.
+1. **Specific Features of Jakarta Persistence, Jakarta NoSQL, etc., and Specializations:** Jakarta Data does not intend to replicate or replace the specific features provided by other Jakarta specifications, such as Jakarta Persistence and Jakarta NoSQL, along with their associated specializations and extensions. These specifications have well-defined scopes and functionalities that cater to specific use cases. Jakarta Data operates with the understanding that it complements these specifications by providing a higher-level, agnostic API. It does not seek to duplicate their capabilities but aims to simplify data access and integration across diverse data sources. The specialized features, specializations, and extensions that address particular behaviors and use cases are crucial within the Jakarta ecosystem but distinct from Jakarta Data's core API. Jakarta Data's core API primarily provides a persistence-agnostic data access and integration framework. It establishes a consistent foundation that abstracts the complexities of data sources and storage engines, offering developers a unified approach.
 
-2. **Replacement of Jakarta Persistence or Jakarta NoSQL Specifications:** Jakarta Data's primary goal is not to replace or supersede the Jakarta Persistence or Jakarta NoSQL specifications. Instead, it works in harmony with these specifications, serving as an additional layer that abstracts the complexities of data access. Jakarta Data enhances the developer experience by offering a persistence-agnostic approach while leveraging the capabilities of Jakarta Persistence and Jakarta NoSQL. Its role is to complement and simplify, not replace, these established specifications."
+2. **Replacement of Jakarta Persistence or Jakarta NoSQL Specifications:** Jakarta Data's primary goal is not to replace or supersede the Jakarta Persistence or Jakarta NoSQL specifications. Instead, it works in harmony with these specifications, serving as an additional layer that abstracts the complexities of data access. Jakarta Data enhances the developer experience by offering a persistence-agnostic approach while leveraging the capabilities of Jakarta Persistence and Jakarta NoSQL. Its role is to complement and simplify, not replace, these established specifications.
 
 These clarifications emphasize Jakarta Data's role as a complementary and simplifying layer within the Jakarta ecosystem, highlighting that it does not aim to replicate existing functionality or replace established specifications.