遅ればせながら、SpringBatch4系から5系にアップグレードが発生しそうなので、自分用メモ。
spring-projectsのspring-batchのSpring Batch 5.0 Migration Guideは英語なので、和訳しながら、コメントをつけていくことで、理解していく。
- JDK 17 baseline
- Dependencies upgrade
- Database schema update
- Infrastructure beans configuration with @EnableBatchProcessing
- Data types updates
- Observability updates
- Execution context serialization updates
- SystemCommandTasklet updates
- Job parameters handling updates
- Default job parameter conversion
- Historical data access implications
- Deprecated APIs
- Moved APIs
- Removed APIs
- Pruning
- SQLFire support removal
- JSR-352 implementation removal
- Gemfire support removal
- 最後に
JDK 17 baseline
Spring Batch 5 is based on Spring Framework 6 which requires Java 17 as a minimum version. Therefore, you need to use Java 17+ to run Spring Batch 5 applications.
(和訳)
JDK 17ベースライン
Spring Batch 5は、最小バージョンとしてJava 17を必要とするSpring Framework 6に基づいています。したがって、Spring Batch 5アプリケーションを実行するには、Java 17 +を使用する必要があります。
<コメント>
Java17以上を使ってねということ。
Java17未満であれば、先にJavaのバージョンを17以上にする必要がある。
Dependencies upgrade
Spring Batch 5 is updating its Spring dependencies across the board to the following versions:
- Spring Framework 6
- Spring Integration 6
- Spring Data 3
- Spring AMQP 3
- Spring for Apache Kafka 3
- Micrometer 1.10
Moreover, this version marks the migration to:
- Jakarta EE 9: Please make sure to update your import statements from
javax.*
tojakarta.*
for all EE APIs you use.- Hibernate 6: Hibernate (cursor/paging) item readers and writer have been updated to use Hibernate 6.1 APIs (previously using Hibernate 5.6 APIs)
In addition to that:
org.springframework:spring-jdbc
is now a required dependency inspring-batch-core
junit:junit
is no more a required dependency inspring-batch-test
.com.fasterxml.jackson.core:jackson-core
is now optional inspring-batch-core
(和訳)
依存関係のアップグレード
Spring Batch 5では、Springの依存関係を以下のバージョンに全面的に更新している:
・Spring Framework 6
・Spring Integration 6
・Spring Data 3
・Spring AMQP 3
・Spring for Apache Kafka 3
・Micrometer 1.10
さらに、このバージョンは、以下への移行を意味する:
Jakarta EE 9:使用するすべてのEE APIについて、import文を javax.* から jakarta.* に更新してください。
Hibernate 6: Hibernate(カーソル/ページング)アイテム・リーダとライタが、Hibernate 6.1 APIを使用するように更新されました(以前はHibernate 5.6 APIを使用していました)。
追加で下記があります。
org.springframework:spring-jdbcは、spring-batch-coreで必須の依存関係になりました。
junit:junitはspring-batch-testの必須依存ではなくなりました。
com.fasterxml.jackson.core:jackson-coreはspring-batch-coreのオプションになりました。
<コメント>
・バージョンの更新については、そもそもどういう目的のフレームワークかが分からな時用にリンクを張った。
Micrometerはメトリクスツールで、デフォルトでもJVMや特定のログ、Tomcat、ExecutorService、HTTP Clientのメトリクスが取得できる。
・Jakarta EE 9に関しては、わかりやすくimport文を書き換える必要がある。
・Hibernate 6.1 APIとHibernate 5.6 APIの違いについては、Migration Guideを張っておく。cursorを見る限りは、5.6と6.1にそんなに違いがないかも?
・依存関係系は、org.springframework:spring-jdbcは必須化、junit:junitとcom.fasterxml.jackson.core:jackson-coreの依存関係が軽くなった。
Database schema update
(和訳)
データベーススキーマの更新
<コメント>
ちょっと長いので、DB毎に分割する
Oracle
In this version, Oracle sequences are now ordered. The sequences creation script has been updated for new applications. Existing applications can use the migration script in
org/springframework/batch/core/migration/5.0/migration-oracle.sql
to alter the existing sequences.Moreover, the DDL scripts for Oracle have been renamed as follows:
org/springframework/batch/core/schema-drop-oracle10g.sql
has been renamed toorg/springframework/batch/core/schema-drop-oracle.sql
org/springframework/batch/core/schema-oracle10g.sql
has been renamed toorg/springframework/batch/core/schema-oracle.sql
(和訳)
オラクル
このバージョンでは、Oracleシーケンスが順番に並べられるようになりました。シーケンス作成スクリプトが新しいアプリケーション用に更新されました。既存のアプリケーションでは、org/springframework/batch/core/migration/5.0/migration-oracle.sql にある移行スクリプトを使用して、既存のシーケンスを変更できます。
さらに、Oracle用のDDLスクリプトの名前が以下のように変更されました:
org/springframework/batch/core/schema-drop-oracle10g.sql は org/springframework/batch/core/schema-drop-oracle.sql に名前が変更されました。
org/springframework/batch/core/schema-oracle10g.sql は org/springframework/batch/core/schema-oracle.sql に名前が変更されました。
<コメント>
・シーケンスに関する変更があった様子。また、スクリプト名が変更。
移行スクリプトを実行する必要があるので、リリースタイミング等に影響ありそう。
MS SQLServer
Up until v4, the DDL script for MS SQLServer used tables to emulate sequences. In this version, this usage has been updated with real sequences:
CREATE SEQUENCE BATCH_STEP_EXECUTION_SEQ START WITH 0 MINVALUE 0 MAXVALUE 9223372036854775807 NO CACHE NO CYCLE; CREATE SEQUENCE BATCH_JOB_EXECUTION_SEQ START WITH 0 MINVALUE 0 MAXVALUE 9223372036854775807 NO CACHE NO CYCLE; CREATE SEQUENCE BATCH_JOB_SEQ START WITH 0 MINVALUE 0 MAXVALUE 9223372036854775807 NO CACHE NO CYCLE;New applications can use the provided script with no modifications. Existing applications should consider modifying the snippet above to start sequences from the last value in sequence tables used with v4.
(和訳)
MS SQLServer
v4 までは、MS SQLServer 用の DDL スクリプトはシーケンスをエミュレートするためにテーブルを使用していました。このバージョンでは、この使用法が実際のシーケンスに更新されました:
(省略)
新規アプリケーションは、提供されたスクリプトを使用することができます;
新しいアプリケーションは、提供されたスクリプトを修正することなく使用できます。既存のアプリケーションは、v4で使用されるシーケンス・テーブルの最後の値からシーケンスを開始するように、上記のスニペットを修正することを検討してください。
<コメント>
・こちらもシーケンスの扱いが変更。
・現状に合わせて、「シーケンス・テーブルの最後の値からシーケンスを開始」させるのは、ちょっと面倒。
All platforms
Removal of
BATCH_JOB_EXECUTION#JOB_CONFIGURATION_LOCATION
columnThe column
JOB_CONFIGURATION_LOCATION
in theBATCH_JOB_EXECUTION
table is not used anymore and can be marked as unused or dropped if needed:ALTER TABLE BATCH_JOB_EXECUTION DROP COLUMN JOB_CONFIGURATION_LOCATION;
The syntax to drop the column might differ depending on the version of your database server, so please check the syntax of column deletion. This change might require a table reorganisation on some platforms.
❗ Important note ❗ This change is mainly related to the removal of the JSR-352 implementation which was the only part of the framework using this column. As a consequence, the field
JobExecution#jobConfigurationName
has been removed as well as all APIs using it (constructors and getter in the domain objectJobExecution
, methodJobRepository#createJobExecution(JobInstance, JobParameters, String);
inJobRepository
).
(和訳)
すべてのプラットフォーム
BATCH_JOB_EXECUTION#JOB_CONFIGURATION_LOCATION列の削除
BATCH_JOB_EXECUTIONテーブルのJOB_CONFIGURATION_LOCATION列は使用されなくなりました:
(省略)
カラムを削除する構文はデータベースサーバーのバージョンによって異なる可能性があるので、カラム削除の構文を確認してください。この変更により、プラットフォームによってはテーブルの再編成が必要になるかもしれません。
❗ 重要な注意❗ この変更は主に、このカラムを使用していたフレームワークの唯一の部分であった JSR-352 実装の削除に関連しています。その結果、JobExecution#jobConfigurationName フィールドが削除され、それを使用するすべての API(ドメインオブジェクト JobExecution のコンストラクタとゲッター、JobRepository#createJobExecution(JobInstance, JobParameters, String); in JobRepository)も削除されました。
<コメント>
・BATCH_JOB_EXECUTIONは、JobRepositoryのメタデータテーブルの一つ。メタデータテーブルに関しては、下記を参照。
メタデータスキーマ :: Spring Batch - リファレンス
BATCH_JOB_EXECUTION.JOB_CONFIGURATION_LOCATIONをdropしてねということ。
また、JobRepository#createJobExecution(JobInstance, JobParameters, String)が削除されているので、注意。
・JSR-352については、JavaEEの標準バッチAPIのこと。JobやChunk、Stepのような概念はここからきている。詳しくは、下記を参照。
Java EE の標準バッチAPI -- JSR-352 Batch Applications for the Java Platform -- - A Memorandum
Column change in
BATCH_JOB_EXECUTION_PARAMS
The
BATCH_JOB_EXECUTION_PARAMS
has been updated as follows:CREATE TABLE BATCH_JOB_EXECUTION_PARAMS ( JOB_EXECUTION_ID BIGINT NOT NULL , --- TYPE_CD VARCHAR(6) NOT NULL , --- KEY_NAME VARCHAR(100) NOT NULL , --- STRING_VAL VARCHAR(250) , --- DATE_VAL DATETIME(6) DEFAULT NULL , --- LONG_VAL BIGINT , --- DOUBLE_VAL DOUBLE PRECISION , +++ PARAMETER_NAME VARCHAR(100) NOT NULL , +++ PARAMETER_TYPE VARCHAR(100) NOT NULL , +++ PARAMETER_VALUE VARCHAR(2500) , IDENTIFYING CHAR(1) NOT NULL , constraint JOB_EXEC_PARAMS_FK foreign key (JOB_EXECUTION_ID) references BATCH_JOB_EXECUTION(JOB_EXECUTION_ID) );This is related to the way job parameters are persisted as revisited in https://github.com/spring-projects/spring-batch/issues/3960. Migration scripts can be found in
org/springframework/batch/core/migration/5.0
.
(和訳)
BATCH_JOB_EXECUTION_PARAMSのカラム変更
BATCH_JOB_EXECUTION_PARAMSが以下のように更新されました:
(省略)
これは、https://github.com/spring-projects/spring-batch/issues/3960 で再確認したように、ジョブパラメータが永続化される方法に関連しています。移行スクリプトはorg/springframework/batch/core/migration/5.0にあります。
<コメント>
・BATCH_JOB_EXECUTION_PARAMSもJobRepositoryのメタデータテーブルの一つ。
テーブル定義に変更があるので、移行スクリプトを利用するとよい。
Column change in
BATCH_STEP_EXECUTION
A new column
CREATE_TIME
was added in v5. You should create it in the table according to your database server, something like:ALTER TABLE BATCH_STEP_EXECUTION ADD CREATE_TIME TIMESTAMP NOT NULL DEFAULT '1970-01-01 00:00:00';Moreover, the
NOT NULL
constraint was dropped from theSTART_TIME
column:ALTER TABLE BATCH_STEP_EXECUTION ALTER COLUMN START_TIME DROP NOT NULL;
(和訳)
BATCH_STEP_EXECUTIONにおけるカラムの変更
v5で新しいカラムCREATE_TIMEが追加された:
(省略)
さらに、START_TIME列からNOT NULL制約が削除された:
(省略)
<コメント>
・BATCH_STEP_EXECUTIONもJobRepositoryのメタデータテーブルの一つ。
定義が変更されているので、使用箇所の調査対象となる。
Infrastructure beans configuration with
@EnableBatchProcessing
(和訳)
EnableBatchProcessingによるインフラビーンズの設定
<コメント>
・EnableBatchProcessingはSpring Boot の Spring Batch の自動構成を有効にするアノテーション。
この変更が破壊的なものであるため、移行時には注意が必要な部分。
Spring Boot 3にアップデートしたらSpring Batchが動かなくなった
Job repository/explorer configuration updates
The Map-based job repository/explorer implementation were deprecated in v4 and completely removed in v5. You should use the Jdbc-based implementation instead. Unless you are using a custom Job repository/explorer implementation, the
@EnableBatchProcessing
annotation will configure a Jdbc-basedJobRepository
which requires aDataSource
bean in the application context. TheDataSource
bean could refer to an embedded database like H2, HSQL, etc to work with an in-memory job repository
(和訳)
ジョブリポジトリ/エクスプローラ設定の更新
Map ベースのジョブ・リポジトリ/エクスプローラの実装は v4 で非推奨となり、v5 で完全に削除されました。 代わりに Jdbc ベースの実装を使用する必要があります。
カスタムのジョブリポジトリ/エクスプローラ実装を使用していない限り、@EnableBatchProcessing アノテーションはアプリケーションコンテキストに DataSource Bean を必要とする Jdbc ベースのジョブリポジトリを構成します。
DataSource BeanはH2やHSQLなどの組み込みデータベースを参照し、インメモリジョブリポジトリと連携することができます。
<コメント>
・今までメタテーブルに関する情報を使用しないことができたが、今回のバージョンアップで、できなくなった。
考えられる対応策としては、①記載の通りH2やHSQLなどの組み込みデータベースを利用するか、②既に存在するDBにメタテーブルを作成することになりそう。
ちなみに、H2については、最新バージョンだとダメという情報もある。
【SpringBatch】メタデータテーブルをDBに生成せずに済ませるには(検証ソースあり) - HIRO Tracks
Transaction manager bean exposure/configuration
Up until version 4.3, the
@EnableBatchProcessing
annotation exposed a tranasaction manager bean in the application context. While this was convenient in many cases, the unconditional exposure of a tranasaction manager could interfere with a user-defined transaction manager. In this release,@EnableBatchProcessing
does not expose a transaction manager bean in the application context anymore. This change is related to issue https://github.com/spring-projects/spring-batch/issues/816.As a result of the aforementioned issue, and in combination with the inconsistency between the XML and Java config styles regarding the transaction manager that was fixed in https://github.com/spring-projects/spring-batch/issues/4130, it is now required to manually configure the transaction manager on any tasklet step definition. The method
StepBuilderHelper#transactionManager(PlatformTransactionManager)
was moved down a level, toAbstractTaskletStepBuilder
.The typical migration path from v4 to v5 in that regard is as follows:
// Sample with v4 @Configuration @EnableBatchProcessing public class MyStepConfig { @Autowired private StepBuilderFactory stepBuilderFactory; @Bean public Step myStep() { return this.stepBuilderFactory.get("myStep") .tasklet(..) // or .chunk() .build(); } }
// Sample with v5 @Configuration @EnableBatchProcessing public class MyStepConfig { @Bean public Tasklet myTasklet() { return new MyTasklet(); } @Bean public Step myStep(JobRepository jobRepository, Tasklet myTasklet, PlatformTransactionManager transactionManager) { return new StepBuilder("myStep", jobRepository) .tasklet(myTasklet, transactionManager) // or .chunk(chunkSize, transactionManager) .build(); } }
This is only required for tasklet steps, other step types do not require a transaction manager by design.
Moreover, the transaction manager was configurable by implementing
BatchConfigurer#getTransactionManager
. The transaction manager being an implementation detail of theJobRepository
, it should not be configurable at the same level as theJobRepository
(ie in the same interface). In this release, theBatchConfigurer
interface was removed. If needed, a custom transaction manager could be supplied either declaratively as an attribute of@EnableBatchProcessing
, or programmatically by overridingDefaultBatchConfiguration#getTransactionManager()
. For more details about this change, please check https://github.com/spring-projects/spring-batch/issues/3942.
(和訳)
トランザクション・マネージャ・ビーンの公開/構成
バージョン 4.3 までは、@EnableBatchProcessing アノテーションはアプリケーション・コンテキストでトランザクション・マネージャ Bean を公開していました。これは多くの場合に便利でしたが、トランザクション・マネジャーを無条件に公開すると、ユーザー定義のトランザクション・マネジャーと干渉する可能性がありました。このリリースでは、@EnableBatchProcessing はアプリケーション・コンテキストでトランザクション・マネージャ・ビーンを公開しません。この変更は、問題 https://github.com/spring-projects/spring-batch/issues/816 に関連しています。
前述の問題と、https://github.com/spring-projects/spring-batch/issues/4130 で修正されたトランザクション・マネージャに関する XML 構成スタイルと Java 構成スタイルの不一致の結果として、タスクレット・ステップ定義でトランザクション・マネージャを手動で構成する必要があります。StepBuilderHelper#transactionManager(PlatformTransactionManager)メソッドは、AbstractTaskletStepBuilderにレベルダウンされました。
v4からv5への典型的な移行パスは以下の通りです:
(省略)
これはタスクレットステップにのみ必要で、他のステップタイプは設計上トランザクションマネージャーを必要としない。
さらに、トランザクション・マネージャーはBatchConfigurer#getTransactionManagerを実装することで設定可能であった。トランザクション・マネージャーはJobRepositoryの実装の詳細であるため、JobRepositoryと同じレベルで(つまり同じインターフェースで)設定できるべきではありません。このリリースでは、BatchConfigurer インターフェースは削除されました。必要であれば、@EnableBatchProcessingの属性として宣言的に、またはDefaultBatchConfiguration#getTransactionManager()をオーバーライドしてプログラム的に、カスタムトランザクションマネージャを提供することができます。この変更の詳細については、https://github.com/spring-projects/spring-batch/issues/3942。
<コメント>
・TransactionManagerの変更で、どうしても設定を変えたい場合は、DefaultBatchConfiguration#getTransactionManager()をオーバーライドしろということ。合わせて、BatchConfigurerが削除。
・例の通りStepの定義が変わっていて、引数が変わっているので、この辺の対応が必要。
JobBuilderFactory and StepBuilderFactory bean exposure/configuration
JobBuilderFactory
andStepBuilderFactory
are not exposed as beans in the application context anymore, and are now deprecated for removal in v5.2 in favor of using the respective builders they create.The typical migration path from v4 to v5 in that regard is as follows:
// Sample with v4 @Configuration @EnableBatchProcessing public class MyJobConfig { @Autowired private JobBuilderFactory jobBuilderFactory; @Bean public Job myJob(Step step) { return this.jobBuilderFactory.get("myJob") .start(step) .build(); } }
// Sample with v5 @Configuration @EnableBatchProcessing public class MyJobConfig { @Bean public Job myJob(JobRepository jobRepository, Step step) { return new JobBuilder("myJob", jobRepository) .start(step) .build(); } }
The same pattern can be used to remove the usage of the deprecated
StepBuilderFactory
. For more details about this change, please check https://github.com/spring-projects/spring-batch/issues/4188.
(和訳)
JobBuilderFactory と StepBuilderFactory ビーンの公開/設定
JobBuilderFactoryとStepBuilderFactoryはアプリケーションコンテキストでBeanとして公開されなくなり、v5.2では削除されました。
この点に関するv4からv5への典型的な移行パスは以下の通りです:
(省略)
同じパターンを使って、非推奨のStepBuilderFactoryの使用を削除することができる。この変更の詳細については、https://github.com/spring-projects/spring-batch/issues/4188。
<コメント>
・Jobの定義方法が変わった。引数にjobRepositoryが増えている。
・StepBuilderFactoryの削除の例は、Transaction manager bean exposure/configurationの項にあるので、参照。StepBuilderFactoryは削除しても、何とかなるようになった。
Data types updates
- Metric counters (
readCount
,writeCount
, etc) inorg.springframework.batch.core.StepExecution
andorg.springframework.batch.core.StepContribution
have been changed fromint
tolong
. All getters and setters have been updated accordingly.- The
skipCount
parameter inorg.springframework.batch.core.step.skip.SkipPolicy#shouldSkip
has been changed fromint
tolong
. This is related to the previous point.- The type of fields
startTime
,endTime
,createTime
andlastUpdated
inJobExecution
andStepExecution
was changed fromjava.util.Date
tojava.time.LocalDateTime
.
(和訳)
データ型の更新
org.springframework.batch.core.StepExecutionとorg.springframework.batch.core.StepContributionのメトリックカウンタ(readCount, writeCountなど)がintからlongに変更されました。すべてのゲッターとセッターはそれに合わせて更新されました。
org.springframework.batch.core.step.skip.SkipPolicy#shouldSkipのskipCountパラメータがintからlongに変更された。これは前の点と関連している。
JobExecutionとStepExecutionのフィールドstartTime、endTime、createTime、lastUpdatedの型がjava.util.Dateからjava.time.LocalDateTimeに変更された。
<コメント>
・型の変更なので、既存からわかりやすくコンパイルエラーになりそう。
Observability updates
- Micrometer has been updated to version 1.10
- All tags are now prefixed with the meter name. For example, the tags of the timer
spring.batch.job
are namedname
andstatus
in version 4.x. In version 5, those tags are now namedspring.batch.job.name
andspring.batch.job.status
respectively.- The
BatchMetrics
class (which is intended for internal use only) has been moved fromorg.springframework.batch.core.metrics
to theorg.springframework.batch.core.observability
package.
(和訳)
観測可能性の更新
Micrometerがバージョン1.10に更新されました。
すべてのタグの先頭にメーター名が付くようになりました。例えば、spring.batch.jobというタイマーのタグはバージョン4.xではnameとstatusという名前でしたが、バージョン5ではそれぞれspring.batch.job.nameとspring.batch.job.statusという名前になりました。
BatchMetricsクラス(内部使用のみ)はorg.springframework.batch.core.metricsからorg.springframework.batch.core.observabilityパッケージに移動しました。
<コメント>
・Micrometerに関する更新。
Execution context serialization updates
Starting from v5, the default
ExecutionContextSerializer
was changed fromJacksonExecutionContextStringSerializer
toDefaultExecutionContextSerializer
. The default execution context serializer was updated to serialize/deserialize the context to/from Base64.The dependency to Jackson was made optional. In order to use the
JacksonExecutionContextStringSerializer
,jackson-core
should be added to the classpath.
(和訳)
実行コンテキスト・シリアライズの更新
v5 から、デフォルトの ExecutionContextSerializer が JacksonExecutionContextStringSerializer から DefaultExecutionContextSerializer に変更されました。デフォルトの実行コンテキスト・シリアライザーが更新され、コンテキストを Base64 にシリアライズ/Base64 からシリアライズ解除するようになりました。
Jackson への依存関係がオプションになりました。JacksonExecutionContextStringSerializer を使用するには、jackson-core をクラスパスに追加する必要があります。
<コメント>
・ExecutionContextSerializerは、実行コンテキストの直列化と逆直列化の両方を単一の実装に組み合わせた複合インターフェース。
SystemCommandTasklet updates
The
SystemCommandTasklet
has been revisited in this release and was changed as follows:
A new strategy interface named
CommandRunner
was introduced in order to decouple the command execution from the tasklet execution. The default implementation is theJvmCommandRunner
which uses thejava.lang.Runtime#exec
API to run system commands. This interface can be implemented to use any other API to run system commands.The method that runs the command now accepts an array of
String
s representing the command and its arguments. There is no need anymore to tokenize the command or do any pre-processing. This change makes the API more intuitive, and less prone to errors.
(和訳)
SystemCommandTasklet のアップデート
今回のリリースでは、SystemCommandTaskletが見直され、以下のように変更されました:
コマンドの実行をタスクレットの実行から切り離すために CommandRunner という新しいストラテジインタフェースが導入されました。デフォルトの実装はJvmCommandRunnerで、java.lang.Runtime#exec APIを使ってシステムコマンドを実行します。このインタフェースは、システムコマンドを実行するために他のAPIを使用するように実装することができます。
コマンドを実行するメソッドは、コマンドとその引数を表す文字列の配列を受け取ります。コマンドをトークン化したり、前処理をしたりする必要はなくなった。この変更により、APIはより直感的になり、エラーが発生しにくくなりました。
<コメント>
・SystemCommandTaskletはその名の通り、システムコマンドを実行するタスクレット。
Job parameters handling updates
(和訳)
ジョブ・パラメータの更新
<コメント>
・ここのも多いので、セクションごとにに分ける。
Support for any type as a job parameter
This change adds support to use any type as a job parameter, and not only the 4 pre-defined types (long, double, string, date) as in v4. The main change in the following:
---public class JobParameter implements Serializable { +++public class JobParameter<T> implements Serializable { --- private Object parameter; +++ private T value; --- private ParameterType parameterType; +++ private Class<T> type; }With this revision, the
JobParameter
can be of any type. This change required many API changes like changing the return type ofgetType()
, or the removal of theParameterType
enum. All changes related to this update can be found in the "[Deprecated|Moved|Removed] APIs" sections.This change had an impact on how job parameters are persisted in the database (There are no more 4 distinct columns for each predefined type). Please check Column change in BATCH_JOB_EXECUTION_PARAMS for DDL changes. The fully qualified name of the type of the parameter is now persisted as a
String
, as well as the parameter value. String literals are converted to the parameter type with the standard Spring conversion service. The standard conversion service can be enriched with any required converter to convert user specific types to and from String literals.
(和訳)
ジョブパラメータとしての任意の型のサポート
この変更により、v4のようにあらかじめ定義された4つの型(long, double, string, date)だけでなく、任意の型をジョブパラメータとして使用できるようになりました:
(省略)
この改訂により、JobParameter は任意の型にすることができるようになりました。この変更により、getType() の戻り値の型の変更や、ParameterType 列挙型の削除など、多くの API の変更が必要になりました。この更新に関連するすべての変更は、"[Deprecated|Moved|Removed] APIs" セクションにあります。
この変更は、ジョブパラメータがデータベースに永続化される方法に影響を及ぼしました (定義済みの型ごとに4つの異なるカラムがなくなりました)。DDLの変更については、BATCH_JOB_EXECUTION_PARAMSの列の変更を確認してください。パラメータの型の完全修飾名が、パラメータ値と同様にStringとして永続化されるようになりました。文字列リテラルは、Springの標準変換サービスでパラメータ型に変換されます。標準の変換サービスは、ユーザー固有の型をStringリテラルに変換したり、Stringリテラルから変換したりするために必要なコンバータで強化することができます。
<コメント>
・ジョブパラメーターの型の縛りがなかったので、自由になったともいえるが、BATCH_JOB_EXECUTION_PARAMSに影響を与えていて、型でオリジナリティを出すと、変換コンバーターが必要になる。
Default job parameter conversion
The default notation of job parameters in v4 was specified as follows:
[+|-]parameterName(parameterType)=value
where
parameterType
is one of [string,long,double,date]. In addition to be limited and constraining, this notation caused several issues as described in https://github.com/spring-projects/spring-batch/issues/3960.In v5, there are two way to specify job parameters:
Default notation
The default notation is specified as follows:
parameterName=parameterValue,parameterType,identificationFlag
where
parameterType
is the fully qualified name of the type of the parameter. Spring Batch provides theDefaultJobParametersConverter
to support this notation.Extended notation
While the default notation is well suited for the majority of use cases, it might be inconvenient when the value contains a comma for example. In this case, the extended notation can be used, which is inspired by Spring Boot's Json Application Properties and specified as follows:
parameterName='{"value": "parameterValue", "type":"parameterType", "identifying": "booleanValue"}'
where
parameterType
is the fully qualified name of the type of the parameter. Spring Batch provides theJsonJobParametersConverter
to support this notation.
(和訳)
ジョブパラメータのデフォルト変換
v4におけるジョブ・パラメータのデフォルト表記は以下のように規定されている:
[parameterName(parameterType)=value
ここで、parameterTypeは[string,long,double,date]のいずれかです。限定的で制約の多いこの表記法は、https://github.com/spring-projects/spring-batch/issues/3960 で説明されているように、いくつかの問題を引き起こしていました。
v5では、ジョブパラメータを指定する2つの方法があります:
デフォルト表記法
デフォルトの表記方法は以下の通りです:
parameterName=parameterValue,parameterType,identificationFlag
ここで、parameterTypeはパラメータの型の完全修飾名です。Spring Batchはこの表記法をサポートするDefaultJobParametersConverterを提供します。
拡張表記法
デフォルトの記法は大半のユースケースに適していますが、例えば値にカンマが含まれている場合は不便かもしれません。この場合、Spring BootのJson Application Propertiesにヒントを得た拡張記法を使うことができ、次のように指定します:
parameterName='{"value":parameterName='{"value": "parameterValue", "type": "parameterType", "identifying":"booleanValue"}'
ここで、parameterTypeはパラメータの型の完全修飾名です。Spring Batchはこの記法をサポートするJsonJobParametersConverterを提供します。
<コメント>
・これはジョブを起動する際に、アプリケーションに引き渡すパラメーターのお話。
SpringBootを起動する際に引き渡すパラメーターの型を説明している。
かなり複雑なものも対応できるように見える。
Historical data access implications
Due to this breaking change about handling job parameters, some APIs that are designed to explore batch meta-data should not be used for job instances that were launched with v4. For example:
JobExplorer#getJobInstances
could retrieve a mix of historical data between v4 and v5 and might fails at loading job parameters of v4 (#4352). In this particular case, make sure to start at the index of the first instance executed with v5.JobExplorer#getJobExecution
could fail at retrieving job parameters if the passed job execution ID is one of an execution that was run with v4.Another case where this change has implications on loading job parameters is when restarting failed job instances. It is expected that all failed v4 job instances are either restarted to success or abandoned before the migration to v5 is done.
(和訳)
履歴データアクセスへの影響
ジョブパラメータの取り扱いに関するこの変更により、バッチメタデータを探索するように設計されたいくつかのAPIは、v4で起動されたジョブインスタンスには使用できません。 たとえば、以下のようなものです:
JobExplorer#getJobInstancesはv4とv5の履歴データを混在して取得する可能性があり、v4のジョブパラメータの読み込みに失敗する可能性があります(#4352)。このような場合は、v5で最初に実行されたインスタンスのインデックスから開始するようにしてください。
渡されたジョブ実行IDがv4で実行されたものである場合、JobExplorer#getJobExecutionはジョブパラメータの取得に失敗する可能性があります。
この変更がジョブパラメータのロードに影響するもう1つのケースは、失敗したジョブインスタンスを再起動する場合です。v5への移行が完了する前に、すべての失敗したv4ジョブインスタンスが成功するように再起動されるか、放棄されることが期待されます。
<コメント>
・v4のジョブパラメーターで起動したデータが残っていると、v5で失敗する可能性があると…
結構な負の遺産なのと、環境によっては、バッチが起動しないみたいなことが発生しそうなので、要注意。
Deprecated APIs
(和訳)
・非推奨API
<コメント>
・そのうち消えるので、使っていたら要注意。
The following APIs have been deprecated in version 5.0:
org.springframework.batch.core.listener.ChunkListenerSupport
org.springframework.batch.core.listener.StepExecutionListenerSupport
org.springframework.batch.repeat.listener.RepeatListenerSupport
org.springframework.batch.core.listener.JobExecutionListenerSupport
org.springframework.batch.core.listener.SkipListenerSupport
org.springframework.batch.item.data.Neo4jItemReader
org.springframework.batch.item.data.builder.Neo4jItemWriterBuilder
org.springframework.batch.item.data.Neo4jItemWriter
org.springframework.batch.item.data.builder.Neo4jItemWriterBuilder
org.springframework.batch.item.database.support.SqlPagingQueryUtils#generateLimitGroupedSqlQuery(org.springframework.batch.item.database.support.AbstractSqlPagingQueryProvider, boolean, java.lang.String)
org.springframework.batch.core.repository.dao.JdbcJobInstanceDao#setJobIncrementer(DataFieldMaxValueIncrementer jobIncrementer)
org.springframework.batch.core.launch.support.SimpleJobLauncher
org.springframework.batch.core.configuration.annotation.JobBuilderFactory
org.springframework.batch.core.configuration.annotation.StepBuilderFactory
- The constructor
org.springframework.batch.core.job.builder.JobBuilder#JobBuilder(java.lang.String)
- The constructor
org.springframework.batch.core.step.builder.StepBuilder#StepBuilder(java.lang.String)
- The method
org.springframework.batch.core.step.builder.StepBuilder#tasklet(org.springframework.batch.core.step.tasklet.Tasklet)
- The method
org.springframework.batch.core.step.builder.StepBuilder#chunk(int)
- The method
org.springframework.batch.core.step.builder.StepBuilder#chunk(org.springframework.batch.repeat.CompletionPolicy)
- The method
org.springframework.batch.core.step.builder.TaskletStepBuilder#tasklet(org.springframework.batch.core.step.tasklet.Tasklet)
- The constructor
org.springframework.batch.integration.chunk.RemoteChunkingManagerStepBuilder#RemoteChunkingManagerStepBuilder(java.lang.String)
- The constructor
org.springframework.batch.integration.partition.RemotePartitioningManagerStepBuilder#RemotePartitioningManagerStepBuilder(java.lang.String)
- The constructor
org.springframework.batch.integration.partition.RemotePartitioningWorkerStepBuilder#RemotePartitioningWorkerStepBuilder(java.lang.String)
- The method
org.springframework.batch.integration.partition.RemotePartitioningWorkerStepBuilder#tasklet(org.springframework.batch.core.step.tasklet.Tasklet)
- The method
org.springframework.batch.integration.partition.RemotePartitioningWorkerStepBuilder#chunk(int)
- The method
org.springframework.batch.integration.partition.RemotePartitioningWorkerStepBuilder#chunk(org.springframework.batch.repeat.CompletionPolicy)
- The method
org.springframework.batch.core.JobParameters#toProperties
- The method
org.springframework.batch.core.JobParametersBuilder#addParameter
- The class
org.springframework.batch.core.launch.support.JobRegistryBackgroundJobRunner
- The class
org.springframework.batch.test.DataSourceInitializer
- The class
org.springframework.batch.integration.step.DelegateStep
- The annotation
org.springframework.batch.support.annotation.Classifier
- The class
org.springframework.batch.item.ItemStreamSupport
- The method
org.springframework.batch.core.step.builder.AbstractTaskletStepBuilder#throttleLimit
- The method
org.springframework.batch.repeat.support.TaskExecutorRepeatTemplate#setThrottleLimit
- The interface
org.springframework.batch.repeat.support.ResultHolder
- The interface
org.springframework.batch.repeat.support.ResultQueue
- The class
org.springframework.batch.repeat.support.ResultHolderResultQueue
- The class
org.springframework.batch.repeat.support.ThrottleLimitResultQueue
Please refer to the Javadoc of each API for more details about the suggested replacement.
(和訳)
推奨される置き換えの詳細については、各APIのJavadocを参照のこと。
<コメント>
・Javadoc見ましょう。
Moved APIs
(和訳)
・移動したAPI
<コメント>
・使っていたら、import文のパッケージの変更が必要となりそう。
- The
BatchMetrics
class (which is intended for internal use only) has been moved fromorg.springframework.batch.core.metrics
to theorg.springframework.batch.core.observability
package.- The
Chunk
class was moved from theorg.springframework.batch.core.step.item
package (spring-batch-core
module) to theorg.springframework.batch.item
package (spring-batch-infrastrucutre
module)- The
ScopeConfiguration
class has moved fromorg.springframework.batch.core.configuration.annotation
toorg.springframework.batch.core.configuration.support
Removed APIs
(和訳)
削除されたAPI
<コメント>
・バージョンアップすると、使えません。
- Class
org.springframework.batch.core.repository.support.MapJobRepositoryFactoryBean
- Class
org.springframework.batch.core.repository.dao.MapExecutionContextDao
- Class
org.springframework.batch.core.repository.dao.MapJobExecutionDao
- Class
org.springframework.batch.core.repository.dao.MapJobInstanceDao
- Class
org.springframework.batch.core.repository.dao.MapStepExecutionDao
- Class
org.springframework.batch.core.explore.support.MapJobExplorerFactoryBean
- Class
org.springframework.batch.core.repository.dao.XStreamExecutionContextStringSerializer
- Class
org.springframework.batch.core.configuration.support.ClassPathXmlJobRegistry
- Class
org.springframework.batch.core.configuration.support.ClassPathXmlApplicationContextFactory
- Class
org.springframework.batch.core.launch.support.ScheduledJobParametersFactory
- Class
org.springframework.batch.item.data.AbstractNeo4jItemReader
- Class
org.springframework.batch.item.database.support.ListPreparedStatementSetter
- Class
org.springframework.batch.integration.chunk.RemoteChunkingMasterStepBuilder
- Class
org.springframework.batch.integration.chunk.RemoteChunkingMasterStepBuilderFactory
- Class
org.springframework.batch.integration.partition.RemotePartitioningMasterStepBuilder
- Class
org.springframework.batch.integration.partition.RemotePartitioningMasterStepBuilderFactory
- Class
org.springframework.batch.test.AbstractJobTests
- Class
org.springframework.batch.item.xml.StaxUtils
<コメント>
・代替手段がないものもあるのか、要注意。
- Enum
org.springframework.batch.item.file.transform.Alignment
- Enum
org.springframework.batch.core.JobParameter#ParameterType
<コメント>
・使う必要がなくなったEnum。多分、廃止されたClass関連のもの。
- Method
org.springframework.batch.core.JobExecution#stop()
- Method
org.springframework.batch.core.JobParameters#getDouble(String key, double defaultValue)
- Method
org.springframework.batch.core.JobParameters#getLong(String key, long defaultValue)
- Method
org.springframework.batch.core.partition.support.SimpleStepExecutionSplitter(JobRepository jobRepository, Step step, Partitioner partitioner)
- Method
org.springframework.batch.core.partition.support.SimpleStepExecutionSplitter#getStartable(StepExecution stepExecution, ExecutionContext context)
- Method
org.springframework.batch.core.repository.support.AbstractJobRepositoryFactoryBean#getJobRepository()
- Method
org.springframework.batch.item.database.AbstractCursorItemReader#cleanupOnClose()
- Method
org.springframework.batch.item.database.HibernateItemWriter#doWrite(HibernateOperations hibernateTemplate, List<? extends T> items)
- Method
org.springframework.batch.item.database.JdbcCursorItemReader#cleanupOnClose()
- Method
org.springframework.batch.item.database.StoredProcedureItemReader#cleanupOnClose()
- Method
org.springframework.batch.item.database.builder.HibernatePagingItemReaderBuilder#useSatelessSession(boolean useStatelessSession)
- Method
org.springframework.batch.item.file.MultiResourceItemReader#getCurrentResource()
- Method
org.springframework.batch.integration.config.annotation.BatchIntegrationConfiguration#remoteChunkingMasterStepBuilderFactory()
- Method
org.springframework.batch.integration.config.annotation.BatchIntegrationConfiguration#remotePartitioningMasterStepBuilderFactory()
- Method
org.springframework.batch.item.util.FileUtils#setUpOutputFile(File file, boolean restarted, boolean overwriteOutputFile)
<コメント>
・メソッドは引数が変わっている等ありえるので、同じメソッド名で確認する。
Moreover, the following APIs have been removed/updated without deprecation:
- The interface
org.springframework.batch.core.configuration.annotation.BatchConfigurer
was removed. See https://github.com/spring-projects/spring-batch/issues/3942- The class
org.springframework.batch.core.configuration.annotation.DefaultBatchConfigurer
was removed. See https://github.com/spring-projects/spring-batch/issues/3942- The method
org.springframework.batch.core.step.builder.SimpleStepBuilder#processor(Function)
has been removed to allow lambdas to be passed as item processors. See https://github.com/spring-projects/spring-batch/issues/4061 for more details about the rationale behind this removal. If you use an actualFunction
as argument forSimpleStepBuilder::processor
, then you can change that to.processor(function::apply)
to migrate to v5.org.springframework.batch.item.file.builder.FlatFileItemWriterBuilder#resource
,org.springframework.batch.item.file.ResourceAwareItemWriterItemStream#setResource
,org.springframework.batch.item.json.builder.JsonFileItemWriterBuilder#resource
,org.springframework.batch.item.json.JsonFileItemWriter#JsonFileItemWriter
,org.springframework.batch.item.support.AbstractFileItemWriter#setResource
,org.springframework.batch.item.xml.builder.StaxEventItemWriterBuilder#resource
andorg.springframework.batch.item.xml.StaxEventItemWriter#setResource
have been updated to accept aorg.springframework.core.io.WritableResource
instead of aorg.springframework.core.io.Resource
. For more details about this change, please check https://github.com/spring-projects/spring-batch/issues/756- The static type
org.springframework.batch.item.data.builder.RepositoryItemReaderBuilder.RepositoryMethodReference
along with the methodorg.springframework.batch.item.data.builder.RepositoryItemReaderBuilder#repository(RepositoryMethodReference<?>)
have been removed.- The signature of the method
ItemWriter#write(List)
was changed toItemWriter#write(Chunk)
- All implementations of
ItemWriter
were updated to use theChunk
API instead ofList
- All methods in the
ItemWriteListener
interface were updated to use theChunk
API instead ofList
- All implementations of
ItemWriteListener
were updated to use theChunk
API instead ofList
- The constructor of
ChunkRequest
was changed to accept aChunk
instead of aCollection
of items- The return type of
ChunkRequest#getItems()
was changed fromList
toChunk
- The
JobRepositoryTestUtils
was changed to work against theJobRepository
interface without depending on a datasource bean. For this change, the constructor that takes aDataSource
as a parameter (JobRepositoryTestUtils(JobRepository jobRepository, DataSource dataSource)
) as well as the publicDataSource
setter were removed. This is related to issue #4070.- The method
StepBuilderHelper#transactionManager(PlatformTransactionManager)
was moved toAbstractTaskletStepBuilder
. This is related to issue https://github.com/spring-projects/spring-batch/issues/4130.- The methods
RemotePartitioningManagerStepBuilder#transactionManager(PlatformTransactionManager)
andRemotePartitioningWorkerStepBuilder#transactionManager(PlatformTransactionManager)
were removed. A transaction manager is not required for those type of steps. This is related to issue https://github.com/spring-projects/spring-batch/issues/4130.- The method
JobParameter#getType
now returnsT
instead ofObject
- The constructors in
JobParameter
that took the 4 pre-defined job parameter types (date, string, long, double) where removed.- The constructor
SkipWrapper(Throwable e)
was removed- The setter
setIsolationLevelForCreate(Isolation)
inAbstractJobRepositoryFactoryBean
was renamed tosetIsolationLevelForCreateEnum
- The return type of
JobExplorer#getJobInstanceCount
andJobInstanceDao#getJobInstanceCount
has been changed fromint
tolong
- The return type of
JobRepository#getStepExecutionCount
andStepExecutionDao#countStepExecutions
has been changed fromint
tolong
(和訳)
さらに、以下のAPIが廃止されることなく削除/更新された:
org.springframework.batch.core.configuration.annotation.BatchConfigurer インターフェースが削除されました。https://github.com/spring-projects/spring-batch/issues/3942 を参照してください。
org.springframework.batch.core.configuration.annotation.DefaultBatchConfigurer クラスが削除されました。https://github.com/spring-projects/spring-batch/issues/3942 を参照。
org.springframework.batch.core.step.builder.SimpleStepBuilder#processor(Function) メソッドが削除され、項目プロセッサとしてラムダを渡せるようになった。この削除の根拠については https://github.com/spring-projects/spring-batch/issues/4061 を参照してください。SimpleStepBuilder::processorの引数として実際のFunctionを使用している場合、v5に移行するために.processor(function::apply)に変更することができます。
org.springframework.batch.item.data.builder.RepositoryItemReaderBuilder.RepositoryMethodReference という静的型と org.springframework.batch.item.data.builder.RepositoryItemReaderBuilder#repository(RepositoryMethodReference<? >) というメソッドが削除されました。
ItemWriter#write(List)メソッドのシグネチャがItemWriter#write(Chunk)に変更された。
ItemWriterのすべての実装が、Listの代わりにChunk APIを使用するように更新されました。
ItemWriteListenerインターフェイスのすべてのメソッドが、Listの代わりにChunk APIを使用するように更新されました。
ItemWriteListener のすべての実装が、List の代わりに Chunk API を使用するように更新されました。
ChunkRequest のコンストラクタは、アイテムの Collection の代わりに Chunk を受け入れるように変更されました。
ChunkRequest#getItems() の戻り値の型が List から Chunk に変更されました。
JobRepositoryTestUtils は、データソースビーンに依存せずに JobRepository インターフェースに対して動作するように変更されました。この変更に伴い、データソースをパラメータとして受け取るコンストラクタ(JobRepositoryTestUtils(JobRepository jobRepository, DataSource dataSource))とパブリックデータソースセッタが削除されました。これは issue #4070 に関連しています。
StepBuilderHelper#transactionManager(PlatformTransactionManager) は AbstractTaskletStepBuilder に移動されました。これは問題 https://github.com/spring-projects/spring-batch/issues/4130 に関連しています。
RemotePartitioningManagerStepBuilder#transactionManager(PlatformTransactionManager) および RemotePartitioningWorkerStepBuilder#transactionManager(PlatformTransactionManager) メソッドは削除されました。これらのタイプのステップでは、トランザクションマネージャは必要ありません。これは問題 https://github.com/spring-projects/spring-batch/issues/4130 に関連しています。
JobParameter#getType メソッドは Object ではなく T を返すようになりました。
JobParameterのコンストラクタで、事前に定義された4つのジョブパラメータ型(date、string、long、double)が削除されました。
コンストラクタSkipWrapper(Throwable e)が削除されました。
AbstractJobRepositoryFactoryBean のセッター setIsolationLevelForCreate(Isolation) は setIsolationLevelForCreateEnum に名前が変更されました。
JobExplorer#getJobInstanceCountとJobInstanceDao#getJobInstanceCountの戻り値の型がintからlongに変更されました。
JobRepository#getStepExecutionCountおよびStepExecutionDao#countStepExecutionsの戻り値の型がintからlongに変更されました。
<コメント>
・関連するクラスやメソッドをgrepして、該当したら、各理由を確認するのがよさそう。
Pruning
(和訳)
剪定
<コメント>
・サポート終了系
SQLFire support removal
SqlFire has been announced to be EOL as of November 1st, 2014. The support of SQLFire as a job repository was deprecated in version 4.3 and removed in version 5.0.
(和訳)
SQLFireサポート終了のお知らせ
SqlFireは2014年11月1日をもってEOLとなることが発表されました。SQLFireのジョブリポジトリとしてのサポートはバージョン4.3で廃止され、バージョン5.0で削除されました。
<コメント>
・削除されているので、使えない。
JSR-352 implementation removal
Due to a lack of adoption, the implementation of the JSR-352 has been discontinued in this release.
(和訳)
JSR-352実装の削除
JSR-352 の実装は、採用されなかったため、このリリースで廃止されました。
<コメント>
・関連する実装をしている場合は、SpringBatchを使えない?
Gemfire support removal
Based on the decision to discontinue the support of Spring Data for Apache Geode, the support for Geode in Spring Batch was removed. The code was moved to the spring-batch-extensions repository as a community-driven effort.
(和訳)
Gemfireサポートの廃止
Spring Data for Apache Geodeのサポート中止の決定に基づき、Spring BatchにおけるGeodeのサポートが削除された。コミュニティ主導の取り組みとして、コードはspring-batch-extensionsリポジトリに移動された。
<コメント>
・ユーザーのセッション管理に使われるライブラリの様子。リポジトリが変わるので、別途追加が必要になる?
最後に
意外と根本的な考え方の変更があるので、特にイレギュラーなことをやっている場合、今までできたことがそのままの形でできると思わないほうがよさそう。