Использование языка спецификации задания

Язык спецификации задания (JSL) позволяет вам определить шаги в задании и порядок их выполнения, используя файл XML. В следующем примере показано, как определить простое задание, содержащее один шаг фрагмента и один шаг задачи:

<job id="loganalysis" xmlns="http://xmlns.jcp.org/xml/ns/javaee"
                      version="1.0">
  <properties>
    <property name="input_file" value="input1.txt"/>
    <property name="output_file" value="output2.txt"/>
  </properties>

  <step id="logprocessor" next="cleanup">
    <chunk checkpoint-policy="item" item-count="10">
      <reader ref="com.example.pkg.LogItemReader"></reader>
      <processor ref="com.example.pkg.LogItemProcessor"></processor>
      <writer ref="com.example.pkg.LogItemWriter"></writer>
    </chunk>
  </step>

  <step id="cleanup">
    <batchlet ref="com.example.pkg.CleanUp"></batchlet>
    <end on="COMPLETED"/>
  </step>
</job>

В этом примере определяется задание loganalysis, которое состоит из шага фрагмента logprocessor и шага задачи cleanup. Шаг logprocessor переходит к шагу cleanup, при завершении которого завершается и всё задание.

Элемент job определяет два свойства: input_file и output_file. Указание свойств таким способом позволяет запускать пакетное задание с различными параметрами конфигурации без необходимости перекомпиляции его пакетных артефактов Java. Пакетные артефакты могут обращаться к этим свойствам с помощью объектов контекста из пакетной среды выполнения.

Шаг logprocessor является шагом фрагмента, который указывает пакетные артефакты для чтения (LogItemReader), обработки (LogItemProcessor) и записи (LogItemWriter). Этот шаг создаёт контрольную точку для каждых десяти обработанных элементов.

Шаг cleanup — это шаг задачи, который определяет класс CleanUp в качестве своего пакетного артефакта. Задание в целом завершается вместе с завершением этого шага.

В следующих разделах более подробно описываются элементы языка спецификации заданий (JSL) и демонстрируются наиболее распространённые атрибуты и дочерние элементы.

Элемент job

Элемент job всегда является элементом верхнего уровня в файле определения задания. Его основные атрибуты id и restartable. Элемент job может содержать один элемент properties и ноль или более каждого из следующих элементов: listener, step , flow и split. Например:

<job id="jobname" restartable="true">
  <listeners>
    <listener ref="com.example.pkg.ListenerBatchArtifact"/>
  </listeners>
  <properties>
    <property name="propertyName1" value="propertyValue1"/>
    <property name="propertyName2" value="propertyValue2"/>
  </properties>
  <step ...> ... </step>
  <step ...> ... </step>
  <decision ...> ... </decision>
  <flow ...> ... </flow>
  <split ...> ... </split>
</job>

Элемент listener указывает пакетный артефакт, методы которого вызываются до и после выполнения задания. Пакетный артефакт реализует интерфейс javax.batch.api.listener.JobListener. Смотрите Пакетные артефакты слушателя для примера реализации слушателя задания.

Первым выполняется первый элемент step, flow или split внутри элемента job.

Элемент step

Элемент step может быть дочерним элементом элементов job и flow. Его основные атрибуты id и next. Элемент step может содержать следующие элементы:

Один элемент chunk для шагов, ориентированных на фрагменты, или один элемент batchlet для шагов, ориентированных на задачи.
Один элемент properties (необязательно).

Этот элемент определяет набор свойств, к которым пакетные артефакты могут получить доступ с помощью объектов контекста пакета.
Один элемент listener (необязательно). Один элемент listeners, если указано более одного слушателя.

Этот элемент определяет артефакты слушателя, которые перехватывают различные фазы выполнения шага.

