2 Invoking BPEL2oWFN
The standard invocation of BPEL2oWFN is:
bpel2owfn -i service.bpel -m petrinet -f owfn -o
where service.bpel is a BPEL process. The option
-f owfn causes BPEL2oWFN to generate an open workflow net (option
-m petrinet). This net is written to a file named service.owfn, because of the option
-o.
BPEL2oWFN can be called without any parameter. In this case, it acts
as a simple parser for BPEL processes that reads its input from the
standard input (stdin
).
2.1 Options
BPEL2oWFN supports the following command-line options:
- --help
- -h
- Print an overview of the command-line options and exit.
- --version
- -v
- Print version information and exit.
- --input=filename.bpel
- -i filename.bpel
- Read a BPEL process from file filename.bpel.
If this parameter is omitted, input is read from standard input
(
stdin
). Wildcards such as process*.bpel are also allowed.
- --wsdl=filename.wsdl
- -w filename.wsdl
- Read a WSDL file to support the translation.
- --topology=filename.xml
- -t filename.xml
- Read a BPEL4Chor participant topology file to support the translation of BPEL4Chor choreographies. Can only be used with the choreography mode.
- --output[=filename]
- -o
- The generated output is written to a file called filename. If the short
form is used or the filename is omitted, the input file name is taken and
extended by the suffix of the chosen file format(s). If this parameter is
omitted, the output is passed to the standard output (
stdout
).
- --log[=filename]
- -l
- All additional information like warnings and processing information are
written to a file called filename. If the short form is used or the
filename is omitted, the output file name is taken and extended by the
suffix .log. If this parameter is omitted, the information is passed to
the standard error output (
stderr
).
- --debug=1-4 | flex | bison
- -d 1-4 | flex | bison
- This option triggers different debug levels, and can enable additional
information from Flex and Bison about how the input is lexed and parsed.
Debug level:
- 0
- When errors are found, only display the error code and skip additional
information.
- 1
- No debug information, but display warning and error messages. Furthermore,
detailled information about syntax errors are displayed.
- 2
- All messages from -d1. Additionally, information about the current
steps is displayed.
- 3
- All messages from -d2. Additionally, the structure of the process is
shown, i.e. when a Petri net is generated...
- 4
- All messages from -d3. Additionally, a message is displayed each time a
function is entered or left.
- flex
- Displays messages from Flex. Can be combined with any other debug level.
- bison
- Displays messages from Bison. Can be combined with any other debug level.
- --reduce=0-5
- -r 0-5
- Apply several structural reduction rules to the generated Petri net model
(implies mode petrinet or choreography). The rules preserve
deadlocks, livelocks and all deadlock-free communicating partners. The rules
are organized in reduction levels:
- 0
- No rules are applied (standard).
- 1
- Structural dead nodes are removed; that is, unmarked places with empty preset
and transitions with a dead place in its preset are removed.
- 2
- All reduction rules from -r1. Additionally, unnecessary status places
are removed. A status place is considered unnecessary if it has no outgoing
arcs.
- 3
- All reduction rules from -r2. Additionally, identical nodes are merged.
Two nodes are considered identical if their presets and postsets are equal:
- 4
- All reduction rules from -r3. Additionally, remove serial nodes:
- 5
- All reduction rules from -r4. Additionally, remove self-loop nodes.
2.1.1 Modes
When invoking BPEL2oWFN several modes are possible.
- --mode=modus
- -m modus
-
BPEL2oWFN supports different modes for handling input BPEL
files: modus can be one of the following:
- ast
-
Outputs the AST (abstract syntax tree) generated while
parsing the input file to standard output. This option is mostly
used for debugging reasons since it shows the implicit transformations
and the phylum names used when generating the Petri net.
- cfg
-
For control flow analysis (a form of static analysis) a CFG (Control
Flow Graph) is generated. It can be printed in graphical (dot)
representation. With the CFG, several design flaws of BPEL
processes such as cyclic control links or read access to uninitialized
variables can be detected statically. Furthermore, faulty constellations such
as conflicting receiving activities can be found using the cfg mode.
- choreography
-
The choreography mode1 is an extension of the petrinet mode. In the
choreography mode, several BPEL processes can be parsed, and a Petri
net model of their composition is generated.
For examples, check test/bpel4chor directory.
When combined with LoLA file output, an additional .task file
is generated. With the help of this file LoLA can check for weak
termination of the composition.
Note that the choreography mode is only tested with the small mode.
To support the translation of a BPEL4Chor choreography, a participant topology
can be additionally parsed using the topology parameter.
- petrinet
-
Generates a Petri net representing the semantics of the given
process. Other options can be added to simplify or modify that generated Petri
net (see below).
- pretty
-
Outputs the parsed BPEL file in XML representation. This
option is mostly used for debugging reasons as it shows the implicit
transformations and the identifiers of the BPEL constructs.
At most one mode can be selected. If no mode is given, BPEL2oWFN acts like
a plain BPEL parser; that is, the input file is read, but no output
is generated.
2.1.2 Additional parameters
These options control some Petri net-related options.
- --parameter=par
- -p par
-
- small
-
With the small parameter2, only the communicational behavior of the input BPEL process is
modeled. That is, the negative control flow (fault, termination, or compensation handlers, as well as
<exit>
, <throw>
, <compensate>
, <compensateScope>
activities) is not translated to
the Petri net model. When combined with reduce, this parameter yields
the most compact Petri net model.
- fhfaults
-
Confines the standardfaults parameter: in the negative control flow
(in activities in fault handlers), no further BPEL standard faults
can occur.
- nointerface
-
When creating a .dot file, no interface is printed.
- reduce
-
Apply all implemented structural reduction rules. This parameter is a shortcut
for -r5 and overrides any other defined reduction level.
- standardfaults
-
Model the occurrence of standard faults. When this parameter is ommited, only
user-defined faults, that is, faults thrown with
<throw>
activities, and
join failures can occur. With the standardfaults parameter, also the
occurrence of other BPEL standard faults is modeled. This parameter
yields the most-detailled, and thus biggest Petri net model.
- variables
-
Add places for the variables of the input BPEL process to the Petri
net model. As the generated model abstracts from data, that is, a low-level
Petri net is generated, the variables parameter also does not introduce
data aspects. Thus, this mode is experimental.
If you want to enable more than one parameter you have to add -p/
--parameter to each parameter.
2.1.3 Output formats
Especially for the Petri net mode, a variaty of output formats are supported. There are invoked by the
following option:
- --format=fileformat
- -f fileformat
-
Creates a file in a given ouput file format. Each file format is only available in
certain modes. If you want to use more than one output file format you have to add -f/
--format to each file format. Please note that the underlying modes
of the given file formats are the same. You cannot, for example, create XML and
LoLA files together since XML requires the mode
pretty, whereas LoLA requires the mode petrinet.
- Petri net file formats (imply mode petrinet or choreography):
-
- apnn
- Outputs the inner of the generated open workflow net in
APNN (Abstract Petri Net Notation). When the parameter -o is
used, a file with the suffix .apnn is created.
- ina
- Outputs the inner of the generated open workflow net as untimed low-level
Petri net in INA (Integrated Net Analyzer) format. When the parameter
-o is used, a file with the suffix .pnt is created.
- lola
- Outputs the inner of the generated open workflow net as low-level Petri net in
LoLA (Low-Level Analyzer) file format. When the parameter -o
is used, a file with the suffix .lola is created.
- owfn
- Outputs the generated open workflow net in Fiona file format. Note that the
Fiona file format is — together with the PNML file format — the
only Petri net output format that outputs the complete open workflow net, that
is, also the interface is exported. When the parameter -o is used, a
file with the suffix .owfn is created.
- pep
- Outputs the inner of the generated open workflow net as low-level Petri net in
low-level PEP notation. When the parameter -o is used, a
file with the suffix .llnet is created.
- pnml
- Outputs the generated open workflow net in PNML (Petri Net Markup
Language). Note that the PNML file format is — together with the
Fiona file format — the only Petri net output format that outputs the
complete open workflow net, that is, also the interface is exported.
Currently, the interface places are annotated using a
<type>
tag
which is only supported by Yasper3. When the parameter -o is used, a
file with the suffix .pnml is created.
- spin
- Outputs the inner of the generated open workflow net as low-level Petri net in
Promela (Process Meta Language) for the model checker SPIN. When the parameter
-o is used, a file with the suffix .spin is created.
- Other file formats (note the required mode):
-
- dot
- When mode petrinet is used, the generated open workflow net is printed
in Graphviz dot representation. When mode ast is used, the
AST (abstract syntax tree) is printed in Graphviz dot representation.
When mode cfg is used, the CFG (control flow graph) is printed
in Graphviz dot representation.
In any case, when the tool dot
is found in the search path during
configuration of BPEL2oWFN and the parameter -o is used,
dot
is used to generate a PNG (Portable Network Image) file.
In this case, two files with the suffixes .dot and .png are
created. Note that when the ast mode is used with the dot file
format, the -o parameter has to be used.
- info
- When mode petrinet is used, information about the places and
transitions of the generated net in a
proprietary ASCII-based format. For each place and transition, all
roles, that is, inscriptions of the Petri net patterns, are listed. The
information can be used to correlate the generated Petri net model with the
input BPEL process. When the parameter -o is used, a file
with the suffix .info is created.
- xml
- When the mode pretty is used, the pretty-printed input BPEL
process — with the implicit transformation rules applied – exported in
XML (Extensible Markup Lanuage). When the parameter -o is
used, a file with the suffix .xml is created.
2.2 Exit Values
- 0
- No error occurred.
- 1
- A critical error occured; that is, a fault was detected that makes further processing
impossible.
- 2
- An input file could not be opened.
- 3
- A syntax error in the input BPEL occurred. The input file cannot be
further processed.
- 4
- Any other error.
2.3 Examples
In this section we show some examples how BPEL2oWFN can be invoked. See File Formats
for more examples.
- bpel2owfn -i sample.bpel -m petrinet -f lola -f info -o -p reduce
-
Reads the file sample.bpel, generates a structural reduced
low-level Petri net and saves it in a LoLA file
sample.lola. For further information a file
sample.info is generated.
- bpel2owfn -i sample.bpel -mpetrinet -fowfn -d3 -o
-
Reads the file sample.bpel, generates a low-level open
workflow net and saves it in an oWFN file
sample.owfn. For further information a file
sample.info is generated. During the conversion several debug
messages are printed to standard output.
- prog | bpel2owfn -fdot -m petrinet | dot -Tps -osample.ps
-
Runs the program prog and reads its output as BPEL
process, generates a Petri net and outputs its Graphviz dot representation.
This stream is read by
dot
which layouts the Petri net and creates an output
PostScript file sample.ps.
- bpel2owfn -i sample.bpel -m ast
-
Reads the file sample.bpel and prints the abstract syntax tree
(AST) to standard output.
- bpel2owfn -m choreography -i service1.bpel -i service2.bpel -f lola -o
-
Reads the files service1.bpel and service2.bpel and creates
a Petri net model of their composition. The result is written to the
LoLA file service1_service2.lola. Furthermore, an analysis
file service1_service2.task is written that can be processed by
LoLA.
Further examples for invocations of BPEL2oWFN can be found in the tests directory of the source distribution.