Added a bunch of javadoc

Signed-off-by: coduz <alberto.codutti@eurotech.com>

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/JPAPersistenceManagerImpl.java

@@ -22,6 +22,7 @@
 import com.ibm.jbatch.container.persistence.CheckpointDataKey;
 import com.ibm.jbatch.container.services.IJobExecution;
 import com.ibm.jbatch.container.services.IPersistenceManagerService;
+import com.ibm.jbatch.container.services.impl.JDBCPersistenceManagerImpl;
 import com.ibm.jbatch.container.status.JobStatus;
 import com.ibm.jbatch.container.status.StepStatus;
 import com.ibm.jbatch.spi.services.IBatchConfig;
@@ -57,6 +58,27 @@
 import java.util.stream.Collectors;
 
 /**
+ * This is a custom implementation of the {@link IPersistenceManagerService} for jBatch which replace the default {@link JDBCPersistenceManagerImpl}.
+ * <p>
+ * This implementation is much more performant for many reasons, starting from using a DB connection pool and query that are precompiled by JPA using the {@link javax.persistence.NamedQueries}.
+ * Entity have been optimized and code now skips some checks that {@link  JDBCPersistenceManagerImpl} performs since those checks are not required by our usage of jBatch.
+ * This makes this implementation not compatible with the regular behaviour of the {@link JDBCPersistenceManagerImpl} but makes it fit our needing.
+ * <p>
+ * As a general overview if the jBatch tables they follow the schema below
+ *
+ * <pre>
+ *     JobInstanceData (aka: JobInstace)
+ *     |
+ *     |-- as one --- JobStatus
+ *     |-- as many -- ExecutionInstanceData (aka: JobExecution)
+ *                    |
+ *                    |-- as many -- StepExecutionInstanceData (aka: JobStepExecution)
+ *                    |              |
+ *                    |              |-- as one --- StepStatus
+ *                    |
+ *                    |-- as many -- CheckpointData
+ * </pre>
+ *
  * @since 1.2.0
  */
 public class JPAPersistenceManagerImpl extends AbstractKapuaService implements IPersistenceManagerService {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/JbatchEntityManagerFactory.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -19,7 +19,7 @@
 import java.util.Map;
 
 /**
- * {@link EntityManagerFactory} for the jbatch module.
+ * {@link EntityManagerFactory} for the jBatch module.
  *
  * @since 1.2.0
  */

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/AbstractJpaJbatchEntity.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -19,6 +19,14 @@
 import java.io.Serializable;
 
 /**
+ * Base class for JPA counterpart of jBatch entities.
+ * <p>
+ * It offers {@link #readObject(byte[])} and {@link #writeObject(Serializable)} as utility method since most of the jBatch entities on the default {@link com.ibm.jbatch.container.services.impl.JDBCPersistenceManagerImpl}
+ * contains binary objects. This is odd but current deployment have that format and, for backward compatibility we need to keep this format.
+ * <p>
+ * Further improvement could be use the Apache Lang 3 {@link org.apache.commons.lang3.SerializationUtils#serialize(Serializable)} and {@link org.apache.commons.lang3.SerializationUtils#deserialize(byte[])},
+ * but compatibility needs to be checked.
+ *
  * @since 1.2.0
  */
 public abstract class AbstractJpaJbatchEntity implements Serializable {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaCheckpointData.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -19,6 +19,11 @@
 import javax.persistence.Lob;
 import javax.persistence.Table;
 
+/**
+ * JPA counterpart of the {@link CheckpointData} object.
+ *
+ * @since 1.2.0
+ */
 @Entity(name = "CheckpointData")
 @Table(name = "jbtc_checkpoint_data")
 public class JpaCheckpointData extends AbstractJpaJbatchEntity {
@@ -35,6 +40,7 @@ public class JpaCheckpointData extends AbstractJpaJbatchEntity {
     private byte[] obj;
 
     public JpaCheckpointData() {
+        // Required by JPA
     }
 
     public long getJobInstanceId() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaCheckpointDataDAO.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -15,6 +15,11 @@
 import com.ibm.jbatch.container.persistence.CheckpointDataKey;
 import org.eclipse.kapua.commons.jpa.EntityManager;
 
+/**
+ * Service DAO for {@link JpaCheckpointData}
+ *
+ * @since 1.2.0
+ */
 public class JpaCheckpointDataDAO {
 
     private JpaCheckpointDataDAO() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaExecutionInstanceData.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -31,6 +31,11 @@
 import java.util.Date;
 import java.util.Properties;
 
+/**
+ * JPA counterpart of the {@link JobOperatorJobExecution} object.
+ *
+ * @since 1.2.0
+ */
 @Entity(name = "ExecutionInstanceData")
 @Table(name = "jbtc_execution_instance_data")
 @NamedQueries({
@@ -77,6 +82,7 @@ public class JpaExecutionInstanceData extends AbstractJpaJbatchEntity {
     private String exitStatus;
 
     public JpaExecutionInstanceData() {
+        // Required by JPA
     }
 
     public long getId() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaExecutionInstanceDataDAO.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -22,6 +22,11 @@
 import java.util.Properties;
 import java.util.Set;
 
+/**
+ * Service DAO for {@link JpaExecutionInstanceData}.
+ *
+ * @since 1.2.0
+ */
 public class JpaExecutionInstanceDataDAO {
 
     private JpaExecutionInstanceDataDAO() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaExecutionInstanceDataFields.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -11,6 +11,11 @@
  *******************************************************************************/
 package org.eclipse.kapua.job.engine.jbatch.persistence.jpa;
 
+/**
+ * Enumeration of {@link JpaExecutionInstanceDataFields}.
+ *
+ * @since 1.2.0
+ */
 public enum JpaExecutionInstanceDataFields {
     JOB_EXEC_ID,
     JOB_INSTANCE_ID,

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaJobInstanceData.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -25,6 +25,11 @@
 import javax.persistence.Transient;
 import java.io.Serializable;
 
+/**
+ * JPA counterpart of {@link JobInstance}
+ *
+ * @since 1.2.0
+ */
 @Entity(name = "JobInstanceData")
 @Table(name = "jbtc_job_instance_data")
 @NamedQueries({
@@ -58,6 +63,7 @@ public class JpaJobInstanceData implements Serializable {
     private String jobXml;
 
     public JpaJobInstanceData() {
+        // Required by JPA
     }
 
     public long getId() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaJobInstanceDataDAO.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -19,6 +19,11 @@
 import java.util.Map;
 import java.util.stream.Collectors;
 
+/**
+ * Service DAO for {@link JpaJobInstanceData}.
+ *
+ * @since 1.2.0
+ */
 public class JpaJobInstanceDataDAO {
 
     private JpaJobInstanceDataDAO() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaJobStatus.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -19,6 +19,11 @@
 import javax.persistence.Lob;
 import javax.persistence.Table;
 
+/**
+ * JPA counterpart for {@link JobStatus} object.
+ *
+ * @sicne 1.2.0
+ */
 @Entity(name = "JobStatus")
 @Table(name = "jbtc_job_status")
 public class JpaJobStatus extends AbstractJpaJbatchEntity {
@@ -32,6 +37,7 @@ public class JpaJobStatus extends AbstractJpaJbatchEntity {
     private byte[] obj;
 
     public JpaJobStatus() {
+        // Required by JPA
     }
 
     public long getJobInstanceId() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaJobStatusDAO.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -14,6 +14,11 @@
 import com.ibm.jbatch.container.status.JobStatus;
 import org.eclipse.kapua.commons.jpa.EntityManager;
 
+/**
+ * Service DAO for {@link JpaJobStatus}
+ *
+ * @since 1.2.0
+ */
 public class JpaJobStatusDAO {
 
     private JpaJobStatusDAO() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaStepExecutionInstanceData.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -33,6 +33,11 @@
 import java.sql.Timestamp;
 import java.util.Date;
 
+/**
+ * JPA counterpart of {@link javax.batch.runtime.StepExecution}
+ *
+ * @since 1.2.0
+ */
 @Entity(name = "StepExecutionInstanceData")
 @Table(name = "jbtc_step_execution_instance_data")
 @NamedQueries({
@@ -98,6 +103,7 @@ public class JpaStepExecutionInstanceData extends AbstractJpaJbatchEntity {
     private byte[] persistentData;
 
     public JpaStepExecutionInstanceData() {
+        // Required by JPA
     }
 
     public long getId() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaStepExecutionInstanceDataDAO.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -20,6 +20,11 @@
 import java.util.Map;
 import java.util.stream.Collectors;
 
+/**
+ * Service DAO for {@link JpaStepExecutionInstanceData}
+ *
+ * @since 1.2.0
+ */
 public class JpaStepExecutionInstanceDataDAO {
 
     private JpaStepExecutionInstanceDataDAO() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaStepStatus.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -21,6 +21,11 @@
 import javax.persistence.NamedQuery;
 import javax.persistence.Table;
 
+/**
+ * JPA counterpart of {@link StepStatus}.
+ *
+ * @since 1.2.0
+ */
 @Entity(name = "StepStatus")
 @Table(name = "jbtc_step_status")
 @NamedQueries({
@@ -46,6 +51,7 @@ public class JpaStepStatus extends AbstractJpaJbatchEntity {
     private byte[] obj;
 
     public JpaStepStatus() {
+        // Required by JPA
     }
 
     public long getStepExecutionId() {

job-engine/jbatch/src/main/java/org/eclipse/kapua/job/engine/jbatch/persistence/jpa/JpaStepStatusDAO.java

@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2019 Eurotech and/or its affiliates and others
+ * Copyright (c) 2020 Eurotech and/or its affiliates and others
  *
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
@@ -17,6 +17,11 @@
 import javax.persistence.TypedQuery;
 import java.util.List;
 
+/**
+ * Service DAO for {@link JpaStepStatus}.
+ *
+ * @since 1.2.0
+ */
 public class JpaStepStatusDAO {
 
     private JpaStepStatusDAO() {