From 9766ed7cef1d7377ddf42a3853c5e7d668ed4a26 Mon Sep 17 00:00:00 2001 From: Nathan Rauh Date: Wed, 22 Nov 2023 11:11:15 -0600 Subject: [PATCH] Issue #353 preliminary review for conciseness Signed-off-by: Nathan Rauh --- .../asciidoc/chapters/introduction/introduction.asciidoc | 8 +++----- spec/src/main/asciidoc/repository.asciidoc | 6 +++--- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/spec/src/main/asciidoc/chapters/introduction/introduction.asciidoc b/spec/src/main/asciidoc/chapters/introduction/introduction.asciidoc index 8bbfe05e9..e2d8f772e 100644 --- a/spec/src/main/asciidoc/chapters/introduction/introduction.asciidoc +++ b/spec/src/main/asciidoc/chapters/introduction/introduction.asciidoc @@ -26,7 +26,7 @@ In this context, a domain-centric approach refers to designing the application's === Goals -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. +Jakarta Data 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—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. @@ -50,14 +50,12 @@ Jakarta Data is guided by a set of clear and well-defined objectives to simplify === 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: +The following are not goals of Jakarta Data: -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. +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. 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. - === Conventions The terms, _entity attribute_ and _entity property_, are used interchangeably throughout the specification. diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc index 0115aca02..609844b46 100644 --- a/spec/src/main/asciidoc/repository.asciidoc +++ b/spec/src/main/asciidoc/repository.asciidoc @@ -50,7 +50,7 @@ Several characteristics define repositories: - **Entity Associations:** Entities within a repository may have associations between them, especially in the case of relational data access. However, this specification does not define the semantics of associations between entities belonging to different repositories. -- **Stateless Repositories:** Repositories are typically designed to be stateless. However, it is important to note that this specification does not address the definition of repositories backed by Jakarta Persistence-style stateful persistence contexts. +- **Stateless Repositories:** Repositories are stateless. This specification does not address the definition of repositories that externalize Jakarta Persistence-style stateful persistence contexts. Repositories in Jakarta Data serve as efficient gateways for managing and interacting with persistent data, offering a simplified and consistent approach to data access and modification within Java applications. @@ -154,7 +154,7 @@ In Jakarta Data, an entity refers to a fundamental data representation and manag 3. *Persistence and Representation*: Entities are associated with persistent data, meaning the data outlives any specific Java process utilizing it. Each persistent instantiation of the schema is distinguishable by a unique identifier. For example, a row of a relational database table is identifiable by the value of its primary key. In Java, these entities are represented as classes, referred to as entity classes. It's important to note that multiple instances of the entity class within a Java program can represent a single persistent instance of the schema. -4. *Provider Differentiation*: To maintain clarity and specify the desired provider when using Jakarta Data, it's recommended that applications do not mix Entity annotations from different models. This practice allows the Entity annotation to indicate the desired provider, especially in cases where multiple types of Jakarta Data providers are available. A Jakarta Data provider must provide implementation of repositories for Entity types having the Entity annotations that it supports, ignoring Entity types only having identifiable Entity annotations that the Jakarta Data provider does not support. The latter are to be handled by other Jakarta Data providers that do support the other types of Entity annotations. +4. *Provider Differentiation*: To maintain clarity and specify the desired provider when using Jakarta Data, it is recommended that applications do not mix Entity annotations from different models. This practice allows the Entity annotation to indicate the desired provider, especially in cases where multiple types of Jakarta Data providers are available. A Jakarta Data provider must provide implementation of repositories for Entity types having the Entity annotations that it supports, ignoring Entity types only having identifiable Entity annotations that the Jakarta Data provider does not support. The latter are to be handled by other Jakarta Data providers that do support the other types of Entity annotations. An entity within Jakarta Data encompasses the Java class representing the data and the schema, persistence characteristics, and provider-specific annotations, all working together to simplify data access and management within Java applications. While a Jakarta Data provider might require a default constructor and work primarily with mutable entities, Jakarta Data allows for the use of immutable entity classes, which are best represented as Java records. @@ -761,7 +761,7 @@ The parsing of query method names follows a specific format: - The order clause, which is optional, begins with `OrderBy` and consists of an ordered collection of entity attributes by which to sort results, delimited by `Asc` or `Desc` to specify the sort direction of the preceding attribute. - The method name is formed by combining the subject, predicate, and order clause, in that order. -NOTE: This specification uses the terms subject and predicate in a way that aligns with industry terminology rather than how they are defined in English grammar. Aligning with the rules of English grammar, the subject would be the repository instance upon which the method is invoked, and the predicate would start with the action (such as `find`) and include the prepositional phrase `By...`. +NOTE: This specification uses the terms subject and predicate in a way that aligns with industry terminology rather than how they are defined in English grammar. Queries can also handle entities with relation attributes by specifying the relationship using dot notation, with the dot converted to underscore so that it is a valid character within the method name. See Scenario 3 below for an example.