Для шагов фрагмента пакетные артефакты для этих слушателей могут быть реализациями следующих интерфейсов: StepListener, ItemReadListener, ItemProcessListener, ItemWriteListener, ChunkListener, RetryReadListener, RetryProcessListener, RetryWriteListener, SkipReadListener, SkipProcessListener и SkipWriteListener.

Для шагов задачи артефакт пакета для этих слушателей должен реализовывать интерфейс StepListener.

Посмотрите Пакетные артефакты слушателя для примера реализации слушателя.
Один элемент partition (необязательно).

Этот элемент используется в разделённых шагах, которые выполняются в более чем одном потоке (thread).
Один элемент end, если это последний шаг в задании.

Этот элемент устанавливает статус пакета в COMPLETED.
Один элемент stop (необязательно), чтобы остановить работу на этом шаге.

Этот элемент устанавливает статус пакета в STOPPED.
Один элемент fail (необязательно), который завершает работу на этом этапе.

Этот элемент устанавливает статус пакета на FAILED.
Один или несколько элементов next, если не указан атрибут next.

Этот элемент связан со статусом завершения и относится к другому шагу, потоку (flow), разделителю или элементу принятия решения.

Ниже приведён пример шага фрагмента:

<step id="stepA" next="stepB">
  <properties> ... </properties>
  <listeners>
    <listener ref="MyItemReadListenerImpl"/>
    ...
  </listeners>
  <chunk ...> ... </chunk>
  <partition> ... </partition>
  <end on="COMPLETED" exit-status="MY_COMPLETED_EXIT_STATUS"/>
  <stop on="MY_TEMP_ISSUE_EXIST_STATUS" restart="step0"/>
  <fail on="MY_ERROR_EXIT_STATUS" exit-status="MY_ERROR_EXIT_STATUS"/>
</step>

Ниже приведён пример шага задачи:

<step id="stepB" next="stepC">
  <batchlet ...> ... </batchlet>
  <properties> ... </properties>
  <listener ref="MyStepListenerImpl"/>
</step>

Элемент chunk

Элемент chunk является дочерним элементом элемента step для шагов, ориентированных на фрагменты. Атрибуты этого элемента перечислены в таблице 58-2.

Таблица 58-2 Атрибуты элемента chunk

Название атрибута

Описание

Значение по умолчанию

checkpoint-policy

Определяет, как зафиксировать результаты обработки каждого фрагмента:

"item": фрагмент фиксируется после обработки item-count элементов
"custom": фрагмент фиксируется в соответствии с алгоритмом контрольной точки, указанном в элементе checkpoint-algorithm

Контрольная точка обновляется при фиксации результатов обработки фрагмента.

Каждый фрагмент обрабатывается в глобальной транзакции Java EE. Если обработка одного элемента во фрагменте не удалась, транзакция откатывается и никакие обработанные элементы из этого фрагменты не сохраняются.

"item"

item-count

Определяет количество элементов для обработки перед фиксацией фрагмента и принятием контрольной точки.

time-limit

Указывает количество секунд до фиксации фрагмента и получения контрольной точки, когда checkpoint-policy = "item".

Если элементы item-count не были обработаны в течение time-limit секунд, фрагмент фиксируется и берётся контрольная точка.

0 (без ограничений)

buffer-items

Указывает, буферизуются ли обработанные элементы до тех пор, пока не настанет время проходить контрольную точку. Если значение true, выполняется один вызов к элементу записи со списком буферизованных элементов перед фиксацией фрагмента и принятием контрольной точки.

true

skip-limit

Задаёт максимальное количество пропускаемых исключений, которые можно пропустить на этом шаге при обработке фрагмента. Классы исключений, которые можно пропустить, указываются с помощью элемента skippable-exception-classes.

Без ограничений

retry-limit

Задаёт количество попыток выполнить этот шаг, если возникают повторяющиеся исключения. Классы повторяющихся исключений указываются с помощью элемента retryable-exception-classes.

Без ограничений

Элемент chunk может содержать следующие элементы:

