fsmGenerate.py -- FSM/REST Application Generator

---

 
Front Matter

Copyright (c) 2003 Dave Kuhlman

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Abstract:

Contents

• Front Matter
• 1. Introduction
• 2. What It Does
  • 2.1 FSM and REST -- Application Structure
  • 2.2 Output -- What fsmGenerate.py Generates
• 3. How to Use It
  • 3.1 Create an Application Description Document
  • 3.2 Run fsmGenerate.py
• 4. What To Do with The Generated Code
  • 4.1 The XML Schemas and what to do with them
  • 4.2 The FSM/REST/Quixote state modules and what to do with them
  • 4.3 The wxGlade definition file and what to do with it
  • 4.4 Implementing a client
• 5. Future Work
  • 5.1 Business process markup language
  • 5.2 Alternative URIs
• 6. Software Requirements
• End Matter
  • Acknowledgements and Thanks
• About this document ...

 
1. Introduction

fsmGenerate.py can produce:

• State definition modules -- These Python modules needed to implement a Quixote application. One module is generated for each state in the FSM. Each generated module contains a class that implements the state.

• A __init__.py file -- This file implements the dispatcher for the application. It takes the current state name and calls the implementation of that state.

• A states.py file -- This file contains a dictionary which maps state names to state implementation.

• XML Schema files -- One file is generated for each state in the FSM. And, these XML Schema files are used to generate a python parser and Python classes that represent the XML documents and the elements in them.

• A GUI definition file -- A definition file for a graphical user interface which can be edited with wxGlade, which can also generate Python code that implements the user interface. This code can be used in the implementation of client applications.

And, optionally fsmGenerate.py will package the entire generated application into a .zip file that can be imported (by Python 2.3).

 
2. What It Does

fsmGenerate.py generates an FSM/REST application for the Quixote Web application server. For more information on FSM/REST see REST and FSM and BP for Quixote How-to.

2.1 FSM and REST -- Application Structure

fsmGenerate.py generates source code for an FSM/REST web application. The application is a skeleton in the sense that code implementing the special behavior of each state must be added by hand. (Note for future work: The FSM/REST application is generated from an XML document that describes the FSM. It may be possible to ``enrich'' that document so that it contains implementations of behaviors that implement actions and conditions used by each state.)

The application is structured as an FSM (finite state machine). This means that each request from a client provides input values that are used by the application (the current state in particular) to determine and perform a transition. Performing the transition causes the FSM to execute an action and select a new current state.

The application is a REST (representation state transfer) application. This means, among other things, the following:

• Each request has a name, i.e. a URI.

• Each request is a request for the representation of a resource.

• State (session information) is maintained by the client, not the server.

The server and the client communicate with each other by passing XML documents back and forth. The definition of the XML interchange document is specific to each state in the FSM. For each state, fsmGenerate.py generates an XML Schema definition which describes the XML interchange document for that state. In addition, generateDS.py is used to translate the XML Schema document input Python code that implements a parser for the XML interchange document and classes that represent the elements defined by the XML Schema document.

The generated implementation is structured as a Python package (a directory containing a __init__.py file). The package contains a module (a Python .py file) for each state in the FSM. Each of these ``state'' modules contains a class that implements the state.

 
2.2 Output -- What fsmGenerate.py Generates

fsmGenerate.py generates a directory, which, because it contains a __init__.py file, is a Python package.

This package will contain, depending on the command-line options given to fsmGenerate.py and used to generate it, the following:

• An __init__.py file containing a dispatch function containing a function that maps the current state name to the implementation for that state.

• A Python module for each state in the FSM. This module implements the state.

• An XML Schema document for each state. This Schema defines the XML interchange document for that state used by the server and the client to pass information back and forth.

• Python modules generated from the XML Schema document for each state which can be used to parse and access XML interchange documents of that type.

• An input file for wxGlade that describes the skeleton of a graphical user interface (GUI) for each state. This user interface definition can be edited and used, by wxGlade to generate Python code that implements a wxPython user interface.

 
3. How to Use It

This section describes a suggested sequence of steps to be followed in using fsmGenerate.py.

 
3.1 Create an Application Description Document

You must create an FSM-XML document that describes your application. This FSM-XML document is used as input to fsmGenerate.py, which uses it to create the application and a client user interface (GUI).

The FSM-XML document contains elements that describe each state in the FSM. The distribution (fsmGenerate_examples.zip) contains an XML Schema (fsm.xsd) that describes the FSM-XML document type. There is also a sample document (fsm_plants.xml). Here is a brief description of the elements in that document:

