2 Invoking BPEL2oWFN
The standard invocation of BPEL2oWFN is:
bpel2owfn -i inputfile.bpel -f owfn -o
where inputfile.bpel is a BPEL process. The option
-f owfn cause BPEL2oWFN to generate an open workflow net. This
net is written to a file named inputfile.owfn, because of the option
-o. For more examples, see Examples.
BPEL2oWFN can be called without any parameter. In this case, it acts
as a parser for BPEL, 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 BPEL input from file filename.bpel.
If this parameter is omitted, input is read from standard input (
stdin
).
- --output[=filename]
- -o
- The generated files are 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.
- --bpel2pn
- This option makes BPEL2oWFN behave like its predecessor,
BPEL2PN: it generates a Petri net LoLA format and an
information file. The option --bpel2pn is a shortcut for
--mode=petrinet --format=lola --format=info --output.
2.1.1 Modes
When invoking BPEL2oWFN several modes are possible.
- --mode=modus
- -m modus
-
BPEL2oWFN supports four different modes for handling
BPEL, so modus can be one of the following options:
- 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.
- 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. Any
unnecessary attributes are omitted. This option is mostly used for debugging
reasons as it shows the implicit transformations and the identifiers of the
BPEL constructs.
Please note that you can only use at most one mode.
2.1.2 Additional parameters
These options control some Petri net-related options. See Petri Net-related Functions for more details.
- --parameter=par
- -p par
-
- simplify
- Structurally simplify the generated Petri net.
- finishloop
- Add an extra loop transition to the final place of the generated Petri net to
live-lock the system in order to find deadlocks.
- nostandardfaults
- When the parameter is set, only used-defined faults using the
<throw>
activity can occur.
- cyclicwhile
- When the parameter is set, the pattern for the
<while>
activity is
cyclic as depicted in Fig. 18 of [Sta05]. If the parameter is not set
(standard case), the pattern is acyclic: the activity embedded in the
<while>
activity is at most executed once, chosen non-deterministically.
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,
see File Formats for more information. There are invoked by the
following option:
- --format=fileformat
- -f fileformat
-
- apnn
- Create a Petri net in APNN (Abstract Petri Net Notation). Implies the
mode petrinet.
- dot
- Create a Dot representation of the structure generated in the current mode
which can be any kind of Petri net (mode petrinet).
- info
- Create an additional information file. Implies the mode petrinet.
- lola
- Create a LoLA place/transition net. Implies the mode
petrinet
.
- owfn
- Create a low-level oWFN in LoLA file format. Implies the
mode petrinet.
- pep
- Create a Petri net in low-level PEP notation. Implies the mode
petrinet.
- pnml
- Create a PNML Petri net. Implies the mode petrinet.
- xml
- Create an XML (Extensible Markup Lanuage) file. Implies the mode
pretty
.
If you want to use more than one output file format you have to add -f/
--fileformat to each file format. Please note that the underlying modes
of the given file formats are the same, i.e. you cannot create XML and
LoLA files together since XML uses the mode pretty
whereas LoLA uses the mode petrinet.
2.2 Examples
In this section we show some examples how BPEL2oWFN can be
invoked.
- bpel2owfn -i sample.bpel -flola -finfo -o -p simplify
-
Reads the file sample.bpel, generates a structural simplified
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 -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 -Tpng -osample.png
-
Runs the program prog and reads its output as BPEL
process, generates a Petri net and outputs its Dot representation.
This stream is read by Dot which layouts the Petri net and creates an output
PNG (Portable Network Graphic) file sample.png.
- bpel2owfn -i sample.bpel -m ast
-
Reads the file sample.bpel and prints the abstract syntax tree
(AST) to standard output.
2.3 Exit Values
When BPEL2oWFN is invoked and run without any error, the
exit value is 0.
- 0
- No error. The input file could be correctly opened, parsed and
the output file(s) could be generated without any error.
- 1
- Lexical or syntax error. This error occurs while lexing or
parsing the input file. It is thrown by the lexer or the parser,
resp. Usually the `source' of the error (i.e. the filename and line
number) is indicated together with the unexpected (last read) and
expected token.
An example:
Error while parsing
syntax error, unexpected X_SLASH, expecting X_OPEN
Error in `example.bpel' in line 12:
token/text last read was `/'
|
Please note that the indicated position (i.e. the line number) may
be fuzzy — it should be understood as a hint to the erroneous
line.
- 2
- `File not found' exception. The given input file was not found
resp. could not be opened.
An example:
An error has occurred while parsing "example.bpel"!
Exception #2 occurred!
File `example.bpel' not found.
|
- 3
- `File could not be opened' exception. An output file could not be opened
for write access. You may check the appropriate for the target directory or the
file if it already exists.
An example:
An error has occured while parsing "example.bpel"!
Exception #3 occured!
File "example.dot" could not be opened for writing access!
|
- 10
- Option mismatch. The given command-line options cannot be
processed together.
An example:
An error has occurred while parsing "example.bpel"!
An error has occured while parsing "<STDIN>"!
Exception #10 occured!
Choose only one mode
Additional information:
Type ./bpel2owfn -h for more information.
|
- 30
- `Dynamic cast error' exception. While building an internal scope
tree an unexpected error has occurred.
- 40
- Node not found.
- 41
- `Node already defined' exception. While generating the Petri net
a node was found having a history entry covered by another node
before.
An example:
An error has occurred while parsing "example.bpel"!
Exception #41 occurred!
Place with role `1.internal.final' already defined.
|
- 42
- `Merging error' exception. While generating the Petri net an
error occurred while merging two nodes. It happens either when one
of the nodes was not found or one of the nodes is a guarded
transition—the merging of guarded transitions is not yet
supported.
- 43
- `Arc error' exception. While generating the Petri net an error
occurred while adding an arc to the net. It happens either on type
errors — i.e. an arc between two transitions (or two places, resp.)
should be drawn — or when the source or target node of an arc was
not found.
Please report the occurrence of any exception with numbers 30–50
since it indicates a bug in BPEL2oWFN we would like to fix
immediately (see Reporting Bugs).