fix up and update README.md

Author: Gerald Unterrainer

README.md

@@ -421,3 +421,87 @@ List<NexusUserJpa> g = query.getN(22);
 NexusUserJpa h = query.getSingle();
 ```
 
+#### Tenant Capability
+
+The system allows to save different tennants within the same tables, in order to ease development.
+
+This is done on a per-DAO basis (per -table so to say), as there has to be a separate table holding permission-data regarding the tenant-IDs and corresponding reference-IDs.
+
+```bash
+--- Person
+id		(Long)
+name	(String)
+
+--- Person_Permission
+id				(Long)
+referenceId		(Long)
+tenantId		(Long)
+
+----------------------------------------
+--- Person
+1	Peter
+2	Paul
+3	Mary
+
+--- Person_Permission
+1	1	1
+2	2	1
+2	3	2
+```
+
+When a user having tenantId=1 associated will query the full list of Persons, he will inevitably receive 'Peter and Paul', whereas another user associated with tennantId=2 would receive 'Mary'.
+
+##### Data-Side
+
+To enable this feature, you have to generate a special DAO that is linked to the corresponding permissions-DAO by specifying the JPA-type of the permission-DAO and both the name of the reference-ID and tenant-ID field (all that is explained in the constructor of the DAO).
+
+So you have to create the appropriate permission-table, a permission-JPA for the table.
+
+##### User-Side
+
+In order to query those tables accordingly, your querying user has to be associated with a tenant-ID.
+
+In fact there are TWO associations with multiple tenant-IDs there.
+The `tenant_read` set, used to determine if a user can see (and therefore modify or delete) a row, and the `tenant_write` set, used to determine how many and which permission-rows there are to write when creating a new row in the main-table.
+
+###### Setting permissions in the DAO
+
+On the DAO-level (if you do DB stuff on the server) you may specify those freely using the according setters in the query-builders of the DAO. When using the DAO you will only have to specify a single set of tenant-IDs since you know how you're planning on using those yourself (if you will create a row, then the tenant-ID set is equivalent to the `tenant_write` set; if you will only query, then specify a tenant-ID set equivalent to the `tenant_read` set).
+
+###### Setting permissions via KeyCloak
+
+In KeyCloak you have to specify both sets per user and the system will pick the appropriate set when manipulating or querying the database.
+
+This is done by settings User-Attributes.
+
+```bash
+User: Psilo / Attributes
+-- tenant_read:		1,3
+-- tenant_write:	1
+```
+
+On KeyCloak-Setup, be advised that you have to specify an Attribute-Mapper for both attributes (`Clients-><ClientName>->Mappers, create with name=tenants_read/tenants_write, User Attribute=<name>, Token Claim Name=<name>, Claim JSON Type=String`).
+
+That set up, the Attribute values will be passed on into the JWT token and parsed by Http-Server (the data will be copied to the Context.Attribute Object from where you may retrieve them at any time during a request).
+The system will decide automatically which set to use, so that in this example the user `Psilo` will be able to see rows that have the permission for tenant-ID 1 or 3, but when creating a row, it will only write a permission for tenant-ID 1.
+
+##### Example
+
+```java
+// Passing the TestPermissionJpa class enables the tenant-capability.
+// The TestPermissionJpa has a getReferenceId() and getTenantId() method
+// as required by the default setting.
+server.handlerGroupFor(TestJpa.class, TestJson.class,
+	new JpqlDao<>(emf, TestJpa.class, TestPermissionJpa.class))
+.path("/tenanttests")
+.endpoints(Endpoint.ALL)
+.jsonMapper(mapper)
+.addRoleFor(Endpoint.ALL, RoleBuilder.authenticated())...
+
+// The next example sets up tenant-capability using a JPA that has a
+// getRefId() and a getTId() method (not default).
+server.handlerGroupFor(TestJpa.class, TestJson.class,
+	new JpqlDao<>(emf, TestJpa.class, TestPermissionJpa.class, "refId", "tId"))
+.path("/tenanttests")
+```
+

src/main/java/info/unterrainer/commons/httpserver/GenericHandlerGroup.java

@@ -44,11 +44,6 @@ public class GenericHandlerGroup<P extends BasicJpa, J extends BasicJson, E> imp
 	private final LinkedHashMap<Endpoint, Role[]> accessRoles;
 	private final ExecutorService executorService;
 	private final HandlerUtils hu = new HandlerUtils();
-	private final String tenantIdRowName;
-	private final CoreDao<? extends BasicJpa, E> tenantDao;
-	private final Class<? extends BasicJpa> tenantJpaType;
-	private final String fieldRowName;
-	private final String tenantRowName;
 
 	@Override
 	public void addHandlers(final HttpServer server) {
@@ -132,7 +127,7 @@ private void getList(final Context ctx) {
 
 		ListJson<P> bList = dao.getList(transaction.getManager(), offset, size, interceptorResult.getSelectClause(),
 				interceptorResult.getJoinClause(), interceptorResult.getWhereClause(), interceptorResult.getParams(),
-				interceptorResult.getOrderByClause());
+				interceptorResult.getOrderByClause(), hu.getReadTenantIdsFrom(ctx));
 		ListJson<J> jList = new ListJson<>();
 		for (P entry : bList.getEntries())
 			jList.getEntries().add(orikaMapper.map(entry, jsonType));
@@ -153,7 +148,7 @@ private void create(final Context ctx) throws IOException {
 			DaoTransaction<E> transaction = dao.getTransactionManager().beginTransaction();
 
 			mappedJpa = extensions.runPreInsert(ctx, transaction.getManager(), json, mappedJpa, executorService);
-			P createdJpa = dao.create(transaction.getManager(), mappedJpa);
+			P createdJpa = dao.create(transaction.getManager(), mappedJpa, hu.getWriteTenantIdsFrom(ctx));
 			J r = orikaMapper.map(createdJpa, jsonType);
 
 			r = extensions.runPostInsert(ctx, transaction.getManager(), json, mappedJpa, createdJpa, r,
@@ -179,7 +174,7 @@ private void fullUpdate(final Context ctx) throws IOException {
 
 			mappedJpa = extensions.runPreModify(ctx, transaction.getManager(), jpa.getId(), json, jpa, mappedJpa,
 					executorService);
-			P persistedJpa = dao.update(transaction.getManager(), mappedJpa);
+			P persistedJpa = dao.update(transaction.getManager(), mappedJpa, hu.getReadTenantIdsFrom(ctx));
 
 			J r = orikaMapper.map(persistedJpa, jsonType);
 			r = extensions.runPostModify(ctx, transaction.getManager(), jpa.getId(), json, jpa, mappedJpa, persistedJpa,
@@ -200,7 +195,7 @@ private void delete(final Context ctx) {
 		DaoTransaction<E> transaction = dao.getTransactionManager().beginTransaction();
 
 		id = extensions.runPreDelete(ctx, transaction.getManager(), id, executorService);
-		dao.delete(transaction.getManager(), id);
+		dao.delete(transaction.getManager(), id, hu.getReadTenantIdsFrom(ctx));
 		ctx.status(204);
 		extensions.runPostDelete(ctx, transaction.getManager(), id, executorService);
 

src/main/java/info/unterrainer/commons/httpserver/GenericHandlerGroupBuilder.java

@@ -37,12 +37,6 @@ public class GenericHandlerGroupBuilder<P extends BasicJpa, J extends BasicJson,
 	private List<GetListInterceptor> getListInterceptors = new ArrayList<>();
 	private ExecutorService executorService;
 
-	private String tenantIdRowName;
-	private String tenantRowName;
-	private String tenantFieldRowName;
-	private CoreDao<? extends BasicJpa, E> tenantDao;
-	private Class<? extends BasicJpa> tenantJpaType;
-
 	HandlerExtensions<P, J, E> extensions = new HandlerExtensions<>();
 	private LinkedHashMap<Endpoint, Role[]> accessRoles = new LinkedHashMap<>();
 
@@ -55,8 +49,7 @@ public HttpServer add() {
 			executorService = server.executorService;
 		GenericHandlerGroup<P, J, E> handlerGroupInstance = new GenericHandlerGroup<>(dao, jpaType, jsonType,
 				jsonMapper, orikaFactory.getMapperFacade(), path, endpoints, getListInterceptors, extensions,
-				accessRoles, executorService, tenantIdRowName, tenantDao, tenantJpaType, tenantFieldRowName,
-				tenantRowName);
+				accessRoles, executorService);
 		server.addHandlerGroup(handlerGroupInstance);
 		return server;
 	}
@@ -70,21 +63,6 @@ public GenericHandlerGroupBuilder<P, J, E> addRoleFor(final Endpoint endpoint, f
 		return this;
 	}
 
-	public GenericHandlerGroupBuilder<P, J, E> isMultiTenantEnabledByIdRow(final String tenantIdRowName) {
-		this.tenantIdRowName = tenantIdRowName;
-		return this;
-	}
-
-	public <TP extends BasicJpa> GenericHandlerGroupBuilder<P, J, E> isMultiTenantEnabledByTable(
-			final CoreDao<TP, E> tenantDao, final Class<TP> tenantJpaType, final String fieldRowName,
-			final String tenantRowName) {
-		this.tenantDao = tenantDao;
-		this.tenantJpaType = tenantJpaType;
-		this.tenantFieldRowName = fieldRowName;
-		this.tenantRowName = tenantRowName;
-		return this;
-	}
-
 	public GenericHandlerGroupBuilder<P, J, E> jsonMapper(final JsonMapper jsonMapper) {
 		this.jsonMapper = jsonMapper;
 		return this;

src/main/java/info/unterrainer/commons/httpserver/HandlerUtils.java

@@ -3,9 +3,11 @@
 import java.time.LocalDateTime;
 import java.time.format.DateTimeFormatter;
 import java.time.format.DateTimeParseException;
+import java.util.Set;
 
 import info.unterrainer.commons.httpserver.daos.CoreDao;
 import info.unterrainer.commons.httpserver.daos.DaoTransaction;
+import info.unterrainer.commons.httpserver.enums.Attribute;
 import info.unterrainer.commons.httpserver.enums.QueryField;
 import info.unterrainer.commons.httpserver.exceptions.BadRequestException;
 import info.unterrainer.commons.httpserver.exceptions.NotFoundException;
@@ -22,17 +24,25 @@ public Long checkAndGetId(final Context ctx) {
 
 	public <P extends BasicJpa, E> P getJpaById(final Context ctx, final E manager, final CoreDao<P, E> dao) {
 		Long id = checkAndGetId(ctx);
-		P jpa = dao.getById(manager, id);
+		P jpa = dao.getById(manager, id, getReadTenantIdsFrom(ctx));
 		if (jpa == null)
 			throw new NotFoundException();
 		return jpa;
 	}
 
+	public Set<Long> getReadTenantIdsFrom(final Context ctx) {
+		return ctx.attribute(Attribute.USER_TENANTS_READ_SET);
+	}
+
+	public Set<Long> getWriteTenantIdsFrom(final Context ctx) {
+		return ctx.attribute(Attribute.USER_TENANTS_WRITE_SET);
+	}
+
 	public <P extends BasicJpa, E> P getJpaById(final Context ctx, final CoreDao<P, E> dao) {
 		Long id = checkAndGetId(ctx);
 		DaoTransaction<E> transaction = dao.getTransactionManager().beginTransaction();
 		try {
-			P jpa = dao.getById(transaction.getManager(), id);
+			P jpa = dao.getById(transaction.getManager(), id, getReadTenantIdsFrom(ctx));
 			if (jpa == null)
 				throw new NotFoundException();
 			return jpa;

src/main/java/info/unterrainer/commons/httpserver/daos/AsyncJpaListQueryBuilder.java

@@ -0,0 +1,44 @@
+package info.unterrainer.commons.httpserver.daos;
+
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
+
+import javax.persistence.EntityManagerFactory;
+
+import info.unterrainer.commons.rdbutils.entities.BasicAsyncJpa;
+import info.unterrainer.commons.rdbutils.enums.AsyncState;
+
+public class AsyncJpaListQueryBuilder<P extends BasicAsyncJpa>
+		extends BasicListQueryBuilder<P, P, AsyncJpaListQueryBuilder<P>> implements QueryInterface<P, P> {
+
+	private Set<AsyncState> asyncStates = new HashSet<>();
+
+	AsyncJpaListQueryBuilder(final EntityManagerFactory emf, final AsyncJpqlDao<P> dao, final Class<P> resultType) {
+		super(emf, dao, resultType);
+	}
+
+	public JpaListQuery<P> build() {
+		return new JpaListQuery<>(emf, this);
+	}
+
+	/**
+	 * Adds a single or multiple OR-clauses containing the specified
+	 * {@link AsyncState}s.
+	 * <p>
+	 * For example calling
+	 * {@code .whereStateOf(AsyncState.NEW, AsyncState.PROCESSING)} will result in
+	 * the where-clause
+	 * {@code (..rest of where clause..) AND (state = 'NEW' OR state = 'PROCESSING').}
+	 * <p>
+	 * Repetitive calling of this method just adds all the AsyncState values
+	 * (doesn't clear the collection).
+	 *
+	 * @param asyncStates a single or number of AsyncState values
+	 * @return an instance of this builder to provide a fluent interface
+	 */
+	public AsyncJpaListQueryBuilder<P> asyncStateOf(final AsyncState... asyncStates) {
+		this.asyncStates.addAll(Arrays.asList(asyncStates));
+		return this;
+	}
+}

src/main/java/info/unterrainer/commons/httpserver/daos/AsyncJpqlDao.java

@@ -3,9 +3,51 @@
 import javax.persistence.EntityManagerFactory;
 
 import info.unterrainer.commons.rdbutils.entities.BasicAsyncJpa;
+import info.unterrainer.commons.rdbutils.entities.BasicJpa;
 
 public class AsyncJpqlDao<P extends BasicAsyncJpa> extends BasicJpqlDao<P> {
 
+	/**
+	 * Generates a DAO that lets you build and execute queries.
+	 * <p>
+	 * This dao has a tenant-permission table attached and may retrieve and write
+	 * data per tenant.
+	 * <p>
+	 * {@code tenantReferenceFieldName} defaults to {@code referenceId}<br>
+	 * {@code tenantReferenceFieldName} defaults to {@code tenantId}
+	 *
+	 * @param emf           the {@link EntityManagerFactory} to use
+	 * @param type          the return-type of the query (the underlying JPA)
+	 * @param tenantJpaType the JPA of the tenant-permission table associated
+	 */
+	public AsyncJpqlDao(final EntityManagerFactory emf, final Class<P> type,
+			final Class<? extends BasicJpa> tenantJpaType) {
+		super(emf, type);
+		this.coreDao.tenantData = new TenantData(tenantJpaType);
+	}
+
+	/**
+	 * Generates a DAO that lets you build and execute queries.
+	 * <p>
+	 * This dao has a tenant-permission table attached and may retrieve and write
+	 * data per tenant.
+	 *
+	 * @param emf                      the {@link EntityManagerFactory} to use
+	 * @param type                     the return-type of the query (the underlying
+	 *                                 JPA)
+	 * @param tenantJpaType            the JPA of the tenant-permission table
+	 *                                 associated
+	 * @param tenantReferenceFieldName the name of the field holding the reference
+	 *                                 to the main-table-id
+	 * @param tenantIdFieldName        the name of the field holding the tenant-ID
+	 */
+	public AsyncJpqlDao(final EntityManagerFactory emf, final Class<P> type,
+			final Class<? extends BasicJpa> tenantJpaType, final String tenantReferenceFieldName,
+			final String tenantIdFieldName) {
+		super(emf, type);
+		this.coreDao.tenantData = new TenantData(tenantJpaType, tenantReferenceFieldName, tenantIdFieldName);
+	}
+
 	/**
 	 * Generates a DAO that lets you build and execute queries.
 	 *
@@ -22,8 +64,8 @@ public AsyncJpqlDao(final EntityManagerFactory emf, final Class<P> type) {
 	 *
 	 * @return a query-builder
 	 */
-	public AsyncListQueryBuilder<P, P> select() {
-		return new AsyncListQueryBuilder<>(emf, this, type);
+	public AsyncJpaListQueryBuilder<P> select() {
+		return new AsyncJpaListQueryBuilder<>(emf, this, type);
 	}
 
 	/**
@@ -64,8 +106,8 @@ public <T> AsyncListQueryBuilder<P, T> select(final String selectClause, final C
 	 *                     a "SELECT o")
 	 * @return a query-builder
 	 */
-	public AsyncListQueryBuilder<P, P> select(final String selectClause) {
-		AsyncListQueryBuilder<P, P> b = new AsyncListQueryBuilder<>(emf, this, type);
+	public AsyncJpaListQueryBuilder<P> select(final String selectClause) {
+		AsyncJpaListQueryBuilder<P> b = new AsyncJpaListQueryBuilder<>(emf, this, type);
 		b.setSelect(selectClause);
 		return b;
 	}

src/main/java/info/unterrainer/commons/httpserver/daos/BasicJpqlDao.java

@@ -1,13 +1,12 @@
 package info.unterrainer.commons.httpserver.daos;
 
-import java.time.LocalDateTime;
 import java.util.List;
+import java.util.Set;
 
 import javax.persistence.EntityManager;
 import javax.persistence.EntityManagerFactory;
 import javax.persistence.TypedQuery;
 
-import info.unterrainer.commons.jreutils.DateUtils;
 import info.unterrainer.commons.rdbutils.entities.BasicJpa;
 import lombok.Getter;
 
@@ -25,12 +24,6 @@ public BasicJpqlDao(final EntityManagerFactory emf, final Class<P> type) {
 		coreDao = new JpqlCoreDao<>(emf, type);
 	}
 
-	P update(final EntityManager em, final P entity) {
-		LocalDateTime time = DateUtils.nowUtc();
-		entity.setEditedOn(time);
-		return em.merge(entity);
-	}
-
 	<T> List<T> getList(final EntityManager em, final TypedQuery<T> query, final long offset, final long size) {
 		int s = Integer.MAX_VALUE;
 		if (size < s)
@@ -52,17 +45,18 @@ private <T> T getFirst(final EntityManager em, final TypedQuery<T> query) {
 		return null;
 	}
 
-	UpsertResult<P> upsert(final EntityManager em, final TypedQuery<P> query, final P entity) {
+	UpsertResult<P> upsert(final EntityManager em, final TypedQuery<P> query, final P entity,
+			final Set<Long> tenantIds) {
 		boolean wasInserted = false;
 		boolean wasUpdated = false;
 		P e = getFirst(em, query);
 		if (e == null) {
-			e = coreDao.create(em, entity);
+			e = coreDao.create(em, entity, tenantIds);
 			wasInserted = true;
 		} else {
 			entity.setId(e.getId());
 			entity.setCreatedOn(e.getCreatedOn());
-			e = update(em, entity);
+			e = coreDao.update(em, entity, tenantIds);
 			wasUpdated = true;
 		}
 		return UpsertResult.<P>builder().wasInserted(wasInserted).wasUpdated(wasUpdated).jpa(e).build();