Macchinetta Batch Framework (2.x) Development Guideline
Macchinetta Batch Framework (2.x) Development Guideline - version 2.6.1.RELEASE, 2026-3-30
> INDEX

# ジョブの起動パラメータ

## Overview

本節では、ジョブの起動パラメータ(以降、パラメータ)の利用方法について説明する。

本機能は、チャンクモデルとタスクレットモデルとで同じ使い方になる。

パラメータは、以下のような実行環境や実行タイミングに応じてジョブの動作を柔軟に切替える際に使用する。

- 処理対象のファイルパス

- システムの運用日時

パラメータを与える方法は、以下のとおりである。

1. コマンドライン引数から与える

2. ファイルから標準入力へリダイレクトする

指定したパラメータは、Bean定義やSpring管理下のJavaで参照できる。

## How to use

### パラメータ変換クラスについて

Spring Batchでは、受け取ったパラメータを以下の流れで処理する。

1. `JobParametersConverter`の実装クラスが`JobParameters`に変換する。

2. Bean定義やSpring管理下のJavaにて`JobParameters`からパラメータを参照する。

パラメータ変換クラスの実装クラスについて

Macchinetta Batch 2.xでは、前述した`JobParametersConverter`の実装クラスを複数提供する。 以下にそれぞれの特徴を示す。

- DefaultJobParametersConverter

  - Spring Batchが提供する。

  - パラメータのデータ型は `java.io.Serializable` を実装した任意のJavaBeansを指定できる。

- JobParametersConverterImpl

  - Macchinetta Batch 2.xが提供する。もともとSpring Batchで提供していたJsrJobParametersConverterを、JSR-352の廃止に伴いMacchinetta Batch 2.xへと移植したもの。

  - パラメータのデータ型を指定することができない(Stringのみ)。

  - パラメータにジョブ実行を識別するID(RUN_ID)を`jsr_batch_run_id`という名称で自動的に付与する。

    - RUN_IDは、ジョブが実行される都度増加する。増加は、データベースのSEQUENCE(名称は`JOB_SEQ`となる)を利用するため、重複することがない。

    - Spring Batchでは、同じパラメータで起動したジョブは同一ジョブとして認識され、同一ジョブは1度しか実行できない、という仕様がある。 これに対し、`jsr_batch_run_id`という名称のパラメータを一意な値で付加することにより、別のジョブと認識する仕組みとなっている。 詳細は、Spring Batchのアーキテクチャを参照。

Spring BatchではBean定義で使用する`JobParametersConverter`の実装クラスを指定しない場合、`DefaultJobParametersConverter`が使用される。
しかし、Macchinetta Batch 2.xでは以下の理由により`DefaultJobParametersConverter`は採用しない。

- 1つのジョブを同じパラメータによって、異なるタイミングで起動することは一般的である。

- 起動時刻のタイムスタンプなどを指定し、異なるジョブとして管理することも可能だが、それだけのためにジョブパラメータを指定するのは煩雑である。

- `DefaultJobParametersConverter`はパラメータに対しデータ型を指定することができるが、型変換に失敗した場合のハンドリングが煩雑になる。

Macchinetta Batch 2.xでは、`JobParametersConverterImpl`を利用することで、ユーザが意識することなく自動的にRUN_IDを付与している。 この仕組みにより、ユーザから見ると同一ジョブをSpring Batchとしては異なるジョブとして扱っている。

パラメータ変換クラスの設定について

ブランクプロジェクトでは、あらかじめ`TerasolunaBatchConfiguration.java/launch-context.xml`にて`JobParametersConverterImpl`を使用するように設定している。
そのためMacchinetta Batch 2.xを推奨設定で使用する場合は`JobParametersConverter`の設定を行う必要はない。