Один элемент reader.

Этот элемент указывает пакетный артефакт, который реализует интерфейс ItemReader.
Один элемент processor.

Этот элемент указывает пакетный артефакт, который реализует интерфейс ItemProcessor.
Один элемент writer.

Этот элемент указывает пакетный артефакт, который реализует интерфейс ItemWriter.
Один элемент checkpoint-algorithm (необязательно).

Этот элемент указывает пакетный артефакт, который реализует интерфейс CheckpointAlgorithm и предоставляет настраиваемую политику контрольных точек.
Один элемент skippable-exception-classes (необязательно).

Этот элемент определяет набор исключений, выдаваемых из артефактов чтения, записи и обработки, которые при обработке фрагмента следует пропустить. Атрибут skip-limit из элемента chunk указывает максимальное количество пропущенных исключений.
Один элемент retryable-exception-classes (необязательно).

Этот элемент задаёт набор исключений, выдаваемых артефактами пакета чтения, записи и обработки, которые повторяется при обработке фрагмента. Атрибут retry-limit из элемента chunk указывает максимальное количество попыток.
Один элемент no-rollback-exception-classes (необязательно).

Этот элемент определяет набор исключений, выдаваемых артефактами пакетного чтения, записи и процессора, которые не должны приводить к тому, что среда выполнения пакета выполняет откат текущего фрагмента, а вместо этого повторяет текущую операцию без отката.

Для типов исключений, не указанных в этом элементе, текущий фрагмент по умолчанию откатывается при возникновении исключения.

Ниже приведён пример шага, ориентированного на фрагменты:

<step id="stepC" next="stepD">
  <chunk checkpoint-policy="item" item-count="5" time-limit="180"
         buffer-items="true" skip-limit="10" retry-limit="3">
    <reader ref="pkg.MyItemReaderImpl"></reader>
    <processor ref="pkg.MyItemProcessorImpl"></processor>
    <writer ref="pkg.MyItemWriterImpl"></writer>
    <skippable-exception-classes>
      <include class="pkg.MyItemException"/>
      <exclude class="pkg.MyItemSeriousSubException"/>
    </skippable-exception-classes>
    <retryable-exception-classes>
      <include class="pkg.MyResourceTempUnavailable"/>
    </retryable-exception-classes>
  </chunk>
</step>

В этом примере определяется шаг фрагмента и указываются артефакты чтения, обработки и записи. Шаг обновляет контрольную точку и фиксирует каждый фрагмент после обработки пяти элементов. Он пропускает все исключения MyItemException и все его подтипы, кроме MyItemSeriousSubException, но не более десяти пропущенных исключений. Шаг повторяет фрагмент, когда возникает исключение MyResourceTempUnavailable, максимум до трёх попыток.

Элемент batchlet

Элемент batchlet является дочерним элементом элемента step для шагов, ориентированных на задачи. Этот элемент имеет только атрибут ref, указывающий артефакт пакета, реализующего интерфейс Batchlet. Элемент batch может содержать элемент properties.

Ниже приведён пример шага, ориентированного на задачу:

<step id="stepD" next="stepE">
  <batchlet ref="pkg.MyBatchletImpl">
    <properties>
      <property name="pname" value="pvalue"/>
    </properties>
  </batchlet>
</step>

В этом примере определяется шаг пакета и указывается его пакетный артефакт.

Элемент partition

Элемент partition является дочерним элементом элемента step. Он указывает на то, что шаг разделён. Большинство разделённых шагов являются шагами, когда обработка каждого элемента не зависит от результатов обработки предыдущих элементов. Вы указываете количество разделений в шаге и предоставляете каждому разделению конкретную информацию о том, какие элементы обрабатывать. Как пример:

Диапазон элементов. Например, разделение 1 обрабатывает элементы с 1 по 500, а разделение 2 обрабатывает элементы с 501 по 1000.
Источник ввода. Например, разделение 1 обрабатывает элементы в input1.txt, а разделение 2 обрабатывает элементы в input2.txt.

