Batch Properties
Batch Property Scopes
Batch properties are defined in job xml to configure the job. There are 3 groups of batch properties, according to their scopes:
Job-level batch properties:
To define job-level batch properties in job xml:
<job version="1.0" id="job1" xmlns="http://xmlns.jcp.org/xml/ns/javaee">
<properties>
<property name="jobProp1" value="value1"/>
</properties>
<!-- other elements omitted -->
</job>
Access job-level batch properties from a batch artifact class with javax.batch.runtime.context.JobContext#getProperties
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
JobContext jobContext;
private Properties jobProperties;
@Override
public String process() throws Exception {
jobProperties = jobContext.getProperties();
String value1 = jobProperties.getProperty("jobProp1");
// ...
return "Processed";
}
}
Note that the properties obtained from JobContext#getProperties
contains job-level batch properties as defined in job xml, and should not be used by application to store application data. For this purpose, JobContext#setTransientUserData
should be used instead.
Step-level batch properties
To define step-level batch properties in job xml:
<step id="step1" start-limit="5" allow-start-if-complete="true">
<properties>
<property name="stepProp1" value="value1"/>
</properties>
<!-- other elements omitted -->
</step>
Access step-level batch properties from a batch artifact class with javax.batch.runtime.context.StepContext#getProperties
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
StepContext stepContext;
private Properties stepProperties;
@Override
public String process() throws Exception {
stepProperties = stepContext.getProperties();
String value1 = stepProperties.getProperty("stepProp1");
// ...
return "Processed";
}
}
Note that the properties obtained from StepContext#getProperties
contains step-level batch properties as defined in job xml, and should not be used by application to store application data. For this purpose, StepContext#setTransientUserData
or StepContext#setPersistentUserData
should be used instead.
Batch artifact properties
To define batch artifact properties in job xml:
<batchlet ref="myBatchlet">
<properties>
<property name="name1" value="value1"/>
</properties>
</batchlet>
Batch artifact properties can be accessed from a batch artifact with injection. The optional attribute javax.batch.api.BatchProperty#name
tells which batch property to inject into the annotated field. When name
attribute is omitted, the target batch property name is the same as the field name. The following batchlet class injects the batch property named name1
configured in the above job.xml into 2 fields:
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
@BatchProperty
String name1;
@Inject
@BatchProperty(name = "name1")
String title;
//...
}
Note that job- and step-level batch properties may not be directly injected into batch artifact classes. However, application may inject an batch artifact property that references a job- or step-level batch property via jobProperties
substitution in job xml. For example,
<job id="job1" xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="1.0">
<properties>
<property name="jobProp1" value="value1"/>
</properties>
<step id="step1">
<properties>
<property name="stepProp1" value="value1"/>
</properties>
<batchlet ref="myBatchlet">
<properties>
<property name="prop1"
value="#{jobProperties['jobProp1']}" />
<property name="prop2"
value="#{jobProperties['stepProp1']}"/>
</properties>
<!-- other elements omitted -->
</batchlet>
</step>
</job>
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
@BatchProperty
String prop1;
@Inject
@BatchProperty
String prop2;
//...
}
Batch Property Injection with @BatchProperty
A batch artifact class can contain fields annotated with @Inject
and @BatchProperty
to inject properties defined in job xml into these fields. The injection field can be any of the following java types:
java.lang.String
java.lang.StringBuilder
java.lang.StringBuffer
- any primitive type, and its wrapper type:
boolean, Boolean
int, Integer
double, Double
long, Long
char, Character
float, Float
short, Short
byte, Byte
java.math.BigInteger
java.math.BigDecimal
java.net.URL
java.net.URI
java.io.File
java.util.jar.JarFile
java.util.Date
java.lang.Class
java.net.Inet4Address
java.net.Inet6Address
java.util.List, List<?>, List<String>
java.util.Set, Set<?>, Set<String>
java.util.Map, Map<?, ?>, Map<String, String>, Map<String, ?>
java.util.logging.Logger
java.util.regex.Pattern
javax.management.ObjectName
The following array types are also supported:
java.lang.String[]
- any primitive type, and its wrapper type:
boolean[], Boolean[]
int[], Integer[]
double[], Double[]
long[], Long[]
char[], Character[]
float[], Float[]
short[], Short[]
byte[], Byte[]
java.math.BigInteger[]
java.math.BigDecimal[]
java.net.URL[]
java.net.URI[]
java.io.File[]
java.util.jar.JarFile[]
java.util.zip.ZipFile[]
java.util.Date[]
java.lang.Class[]
The following example injects a number into the batchlet class as various suitable types:
<batchlet ref="myBatchlet">
<properties>
<property name="number" value="10"/>
</properties>
</batchlet>
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
@BatchProperty
int number; // field name is the same as batch property name
@Inject
@BatchProperty (name = "number")
long asLong; // use name attribute to locate batch property
@Inject
@BatchProperty (name = "number")
Double asDouble; // inject as Double wrapper type
@Inject
@BatchProperty (name = "number")
private String asString; // inject as private String
@Inject
@BatchProperty (name = "number")
BigInteger asBigInteger; // inject as BigInteger
@Inject
@BatchProperty (name = "number")
BigDecimal asBigDecimal; // inject as BigDecimal
}
The following example injects a number sequence into the batchlet class as various arrays and collections:
<batchlet ref="myBatchlet">
<properties>
<property name="weekDays" value="1,2,3,4, 5, 6, 7"/>
</properties>
</batchlet>
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
@BatchProperty
int[] weekDays;
@Inject
@BatchProperty (name = "weekDays")
Integer[] asIntegers;
@Inject
@BatchProperty (name = "weekDays")
String[] asStrings;
@Inject
@BatchProperty (name = "weekDays")
byte[] asBytes;
@Inject
@BatchProperty (name = "weekDays")
BigInteger[] asBigIntegers;
@Inject
@BatchProperty (name = "weekDays")
BigDecimal[] asBigDecimals;
@Inject
@BatchProperty (name = "weekDays")
List asList
@Inject
@BatchProperty (name = "weekDays")
List<String> asListString;
@Inject
@BatchProperty (name = "weekDays")
Set asSet;
@Inject
@BatchProperty (name = "weekDays")
Set<String> asSetString;
}
The following example injects key-value pairs batch property into the batchlet class as a Map:
<batchlet ref="myBatchlet">
<properties>
<property name="pairs"
value="id=1, name=Jon, age=30"/>
</properties>
</batchlet>
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
@BatchProperty
protected Map<String, String> pairs;
@Inject
@BatchProperty (name = "pairs")
private Map asMap;
}
The following example injects class batch property into the batchlet class:
<batchlet ref="myBatchlet">
<properties>
<property name="clazz" value="org.jberet.support.io.Person"/>
</properties>
</batchlet>
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
@BatchProperty
private Class clazz;
}
The following example injects java.util.Date batch property into the batchlet class. Its string value is converted to java.util.Date based on the current system locale.
<batchlet ref="myBatchlet">
<properties>
<property name="date" value="05/09/2013 7:03 AM"/>
</properties>
</batchlet>
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
@BatchProperty
private java.util.Date date;
}
The following example injects URL or URI batch property into the batchlet class:
<batchlet ref="myBatchlet">
<properties>
<property name="url" value="www.jboss.org"/>
</properties>
</batchlet>
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
@BatchProperty
private URL url;
@Inject
@BatchProperty (name = "url")
private URI uri;
}
The following example injects File or JarFile batch property into the batchlet class:
<batchlet ref="myBatchlet">
<properties>
<property name="file"
value="#{systemProperties['java.home']}/lib/jce.jar"/>
</properties>
</batchlet>
@Named
public class MyBatchlet extends AbstractBatchlet {
@Inject
@BatchProperty
private File file;
@Inject
@BatchProperty (name = "file")
private JarFile asJarFile
}
Sometimes it's convenient to assign a default value to a field in artifact java class, whether the target batch property is defined in job xml or not. If the target property is resolved to a valid value, it is injected into that field; otherwise, no value is injected and the default field value is preserved. For example,
/**
* Comment character. If commentChar batch property is not specified in job xml,
* use the default value '#'.
*/
@Inject
@BatchProperty
private char commentChar = '#';
Comparison of Various Batch Properties and Parameters
What | API Access | JSL Access | @BatchProperty Injectable? | |
---|---|---|---|---|
Job Parameters | Props when starting or restarting a job | JobExecution.getJobParameters() | #{jobParameters['x']} | No |
Job-level Properties | Props element in job.xml directly within |
JobContext.getProperties() | #{jobProperties['x']} | No |
Step-level Properties | Props element in job.xml directly within step element | StepContext.getProperties() | #{jobProperties['x']} | No |
Batch Artifact Properties | Props directly within batch artifact in job.xml | @Inject @BatchProperty | #{jobParameters['x']} | Yes |
Partition Plan Properties | Props element with partition plan element in job.xml | None | #{partitionPlan['x']} | No |
Java System Properties | Java system properties | System.getProperty(), System.getProperties() | #{systemProperties['x']} | No |