fsm -- The wrapper element for the whole document. Contents:

• name -- The descriptive name for the FSM.

• lastmodified -- The date (and possibly time) of the last edit.

• description -- Descriptive comments.

• currentstate -- If a snapshot of a running FSM were saved, this would contain the name of the current state.

• startstate -- The name of the state which is the first state entered when running the FSM.

• endstates -- A list of the names of the ``end'' or ``finish'' states.

• state -- Description of a single state in the FSM. Occurs multiple times.

state -- Contents:

• name -- The name of the state.

• pagename -- A name for the page returned to the client.

• transition -- A possible transition to a new state. Each transition contains a condition. The FSM engine tests the condition of each transition in turn. The first condition that evaluates to True is selected. The engine then executes the action in that transition and makes the state specified in that transition the new current state. Occurs multiple times.

• inputs -- A list of the input values submitted by the client to the FSM/REST Web application. These values may be used in the conditions and as parameters to the action. The graphical user interface (GUI) definition file generated for use with wxGlade contains graphical controls for data entry for these input items.

• classcode -- The text/content in this element is added to the end of the class that is generated to implement this state. A typical use for this is to provide an implementation for methods referenced in the condition or action in a transition. You will have to adjust the indentation so that the code is in the scope of the class.

• globalcode -- The text/content in this element is generated above and outside the implementation of the class that implements this state. A typical use for this is to provide an implementation for (global) functions, constants, etc referenced in the condition or action in a transition.

transition -- Contents:

• id -- An identifier for the transition.

• condition -- A Python expression to test whether to use this transition. If the condition returns a True value, then this transition is selected.

• action -- A action to be performed if this transition is selected. Should be a Python expression.

• newstate -- The name of the state that will become the next current state if this transition is selected.

inputs -- Contents:

• field -- An input item. Occurs multiple times.

field -- Each field results in the generation of a graphical user interface (GUI) control in the .wxg file generated for wxGlade. Contents:

• name -- The name of the field or variable.

• label -- A descriptive label. Used to generate a label for the client's GUI.

• defaultvalue -- The default value if the client does not provide a value. Also used as the default value in the client's GUI.

• controltype -- The GUI control type for the generated client's user interface.

• tooltip -- A tooltip for the client's user interface.

 
3.2 Run fsmGenerate.py

Run fsmGenerate.py to produce the application and support code. You can find fsmGenerate.py in the distribution file: fsmGenerate_examples.zip.

Here is the ``help'' message from fsmGenerate.py:

fsmGenerate -- Generate Quixote application skeleton, wxGlade GUI
    definition, and X Schema definitions for FSM REST Web application.
Usage:
    python fsmGenerate.py [options] <in_file_name> <out_name>
Options:
    -h, --help      Display this help message.
    -a, --app       Generate Quixote application skeleton.
    -g, --gui       Generate .wxg file for client-side GUI.
    -s, --schema    Generate .xsd X Schema files for XML interchange docs.
    -z, --zip       Zip into PyZipFile.
Example:
    python -a -g -s -z fsmGenerate.py myapp1

And, here is a description of the options:

• -a, -app -- Generate Quixote application skeleton. This option generates a Python package which contains:
  • __init__.py -- In addition to marking the directory as a Python package, this module contains the dispatcher to the implementation for individual states.

  • state.py -- Contains the implementation of the superclass State.

  • For each state in the FSM, a module that implements the state. The module contains a class which is a subclass of class state and which implements the state. The name of the module is the same as the state name.

• -g, -gui -- Generate a .wxg file for the client-side GUI. This file can be loaded into wxGlade, a visual user interface editor, and manipulated to produce graphical user interfaces that can be presented to the end-user so that the end-user can enter input to be submitted by the client to the FSM/REST application. wxGlade can generate an executable Python implementation of the user interface.

• -s, -schema -- Generate .xsd X Schema files for XML interchange documents. Generates one XML Schema document for each state. Each schema describes elements needed to carry (1) state information such as the current state name and the URI of the application and (2) the input variables. fsmGenerate.py also uses generateDS.py to generate Python code that can parse and that represent the elements in the XML interchange documents. These Python files can be recognized because of their names: *sup.py and *sub.py.

• -z, -zip -- Zip into PyZipFile. This option creates a .zip file containing all the generated files plus .pyc files for the Python modules. Modules in this Zip file can be imported by Python (new in Python 2.3).

 
4. What To Do with The Generated Code

