The reason I didn't want to wrap the JSR 352 APIs in our APIs in the first place is it would actually limit what users can do. For now there are just a few methods that use parameters (start, restart), but the JSR 352 spec might add more in the future. For instance startInThreadPool(String threadPoolName, String jobName, Properties parameters). Or even a JSR 352 runtime could provide its own, alternative interfaces that accept a job name and job parameters.

Yes, we should not limit what users can do. In particular, the re-usability of parameters that they built in future usages, like start, restart. Therefore, returning only the execution id is clearly not a good idea. My feeling is the current implementation is too verbose, users may not need to know the job name, and the chained method .parameters().

What about splitting the job construction into two steps, where:

• Step 1 creates all the parameters
• Step 2 uses either JSR-325 standard or our wrapper:
  • Get parameters and use JSR-352 standard
  • Use our wrapper to start

Properties params = MassIndexingJob
        .forEntities( EntityA.class, EntityB.class )
        .paramA( "foo" )
        .paramB( "bar" )
        .build();
JobOperator jobOperator = BatchRuntime.getJobOperator();
long executionId = jobOperator.start( MassIndexingJob.NAME, parameters );

When using our wrapper, the main benefit is that users don't need to know about the MassIndexingJob.NAME, and MassIndexingJob#parameters anymore:

// `sth` can be the execution ID
// or another wrapper including the parameters
Object sth = MassIndexingJob
        .forEntities( EntityA.class, EntityB.class )
        .paramA( "foo" )
        .paramB( "bar" )
        .start();

If we forced users to go through our APIs, we would have to maintain them to keep them in sync with the JSR-352 APIs. I don't really want to do that.

My new proposal might avoid being sync with the JSR-352 API, where we provide only the start-command wrapping. Other commands are considered as advanced commands, therefore, users need to use the standard JSR-352 APIs (or create their own wrapper).