Access Job Description

[VascoFreire]

Issue:
In a project that I'm working on, we are listing the instantiated jobs.

One of the requests that we have is to have a description for each job.

Suggestion:
Since it is possible to define a description for the job (in xml), it would be useful to have access to this field in the java object.

[fmbenhassine]

I agree, thank you for raising this discrepancy between the XML and Java config styles. I will plan this for v6.

[fmbenhassine]

I just wanted to write down some findings here after a quick look to estimate the cost of the required change to support this feature. Adding the description to BATCH_JOB_INSTANCE would be duplicated (the name is already duplicated in all records..), so this will be problematic for a normalized DB schema as we already have. Therefore, this might require a new table for jobs.

Here is the change I think we might need to support this feature properly:

Index: spring-batch-core/src/main/resources/org/springframework/batch/core/schema-mysql.sql
 -- Autogenerated: do not edit this file
+CREATE TABLE BATCH_JOB (
+    JOB_ID BIGINT  NOT NULL PRIMARY KEY,
+    JOB_NAME VARCHAR(100) NOT NULL,
+    JOB_DESCRIPTION VARCHAR(2500) NOT NULL,
+    constraint JOB_NAME_UN unique (JOB_NAME)
+)
 
 CREATE TABLE BATCH_JOB_INSTANCE (
 	JOB_INSTANCE_ID BIGINT  NOT NULL PRIMARY KEY,
+    JOB_ID BIGINT NOT NULL,
 	VERSION BIGINT,
-	JOB_NAME VARCHAR(100) NOT NULL,
-	JOB_KEY VARCHAR(32) NOT NULL,
-	constraint JOB_INST_UN unique (JOB_NAME, JOB_KEY)
-) ENGINE=InnoDB;
+	JOB_INSTANCE_KEY VARCHAR(32) NOT NULL,
+    constraint JOB_FK foreign key (JOB_ID) references BATCH_JOB(JOB_ID),
+	constraint JOB_INSTANCE_KEY_UN unique (JOB_INSTANCE_KEY)
+)
 

Job names and descriptions would be saved only once in BATCH_JOB, and BATCH_JOB_INSTANCE would link to that new table via the new JOB_ID column.

EDIT: The Job and Step interfaces could be turned into domain entities.

[benelog]

@fmbenhassine
I assume that @VascoFreire’s initial requirement was not necessarily about storing the job’s description in the metadata tables.
Of course, persisting it in the DB would give the benefit of tracking the full history of changes to the description.

However, implementing it that way comes with some drawbacks:

• It would require significant effort to migrate schemas from Spring Batch V5 to V6.
• Additional queries would be executed on the BATCH_JOB table for every job run.

In my opinion, unless there is strong demand for storing the description history in the DB, a more efficient s solution would be to simply add a description field to the Java class, as suggested in the following PR:

#4830

The history of how the description has changed can be tracked through Git commit history as well.

For reference, if you look at Quartz’s JobStore DB schema, it also uses JOB_NAME as the reference key in a similar way:
https://stackoverflow.com/questions/48557255/what-does-each-table-for-quartz-scheduler-signify

[fmbenhassine]

@benelog Thank you for your input! Indeed, my understanding was that the job description should be persisted. I think I misread "we are listing the instantiated jobs" in the initial issue description. I will let @VascoFreire confirm, but does this imply we are in a case of having a single JVM running several jobs? I would not recommend this deployment pattern but this is a discussion for another day. @VascoFreire Can you please confirm and share more context about your use case that requires the job description?

My question is: what is the added value of having the description only in memory? It's not really about tracking the history of the description changes (that would rarely change anyway), but more about being able to access the job name and description from the database, for example, to create a dashboard or generate a report. If I fire up a JVM to run a single job and shut down what would be the added value of having the job description?

I am just asking questions to correctly understand the requirement here. Looking forward to your feedback to see if we can include this in the upcoming v6.