Когда число разделений, количество элементов и источники ввода для шага разделения известны во время разработки или развёртывания, вы можете использовать свойства разделения в файле определения задания, чтобы указать информацию о разделении и получить доступ к этим свойствам из пакетных артефактов. Во время выполнения инстанцируется столько объектов пакетных артефактов (читателей, обработчиков и писателей), сколько разделений, и каждый объект артефакта получает свойства, характерные для его разделения.

В большинстве случаев количество разделений, количество элементов или входные источники для шага разделения могут быть определены только во время выполнения. Вместо статического указания специфичных для разделения свойств в файле определения задания вы предоставляете пакетный артефакт, который может обращаться к вашим источникам данных во время выполнения и определять, сколько разделений необходимо и какой диапазон элементов должно обрабатывать каждое разделение. Этот пакетный артефакт является реализацией интерфейса PartitionMapper. Пакетная среда выполнения вызывает этот артефакт, а затем использует информацию, которую он предоставляет, для инстанцирования объектов пошаговых пакетных артефактов (читателя, обработчика и писателя) для каждого разделения и для передачи им данных, специфичных для разделения, в качестве параметров.

В оставшейся части этого раздела подробно описывается элемент partition и показаны два примера файлов определения задания: один, использующий свойства разделения для указания диапазона элементов для каждого разделения, и другой, который опирается на PartitionMapper реализация для определения специфичной для разделения информации.

См. Шаг фрагмента телефонного биллинга в Примере phonebilling для полного примера разделённого шага фрагмента.

Элемент partition может содержать следующие элементы:

Один элемент plan, если элемент mapper не указан.

Этот элемент определяет количество разделений, количество потоков (thread) и свойства для каждого разделения в файле определения задания. Элемент plan полезен, когда эта информация известна во время разработки или развёртывания.
Один элемент mapper, если элемент plan не указан.

Этот элемент указывает пакетный артефакт, который предоставляет количество разделений, количество потоков (thread) и свойства для каждого разделения. Пакетный артефакт является реализацией интерфейса PartitionMapper. Этот параметр используется, когда информация, необходимая для каждого разделения, известна только во время выполнения.
Один элемент reducer (необязательно).

Этот элемент указывает пакетный артефакт, который получает управление, когда разделённый шаг начинается, заканчивается или откатывается. Пакетный артефакт позволяет объединять результаты из разных разделений и выполнять другие сопутствующие операции. Пакетный артефакт является реализацией интерфейса PartitionReducer.
Один элемент collector (необязательно).

Этот элемент указывает пакетный артефакт, который отправляет промежуточные результаты из каждого разделения в анализатор разделений. Пакетный артефакт отправляет промежуточные результаты после каждой контрольной точки для шагов фрагментов и в конце шага для шагов задач. Пакетный артефакт является реализацией интерфейса PartitionCollector.
Один элемент analyzer (необязательно).

Этот элемент указывает пакетный артефакт, который анализирует промежуточные результаты от объектов сборщика разделений. Пакетный артефакт является реализацией интерфейса PartitionAnalyzer.

Ниже приведён пример разделённого шага с использованием элемента plan:

<step id="stepE" next="stepF">
  <chunk>
    <reader ...></reader>
    <processor ...></processor>
    <writer ...></writer>
  </chunk>
  <partition>
    <plan partitions="2" threads="2">
      <properties partition="0">
        <property name="firstItem" value="0"/>
        <property name="lastItem" value="500"/>
      </properties>
      <properties partition="1">
        <property name="firstItem" value="501"/>
        <property name="lastItem" value="999"/>
      </properties>
    </plan>
  </partition>
  <reducer ref="MyPartitionReducerImpl"/>
  <collector ref="MyPartitionCollectorImpl"/>
  <analyzer ref="MyPartitionAnalyzerImpl"/>
