Mark jobs as final once again, but add an abstract decorator that helps construction (#82)

Author: yann-eugone

src/batch-symfony-framework/docs/getting-started.md

@@ -88,13 +88,14 @@ use Symfony\Component\HttpKernel\KernelInterface;
 use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
 use Yokai\Batch\Bridge\Doctrine\Persistence\ObjectWriter;
 use Yokai\Batch\Bridge\Symfony\Serializer\DenormalizeItemProcessor;
+use Yokai\Batch\Job\AbstractDecoratedJob;
 use Yokai\Batch\Job\Item\ItemJob;
 use Yokai\Batch\Job\Item\Reader\Filesystem\JsonLinesReader;
 use Yokai\Batch\Job\Parameters\DefaultParameterAccessor;
 use Yokai\Batch\Job\Parameters\JobExecutionParameterAccessor;
 use Yokai\Batch\Storage\JobExecutionStorageInterface;
 
-final class ImportUsersJob extends ItemJob
+final class ImportUsersJob extends AbstractDecoratedJob
 {
     public function __construct(
         JobExecutionStorageInterface $executionStorage,
@@ -103,16 +104,18 @@ final class ImportUsersJob extends ItemJob
         KernelInterface $kernel,
     ) {
         parent::__construct(
-            500,
-            new JsonLinesReader(
-                new DefaultParameterAccessor(
-                    new JobExecutionParameterAccessor('importFile'),
-                    $kernel->getProjectDir() . '/var/import/users.jsonl'
-                )
-            ),
-            new DenormalizeItemProcessor($denormalizer, User::class),
-            new ObjectWriter($doctrine),
-            $executionStorage
+            new ItemJob(
+                500,
+                new JsonLinesReader(
+                    new DefaultParameterAccessor(
+                        new JobExecutionParameterAccessor('importFile'),
+                        $kernel->getProjectDir() . '/var/import/users.jsonl'
+                    )
+                ),
+                new DenormalizeItemProcessor($denormalizer, User::class),
+                new ObjectWriter($doctrine),
+                $executionStorage
+            )
         );
     }
 }

src/batch/docs/domain/job.md

@@ -31,11 +31,14 @@ The only requirement is implementing [`JobInterface`](../../src/Job/JobInterface
 ## What types of job exists ?
 
 **Built-in jobs:**
+- [AbstractDecoratedJob](../../src/Job/AbstractDecoratedJob.php):
+  a job that is designed to be extended, helps job construction.
 - [ItemJob](../../src/Job/Item/ItemJob.php):
   ETL like, batch processing job ([documentation](item-job.md)).
 - [JobWithChildJobs](../../src/Job/JobWithChildJobs.php):
   a job that trigger other jobs ([documentation](job-with-children.md)).
 - [TriggerScheduledJobsJob](../../src/Trigger/TriggerScheduledJobsJob.php):
+  a job that trigger other jobs when schedule is due (todo documentation).
 
 **Jobs from bridges:**
 - [CopyFilesJob (`league/flysystem`)](https://github.com/yokai-php/batch-league-flysystem/blob/0.x/src/Job/CopyFilesJob.php):

src/batch/src/Job/AbstractDecoratedJob.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yokai\Batch\Job;
+
+use Yokai\Batch\JobExecution;
+
+/**
+ * This {@see JobInterface} is designed to be extended in your project.
+ * It decorates another {@see JobInterface} that will actually run the code.
+ * It might be used as a "constructor helper".
+ */
+abstract class AbstractDecoratedJob implements JobInterface
+{
+    public function __construct(
+        private JobInterface $job,
+    ) {
+    }
+
+    final public function execute(JobExecution $jobExecution): void
+    {
+        $this->preExecute($jobExecution);
+        $this->job->execute($jobExecution);
+        $this->postExecute($jobExecution);
+    }
+
+    /**
+     * Overrides this method if you want to do something before the job is executed.
+     */
+    protected function preExecute(JobExecution $jobExecution): void
+    {
+    }
+
+    /**
+     * Overrides this method if you want to do something after the job is executed.
+     */
+    protected function postExecute(JobExecution $jobExecution): void
+    {
+    }
+}

src/batch/src/Job/Item/ItemJob.php

@@ -4,6 +4,7 @@
 
 namespace Yokai\Batch\Job\Item;
 
+use Yokai\Batch\Job\AbstractDecoratedJob;
 use Yokai\Batch\Job\Item\Exception\SkipItemException;
 use Yokai\Batch\Job\JobInterface;
 use Yokai\Batch\JobExecution;
@@ -17,6 +18,8 @@
  * Items are Extracted using an {@see ItemReaderInterface}.
  * Then Transformed using an {@see ItemProcessorInterface}.
  * And finally Loaded using an {@see ItemWriterInterface}.
+ *
+ * @final use {@see AbstractDecoratedJob} instead.
  */
 class ItemJob implements JobInterface
 {

src/batch/src/Job/JobWithChildJobs.php

@@ -11,6 +11,8 @@
 /**
  * This {@see JobInterface} will execute by triggering child jobs.
  * If a child job fails, following child jobs won't be executed.
+ *
+ * @final use {@see AbstractDecoratedJob} instead.
  */
 class JobWithChildJobs implements JobInterface
 {

tests/symfony/src/Job/Country/CountryJob.php

@@ -8,6 +8,7 @@
 use Yokai\Batch\Bridge\Box\Spout\Writer\FlatFileWriter;
 use Yokai\Batch\Bridge\Box\Spout\Writer\Options\CSVOptions;
 use Yokai\Batch\Bridge\Symfony\Framework\JobWithStaticNameInterface;
+use Yokai\Batch\Job\AbstractDecoratedJob;
 use Yokai\Batch\Job\Item\ElementConfiguratorTrait;
 use Yokai\Batch\Job\Item\FlushableInterface;
 use Yokai\Batch\Job\Item\ItemJob;
@@ -43,7 +44,7 @@
  * - a JSONL file, like :
  *   {"iso2":"FR","iso3":"FRA","name":"France","continent":"EU","currency":"EUR","phone":"33"}
  */
-final class CountryJob extends ItemJob implements
+final class CountryJob extends AbstractDecoratedJob implements
     JobWithStaticNameInterface,
     JobExecutionAwareInterface,
     ItemProcessorInterface,
@@ -83,11 +84,13 @@ public function __construct(JobExecutionStorageInterface $executionStorage, Kern
         ]);
 
         parent::__construct(
-            \PHP_INT_MAX,
-            new SequenceReader(\array_map($reader, $fragments)),
-            $this,
-            $this,
-            $executionStorage
+            new ItemJob(
+                \PHP_INT_MAX,
+                new SequenceReader(\array_map($reader, $fragments)),
+                $this,
+                $this,
+                $executionStorage
+            ),
         );
     }
 

tests/symfony/src/Job/StarWars/AbstractImportStartWarsEntityJob.php

@@ -13,6 +13,7 @@
 use Yokai\Batch\Bridge\Doctrine\Persistence\ObjectWriter;
 use Yokai\Batch\Bridge\Symfony\Framework\JobWithStaticNameInterface;
 use Yokai\Batch\Bridge\Symfony\Validator\SkipInvalidItemProcessor;
+use Yokai\Batch\Job\AbstractDecoratedJob;
 use Yokai\Batch\Job\Item\ItemJob;
 use Yokai\Batch\Job\Item\Processor\ArrayMapProcessor;
 use Yokai\Batch\Job\Item\Processor\CallbackProcessor;
@@ -35,7 +36,7 @@
  * Writer :
  * - Write processed entities to the database.
  */
-abstract class AbstractImportStartWarsEntityJob extends ItemJob implements JobWithStaticNameInterface
+abstract class AbstractImportStartWarsEntityJob extends AbstractDecoratedJob implements JobWithStaticNameInterface
 {
     public function __construct(
         string $file,
@@ -45,21 +46,23 @@ public function __construct(
         JobExecutionStorageInterface $executionStorage
     ) {
         parent::__construct(
-            50, // could be much higher, but set this way for demo purpose
-            new FlatFileReader(
-                new StaticValueParameterAccessor($file),
-                new CSVOptions(),
-                HeaderStrategy::combine()
-            ),
-            new ChainProcessor([
-                new ArrayMapProcessor(
-                    fn(string $value) => $value === 'NA' ? null : $value
+            new ItemJob(
+                50, // could be much higher, but set this way for demo purpose
+                new FlatFileReader(
+                    new StaticValueParameterAccessor($file),
+                    new CSVOptions(),
+                    HeaderStrategy::combine()
                 ),
-                new CallbackProcessor($process),
-                new SkipInvalidItemProcessor($validator),
-            ]),
-            new ObjectWriter($doctrine),
-            $executionStorage
+                new ChainProcessor([
+                    new ArrayMapProcessor(
+                        fn(string $value) => $value === 'NA' ? null : $value
+                    ),
+                    new CallbackProcessor($process),
+                    new SkipInvalidItemProcessor($validator),
+                ]),
+                new ObjectWriter($doctrine),
+                $executionStorage
+            )
         );
     }
 }

tests/symfony/src/Job/StarWars/ImportStarWarsJob.php

@@ -5,6 +5,7 @@
 namespace Yokai\Batch\Sources\Tests\Symfony\App\Job\StarWars;
 
 use Yokai\Batch\Bridge\Symfony\Framework\JobWithStaticNameInterface;
+use Yokai\Batch\Job\AbstractDecoratedJob;
 use Yokai\Batch\Job\JobExecutor;
 use Yokai\Batch\Job\JobWithChildJobs;
 use Yokai\Batch\Storage\JobExecutionStorageInterface;
@@ -15,7 +16,7 @@
  *  - {@see ImportStarWarsSpecieJob} : import species
  *  - {@see ImportStarWarsCharacterJob} : import characters
  */
-final class ImportStarWarsJob extends JobWithChildJobs implements JobWithStaticNameInterface
+final class ImportStarWarsJob extends AbstractDecoratedJob implements JobWithStaticNameInterface
 {
     public static function getJobName(): string
     {
@@ -24,11 +25,13 @@ public static function getJobName(): string
 
     public function __construct(JobExecutionStorageInterface $executionStorage, JobExecutor $jobExecutor)
     {
-        parent::__construct($executionStorage, $jobExecutor, [
-            // in that case, job order matters
-            ImportStarWarsPlanetJob::getJobName(),
-            ImportStarWarsSpecieJob::getJobName(),
-            ImportStarWarsCharacterJob::getJobName(),
-        ]);
+        parent::__construct(
+            new JobWithChildJobs($executionStorage, $jobExecutor, [
+                // in that case, job order matters
+                ImportStarWarsPlanetJob::getJobName(),
+                ImportStarWarsSpecieJob::getJobName(),
+                ImportStarWarsCharacterJob::getJobName(),
+            ])
+        );
     }
 }