Overview
This section explains about using the job parameter (hereafter referred to as 'parameter').
The usage method of this function is same in the chunk model as well as tasklet model.
A parameter is used to flexibly switch the operation of the job according to the execution environment and execution timing as shown below.
-
File path of process target
-
System operation date and time
The following explanation is about assigning parameters.
The specified parameters can be referred in Bean definition or in Java under Spring management.
How to use
Regarding parameter conversion class
In Spring Batch, the received parameters are processed in the following sequence.
-
The implementation class of
JobParametersConverter
convert toJobParameters
. -
Refer to the parameters from
JobParameters
in Bean definition and Java under Spring management.
Multiple implementation classes of the above mentioned JobParametersConverter
are provided.
The features of each class are shown below.
-
DefaultJobParametersConverter
-
It can specify the data type of parameters(4 types; String, Long, Date, Double).
-
-
JsrJobParametersConverter
-
It cannot specify the data type of parameters (Only String).
-
It assigns ID (RUN_ID) that identifies job execution to parameter with the name
jsr_batch_run_id
automatically.-
It increments the RUN_ID each time the job is executed. Since it uses SEQUENCE (name is
JOB_SEQ
) of the database for incrementing, the name does not overlap. -
In Spring Batch, runnaing the job by the same parameters is identified as the same job and the same job can be executed only once. Whereas, adding a unique value to the parameter name
jsr_batch_run_id
will recognize it as a separate job. Refer to Spring Batch architecture for details.
-
-
In Spring Batch, when the implementation class of JobParametersConverter
to be used in Bean definition, is not specified, DefaultJobParametersConverter
is used.
However, in TERASOLUNA Batch 5.x, DefaultJobParametersConverter
is not used due to the following reasons.
-
It is common to run one job by the same parameter at different timing.
-
It is possible to specify the time stamp of the start time and manage them as different jobs, but it is complicated to specify job parameters only for that purpose.
-
DefaultJobParametersConverter
can specify data types for parameters, but handling becomes complicated when type conversion fails.
In TERASOLUNA Batch 5.x, by using JsrJobParametersConverter
, RUN_ID is automatically assigned without the user knowledge.
By this, the same job is handled as a different job in Spring Batch as seen by the user.
In TERASOLUNA Batch 5.x, it is set in advance so as to use JsrJobParametersConverter
in launch-context.xml
.
Therefore, when TERASOLUNA Batch 5.x is used with the recommended setting, there is no need to set JobParametersConverter
.
<bean id="jobParametersConverter"
class="org.springframework.batch.core.jsr.JsrJobParametersConverter"
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"
p:jobLauncher-ref="jobLauncher" />
The following description assumes that JsrJobParametersConverter is used.
Assign from command-line arguments
Firstly, how to assign from the most basic command-line arguments, is explained.
Command-line arguments are enumerated in the <Parameter name>=<Value>
format after 3rd argument of CommandLineJobRunner
.
The number and length of parameters are not restricted in Spring Batch and {batch 5 _ shortname}.
However, there are restrictions in the length of command arguments in the OS.
Therefore, when a large number of arguments is required, the method of Redirect from file to standard input and
Using parameters and properties together should be used.
# Execute job
$ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
JobDefined.xml JOBID param1=abc outputFileName=/tmp/result.csv
Parameters can be referred in Bean definition or in Java as shown below.
-
Refer in Bean definition
-
It can be referred by
#{jobParamaters[xxx]}
-
-
Refer in Java
-
It can be referred by
@Value("#{jobParameters[xxx]}")
-
The scope of the Bean that refers to JobParameters should be Step scope
When referring to As its name implies, late binding is setting of the delayed value.
|
@StepScope annotation cannot be used for specifying Step scope
In Spring Batch, Therefore, specify the
|
<!-- (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>
Sr. No. | Explanation |
---|---|
(1) |
Specify scope as scope attribute in bean tag. |
(2) |
Specify the parameter to be referred. |
@Component
@Scope("step") // (1)
public class ParamRefInJavaTasklet implements Tasklet {
/**
* Holds a String type value
*/
@Value("#{jobParameters[str]}") // (2)
private String str;
// omitted execute()
}
Sr. No. | Explanation |
---|---|
(1) |
Specify scope by assigning |
(2) |
Specify the parameter to be referred by using |
Redirect from file to standard input
How to redirect from file to standard input is explained.
Define the parameters in the files as follows.
param1=abc
outputFile=/tmp/result.csv
Redirect the files wherein parameters are defined as command-line arguments.
# Execute job
$ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
JobDefined.xml JOBID < params.txt
How to refer to the parameters is same as the Assign from command-line arguments method.
Set the default value of parameter
When parameters are optional, default values can be set in the following format.
-
#{jobParameters[Parameter name] ?: Default value}
However, in the item where the value is set using parameters, the default values can also differ with the environment and execution timing same as the parameters.
Firstly, how to hardcode the default values in source code is explained. However, there are many cases where it is better to use Using parameters and properties together, so refer them also.
When the relevant parameter is not set, the value set as the default value is referred.
<!-- (1) -->
<bean id="reader"
class="org.springframework.batch.item.file.FlatFileItemReader" scope="step"
p:resource="file:#{jobParamaters[inputFile] ?: /input/sample.csv}"> <!-- (2) -->
<property name="lineMapper">
// omitted settings
</property>
</bean>
Sr. No. | Explanation |
---|---|
(1) |
Specify the scope as scope attribute in the bean tag. |
(2) |
Specify the parameter to be referred. |
@Component
@Scope("step") // (1)
public class ParamRefInJavaTasklet implements Tasklet {
/**
* Holds a String type value
*/
@Value("#{jobParameters[str] ?: xyz}") // (2)
private String str;
// omitted execute()
}
Sr. No. | Explanation |
---|---|
(1) |
Specify the scope by assigning |
(2) |
Specify the parameter to be referred by using |
Validation of parameters
Validation of the parameters is required at job launch in order to prevent operation errors or unintended behavior.
Validation of parameters can be implemented by using the JobParametersValidator
provided by Spring Batch.
Since parameters are referred at various places such as ItemReader/ItemProcessor/ItemWriter, validation is performed immediately after the job is launched.
There are two ways to verify the validity of a parameter, and it differs with the degree of complexity of the verification.
-
-
Application example
-
Verify that the required parameters are set
-
Verify that the unspecified parameters are not set
-
-
Validator to be used
-
DefaultJobParametersValidator
provided by Spring Batch
-
-
-
-
Application example
-
Numerical value range verification and complex verification such as correlation check between parameters
-
Verification that cannot be done by
DefaultJobParametersValidator
provided by Spring Batch
-
-
Validator to be used
-
Class wherein
JobParametersValidator
is implemented independently
-
-
How to verify the validity of Simple validation and Complex validation is explained respectively.
Simple validation
Spring Batch provides DefaultJobParametersValidator
as the default implementation of JobParametersValidator
.
This validator can verify the following as per the settings.
-
Required parameters should be set
-
Parameters other than required or optional should not be specified
Definition example is shown as follows.
<!-- (1) -->
<bean id="jobParametersValidator"
class="org.springframework.batch.core.job.DefaultJobParametersValidator">
<property name="requiredKeys"> <!-- (2) -->
<list>
<value>jsr_batch_run_id</value> <!-- (3) -->
<value>inputFileName</value>
<value>outputFileName</value>
</list>
</property>
<property name="optionalKeys"> <!-- (4) -->
<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"/> <!-- (5) -->
</batch:job>
Sr. No. | Explanation |
---|---|
(1) |
Define Bean for |
(2) |
Set the required parameters to property |
(3) |
Set |
(4) |
Set optional parameters to property |
(5) |
Apply the validator to the job using validator tag in the job tag. |
Required parameters that cannot be omitted in TERASOLUNA Batch 5.x
Therefore, Example of parameter definition
|
An example when the verification result is OK and NG are shown to understand the verification possible conditions in DefaultJobParametersValidator
.
<bean id="jobParametersValidator"
class="org.springframework.batch.core.job.DefaultJobParametersValidator"
p:requiredKeys="outputFileName"
p:optionalKeys="param1"/>
# Execute job
$ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
JobDefined.xml JOBID param1=aaa
NG as the required parameter outputFile
is not set.
# Execute job
$ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
JobDefined.xml JOBID outputFileName=/tmp/result.csv param2=aaa
NG as the parameter param2
which is not specified for either the required parameter or the optional parameter is set.
# Execute job
$ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
JobDefined.xml JOBID param1=aaa outputFileName=/tmp/result.csv
OK as the parameters specified as required and optional are set.
# Execute job
$ java org.springframework.batch.core.launch.support.CommandLineJobRunner \
JobDefined.xml JOBID fileoutputFilename=/tmp/result.csv
OK as the required parameters are set and there is no need to set optional parameters.
Complex validation
Implementing JobParametersValidator
interface independently
helps in verifying the parameters as per requirements.
Implement JobParametersValidator
class as follows.
-
Implement
JobParametersValidator
class and override validate method -
Implement validate method as follows
-
Fetch each parameter from
JobParameters
and verify-
If the verification result is OK, there is no need to perform any operation
-
If verification result is NG, throw
JobParametersInvalidException
-
-
Implementation example of JobParametersValidator
class is shown.
In this case, it is verified that the length of the string specified by str
is less than or equal to the number specified by num
.
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)
}
}
}
Sr. No. | Explanation |
---|---|
(1) |
Implement |
(2) |
Receive the parameters as arguments in |
(3) |
Get parameters by specifying key. |
(4) |
Convert parameters to int type. When handling parameters of other than String type, they should be appropriately converted. |
(5) |
Validation result is NG when the string length of the parameter |
<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="org.terasoluna.batch.functionaltest.ch04.jobparameter.ComplexJobParametersValidator"/>
</batch:validator>
</batch:job>
Sr. No. | Explanation |
---|---|
(1) |
Apply validator in the job by using validator tag in the job tag. |
Regarding validation of parameters at asynchronous start
By the asynchronous start method (DB polling and Web container), it is possible to verify the parameters at the job launch in the same way, however, it is desirable to verify them before launching the job at the following timing.
In case of asynchronous start, since it is necessary to confirm the result separately, errors such as parameter settings should be responded quickly and job requests should be rejected. For validation in this case, there is no need to use |
How to extend
Using parameters and properties together
Spring Framework based on Spring Batch is equipped with the property management function to enable it to handle the values set in the environment variables and property files. For details, refer to Property management of TERASOLUNA Server 5.x Development Guideline.
By combining properties and parameters, it is possible to overwrite some parameters after making common settings for most jobs in the property file.
About when parameters and propertis are resolved
As mentioned above, parameters and properties are different components that provide the function.
The timing of resolving each value is different.
Therefore, the parameter value is given priority by Spring Batch. |
How to set by combining properties and parameters, is explained.
In addition to the setting by environment variables, how to set the parameters using command-line arguments, is explained.
It is possible to refer to it in the same manner as Bean definition.
# 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
@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;
}
Sr. No. | Explanation |
---|---|
(1) |
Specify the environment variables to be referred by using |
(2) |
Specify the parameters to be referred by using |
# 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
@Value("#{jobParameters[param1] ?: '${env1}'}") // (1)
public void setParam1(String param1) {
this.param1 = param1;
}
Sr. No. | Explanation |
---|---|
(1) |
Specify the parameters to be referred by using |
How to set incorrect default values
When the following is defined and param1 is not set by command-line arguments, note that null is set in param1 irrespective of the fact that you want to set env1 value. Setting method example of incorrect default value
|