Next: , Previous: Introducing BPEL2oWFN, Up: Top



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:
images/rb1.png images/rb2.png
4
All reduction rules from -r3. Additionally, remove serial nodes:
images/ra1.png images/ra2.png
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.


Footnotes

[1] This mode was formally called consinstency.

[2] This mode was formally called communicationonly.

[3] Yasper is available at http://www.yasper.org.