JavaConfig
com.example.batch.config.LaunchContextConfig.java

    @Configuration
    @Import(TerasolunaBatchConfiguration.class)
    public class LaunchContextConfig {
    // omitted
    @Bean
    public JobParametersConverter jobParametersConverter(
            @Qualifier("adminDataSource") DataSource adminDataSource) {
        return new JobParametersConverterImpl(adminDataSource);
    }

com.example.batch.config.TerasolunaBatchConfiguration.java

    @Override
    @Bean
    public JobOperator jobOperator(JobRepository jobRepository, JobExplorer jobExplorer, JobRegistry jobRegistry, JobLauncher jobLauncher) throws BatchConfigurationException {
        JobOperatorFactoryBean jobOperatorFactoryBean = new JobOperatorFactoryBean();
        jobOperatorFactoryBean.setTransactionManager(this.getTransactionManager());
        jobOperatorFactoryBean.setJobRepository(jobRepository);
        jobOperatorFactoryBean.setJobExplorer(jobExplorer);
        jobOperatorFactoryBean.setJobRegistry(jobRegistry);
        jobOperatorFactoryBean.setJobLauncher(jobLauncher);
        JobParametersConverterImpl jobParametersConverter = new JobParametersConverterImpl(
                getDataSource());
        jobOperatorFactoryBean.setJobParametersConverter(
                jobParametersConverter); // (1)

        try {
            jobParametersConverter.afterPropertiesSet();
            jobOperatorFactoryBean.afterPropertiesSet();
            return jobOperatorFactoryBean.getObject();

        } catch (BatchConfigurationException e) {
            throw e;
        } catch (Exception e) {
            throw new BatchConfigurationException(
                    "Unable to configure the customized job operator", e);
        }
    }

XMLConfig
META-INF\spring\launch-context.xml

    <bean id="jobParametersConverter"
          class="org.terasoluna.batch.converter.JobParametersConverterImpl"
          c:dataSource-ref="adminDataSource" />

    <bean id="jobOperator"
          class="org.springframework.batch.core.launch.support.SimpleJobOperator"
          p:jobRepository-ref="jobRepository"
          p:jobRegistry-ref="jobRegistry"
          p:jobExplorer-ref="jobExplorer"
          p:jobParametersConverter-ref="jobParametersConverter" <!-- (1) -->
          p:jobLauncher-ref="jobLauncher" />

項番 | 説明
--- | ---
(1) | jobOperatorのjobParametersConverterの設定 XMLConfigでは`jobParametersConverter-ref`属性にBean定義した`jobParametersConverter`を指定している。 JavaConfigでは`JobOperator`の`JobParametersConverter`の実装クラスがデフォルトでは`DefaultJobParametersConverter`のため、Bean定義をオーバーライドして`JobParametersConverterImpl`を設定するようにしている。

以降は`JobParametersConverterImpl`を利用する前提で説明する。

### コマンドライン引数から与える

まず、もっとも基本的な、コマンドライン引数から与える方法について説明する。

パラメータの付与

コマンドライン引数として`CommandLineJobRunner`の第3引数以降に`<パラメータ名>=<値>`形式で列挙する。

パラメータの個数や長さは、Spring BatchやMacchinetta Batch 2.xにおいては制限がない。 しかし、OSにはコマンド引数の長さに制限がある。
そのため、あまりに大量の引数が必要な場合は、ファイルから標準入力へリダイレクトするや パラメータとプロパティの併用などの方法を活用すること。

JavaConfig
コマンドライン引数としてパラメータを設定する例

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        com.example.batch.jobs.JobDefinedConfig.JobDefinedConfig JOBID param1=abc outputFileName=/tmp/result.csv

XMLConfig
コマンドライン引数としてパラメータを設定する例

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        JobDefined.xml JOBID param1=abc outputFileName=/tmp/result.csv

パラメータの参照

以下のように、Bean定義またはJavaで参照することができる。

- Bean定義で参照する

  - `#{jobParameters['xxx']}`で参照可能

- Javaで参照する

  - `@Value("#{jobParameters['xxx']}")`で参照可能

| JobParametersを参照するBeanのスコープはStepスコープでなければならない `JobParameters`を参照する際は、参照するBeanのスコープを`Step`スコープとする必要がある。 これは、`JobParameters`を参照する際に、Spring Batchのlate bindingという仕組みを使用しているためである。 late bindingとはその名のとおり、遅延して値を設定することである。 Spring Frameworkの`ApplicationContext`は、デフォルトでは各種Beanのプロパティを解決してから`ApplicationContext`のインスタンスを生成する。 Spring Batchでは`ApplicationContext`のインスタンスを生成する時にはプロパティを解決せず、 各種Beanが必要になった際にプロパティを解決する機能をもつ。これが遅延という言葉が意味することである。 この機能により、Spring Batch自体の実行に必要な`ApplicationContext`を生成し実行した後に、 パラメータに応じて各種Beanの振る舞いを切替えることが可能となる。 なお、`Step`スコープはSpring Batch独自のスコープであり、Stepの実行ごとに新たなインスタンスが生成される。 また、late bindingによる値の解決は、Bean定義においてSpEL式を用いることで可能となる。

| Stepスコープの定義方法 Spring Batchのlate bindingを使用してJobParametersを参照するreaderやwriterは`Step`スコープとする必要があるが、それ等を参照するコンポーネント(`ItemProcessor`、`Tasklet`)も`Step`スコープとする必要がある。 スコープを統一する理由はチャンクモデルのコンポーネントを利用するTasklet実装で説明しているスコープの統一についてを参照。 ジョブのBean定義にはジョブの構成要素による定義とジョブから呼ばれるコンポーネントの2種類あり、それぞれの定義場所や定義方法は異なる。 `Step`スコープの定義方法も、それぞれのBean定義方法に応じて異なる。 Bean定義に対する`Step`スコープの定義方法を以下に示す。
表 1. Bean定義とStepスコープの定義まとめ
ジョブのBean定義 | Beanの定義場所 | Beanの定義方法 | `Step`スコープの定義方法(定義場所はBeanの定義場所と同じ) | 実装例
--- | --- | --- | --- | ---
ジョブの構成要素(job, step, reader, writer等) | JavaConfigの場合 ジョブのBean定義ファイル(.java) | `@Bean`を付与したメソッド | 対象の`Bean`メソッドに`@StepScope`を設定 `@ComponentScan`に以下の属性を追加 `scopedProxy = ScopedProxyMode.TARGET_CLASS` | コマンドライン引数で与えたパラメータをBean定義で参照する例
XMLConfigの場合 ジョブのBean定義ファイル(.xml) | `<bean>`タグ | 対象の`<bean>`タグの属性に以下を設定 `scope="step"`
ジョブのBean定義ファイルから参照されるコンポーネント(ItemprocessorやTasklet) | Java実装クラス(.java) | `@Component`を付与 | `@Scope("step")`を付与 | コマンドライン引数で与えたパラメータをJavaで参照する例
現状、コンポーネントに`@StepScope`を付与したときの挙動はJavaConfigとXMLConfigで非互換があるため、コンポーネントの`Step`スコープ定義では`@StepScope`は定義してはならない。

コマンドライン引数で与えたパラメータをBean定義で参照する例
JavaConfig

    @Bean
    @StepScope // (1)
    public FlatFileItemReader<SalesPlanDetail> reader(
        @Value("#{jobParameters['inputFile']}") File inputFile) { // (2)
        // omitted
    }

XMLConfig

    <!-- (1) -->
    <bean id="reader"
          class="org.springframework.batch.item.file.FlatFileItemReader" scope="step"
          p:resource="file:#{jobParameters['inputFile']}">  <!-- (2) -->
        <property name="lineMapper">
            <!-- omitted settings -->
        </property>
    </bean>

表 2. 設定内容の項目一覧
項番 | 説明
--- | ---
(1) | `@Beanを付与するメソッドに@StepScopeを付与する/<bean>要素のscope属性でスコープを指定する`
(2) | 参照するパラメータを指定する。

コマンドライン引数で与えたパラメータをJavaで参照する例

    @Component
    @Scope("step")  // (1)
    public class ParamRefInJavaTasklet implements Tasklet {

        /**
         * Holds a String type value
         */
        @Value("#{jobParameters['str']}")  // (2)
        private String str;

        // omitted execute()
    }

表 3. 設定内容の項目一覧
項番 | 説明
--- | ---
(1) | クラスに`@Scope`アノテーションを付与してスコープを指定する。
(2) | `@Value`アノテーションを使用して参照するパラメータを指定する。

### ファイルから標準入力へリダイレクトする

ファイルから標準入力へリダイレクトする方法について説明する。

パラメータを定義するファイルの作成

パラメータは下記のようにファイルに定義する。

params.txt

    param1=abc
    outputFile=/tmp/result.csv

パラメータを定義したファイルを標準入力へリダイレクトする

コマンドライン引数としてパラメータを定義したファイルをリダイレクトする。

JavaConfig
実行方法

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        com.example.batch.jobs.JobDefinedConfig.JobDefinedConfig JOBID < params.txt

XMLConfig
実行方法

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        JobDefined.xml JOBID < params.txt

パラメータの参照

パラメータの参照方法はコマンドライン引数から与える方法と同様である。

### パラメータのデフォルト値を設定する

パラメータを任意とした場合、以下の形式でデフォルト値を設定することができる。

- `#{jobParameters['パラメータ名'] ?: デフォルト値}`

ただし、パラメータを使用して値を設定している項目であるということは、デフォルト値もパラメータと同様に環境や実行タイミングによって異なる可能性がある。

まずは、デフォルト値をソースコード上にハードコードをする方法を説明する。 しかし、後述のパラメータとプロパティの併用を活用する方が適切なケースが多いため、合わせて参照。

デフォルト値を設定したパラメータの参照

該当するパラメータが設定されなかった場合にデフォルト値に設定した値が参照される。

JavaConfig
コマンドライン引数で与えたパラメータをBean定義で参照する例

    @Bean
    @StepScope // (1)
    public FlatFileItemReader<SalesPlanDetail> reader(
        @Value("#{jobParameters['inputFile'] ?: '/input/sample.csv'}") File inputFile) { // (2)
        // omitted
    }

XMLConfig
コマンドライン引数で与えたパラメータをBean定義で参照する例

    <!-- (1) -->
    <bean id="reader"
          class="org.springframework.batch.item.file.FlatFileItemReader" scope="step"
          p:resource="file:#{jobParameters['inputFile'] ?: '/input/sample.csv'}">  <!-- (2) -->
        <property name="lineMapper">
            <!-- omitted settings -->
        </property>
    </bean>

表 4. 設定内容の項目一覧
項番 | 説明
--- | ---
(1) | `@Beanを付与するメソッドに@StepScopeを付与する/<bean>要素のscope属性でスコープを指定する`
(2) | 参照するパラメータを指定する。 デフォルト値に`/input/sample.csv`を設定している。

コマンドライン引数で与えたパラメータをJavaで参照する例

    @Component
    @Scope("step")  // (1)
    public class ParamRefInJavaTasklet implements Tasklet {

        /**
         * Holds a String type value
         */
        @Value("#{jobParameters['str'] ?: 'xyz'}")  // (2)
        private String str;

        // omitted execute()
    }

表 5. 設定内容の項目一覧
項番 | 説明
--- | ---
(1) | クラスに`@Scope`アノテーションを付与してスコープを指定する。
(2) | `@Value`アノテーションを使用して参照するパラメータを指定する。 デフォルト値に`xyz`を設定している。

### パラメータの妥当性検証

オペレーションミスや意図しない挙動を防ぐために、ジョブの起動時にパラメータの妥当性検証が必要となる場合もある。
パラメータの妥当性検証はSpring Batchが提供する`JobParametersValidator`を活用することで実現可能である。

パラメータはItemReader/ItemProcessor/ItemWriterといった様々な場所で参照するため、 ジョブの起動直後に妥当性検証が行われる。

パラメータの妥当性を検証する方法は2つあり、検証の複雑度によって異なる。

- 簡易な妥当性検証

  - 適用例

    - 必須パラメータが設定されていることの検証

    - 意図しないパラメータが設定されていないことの検証

  - 使用するバリデータ

    - Spring Batchが提供している`DefaultJobParametersValidator`

- 複雑な妥当性検証

  - 適用例

    - 数値の範囲検証やパラメータ間の相関チェックなどの複雑な検証

    - Spring Batchが提供している`DefaultJobParametersValidator`にて実現不可能な検証

  - 使用するバリデータ

    - `JobParametersValidator`を自作で実装したクラス

簡易な妥当性検証および複雑な妥当性検証の妥当性を検証する方法についてそれぞれ説明する。

#### 簡易な妥当性検証

Spring Batchは`JobParametersValidator`のデフォルト実装として、`DefaultJobParametersValidator`を提供している。
このバリデータでは設定により以下を検証することができる。

- 必須パラメータが設定されていること

- 必須または任意パラメータ以外のパラメータが指定されていないこと

以下に定義例を示す。

JavaConfig
DefaultJobParametersValidatorを使用する妥当性検証の定義

    @Configuration
    @Import(JobBaseContextConfig.class)
    @ComponentScan(value = "jp.co.ntt.fw.macchinetta.batch.functionaltest.ch04.jobparameter", scopedProxy = ScopedProxyMode.TARGET_CLASS)
    public class JobDefaultJobParametersValidatorConfig {

        // (1)
        @Bean
        public DefaultJobParametersValidator jobParametersValidator() {
            return new DefaultJobParametersValidator(
                    new String[] {"inputFileName", "outputFileName"}, // (2)
                    new String[] {"param1", "param2"}); // (3)
        }

        @Bean
        public Step step01(JobRepository jobRepository,
                           @Qualifier("jobTransactionManager") PlatformTransactionManager transactionManager,
                           RefWithDefaultInJavaTasklet tasklet) {
            return new StepBuilder("jobDefaultJobParametersValidator.step01", jobRepository)
                    .tasklet(tasklet, transactionManager)
                    .build();
        }

        @Bean
        public Job jobDefaultJobParametersValidator(JobRepository jobRepository,
                                           Step step01,
                                           DefaultJobParametersValidator jobParametersValidator) {
            return new JobBuilder("jobDefaultJobParametersValidator",
                    jobRepository)
                    .start(step01)
                    .validator(jobParametersValidator) // (4)
                    .build();
        }

    }

XMLConfig
DefaultJobParametersValidatorを使用する妥当性検証の定義

    <!-- (1) -->
    <bean id="jobParametersValidator"
          class="org.springframework.batch.core.job.DefaultJobParametersValidator">
      <property name="requiredKeys">  <!-- (2) -->
        <list>
            <value>inputFileName</value>
            <value>outputFileName</value>
        </list>
      </property>
      <property name="optionalKeys">  <!-- (3) -->
        <list>
            <value>param1</value>
            <value>param2</value>
        </list>
      </property>
    </bean>

    <batch:job id="jobUseDefaultJobParametersValidator" job-repository="jobRepository">
      <batch:step id="jobUseDefaultJobParametersValidator.step01">
        <batch:tasklet ref="sampleTasklet" transaction-manager="jobTransactionManager"/>
      </batch:step>
      <batch:validator ref="jobParametersValidator"/>  <!-- (4) -->
    </batch:job>

表 6. 設定内容の項目一覧
項番 | 説明
--- | ---
(1) | `DefaultJobParametersValidator`のBeanを定義する。
(2) | 必須パラメータは`requiredKeys`に設定する。 `String配列/<list>要素`を使用して必須パラメータのパラメータ名を複数指定できる。
(3) | 任意パラメータは`optionalKeys`に設定する。 `String配列/<list>要素`を使用して任意パラメータのパラメータ名を複数指定できる。
(4) | `JobBuilderのvalidatorメソッド/<batch:job>要素内の<batch:validator>要素`を使用してジョブにバリデータを適用する。

DefaultJobParametersValidatorを使用した場合のOKケースとNGケース

`DefaultJobParametersValidator`にて検証可能な条件の理解を深めるため、検証結果がOKとなる場合とNGとなる場合の例を示す。

JavaConfig
DefaultJobParametersValidator定義例

    @Bean
    public DefaultJobParametersValidator jobParametersValidator() {
        return new DefaultJobParametersValidator(
                new String[] {"outputFileName"},
                new String[] {"param1"});
    }

XMLConfig
DefaultJobParametersValidator定義例

    <bean id="jobParametersValidator"
        class="org.springframework.batch.core.job.DefaultJobParametersValidator"
        p:requiredKeys="outputFileName"
        p:optionalKeys="param1"/>

JavaConfig
NGケース1（任意パラメータのみ指定）

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        com.example.batch.jobs.JobDefinedConfig JOBID param1=aaa

XMLConfig
NGケース1（任意パラメータのみ指定）

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        JobDefined.xml JOBID param1=aaa

必須パラメータ`outputFileName`が設定されていないためNGとなる。

JavaConfig
OKケース1（必須パラメータのみ指定）

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        com.example.batch.jobs.JobDefinedConfig.JobDefinedConfig JOBID outputFileName=/tmp/result.csv

XMLConfig
OKケース1（必須パラメータのみ指定）

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        JobDefined.xml JOBID outputFileName=/tmp/result.csv

必須パラメータ`outputFileName`が設定されるためOKとなる。任意パラメータ`param1`は設定されていなくてもよい。

JavaConfig
OKケース2（必須パラメータと任意パラメータ指定）

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        com.example.batch.jobs.JobDefinedConfig.JobDefinedConfig JOBID param1=aaa outputFileName=/tmp/result.csv

XMLConfig
OKケース2（必須パラメータと任意パラメータ指定）

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        JobDefined.xml JOBID param1=aaa outputFileName=/tmp/result.csv

必須パラメータ`outputFileName`が設定されるためOKとなる。

JavaConfig
OKケース3（必須パラメータとBean定義にないパラメータ指定）

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        com.example.batch.jobs.JobDefinedConfig.JobDefinedConfig JOBID fileoutputFilename=/tmp/result.csv param2=aaa

XMLConfig
OKケース3（必須パラメータとBean定義にないパラメータ指定）

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        JobDefined.xml JOBID fileoutputFilename=/tmp/result.csv param2=aaa

必須パラメータ`outputFileName`が設定されるためOKとなる。Bean定義にないパラメータ`param2`が設定されてもよい。

#### 複雑な妥当性検証

`JobParametersValidator`インタフェースの実装を自作することで、 要件に応じたパラメータの検証を実現することができる。

`JobParametersValidator`クラスは以下の要領で実装する。

- `JobParametersValidator`クラスを実装し、`validate`メソッドをオーバーライドする

- `validate`メソッドは以下の要領で実装する

  - `JobParameters`から各パラメータを取得し検証する

    - 検証の結果がOKである場合には、何もする必要はない

    - 検証の結果がNGである場合には、`JobParametersInvalidException`をスローする

`JobParametersValidator`クラスの実装例を示す。 ここでは、`str`で指定された文字列の長さが、`num`で指定された数値以下であることを検証している。

JobParametersValidatorインタフェースの実装例

    public class ComplexJobParametersValidator implements JobParametersValidator {  // (1)
        @Override
        public void validate(JobParameters parameters) throws JobParametersInvalidException {
            Map<String, JobParameter> params = parameters.getParameters();  // (2)

            String str = params.get("str").getValue().toString();  // (3)
            int num = Integer.parseInt(params.get("num").getValue().toString()); // (4)

            if(str.length() > num){
                throw new JobParametersInvalidException(
                "The str must be less than or equal to num. [str:"
                        + str + "][num:" + num + "]");  // (5)
            }
        }
    }

表 7. 設定内容の項目一覧
項番 | 説明
--- | ---
(1) | `JobParametersValidator`クラスを実装し`validate`メソッドをオーバーライドする。
(2) | パラメータは`JobParameters`型で引数として受ける。 `parameters.getParameters()`とすることで、Map形式で取得することでパラメータの参照が容易になる。
(3) | keyを指定してパラメータを取得する。
(4) | パラメータをint型へ変換する。String型以外を扱う場合は適宜変換を行うこと。
(5) | パラメータ`str`の文字列長がパラメータ`num`の値を超えている場合に妥当性検証結果NGとしている。

JavaConfig
ジョブの定義例

    @Bean
    public Step step01(JobRepository jobRepository,
                       @Qualifier("jobTransactionManager") PlatformTransactionManager transactionManager,
                       RefWithDefaultInJavaTasklet tasklet) {
        return new StepBuilder("jobDefaultJobParametersValidator.step01", jobRepository)
                .tasklet(tasklet, transactionManager)
                .build();
    }

    @Bean
    public Job jobDefaultJobParametersValidator(JobRepository jobRepository,
                                       Step step01,
                                       DefaultJobParametersValidator jobParametersValidator) {
        return new JobBuilder("jobDefaultJobParametersValidator",
                jobRepository)
                .start(step01)
                .validator(jobParametersValidator) // (1)
                .build();
    }

XMLConfig
ジョブの定義例

    <batch:job id="jobUseComplexJobParametersValidator" job-repository="jobRepository">
        <batch:step id="jobUseComplexJobParametersValidator.step01">
            <batch:tasklet ref="sampleTasklet" transaction-manager="jobTransactionManager"/>
        </batch:step>
        <batch:validator>  <!-- (1) -->
            <bean class="jp.co.ntt.fw.macchinetta.batch.functionaltest.ch04.jobparameter.ComplexJobParametersValidator"/>
        </batch:validator>
    </batch:job>

表 8. 設定内容の項目一覧
項番 | 説明
--- | ---
(1) | `JobBuilderのvalidatorメソッド/<batch:job>要素内の<batch:validator>要素`を使用してジョブにバリデータを適用する。

| 非同期起動時におけるパラメータの妥当性検証について 非同期起動方式(DBポーリングやWebコンテナ)でも、同様にジョブ起動時に検証することは可能だが、 以下のようなタイミングでジョブを起動する前に検証することが望ましい。 DBポーリング ジョブ要求テーブルへのINSERT前 Webコンテナ Controller呼び出し時(@Validatedを付与する) 非同期起動の場合、結果は別途確認する必要が生じるため、パラメータ設定ミスのような 場合は早期にエラーを応答し、ジョブの要求をリジェクトすることが望ましい。 また、この時の妥当性検証において、`JobParametersValidator`を使う必要はない。 ジョブ要求テーブルへINSERTする機能や、Webコンテナ上のControllerは 多くの場合Spring Batchに依存していないはずであり、 `JobParametersValidator`を使用するためだけにSpring Batchに依存することは避けた方がよい。

## How to extend

### パラメータとプロパティの併用

Spring BatchのベースであるSpring Frameworkには、プロパティ管理の機能が備わっており、 環境変数やプロパティファイルに設定した値を扱うことができる。 詳細は、Macchinetta Server 1.x 開発ガイドラインの プロパティ管理 を参照。

プロパティとパラメータを組み合わせることで、大部分のジョブに共通的な設定をプロパティファイルに行ったうえで、一部をパラメータで上書きするといったことが可能になる。

| パラメータとプロパティが解決されるタイミングについて 前述のとおり、パラメータとプロパティは、機能を提供するコンポーネントが異なる。 Spring Batchはパラメータ管理の機能をもち、Spring Frameworkはプロパティ管理の機能をもつ。 この差は記述方法の差に現れている。 Spring Batchがもつ機能の場合 `#{jobParameters[xxx]}` Spring Frameworkがもつ機能の場合 `@Value("${xxx}")` また、それぞれの値が解決されるタイミングが異なる。 Spring Batchがもつ機能の場合 Application Contextを生成後、ジョブを実行するタイミングで設定される。 Spring Frameworkがもつ機能の場合 Application Contextの生成時に設定される。 よって、Spring Batchによるパラメータの値が優先される結果になる。 この点を念頭におくと、組み合わせる際に応用が効くため両者を区別して扱うこと。

以降、プロパティとパラメータを組み合わせて設定する方法について説明する。

環境変数による設定に加えて、コマンドライン引数で追加設定する場合

環境変数による設定に加えて、コマンドライン引数を使用してパラメータを設定する方法を説明する。
Bean定義においても同様に参照可能である。

JavaConfig
環境変数に加えてコマンドライン引数でパラメータを設定する例

    $ # Set environment variables
    $ export env1=aaa
    $ export env2=bbb

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        com.example.batch.jobs.JobDefinedConfig.JobDefinedConfig JOBID param3=ccc outputFile=/tmp/result.csv

XMLConfig
環境変数に加えてコマンドライン引数でパラメータを設定する例

    $ # Set environment variables
    $ export env1=aaa
    $ export env2=bbb

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        JobDefined.xml JOBID param3=ccc outputFile=/tmp/result.csv

Javaにおいて環境変数とパラメータを参照する例

    @Value("${env1}")  // (1)
    private String param1;

    @Value("${env2}")  // (1)
    private String param2;

    private String param3;

    @Value("#{jobParameters['param3']")  // (2)
    public void setParam3(String param3) {
        this.param3 = param3;
    }

表 9. 設定内容の項目一覧
項番 | 説明
--- | ---
(1) | `@Value`アノテーションを使用して参照する環境変数を指定する。 参照する際の形式は`${環境変数名}`である。
(2) | `@Value`アノテーションを使用して参照するパラメータを指定する。 参照する際の形式は`#{jobParameters['パラメータ名']`である。

JavaConfig
環境変数をデフォルトとする場合の例

    $ # Set environment variables
    $ export env1=aaa

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        com.example.batch.jobs.JobDefinedConfig.JobDefinedConfig JOBID param1=bbb outputFile=/tmp/result.csv

XMLConfig
環境変数をデフォルトとする場合の例

    $ # Set environment variables
    $ export env1=aaa

    $ # Execute job
    $ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
        JobDefined.xml JOBID param1=bbb outputFile=/tmp/result.csv

Javaにおいて環境変数をデフォルト値としてパラメータを参照する例

    @Value("#{jobParameters['param1'] ?: '${env1}'}")  // (1)
    public void setParam1(String param1) {
        this.param1 = param1;
    }

表 10. 設定内容の項目一覧
項番 | 説明
--- | ---
(1) | 環境変数をデフォルト値として`@Value`アノテーションを使用して参照するパラメータを指定する。 パラメータが設定されなかった場合、環境変数の値が設定される。

| 誤ったデフォルト値の設定方法 以下の要領で定義した場合、コマンドライン引数からparam1を設定しない場合に、 env1の値が設定されてほしいにも関わらず、param1にnullが設定されてしまうため注意すること。 誤ったデフォルト値の設定方法例
    @Value("${env1}")
    private String param1;

    @Value("#{jobParameters['param1']}")
    public void setParam1(String param1) {
      this.param1 = param1;
    }

Macchinetta Batch Framework (2.x) Development Guideline - version 2.6.1.RELEASE, 2026-3-30
> INDEX