Torque
  1. Torque
  2. TORQUE-50

Supporting local and add-on Generator "Override" jars

    Details

      Description

      <From an e-mail proposal talked about on the torque-dev list>

      I've been looking at how to package, document, contribute
      my betwixt map/dtd generation code. As Thomas pointed out,
      it's not truely mainstream Torque but might be a useful
      addon. Anyway, this got me thinking about how to best
      support template and/or generator local modifications or
      add-on.

      If the generator build scripts supplied by the Torque
      distro had classpaths that first tried to add any
      *-override.jar files before the distro files, then
      Templates and generator classes could easily be locally
      overriden. This is trivial to do with the Ant
      torque-build.xml. I assume that it would be easy in Maven?

      If no *override.jar files exist, it's a standard install.
      But if you've got local changes to implement or want to
      use a supplied add-on, just add *override.jar files to the
      correct directory(s) and use the standard generation
      processes.

      IMHO, this seems cleaner than trying to maintain a full
      customized template or generator distros. If a new
      version comes out, just grab the standard, check for
      any gottcha's between it and your modified code, add back
      in your override jars. All the benefits of a new version
      with your local mods included.

      In a lot of cases, like changes to sql generation
      templates (e.g. MySQL Table options ) or new db
      adaptor support (like Informix/MSSQL7), this will be
      very easy. These areas don't change a lot or are
      mostly new templates.

      It also allows for easier add-on contributions. An add-on
      could be supplied as a set of jars that are simply put in
      the correct directories using common How-To instructions.
      The add-in supplier just needs to document any additional
      settings.

      It's not perfect since add-on's can override each other
      and break... but it's better than it was.

      1. custom-templates.xml
        10 kB
        CG Monroe
      2. Generator Override Support.zip
        17 kB
        CG Monroe
      3. how-templates-work.xml
        7 kB
        CG Monroe

        Activity

        Hide
        CG Monroe added a comment -

        Change Log for Generator Override Support

        G. Monroe 9 Aug 2006

        build-torque.xml
        Added Ant tasks to the torque-class path building stage to use
        *override.jar and a templates directory first in the classpath

        plugin-jelly
        Same mods as for build-torque except added a case if torque.lib.dir
        was not set (Maven doesn't require this)

        navigation.xml
        Added a Custom Generation Item in the Other How Tos section.

        customizing-generator-howto.xml
        New How To that contains info on how to use the modifications to the
        build scripts, pointers on modifying the generation process, and
        guidelines for creating a User Contributed Torque Add On.

        Show
        CG Monroe added a comment - Change Log for Generator Override Support G. Monroe 9 Aug 2006 build-torque.xml Added Ant tasks to the torque-class path building stage to use *override.jar and a templates directory first in the classpath plugin-jelly Same mods as for build-torque except added a case if torque.lib.dir was not set (Maven doesn't require this) navigation.xml Added a Custom Generation Item in the Other How Tos section. customizing-generator-howto.xml New How To that contains info on how to use the modifications to the build scripts, pointers on modifying the generation process, and guidelines for creating a User Contributed Torque Add On.
        Hide
        CG Monroe added a comment -

        Forgot to document that this change also replaces log4j with commons-logging in the ant and maven 1.0 classpath creation section.

        All log4j references in the generator code have been migrated to common-logging. In addition, log4j is not included in the distribution as well. (But log4j can be defined as the implimentor to use in the commons-logging.properties file)

        Show
        CG Monroe added a comment - Forgot to document that this change also replaces log4j with commons-logging in the ant and maven 1.0 classpath creation section. All log4j references in the generator code have been migrated to common-logging. In addition, log4j is not included in the distribution as well. (But log4j can be defined as the implimentor to use in the commons-logging.properties file)
        Hide
        added a comment -

        I have got some comments regarding the documentation, mostly concerning its organisation. On the whole, I like it, but several points need to be addressed in my opinion.
        First, I'm not a big friend of howtos as a main source of documentation. Howtos are nice as a supplement, but if they are used as main documentation, it is very difficult for users to find the information they need because they have to scan through various howtos to find it. In my opinion, documentation should be in a "reference" form.
        Then, the procedure of how to submit supplements should be discussed at the dev mailing list; people should have a chance to object to this procedure if they wish. The main publishuing supplements on the torque site is not as easy as it sounds: First, all that is on there must be donated to the ASF and must have an apache licence. For larger contribution, the ASF wishes that a CLA is signed. Then, there is the problem of mirroring. The infrastructure team has not been amused in the past about non-mirrored downloads, so mirroring must be set up. Also, the ASF has a reputation for delievering rather high-quality software. This is achieved by reviewing all contributions by the committers. So before anything is put on the torque website, we want to be reasonably sure that it works, which also needs effort by the Torque team.
        Dont get me wrong, I'm not saying this is impossible, it is just things to keep in mind when such a procedure should be established.

        So I'd suggest the following:

        • move the documentation from the site to the generator, because it only affects the generator
        • add the property torque.override.dir to the generator properties reference, http://db.apache.org/torque/releases/torque-3.2/generator/properties-reference.html, and thell users that it only works if torque.useClasspath is set to true
        • Move the part about how templates work into an extra file and call it "how templates work" or the like.
        • discuss the part of how to submit references on the dev list
        Show
        added a comment - I have got some comments regarding the documentation, mostly concerning its organisation. On the whole, I like it, but several points need to be addressed in my opinion. First, I'm not a big friend of howtos as a main source of documentation. Howtos are nice as a supplement, but if they are used as main documentation, it is very difficult for users to find the information they need because they have to scan through various howtos to find it. In my opinion, documentation should be in a "reference" form. Then, the procedure of how to submit supplements should be discussed at the dev mailing list; people should have a chance to object to this procedure if they wish. The main publishuing supplements on the torque site is not as easy as it sounds: First, all that is on there must be donated to the ASF and must have an apache licence. For larger contribution, the ASF wishes that a CLA is signed. Then, there is the problem of mirroring. The infrastructure team has not been amused in the past about non-mirrored downloads, so mirroring must be set up. Also, the ASF has a reputation for delievering rather high-quality software. This is achieved by reviewing all contributions by the committers. So before anything is put on the torque website, we want to be reasonably sure that it works, which also needs effort by the Torque team. Dont get me wrong, I'm not saying this is impossible, it is just things to keep in mind when such a procedure should be established. So I'd suggest the following: move the documentation from the site to the generator, because it only affects the generator add the property torque.override.dir to the generator properties reference, http://db.apache.org/torque/releases/torque-3.2/generator/properties-reference.html , and thell users that it only works if torque.useClasspath is set to true Move the part about how templates work into an extra file and call it "how templates work" or the like. discuss the part of how to submit references on the dev list
        Hide
        Thomas Fox added a comment -

        The previous comment was made by me, seems that I ran into a cookie timeout, so jira treated it as anonymous.

        Show
        Thomas Fox added a comment - The previous comment was made by me, seems that I ran into a cookie timeout, so jira treated it as anonymous.
        Hide
        CG Monroe added a comment -

        All good points and your plan of action looks good to me.

        I agree that fewer docs to find stuff the better with the minor exception that a How To-s "Article format" is often more informative than a Reference/API only. (How many new things have you learned from a Java World article vs digging thru an API/ Reference?).

        In an ideal "product" world, there should be a Reference doc and a Users Guide. With the Users Guide filling the HowTo role, but writing and maintaining a good Users Guide is a major thing. IMHO, a majority of Open Source projects delegate the role of User Guide to support lists/forums, FAQS, and How Tos... Not perfect, but more quasi-maintainable given the here today/ gone tomorrow nature of the open source community.

        To be clear, I'm not arguing to keep my How-To, just responding to your "no How To's" point of veiw. Splitting it up your way makes sense. I always assume first pass docs are going to be torn apart and re-organized. My take on this was mostly to explain what the patch was, how it could be used, and think through what I needed to put together to submit my Betwixt support add-on 8).

        Show
        CG Monroe added a comment - All good points and your plan of action looks good to me. I agree that fewer docs to find stuff the better with the minor exception that a How To-s "Article format" is often more informative than a Reference/API only. (How many new things have you learned from a Java World article vs digging thru an API/ Reference?). In an ideal "product" world, there should be a Reference doc and a Users Guide. With the Users Guide filling the HowTo role, but writing and maintaining a good Users Guide is a major thing. IMHO, a majority of Open Source projects delegate the role of User Guide to support lists/forums, FAQS, and How Tos... Not perfect, but more quasi-maintainable given the here today/ gone tomorrow nature of the open source community. To be clear, I'm not arguing to keep my How-To, just responding to your "no How To's" point of veiw. Splitting it up your way makes sense. I always assume first pass docs are going to be torn apart and re-organized. My take on this was mostly to explain what the patch was, how it could be used, and think through what I needed to put together to submit my Betwixt support add-on 8).
        Hide
        Thomas Fox added a comment -

        Well, my no-howto attidude stems mostly from the experience of re-organizing the lot of howtos in the runtime to a documentation where people actually can find anything. That problem does not exist at the moment for the generator, but I do want to stop the beginnings . As you may have noted, some howtos still have survived, so my attitude is not as strict ait it may seem.

        Show
        Thomas Fox added a comment - Well, my no-howto attidude stems mostly from the experience of re-organizing the lot of howtos in the runtime to a documentation where people actually can find anything. That problem does not exist at the moment for the generator, but I do want to stop the beginnings . As you may have noted, some howtos still have survived, so my attitude is not as strict ait it may seem.
        Hide
        Thomas Fox added a comment -

        Reorganized contribution as outlined above and committed it., excluding the part about how to submit patches. I will try to include TORQUE-54 as a contribution and then make a suggestion how I think contributions should be handled.

        Show
        Thomas Fox added a comment - Reorganized contribution as outlined above and committed it., excluding the part about how to submit patches. I will try to include TORQUE-54 as a contribution and then make a suggestion how I think contributions should be handled.
        Hide
        CG Monroe added a comment -

        Some documentation changes for these files in the: generator/xdocs directory.

        custom-templates:

        Some minor edits.

        how-templates-work:

        Expansion to cover the topic better. Now has the following topics:

        1. Introduction
        2. Process Overview
        3. Template Files
        4. Template Variables
        5. The XML Custom Option Element

        Note that section 5 covers the new "Option" schema element submitted as part of the Torque-27 issue. Seemed like a good place to point it out.

        Show
        CG Monroe added a comment - Some documentation changes for these files in the: generator/xdocs directory. custom-templates: Some minor edits. how-templates-work: Expansion to cover the topic better. Now has the following topics: 1. Introduction 2. Process Overview 3. Template Files 4. Template Variables 5. The XML Custom Option Element Note that section 5 covers the new "Option" schema element submitted as part of the Torque-27 issue. Seemed like a good place to point it out.
        Hide
        Thomas Fox added a comment -

        Added the new documentation changes to svn.
        Still left open this issue because we need to find out how to handle contributions in the future.

        Show
        Thomas Fox added a comment - Added the new documentation changes to svn. Still left open this issue because we need to find out how to handle contributions in the future.
        Hide
        Thomas Vandahl added a comment -

        As far as I can see this is supposed to be solved by the external contribution site or isn't it? Can this be closed?

        Show
        Thomas Vandahl added a comment - As far as I can see this is supposed to be solved by the external contribution site or isn't it? Can this be closed?
        Hide
        CG Monroe added a comment -

        It can be closed. The http://torque-addons.sf.net/ external project resolves this.

        Show
        CG Monroe added a comment - It can be closed. The http://torque-addons.sf.net/ external project resolves this.
        Hide
        Thomas Vandahl added a comment -

        This feature is covered by the external site http://torque-addons.sf.net/

        Show
        Thomas Vandahl added a comment - This feature is covered by the external site http://torque-addons.sf.net/
        Hide
        Greg Monroe added a comment -

        Hi Thomas,

        I just noticed which issue this was (thought it was Torque-54).
        Most of this actually got added to Torque. So, technically it's
        not a "Fixed" item and not a "Won't fix"... it just wasn't
        implimented exactly as submitted.

        Don't care if it's change or not, just pointing it out.

        Duke CE Privacy Statement
        Please be advised that this e-mail and any files transmitted with it are confidential communication or may otherwise be privileged or confidential and are intended solely for the individual or entity to whom they are addressed. If you are not the intended recipient you may not rely on the contents of this email or any attachments, and we ask that you please not read, copy or retransmit this communication, but reply to the sender and destroy the email, its contents, and all copies thereof immediately. Any unauthorized dissemination, distribution or copying of this communication is strictly prohibited.

        Show
        Greg Monroe added a comment - Hi Thomas, I just noticed which issue this was (thought it was Torque-54). Most of this actually got added to Torque. So, technically it's not a "Fixed" item and not a "Won't fix"... it just wasn't implimented exactly as submitted. Don't care if it's change or not, just pointing it out. Duke CE Privacy Statement Please be advised that this e-mail and any files transmitted with it are confidential communication or may otherwise be privileged or confidential and are intended solely for the individual or entity to whom they are addressed. If you are not the intended recipient you may not rely on the contents of this email or any attachments, and we ask that you please not read, copy or retransmit this communication, but reply to the sender and destroy the email, its contents, and all copies thereof immediately. Any unauthorized dissemination, distribution or copying of this communication is strictly prohibited.

          People

          • Assignee:
            Unassigned
            Reporter:
            CG Monroe
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development