Because modifying and extending the code generated by fsmGenerate.py depends so much on your application and your needs, this section can at most contain guidelines. However, I'll at least try to offer suggestions on where to put things and how to use the generated code.

 
4.1 The XML Schemas and what to do with them

First, let's make clear what they are. The generated .xsd files describe the XML documents that are passed back and forth between an FSM/REST server and a client. Thus, from the client's point of view, the client must generate an XML document that satisfies the X Schema for the current state and submit that document as the content of the client's request. Likewise, from the client's point of view, the client will receive an XML document from the the server as the result of a request. From the server's point of view, the server will receive (and must parse) a document whose contents are described by the XML Schema for the current state. And, also from the server's point of view, the server must generate an XML document that satisfies the XML Schema for the current state as the representation of the resource for the current request.

Note that these modules generated by generateDS.py are there to help you but are not strictly necessary. Any of a variety of other methods for processing the XML interchange documents with Python could be used. Some examples are (1) using Python's DOM or minidom support and (2) using David Mertz's Gnosis tools (see the ``See Also'' section, below).

fsmGenerate.py helps you process the XML interchange documents by using generateDS.py to produce code that can parse a state specific XML interchange document and then access the elements in that document. It does this by loading the XML document into instances of (generated) Python classes that represent the elements.

For a given state ``X'', fsmGenerate.py produces the following files:

• X.xsd -- The XML Schema for XML the interchange document for state X.

