Home

News: Linguine Maps visualization for Ant, XML DTD, Hibernate, OJB

  1. Linguine Maps 1.1 has been released. This is an open-source utility that can automatically produce UML-style entity-relation diagrams from Ant build files, XML DTD, Hibernate mapping files, and Object relational bridge (OJB) mapping files.

    The intent of the tool is to graphically show a given DTD, XML schema, or object-relational mapping, generated from XML (or, in the case of a DTD, a DTD).

    There's an online installation, as well as a gallery of example graphs. In addition, the download can be used to generate custom graphs.

    The specific filetypes supported, with the type of graph generated, are:
    • Apache ANT build files (task dependency diagrams)
    • Document Type Definition (DTD) for XML documents (entity relationships and attributes)
    • Apache ObJectRelationBridge (OJB) mapping files (UML-style class diagrams)
    • Hibernate mapping files (UML-style class diagrams)

    Threaded Messages (23)

  2. Purpose[ Go to top ]

    Is this tool purely for documentation and communication purposes ? I'm interested to know the level of detail one can expect from the generated UML model, sometimes technical people will want to see a slightly different diagram than the client with whom business requirements/specifications are discussed .. is there anything like this planned or is the tool targetted to development teams only ?

    Also: is there a way to customize the generated output, via templates or something ?

    -- Wouter
  3. Purpose[ Go to top ]

    Thank you for trying things out.

    The purpose behind Linguine Maps is to automate documentation and improve communication! In a dev shop we asked a lot by business people for the pictures and the diagrams. We were tired of doing them by hand…

    Another reason is even more important. Many junior/senior developers on the team did not really know in depth schemas for Hibernate of OJB or even Ant. They can’t really read XML. The UML-style drawing from Linguine Maps brings all team members to the same page. No one has to read full Hibernate spec. to be aware of our object models!

    I tried to do my best for all the diagrams to resemble UML and be readable without training by both developers and smart business folks. Works great! Lots can be improved, but it is a great step forward in eliminating huge amount of tedious manual work
  4. Purpose[ Go to top ]

    Many junior/senior developers on the team did not really know in depth schemas for Hibernate of OJB or even Ant. They can’t really read XML. The UML-style drawing from Linguine Maps brings all team members to the same page. No one has to read full Hibernate spec. to be aware of our object models!
    Huh? From what moment someone needs to read Hibernate spec to be aware of object models?
    Hibernate is a glue level between Object Model and DB Schema ( rather straightforward in many cases if DB schema is good). It looks like that team cripple Object Model to whatever hbm2java generates and that is troublesome IMO.

    And please do not forget that there are supposed to be ERD diagrams for the database, which might be in some cases quite different than Class Diagrams. ERD and Class diagrams are supposed to be primary resources and hibernate mapping is just that: mapping. In some cases it does not work well and then Hibernate allows escaping into native SQL.
  5. Purpose[ Go to top ]

    I am quite aware that ERD diagrams are different from Class Diagrams. But what to do if Hibernate schema or Ant build file structure does not precisely fit into existing UML diagram class? We approximate... If you do not like the kinds of diagrams come out of hbm2java – change it! And draw the kind you think make sense for your team or for you!

    Linguine Maps makes it simple to visualize! It provides simple object-oriented Java API for visualization of any kind of graphs. Many other tools are focused on visualization of one kind of schema. Linguine Maps was designed to be reusable for visualization of graphs in general – any graphs that come to mind.

    To rephrase: it takes long time for people to go into the source code to get an overview. It takes long time to learn XML, DB Schema, Hibernate, Struts, Spring, etc. Learning with a diagram is always easier.
  6. ERD vs UML[ Go to top ]

    I am quite aware that ERD diagrams are different from Class Diagrams.
    The primary difference beinig that ER diagrams are intuitive enough to be useful within a business. The Shlaer-Mellor OOA/D methodology proved to me with its model compilation of ER diagrams that notational simplicity doesn't sacrifice formal rigor nor suitability for downstream automation. The immense added notational complexity of UML's class diagram buys very little in practice downstream and precludes adoption upstream during analysis (before design).
  7. Re: Purpose[ Go to top ]

    Many junior/senior developers on the team did not really know in depth schemas for Hibernate of OJB or even Ant. They can’t really read XML. The UML-style drawing from Linguine Maps brings all team members to the same page. No one has to read full Hibernate spec. to be aware of our object models!
    Huh? From what moment someone needs to read Hibernate spec to be aware of object models?Hibernate is a glue level between Object Model and DB Schema ( rather straightforward in many cases if DB schema is good). It looks like that team cripple Object Model to whatever hbm2java generates and that is troublesome IMO.

    Also IMO. But this is the way most teams use Hibernate. They map tables via hbm files and then they have an object model. Which is of not-so-great quality, of course.
    And please do not forget that there are supposed to be ERD diagrams for the database, which might be in some cases quite different than Class Diagrams. ERD and Class diagrams are supposed to be primary resources and hibernate mapping is just that: mapping.

    Again, this is your opinion and mine. But not most Hibernate users'. Thank you for reminding it to us, though. It is always useful to restate these often-underestimated facts.
  8. SVG, the future of presentation.[ Go to top ]

    Also: is there a way to customize the generated output, via templates or something ?
    If the output instead were a SVG (or maybe some other XUL), then a user could impose arbitrary stylesheets. Stylesheets allow the easy introduction of new graph drawing/layout algorithms, complex custom interactions and behaviors, and hyperlinking. But since Java2D was chosen, the user is stuck with whatever crap Linguine ships.
  9. SVG, the future of presentation.[ Go to top ]

    If the output instead were a SVG (or maybe some other XUL), then a user could impose arbitrary stylesheets.
    Since all but one of the input formats Linguine accepts are XML dialects, Linguine could itself be implemented as a set of stylesheets.
  10. Purpose[ Go to top ]

    Is this tool purely for documentation and communication purposes ?
    It's a small evolutionary step from Linguine as a read-only viewer to a direct-manipulation editor. This lends further credibility to MDA's approach of visual programing and model compilation.
  11. Apache Ant[ Go to top ]

    Apache Ant

    no known limitations for valid XML files that are validate and executed by Ant runtime

    Here's one - Usage of XML Entities.

    <!DOCTYPE project [<!ENTITY % common.entities
        SYSTEM "../build/ant/common.entities">
    %common.entities;
    ]>

    Yields:

      [ant2gif] [Fatal Error] :98:51: The entity "install.depends" was referenced, but not declared.

    Saw no place to post this on the site, and have mailed the Autor as well.
  12. Apache Ant[ Go to top ]

    Thank you for trying things out.

    I have processed several hundreds Ant builds from many different open/closed source projects and it woks fine (with tiny non-fatal issues). The usage XML Entities is not something I see very often. It never gave a problem even when I saw it.

    The error you are citing is from the Sun’s XML parser. And this is where one has to start looking in order to fix it. I will add the problem to the list as “non critical” until we have more examples of this happening from you or others.

    Thank you once again for trying things out.
  13. Sun XML Parser[ Go to top ]

    Thanks for the response (this is not the right forum of course).

    Note: Sun XML Parser also throws bugs in other applications I use, but using the IBM 1.4 JDK, those bugs go away.

    I'll switch JVM and try again.
  14. The Hibernate recommendation is to have a hbm file per class mapping. The example on the site shows all classes in single hbm file. Does this support reading mutiple hbm files at one shot and generate object graph.
  15. It would be very useful if it could produce a wiring diagram for Spring. Same deal for Struts config files: who forward to what?
  16. For Spring you should use BeanDoc:

    http://opensource.atlassian.com/confluence/spring/display/BDOC/Home

    it does exactly what you want.
    Don't know whether there are such tools for Struts (though when your Actions are spring-managed then you'll get it for free via BeanDoc).
  17. Does it do Spring xml files?[ Go to top ]

    For Spring you should use BeanDoc:http://opensource.atlassian.com/confluence/spring/display/BDOC/Homeit does exactly what you want.Don't know whether there are such tools for Struts (though when your Actions are spring-managed then you'll get it for free via BeanDoc).

    Except BeanDoc hasn't kept up and it will die if you use the shorter XML syntax made possible in Spring 1.2+.
  18. Does it do Spring xml files?[ Go to top ]

    Spring BeanDoc is a great tool. It brings together lots of pieces of project documentation in a unified format. The code behind it is interesting as well.

    I am not sure, however, what kind of diagrams it draws. For example, take a look at JPetStore: http://springframework.sourceforge.net/beandoc/jpetstore/
    There is a diagram at the top of the page. Does it approximately follow UML? If not - what does it represent? I am very interested in understanding this better, but did not find any docs in the distribution.

    Linguine maps attempts to create UML-style entity-relation diagram. ER drawings are well understood by most developers and smart business people.
  19. Hibernate mapping.[ Go to top ]

    The hibernate version does not create diagrams to depict inheritance. Here is the my hbm.xml file. It inheritance relationship between BillingDetails, BankAccount and CreditCard is not reflected in the generated diagrams.

    <?xml version="1.0"?>
    <!DOCTYPE hibernate-mapping
            PUBLIC "-//Hibernate/Hibernate Mapping DTD//EN"
            "http://hibernate.sourceforge.net/hibernate-mapping-2.0.dtd">
    <hibernate-mapping
        package="org.hibernate.auction.model">
        <class name="Bid"
            table="BID">
            <id
                name="id"
                unsaved-value="0"
                type="long">
                <generator class="native" />
            </id>
            <many-to-one
                name="item"
                column="ITEM_ID"
                class="Item"
                not-null="true" />
        </class>
        <class name="BillingDetails"
            table="BILLING_DETAILS">
            <id
                name="id"
                column="BILLING_DETAILS_ID"
                type="long">
                <generator class="native" />
            </id>
            <property
                name="owner"
                column="OWNER"
                type="string" />
            <property
                name="number"
                column="NUM"
                type="string" />
            <property
                name="created"
                column="CREATED"
                type="date" />
        </class>
        <joined-subclass
            name="BankAccount" extends="BillingDetails"
            table="BANK_ACCOUNT">
            <key column="BANK_ACCOUNT_ID" />
            <property
                name="bankName"
                column="BANK_NAME"
                type="string" />
            <property
                name="bankSwift"
                column="BANK_SWIFT"
                type="string" />
        </joined-subclass>
        <class name="Category"
            table="CATEGORY">
            <id
                name="id"
                column="CATEGORY_ID"
                type="long">
                <generator class="native"/>
            </id>
            
            <property
                name="name"
                column="NAME"
                type="string"
                length="30"/>
            <many-to-one
                name="parentCategory"
                column="PARENT_CATEGORY"
                class="Category" />
            <set
                name="childCategories"
                inverse="true"
                cascade="all-delete-orphan">
                <key column="PARENT_CATEGORY" /> <!-- Forign key name -->
                <one-to-many class="Category" />
            </set>
            <set name="items" table="CATEGORY_ITEM"
                lazy="true" cascade="save-update"
                inverse="true" >
                <key column="CATEGORY_ID" />
                <many-to-many class="Item" column="ITEM_ID" />
            </set>
        </class>
        <joined-subclass
            name="CreditCard" extends="BillingDetails"
            table="CREDIT_CARD">
            <key column="CREDIT_CARD_ID" />
            <property
                name="type"
                column="TYPE"
                type="integer" />
            <property
                name="expMonth"
                column="EXP_MONTH"
                type="string" />
            <property
                name="expYear"
                column="EXP_YEAR"
                type="string" />
        </joined-subclass>
        <class name="Item"
            table="ITEM">
            <id
                name="id"
                column="ITEM_ID"
                type="long">
                <generator class="native" />
            </id>
            <property
                name="name"
                column="NAME"
                type="string"
                length="25" />
            <property
                name="description"
                column="DESCRIPTION"
                type="string"
                length="25" />
            <set name="bids"
                inverse="true"
                cascade="all-delete-orphan" >
                <key column="ITEM_ID" />
                <one-to-many class="Bid" />
            </set>
            <set name="categories" table="CATEGORY_ITEM"
                lazy="true" cascade="save-update" >
                <key column="ITEM_ID" />
                <many-to-many class="Category" column="CATEGORY_ID" />
            </set>
        </class>
        <class name="User"
            table="USERS">
            
            <id
                name="id"
                column="USER_ID"
                type="long">
                <generator class="native"/>
            </id>
            
            <property
                name="user_name"
                column="USER_NAME"
                type="string"
                length="30"/>
            <component
                name="homeAddress"
                class="Address">
                
                <parent name="user" />
                <property
                    name="street"
                    type="string"
                    column="HOME_STREET"
                    not-null="true"
                    length="30"/>
                <property
                    name="city"
                    type="string"
                    column="HOME_CITY"
                    not-null="true"
                    length="30"/>
                <property
                    name="zipCode"
                    type="short"
                    column="HOME_ZIPCODE"
                    not-null="true"/>
            </component>
            
             <component
                name="billingAddress"
                class="Address">
                
                <parent name="user" />
                <property
                    name="street"
                    type="string"
                    column="BILLING_STREET"
                    not-null="true"
                    length="30"/>
                <property
                    name="city"
                    type="string"
                    column="BILLING_CITY"
                    not-null="true"
                    length="30"/>
                <property
                    name="zipCode"
                    type="short"
                    column="BILLING_ZIPCODE"
                    not-null="true"/>
            </component>
        </class>
    </hibernate-mapping>
  20. Hibernate mapping.[ Go to top ]

    The hibernate version does not create diagrams to depict inheritance. Here is the my hbm.xml file. It inheritance relationship between BillingDetails, BankAccount and CreditCard is not reflected in the generated diagrams.

    Do not we have good old class diagrams for that? Why bother with inferring the information from hbm, when it is readily available on the sorce and class levels, and all decent UML tools easily pick it up?
  21. Hibernate mapping.[ Go to top ]

    Thank you for trying this out!

    You are correct – in your example inheritance is not properly discovered. This is a bug…

    I made an assumption that <joined-subclass> can only be inside <class>, in which case it is obvious what the super class is without looking at extends attribute. If you declare BankAccount inside BillingDetails – it all works fine.

    I did not notice this problem, even after testing most mappings found in Hibernate 3.0 distribution. You can see many samples with inheritance here:
    http://www.softwaresecretweapons.com/jspwiki/Wiki.jsp?page=LinguineMapsProgrammaticVisualizationSamplesHBM

    It is definitely a bug. I will fix it in the next update.

    Thank you for the feedback.
  22. Hibernate mapping.[ Go to top ]

    I had a similar problem with <joined-subclass> being specified outside the base <class>. I used oy-lm-1.3 released in November, so it seems that the updat did not fix the problem. Is there a way to do this without changing the structure of my .hbm.xml files? (I am using hibernate 2.1.8)
  23. Poster size printing[ Go to top ]

    I ran this package on our ant build.xml file. I got a 6000x8000 png graphic.

    Does anyone know of a windows utility to print that on several regular pages (tiles)?


    Thanks,
    Thierry Thelliez
  24. Poster size printing[ Go to top ]

    Yes!

    This is what I do:

    - Open Microsoft Excel
    - Open Windows Explorer
    - Drag/Drop imgaes file into Excel
    - Go to Print Preview, select X pages wide by Y pages long in options
    - hit print

    Cool!