RE: JESS: Design and Documentation of Declarative Programs (was Jess and UML)
For our current project, my team cobbled together a tool that reads in each Jess rules module and writes out source for a trivial java class which has one do-nothing method for every rule. We copy the Jess documentation comment for each rule into a JavaDoc style comment on its surrogate method. Once we have something that looks like normal Java documentation, we can import the rule comments into our Rational Rose design model using their standard Java reverse engineering tools. This allows us to extract documentation from Jess that superficially looks like the low-level documentation we extract from our Java code. While everything in this low-level documentation may be accurate, it provides very little insight into how sets of rules interact at the higher levels. With our Java OO code, we normally supplement the Java Doc comments with various UML diagrams to show how objects retain associations with each other and how sequences of method calls build up to higher level functionality. None of the normal UML diagrams seems to describe the overall flow of our ruleset very well. All of our attempts to describe the large scale operation of the rules in UML feel forced, and contain so many approximations and omissions that we fear they may be doing more harm than good. I am trying to question several of my basic assumptions here, and would appreciate any insights from people who have had to document and maintain medium to large rule based systems. 1) Is there a good way to document a rulebased system in UML that I am just not seeing? 2) Is there a non-UML methodology that better describes the top-level structure of a rule-based system? 3) Is software based on pure declarative programming ideally lacking in top level structure? The existence of rule modules and salience levels seem to impose some structure on the software. These features of the Jess language may break down the purity of the declarative programming style, but they seem necessary. -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of friedman_hill ernest j Sent: Friday, June 23, 2006 9:23 PM To: jess-users@sandia.gov Subject: Re: JESS: Design and Documentation of Declarative Programs (was Jess and UML) I think James Owen wrote: JavaDoc ... XML ... Perl script ... chapter 20 in JIA book All worthy ideas, but I should point out the official mechanism, the documentation comment, which every Jess rule, function, template, etc. can have: (defrule rule-name This is a documentation comment. It can contain arbitary text and span multiple lines. ... These comments get stored in the Java representation of the Jess construct and are available at runtime via a method named getDocstring() in the Defrule, Deftemplate, Deffunction, etc, classes. So you can use the Jess parser to parse Jess code, then ask each construct for its own documentation. - Ernest Friedman-Hill Advanced Software Research Phone: (925) 294-2154 Sandia National LabsFAX: (925) 294-2234 PO Box 969, MS 9012 [EMAIL PROTECTED] Livermore, CA 94550 http://herzberg.ca.sandia.gov To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED] To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED]
JESS: Design and Documentation of Declarative Programs (was Jess and UML)
I am reluctant to say it can not be done, but so far I have been unable to find or produce an example of how UML can be used to effectively describe the design of a large declarative program. My software team is pretty comfortable with the use of UML to aid in the up front design and final documentation for most of our software, but UML has not been a good fit to the Jess code in our design. UML does well at describing data structures like fact templates, and can do a passable job at describing any individual rule in isolation. I have not found any UML constructs that serve well to describe how groups of rules are organized or what kind of high level behavior emerges from the low level interaction of the rules. If someone else has to pick up the maintenance of this program a few years from now, they are going to want some description of the program organization and emergent behavior. Has anyone else seen or developed an effective way to use UML to document a rule base design? If not, what alternate types of design documentation have people found effective for documenting a rule based design? -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of Scott Moss Sent: Thursday, June 22, 2006 1:48 AM To: jess-users@sandia.gov Subject: RE: JESS: Jess and UML Could the problem be that UML describes both OO program structures and procedures whereas, with declarative programming, the procedures emerge at runtime? On Wed, 2006-06-21 at 22:49 -0400, Steven Goncalo wrote: Turning the original question inside out, has anyone ever seen a good example of how to describe a rule based system in UML? All of my team's attempts to manually produce a set of UML diagrams to document what the rule based part of our system was doing have been disappointing. The diagrams tended to show how various subsets of the rules might have worked if rephrased as procedures. An automatic round-trip tool between UML and Jess rules would be great, but the first step would be to establish a good mapping between the two domains, which I have not yet seen. -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] On Behalf Of friedman_hill ernest j Sent: Wednesday, June 21, 2006 10:32 AM To: jess-users@sandia.gov Subject: Re: JESS: Jess and UML I think Matthew J Hutchinson wrote: [Charset iso-8859-1 unsupported, filtering to ASCII...] Is it possible to convert a design in UML into a structure in JESS, using facts? *Everything* is possible -- that's what makes life interesting! Now, the question really is: does a tool which does what you ask already exist? And I think the answer is no. There are tools for converting other kinds of designs into Jess code: ontologies in Protege or OWL, for example. But not UML, to the best of my knowledge. - Ernest Friedman-Hill Advanced Software Research Phone: (925) 294-2154 Sandia National LabsFAX: (925) 294-2234 PO Box 969, MS 9012 [EMAIL PROTECTED] Livermore, CA 94550 http://herzberg.ca.sandia.gov To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED] To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED] To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED] To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED]
Re: JESS: Design and Documentation of Declarative Programs (was Jess and UML)
Steven: Some BRMS (Business Rule Management System - fancy way to say rulebase) use rulebase documentation much like JavaDoc and export to XML - MS Word - etc. It shouldn't be too terribly difficult to write a Perl script to go through the rules, pick out the /** begin and */ end commands to use for rule documentation. Also, you can use XML (see chapter 20 in JIA book) to expresss the rules in XML. Comments for documentation purposes can be used there as well. Actually, I remember (way back in 2000) that Arun Indurti did a Perl Script to build rules from a CSV file generated from a spreadsheet and Eric Charpentier did the (was it Perl?) script that allowed us to generate documentation using Java Doc /** */ comments in ILOG JRules. Both on the same monstrous Bell South project. SDG jco Steven Goncalo wrote: I am reluctant to say it can not be done, but so far I have been unable to find or produce an example of how UML can be used to effectively describe the design of a large declarative program. My software team is pretty comfortable with the use of UML to aid in the up front design and final documentation for most of our software, but UML has not been a good fit to the Jess code in our design. UML does well at describing data structures like fact templates, and can do a passable job at describing any individual rule in isolation. I have not found any UML constructs that serve well to describe how groups of rules are organized or what kind of high level behavior emerges from the low level interaction of the rules. If someone else has to pick up the maintenance of this program a few years from now, they are going to want some description of the program organization and emergent behavior. Has anyone else seen or developed an effective way to use UML to document a rule base design? If not, what alternate types of design documentation have people found effective for documenting a rule based design? -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]] On Behalf Of Scott Moss Sent: Thursday, June 22, 2006 1:48 AM To: jess-users@sandia.gov Subject: RE: JESS: Jess and UML Could the problem be that UML describes both OO program structures and procedures whereas, with declarative programming, the procedures emerge at runtime? On Wed, 2006-06-21 at 22:49 -0400, Steven Goncalo wrote: Turning the original question inside out, has anyone ever seen a good example of how to describe a rule based system in UML? All of my team's attempts to manually produce a set of UML diagrams to document what the rule based part of our system was doing have been disappointing. The diagrams tended to show how various subsets of the rules might have worked if rephrased as procedures. An automatic round-trip tool between UML and Jess rules would be great, but the first step would be to establish a good mapping between the two domains, which I have not yet seen. -Original Message- From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED]] On Behalf Of friedman_hill ernest j Sent: Wednesday, June 21, 2006 10:32 AM To: jess-users@sandia.gov Subject: Re: JESS: Jess and UML I think Matthew J Hutchinson wrote: [Charset iso-8859-1 unsupported, filtering to ASCII...] Is it possible to convert a design in UML into a structure in JESS, using facts? *Everything* is possible -- that's what makes life interesting! Now, the question really is: does a tool which does what you ask already exist? And I think the answer is "no." There are tools for converting other kinds of designs into Jess code: ontologies in Protege or OWL, for example. But not UML, to the best of my knowledge. - Ernest Friedman-Hill Advanced Software Research Phone: (925) 294-2154 Sandia National LabsFAX: (925) 294-2234 PO Box 969, MS 9012 [EMAIL PROTECTED] Livermore, CA 94550 http://herzberg.ca.sandia.gov To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED]. To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED]. To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify
Re: JESS: Design and Documentation of Declarative Programs (was Jess and UML)
I think James Owen wrote: JavaDoc ... XML ... Perl script ... chapter 20 in JIA book All worthy ideas, but I should point out the official mechanism, the documentation comment, which every Jess rule, function, template, etc. can have: (defrule rule-name This is a documentation comment. It can contain arbitary text and span multiple lines. ... These comments get stored in the Java representation of the Jess construct and are available at runtime via a method named getDocstring() in the Defrule, Deftemplate, Deffunction, etc, classes. So you can use the Jess parser to parse Jess code, then ask each construct for its own documentation. - Ernest Friedman-Hill Advanced Software Research Phone: (925) 294-2154 Sandia National LabsFAX: (925) 294-2234 PO Box 969, MS 9012 [EMAIL PROTECTED] Livermore, CA 94550 http://herzberg.ca.sandia.gov To unsubscribe, send the words 'unsubscribe jess-users [EMAIL PROTECTED]' in the BODY of a message to [EMAIL PROTECTED], NOT to the list (use your own address!) List problems? Notify [EMAIL PROTECTED]