• Xsup.py -- A Python module containing the class definitions for each of the elements in the XML interchange document for state X. These classes are described by the documentation for generateDS.py. Of particular interest are (1) the getter and setter methods and (2) the export function (which can be used to generate the XML document.

• Xsub.py -- A Python module containing sub-classes of the class definitions in Xsup.py. You can extend the functionality of the classes in Xsup.py by adding methods to these subclasses. In addition, Xsub.py contains a parseString function that can be used to parse an XML document and create intances of the Python classes that represent them.

Here is an example of code that uses a sample module to parse and XML interchange document and then to extract an input value from it:

import Xsub
    o
    o
    o
doc = Xsub.parseString(content)
value = doc.getFsminput().getArg1()

And, here is another example. This one sets a value in the interchange document structure, then uses that structure to generate XML content:

import Xsub
import StringIO
    o
    o
    o
doc = Xsub.parseString(content)
value = doc.getFsminput().getArg1()
    o
    o
    o
doc.getFsmoutput().setContent(someNewContent)
contentStream = StringIO.StringIO()
doc.export(contentStream, 0)
newContent = contentStream.getvalue()
contentStream.close()
#
# Do something with newContent.
#

 
4.2 The FSM/REST/Quixote state modules and what to do with them

For each state named ``X'' in the FSM XML specification file, fsmGenerate.py generates a file named X.py. You can add application specific code to each of these Python modules.

Here is an example -- a generated module that implements a state named ``Plant'':

# Plant.py
#

from states import State

class Plant(State):
    def __init__(self, doc):
        State.__init__(self, doc)
    def _q_index(self, request):
        nextState = None
        # Transition tr_plant_1
        if compareArg(arg1, "fruit"):
            nextState = 'Fruit'
            action2()
        # Transition tr_plant_2
        if compareArg(arg1, "vegetable"):
            nextState = 'Vegetable'
            action3()
        self.doc.setFsmcurrentstate(nextState)
        content = self.generateContent()
        self.setXmlResponse(request)
        return content

Here are some things you will need to do to this generated code:

• Add any initialization code you need to the __init__ constructor method.

• There is code in the condition that must be implemented. In our example above, the function compareArg needs an implementation. Note that this condition was copied from the XML FSM specification document.

• There are actions that need to be implemented. In our example, the functions action2 and action3 need implementations.

 
4.3 The wxGlade definition file and what to do with it

The generated file has the name gui.wxg.

Start up wxGlade and then open this file.

This file contains a number of dialog/frame definitions, one for each state in the FSM. From within wxGlade, you can modify these dialog definitions, then use wxGlade to generate Python code that implements the dialogs. If you do not change the name of the output, it will generate a Python file/module named gui.py.

 
4.4 Implementing a client

You will want to implement a client. I'm going to assume that you will do this in Python. If you want to implement your client in some other programming language, you will have to do a bit of translation of my guidance.

The distribution contains a minimal example of a client: client.py. There are more client examples in the fsm examples file, which are described in http://www.rexx.com/ dkuhlman/fsm_howto.html.

Here are a few comments and guide-lines:

• You are likely to want to use httplib from the Python standard library to submit requests to the FSM/REST server application.

• For ``Content-type'' use ``text-xml''.

• In order to parse content received from the FSM/REST server, import the *sub module for the current state. Then, use the parseString function to parse the content received from the server.

• In order to generate content to be submitted to the server, import the *sub module for the new current state. Then, (1) create an instance of the root object and populate that structure and (2) use the export method in the root object to generate content to be submitted to the server.

If your client talks to a warm body and you want that end-user to be able to enter input values into a graphical user interface, then you may want to use the ``- -gui'' option and then work with the generated .wxg file. Here are a few suggestions:

• wxGlade can be used to edit the user interfaces defined in the .wxg file and then to generate Python code that implements a graphical user interface.

• The .wxg file generated by fsmGenerate.py contains a separate user interface for each state in the FSM.

• You can change the name of the generated Python from within wxGlade.

• You can add your own code to the Python module generated by wxGlade. Your added code will be preserved when you re-generate the Python module with wxGlade. You will need to read the wxGlade documentation and pay attention to comments in the generated file. These comments indicate where it is safe to place your additional code.

 
5. Future Work

 
5.1 Business process markup language

It would be helpful if we could capture FSM XML files from a BPML. We might even consider modifying fsmGenerate.py (actually, the underlying fsmgenapp module) so that it could read the BPML directly.

Another possibly approach would be to take a UML diagram editor such as PyUt, and modify it so that it can export our FSM XML documents. I am investigating that one. I'll have to resolve the following questions, at least:

• Is UML a reasonable or appropriate representation for our purposes? For example, is there a reasonable mapping from XMI (an XML representation for UML) to FSM-XML?

• Does PyUt support the features of UML that we need? UML has a variety of different diagrams. State transition diagrams seem to provide the closest fit to what we need. Does PyUt support them?

• Is PyUt reasonably extensible? It's written in Python -- a good sign. Here are several types of extensions that we might investigate:
  • Extend the export capability so that PyUt exports FSM-XML directly, in stead of forcing us to export to XMI, then translate that to FSM-XML.

  • Extend the diagram editor to support state transition diagrams.

Requirements and desirables -- What would make this usable and valuable? Remember that our goal is to connect BPs to FSMs, i.e. to implement BPs on the Web with FSM/REST.

• Ability to create and edit a BP visually. A good first guess is that we would want to be able to visually edit state transition diagrams (STDs), because they would very likely map most cleanly onto FSM STDs.

• Ability to import BP specifications -- Basically, this means being able to translate a BP XML document of some type into FSM-XML.

• A well-defined and understandable BPML (business process markup language) -- I'll be looking at UML, because it seems to have some industry support. However, the Web services movement may be driving some groups of companies toward other standards (e.g. epBPML, WSFL, ebPML, WSCI, etc.).

 
5.2 Alternative URIs

The examples discussed in this document pass the current state name between the server and the client by including that state name in the XML interchange document. Doing so makes things a bit awkward because (1) you need the current state name in order to determine which parser to use and (2) before you can determine the current state name (and thus the document type), you must at least partially parse the document.

This means that you have to use something like SAX or a regular expression to partially parse the document and obtain the state name and, then use the generated parser to parse the document. (The generated code and the sample client (client.py) use a regular expression.)

A possibly more convenient approach might be to pass the current state as part of the URI. This would solve the problem for the server, though not for the client.

 
6. Software Requirements

In order to use fsmGenerate.pyyou will need several software packages. See the "See Also" section for links to these packages.

• Python 2.2 or later.

• Quixote 0.6 or later.

• generateDS.py.

• wxGlade and wxPython -- These are needed if you intend to use the client user interfaces generated with the ``- -gui'' option.

 
End Matter

Acknowledgements and Thanks

Thanks to the implementors of Quixote for producing an exceptionally usable application server that is so suitable for REST.

Thanks to Alberto Griggio <[email protected]> for wxGlade.

About this document ...

This document was generated using the LaTeX2HTML translator.

LaTeX2HTML is Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The application of LaTeX2HTML to the Python documentation has been heavily tailored by Fred L. Drake, Jr. Original navigation icons were contributed by Christopher Petrilli.

---

fsmGenerate.py -- FSM/REST Application Generator

---

Release 1.00, documentation updated on Mar. 28, 2003.