Repository: polygene-java Updated Branches: refs/heads/develop 2b0a785f9 -> 352a1cd88
Adding a little bit of Javadocs for new SQL ES. Project: http://git-wip-us.apache.org/repos/asf/polygene-java/repo Commit: http://git-wip-us.apache.org/repos/asf/polygene-java/commit/5c46d1e2 Tree: http://git-wip-us.apache.org/repos/asf/polygene-java/tree/5c46d1e2 Diff: http://git-wip-us.apache.org/repos/asf/polygene-java/diff/5c46d1e2 Branch: refs/heads/develop Commit: 5c46d1e230ee4f158cf2ef2f7c637b91f8ccfb24 Parents: 8fb6d58 Author: niclas <[email protected]> Authored: Sat Oct 28 21:20:09 2017 +0800 Committer: niclas <[email protected]> Committed: Sat Oct 28 21:20:09 2017 +0800 ---------------------------------------------------------------------- extensions/entitystore-sql/dev-status.xml | 2 +- extensions/entitystore-sql/src/docs/es-sql.txt | 11 +++++++---- .../polygene/entitystore/sql/AssociationValue.java | 6 ++++++ .../org/apache/polygene/entitystore/sql/BaseEntity.java | 6 ++++++ .../apache/polygene/entitystore/sql/EntitiesTable.java | 7 +++++++ .../apache/polygene/entitystore/sql/JooqDslContext.java | 4 ++++ .../org/apache/polygene/entitystore/sql/MixinTable.java | 10 ++++++++++ .../entitystore/sql/SqlEntityStoreConfiguration.java | 3 +++ .../org/apache/polygene/entitystore/sql/SqlType.java | 3 +++ .../org/apache/polygene/entitystore/sql/TableFields.java | 7 +++++++ .../org/apache/polygene/entitystore/sql/TypesTable.java | 3 +++ .../sql/assembly/AbstractSQLEntityStoreAssembler.java | 2 +- .../sql/assembly/DerbySQLEntityStoreAssembler.java | 3 +++ .../sql/assembly/H2SQLEntityStoreAssembler.java | 3 +++ .../sql/assembly/MariaDbSQLEntityStoreAssembler.java | 3 +++ .../sql/assembly/MySQLEntityStoreAssembler.java | 3 +++ .../sql/assembly/PostgreSQLEntityStoreAssembler.java | 3 +++ .../sql/assembly/SQLiteEntityStoreAssembler.java | 3 +++ 18 files changed, 76 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/dev-status.xml ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/dev-status.xml b/extensions/entitystore-sql/dev-status.xml index b6d4c31..c79727f 100644 --- a/extensions/entitystore-sql/dev-status.xml +++ b/extensions/entitystore-sql/dev-status.xml @@ -24,7 +24,7 @@ http://polygene.apache.org/schemas/2008/dev-status/1/dev-status.xsd";> <status> <!--none,early,beta,stable,mature--> - <codebase>early</codebase> + <codebase>beta</codebase> <!-- none, brief, good, complete --> <documentation>brief</documentation> http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/docs/es-sql.txt ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/docs/es-sql.txt b/extensions/entitystore-sql/src/docs/es-sql.txt index a36d463..bab38ef 100644 --- a/extensions/entitystore-sql/src/docs/es-sql.txt +++ b/extensions/entitystore-sql/src/docs/es-sql.txt @@ -17,16 +17,16 @@ * under the License. /////////////////////////////////////////////////////////////// -[[extension-es-jooq,SQL EntityStore]] +[[extension-es-sql,SQL EntityStore]] = ORM EntityStore = [devstatus] -------------- -source=extensions/entitystore-jooq/dev-status.xml +source=extensions/entitystore-sql/dev-status.xml -------------- This entitystore is backed by a SQL server, and maps each mixin type of the Composite into separate tables. This is more -enterprise-friendly, but comes at the cost of less performance compared to the <<extension-es-sql>>. +enterprise-friendly, but comes at the cost of less performance compared to the <<extension-es-sqlkv>>. This extension fully leverage the <<library-sql>> meaning that you must use it to assemble your DataSource and that you get <<library-circuitbreaker,Circuit Breaker>> and <<library-jmx, JMX>> integration for free. @@ -39,7 +39,7 @@ Assembly is done using the provided Assembler: [snippet,java] ---- -source=extensions/entitystore-jooq/src/test/java/org/apache/polygene/entitystore/jooq/JooqEntityStoreTest.java +source=extensions/entitystore-sql/src/test/java/org/apache/polygene/entitystore/sql/SqlEntityStoreTest.java tag=assembly ---- @@ -56,3 +56,6 @@ tag=config All authentication related properties are optional. By default no authentication is used. As soon as you provide a `username`, authentication is set up. +It is also strongly recommended that a connection pool is setup. <<library-sql-dbcp>> and <<library-bonecp>> are +available in Polygene, but you can create your own. + http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/AssociationValue.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/AssociationValue.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/AssociationValue.java index 9fb6771..fc35c35 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/AssociationValue.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/AssociationValue.java @@ -19,6 +19,12 @@ package org.apache.polygene.entitystore.sql; import org.apache.polygene.api.common.QualifiedName; +/** + * Internal call to hold an assocation temporary in memory. + * <p> + * This class should never be used outside of this extension. + * </p> + */ @SuppressWarnings( "WeakerAccess" ) public class AssociationValue { http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/BaseEntity.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/BaseEntity.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/BaseEntity.java index 982366d..09dfb3b 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/BaseEntity.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/BaseEntity.java @@ -21,6 +21,12 @@ import java.time.Instant; import org.apache.polygene.api.entity.EntityDescriptor; import org.apache.polygene.api.identity.Identity; +/** + * The BaseEntity is the representation of the entity metadata that is associated with a given identity. + * <p> + * Internal class and should never be used outside of this extension. + * </p> + */ @SuppressWarnings( "WeakerAccess" ) public class BaseEntity { http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/EntitiesTable.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/EntitiesTable.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/EntitiesTable.java index 943d274..d3c0d52 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/EntitiesTable.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/EntitiesTable.java @@ -58,6 +58,13 @@ import org.jooq.SelectQuery; import org.jooq.Table; import org.jooq.impl.DSL; +/** + * This class handles all the dealing with the main table, called the Entities Table. + * <p> + * This is the table that holds the {@link BaseEntity} rows, and joins with the different so called + * {@link MixinTable}, which handles one table per Mixin type. + * </p> + */ @SuppressWarnings( "WeakerAccess" ) public class EntitiesTable implements TableFields http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/JooqDslContext.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/JooqDslContext.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/JooqDslContext.java index 47e01ad..da29644 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/JooqDslContext.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/JooqDslContext.java @@ -37,6 +37,10 @@ import org.jooq.impl.DataSourceConnectionProvider; import org.jooq.impl.DefaultConfiguration; import org.jooq.impl.ThreadLocalTransactionProvider; +/** + * The JOOQ Context is extended (Polygene-style) to get additional functionality and still backed by the underlying + * JOOQ DSLContext implementation. + */ @Mixins( JooqDslContext.Mixin.class ) public interface JooqDslContext extends DSLContext { http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/MixinTable.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/MixinTable.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/MixinTable.java index 70d13b9..aa567f2 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/MixinTable.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/MixinTable.java @@ -44,6 +44,16 @@ import org.jooq.Table; import org.jooq.UpdateSetMoreStep; import org.jooq.impl.DSL; +/** + * MixinTable is a class that handles the creation of the queries into the Mixin tables, both for insertions/updates + * as well as retrieval. + * <p> + * Note that these tables are only queried as part of a SQL {@code JOIN} statement and never directly. + * </p> + * <p> + * Creation of the actual Mixin tables happens in {@link TypesTable}. + * </p> + */ class MixinTable implements TableFields { http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlEntityStoreConfiguration.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlEntityStoreConfiguration.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlEntityStoreConfiguration.java index 6c01231..f5a6929 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlEntityStoreConfiguration.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlEntityStoreConfiguration.java @@ -21,6 +21,9 @@ import org.apache.polygene.api.common.UseDefaults; import org.apache.polygene.api.property.Property; import org.apache.polygene.library.sql.common.SQLConfiguration; +/** + * Configuration for the SQL Entity Store. + */ // START SNIPPET: config public interface SqlEntityStoreConfiguration { http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlType.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlType.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlType.java index c522d90..be98bdb 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlType.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/SqlType.java @@ -30,6 +30,9 @@ import org.jooq.DataType; import org.jooq.impl.SQLDataType; import org.jooq.types.Interval; +/** + * Translation of Java types to SQLDataType in JOOQ. + */ class SqlType { @SuppressWarnings( "unchecked" ) http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TableFields.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TableFields.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TableFields.java index cfa9d99..11f0acf 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TableFields.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TableFields.java @@ -22,6 +22,13 @@ import org.jooq.Field; import static org.apache.polygene.entitystore.sql.TypesTable.makeField; +/** + * SQL field names and definitions. + * <p> + * All internal names start with an underscore, to avoid collision, even though there should not be any risk of + * collision and more serves as a marker for what is Polygene overhead vs business data. + * </p> + */ public interface TableFields { // Common in all tables http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TypesTable.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TypesTable.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TypesTable.java index 15626ad..0513768 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TypesTable.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/TypesTable.java @@ -37,6 +37,9 @@ import org.jooq.SQLDialect; import org.jooq.Table; import org.jooq.impl.DSL; +/** + * This class is effectively the manager of the {@link MixinTable} instances. + */ public class TypesTable implements TableFields { http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/AbstractSQLEntityStoreAssembler.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/AbstractSQLEntityStoreAssembler.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/AbstractSQLEntityStoreAssembler.java index 8e9273a..11bc714 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/AbstractSQLEntityStoreAssembler.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/AbstractSQLEntityStoreAssembler.java @@ -33,7 +33,7 @@ import org.jooq.conf.RenderNameStyle; import org.jooq.conf.Settings; /** - * JOOQ EntityStore assembly. + * The common abstract part of the SQL EntityStore assembly. */ @SuppressWarnings( "WeakerAccess" ) public abstract class AbstractSQLEntityStoreAssembler<T extends AbstractSQLEntityStoreAssembler> extends Assemblers.VisibilityIdentityConfig<T> http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/DerbySQLEntityStoreAssembler.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/DerbySQLEntityStoreAssembler.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/DerbySQLEntityStoreAssembler.java index f150ede..121ef42 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/DerbySQLEntityStoreAssembler.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/DerbySQLEntityStoreAssembler.java @@ -2,6 +2,9 @@ package org.apache.polygene.entitystore.sql.assembly; import org.jooq.SQLDialect; +/** + * Assembly for the Derby SQL Entity Store. + */ public class DerbySQLEntityStoreAssembler extends AbstractSQLEntityStoreAssembler<DerbySQLEntityStoreAssembler> { protected SQLDialect getSQLDialect() http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/H2SQLEntityStoreAssembler.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/H2SQLEntityStoreAssembler.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/H2SQLEntityStoreAssembler.java index 4bc40e2..51b9977 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/H2SQLEntityStoreAssembler.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/H2SQLEntityStoreAssembler.java @@ -2,6 +2,9 @@ package org.apache.polygene.entitystore.sql.assembly; import org.jooq.SQLDialect; +/** + * Assembly for the H2 SQL Entity Store. + */ public class H2SQLEntityStoreAssembler extends AbstractSQLEntityStoreAssembler<H2SQLEntityStoreAssembler> { protected SQLDialect getSQLDialect() http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MariaDbSQLEntityStoreAssembler.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MariaDbSQLEntityStoreAssembler.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MariaDbSQLEntityStoreAssembler.java index a9b6d6b..00e85d9 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MariaDbSQLEntityStoreAssembler.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MariaDbSQLEntityStoreAssembler.java @@ -2,6 +2,9 @@ package org.apache.polygene.entitystore.sql.assembly; import org.jooq.SQLDialect; +/** + * Assembly for the MariaDb SQL Entity Store. + */ public class MariaDbSQLEntityStoreAssembler extends AbstractSQLEntityStoreAssembler<MariaDbSQLEntityStoreAssembler> { protected SQLDialect getSQLDialect() http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MySQLEntityStoreAssembler.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MySQLEntityStoreAssembler.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MySQLEntityStoreAssembler.java index 4cc3bda..4704f67 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MySQLEntityStoreAssembler.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/MySQLEntityStoreAssembler.java @@ -2,6 +2,9 @@ package org.apache.polygene.entitystore.sql.assembly; import org.jooq.SQLDialect; +/** + * Assembly for the MySQL Entity Store. + */ public class MySQLEntityStoreAssembler extends AbstractSQLEntityStoreAssembler<MySQLEntityStoreAssembler> { protected SQLDialect getSQLDialect() http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/PostgreSQLEntityStoreAssembler.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/PostgreSQLEntityStoreAssembler.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/PostgreSQLEntityStoreAssembler.java index 34901f4..324e0cf 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/PostgreSQLEntityStoreAssembler.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/PostgreSQLEntityStoreAssembler.java @@ -2,6 +2,9 @@ package org.apache.polygene.entitystore.sql.assembly; import org.jooq.SQLDialect; +/** + * Assembly for the Postgresql SQL Entity Store. + */ public class PostgreSQLEntityStoreAssembler extends AbstractSQLEntityStoreAssembler<PostgreSQLEntityStoreAssembler> { protected SQLDialect getSQLDialect() http://git-wip-us.apache.org/repos/asf/polygene-java/blob/5c46d1e2/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/SQLiteEntityStoreAssembler.java ---------------------------------------------------------------------- diff --git a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/SQLiteEntityStoreAssembler.java b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/SQLiteEntityStoreAssembler.java index 6f132fd..ab2f9a5 100644 --- a/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/SQLiteEntityStoreAssembler.java +++ b/extensions/entitystore-sql/src/main/java/org/apache/polygene/entitystore/sql/assembly/SQLiteEntityStoreAssembler.java @@ -2,6 +2,9 @@ package org.apache.polygene.entitystore.sql.assembly; import org.jooq.SQLDialect; +/** + * Assembly for the SQLite SQL Entity Store. + */ public class SQLiteEntityStoreAssembler extends AbstractSQLEntityStoreAssembler<SQLiteEntityStoreAssembler> { protected SQLDialect getSQLDialect()