</step>

В этом примере элемент plan определяет свойства для каждого разделения в файле определения задания.

В следующем примере вместо элемента plan используется элемент mapper. Реализация PartitionMapper динамически предоставляет ту же информацию, что и элемент plan в файле определения задания:

<step id="stepE" next="stepF">
  <chunk>
    <reader ...></reader>
    <processor ...></processor>
    <writer ...></writer>
  </chunk>
  <partition>
    <mapper ref="MyPartitionMapperImpl"/>
    <reducer ref="MyPartitionReducerImpl"/>
    <collector ref="MyPartitionCollectorImpl"/>
    <analyzer ref="MyPartitionAnalyzerImpl"/>
  </partition>
</step>

Обратитесь к Примеру phonebilling для примера реализации интерфейса PartitionMapper.

Элемент flow

Элемент flow может быть дочерним элементом элементов job, flow и split. Его атрибуты id и next. Потоки (flow) могут переходить к потокам (flow), шагам, разделителям и элементам принятия решения. Элемент flow может содержать следующие элементы:

Один или несколько элементов step
Один или несколько элементов flow (необязательно)
Один или несколько элементов split (необязательно)
Один или несколько элементов decision (необязательно)

Последний step в потоке (flow) — это тот, у которого нет атрибута next или элемента next. Шаги и другие элементы в потоке (flow) не могут переходить к элементам вне потока (flow).

Ниже приведён пример элемента flow:

<flow id="flowA" next="stepE">
  <step id="flowAstepA" next="flowAstepB">...</step>
  <step id="flowAstepB" next="flowAflowC">...</step>
  <flow id="flowAflowC" next="flowAsplitD">...</flow>
  <split id="flowAsplitD" next="flowAstepE">...</split>
  <step id="flowAstepE">...</step>
</flow>

Этот пример потока (flow) содержит три шага, один поток (flow) и один разделитель. Последний шаг не имеет атрибута next. Поток (flow) переходит на stepE, когда его последний шаг завершается.

Элемент split

Элемент split может быть дочерним по отношению к элементам job и flow. Его атрибуты id и next. Разделители могут переходить в разделители, шаги, потоки (flow) и элементы принятия решения. Элемент split может содержать только один или несколько элементов flow, которые могут переходить только к другим элементам flow в группе split.

Ниже приведён пример разделителя с тремя потоками (flow), которые выполняются одновременно:

<split id="splitA" next="stepB">
  <flow id="splitAflowA">...</flow>
  <flow id="splitAflowB">...</flow>
  <flow id="splitAflowC">...</flow>
</split>

Элемент decision

Элемент decision может быть дочерним для элементов job и flow. Его атрибуты id и next. Шаги, потоки (flow) и разделители могут переходить к элементу decision. Этот элемент указывает пакетный артефакт, который решает, какой следующий шаг, поток (flow) или разделитель выполнить, основываясь на информации из выполнения предыдущего шага, потока (flow) или разделителя. Пакетный артефакт реализует интерфейс Decider. Элемент decision может содержать следующие элементы:

Один или несколько элементов end (необязательно).

Этот элемент устанавливает статус пакета в COMPLETED.
Один или несколько элементов stop (необязательно).

Этот элемент устанавливает статус пакета в STOPPED.
Один или несколько элементов fail (необязательно).

Этот элемент устанавливает статус пакета на FAILED.
Один или несколько элементов next (необязательно).
Один элемент properties (необязательно).

Ниже приведён пример элемента decider:

<decision id="decisionA" ref="MyDeciderImpl">
  <fail on="FAILED" exit-status="FAILED_AT_DECIDER"/>
  <end on="COMPLETED" exit-status="COMPLETED_AT_DECIDER"/>
  <stop on="MY_TEMP_ISSUE_EXIST_STATUS" restart="step2"/>
</decision>