5 Replies Latest reply on Oct 12, 2004 2:29 AM by Adrian Newby

    XDoclet, Packaging and version control

    Adrian Newby Newbie

      All,

      I have mixed feelings about the XDoclet and packaging support provided by JBoss-IDE. On the one hand, it's a great personal productivity enhancer. On the other hand, I can't see how to leverage these facilities in a team development environment.

      The first issue I have is I'd like to be able to build the project clean from the command line using ANT. That means no IDE-specific dependencies and no IDE-specific files should be checked into version control.

      Unfortunately, it seems you can't work with the xdoclet-build.xml and packaging-build.xml files directly because they are dynamically regenerated from hidden .xdoclet and .packaging files. If you check in your source and the XML files from one IDE and check out to another, your xdoclet.xml and packaging.xml files are useless, because they hard code the environment of the original IDE in terms of JAR file locations etc. You are also unable to regenerate them from the new IDE because you don't have the .xdoclet and .packaging files and, even if you did, they would not necessarity match the new environment. Asking each developer to create their own xdoclet and packaging configurations in their IDE seems to be unreasonable, unnecessary and fraught with danger.

      The second issue I have is naming conventions. Since a command-line build process requires a compile, as well as xdoclet and packaging operations, you need to build a wrapper build.xml, which provides the compile task and imports xdoclet.xml and packaging.xml for the other stuff. Unfortunately, since both xdoclet.xml and packaging.xml define a task named "_generation_", the order of import becomes an issue. Whichever file is imported first assumes the default task name of "_generation_". the second becomes "Packaging Generator._generation" or "XDoclet Generator,_generation_". If this default behavior varies from version to version of ANT, then the team is in trouble. It would be much more manageable if the XDoclet and Packging configuration processes would support user-definable task names so that import order becomes irrelevant.

      Does anyone out there have information that I may have missed or success stories/recommendations that they could pass on to improve the viability of the JBoss-IDE feature set in a production-grade team development environment?

      Adrian

        • 1. Re: XDoclet, Packaging and version control
          Adrian Newby Newbie

          By the way. On re-reading this post, I left out one important issue ...

          Congratulations Laurent and team on a kick-ass job well done!!

          • 2. Re: XDoclet, Packaging and version control
            Marshall Marshall Expert

            Hi Adrian, I had meant to reply to this a few days ago, but caught up in some other stuff.. (ahh.. life).

            I've had plenty of success with committing a projects .xdoclet / .packaging files to CVS, and sharing them amongst developers. One thing you might want to be mindful of though, when doing an initial checkout of the project via CVS, make sure to go into the Project Properties, and go to the XDoclet/Packaging configuration sections. This will make JBossIDE generate the needed xdoclet-build/packaging-build xml files.

            I've fixed the "_generation_" fiasco in my version of the codebase, and this will be pushed out on JBossIDE 1.4. Packaging's task name is now "_packaging_", and xdoclet is "_xdoclet_".

            Hopefully that answers your questions =)

            • 3. Re: XDoclet, Packaging and version control
              Adrian Newby Newbie

              Marshall,

              Thanks for the reply. Good to hear about the naming convention tidy-up. ANy chance that may be user-definable in the future?


              "marshall" wrote:
              I've had plenty of success with committing a projects .xdoclet / .packaging files to CVS, and sharing them amongst developers.
              One thing you might want to be mindful of though, when doing an initial checkout of the project via CVS, make sure to go into the Project Properties, and go to the XDoclet/Packaging configuration sections. This will make JBossIDE generate the needed xdoclet-build/packaging-build xml files.


              Unfortunately, this wasn't what I was really looking for. Although I completely believe I can syndicate the .xdoclet and .packaging files, it still means I'm tied to a given IDE and a given directory structure.

              Consider these cases:

              1) You need to bundle a JAR with your WAR e.g. struts.jar). For the person who originally built the packaging configuration, this might live in /usr/local/struts/lib, which is hard-coded into .packaging . Now another developer checks out the codebase (including .packaging), but their struts.jar is in /opt/struts. The packaging will fail. What if a third developer is running Windows and can't handle UNIX-style paths?

              2) An automated build process checks out and builds the source every night. Since this is a command-line based process (independent of any IDE), .xdoclet and .packaging are unusable. Also, the xdoclet and packaging XML files cannot be relied on, since they are derivatives of .xdoclet and .packaging and might, therefore, be stale.

              (Note: I chose not to address the issue of groups using different IDEs since you've already asserted that JBoss-IDE will only run under Eclipse. Fair enough - it's your project.)

              So, unless I'm missing something, it still seems as if we're team-challenged.

              In the general ANT world, my first issue is addressed by using property files that allow individual developers to define local pathing, independent of build.xml. If this capability could be added to the JBoss-IDE interface, so that a property file could be defined and then the properties referenced in the XDoclet and Packaging configuration interfaces, that would move us a long way forward. Also, if JBoss-IDE could reverse-engineer .xdoclet and .packaging from their respective XML counterparts, then I think we could have a workable solution as this would reverse the dependency relationship between the XML files and the dot-files.

              What do you think? Does this make it clearer or more confused?

              Adrian


              • 4. Re: XDoclet, Packaging and version control
                Marshall Marshall Expert

                 

                "anewby" wrote:
                Thanks for the reply. Good to hear about the naming convention tidy-up. ANy chance that may be user-definable in the future?


                I don't see why they shouldn't be user definable. I can't promise that it will be in JBossIDE 1.4, but I can try =). (The next two concerns are addressed out of order)

                "anewby" wrote:
                2) An automated build process checks out and builds the source every night. Since this is a command-line based process (independent of any IDE), .xdoclet and .packaging are unusable. Also, the xdoclet and packaging XML files cannot be relied on, since they are derivatives of .xdoclet and .packaging and might, therefore, be stale.


                I haven't assessed the viability of this yet, but it's something I've been contemplating for the past week or so. Right now, all XDoclet and Packaging configuration information is stored in the "dot" files (.xdoclet, .packaging). Later, an xsl stylesheet is applied to each to generate your xdoclet-build.xml, and packaging-build.xml's. What I'd like to do, is combine this 2-file configuration into a single ant readable task file. The problem becomes, of course, if we let users run off with an Ant task that is depended upon for configuration data, it has potential to become a support/usability nightmare. We could easily address this issue, IMO, With a FAQ entry telling users to copy the xxx-build.xml if they want to use it seperate from the IDE, and make changes to it. What are your thoughts?

                "anewby" wrote:
                1) You need to bundle a JAR with your WAR e.g. struts.jar). For the person who originally built the packaging configuration, this might live in /usr/local/struts/lib, which is hard-coded into .packaging . Now another developer checks out the codebase (including .packaging), but their struts.jar is in /opt/struts. The packaging will fail. What if a third developer is running Windows and can't handle UNIX-style paths?


                I think that adding external properties files is also a very valid feature request. I'm sure this won't make it by 1.4 though, unfortunately ;). Regardless though, I would appreciate it if you took the time to submit a new feature request to keep me honest about wanting to implement this in the future. and of course, contributions are always welcome as well =).

                "anewby" wrote:
                What do you think? Does this make it clearer or more confused?


                Your concerns are very clear, Hopefully I'm doing a decent job of addressing them =). Thanks for voicing them.. us developers gotta have someone to keep us honest ;)

                • 5. Re: XDoclet, Packaging and version control
                  Adrian Newby Newbie

                   

                  "marshall" wrote:
                  We could easily address this issue, IMO, With a FAQ entry telling users to copy the xxx-build.xml if they want to use it seperate from the IDE, and make changes to it. What are your thoughts?


                  Isn't it basically the same problem as XDoclet generating interface classes for EJBs? The solution to that problem is a big fat "Don't mess with this file" comment in the interface sources. You could go one better with ANT and make it a message that's echo'd every time the build file is run. I think we have to assume that the average user of this tool is basically not a dummy and understands the risks involved in changing an auto-generated file.

                  "marshall" wrote:
                  Regardless though, I would appreciate it if you took the time to submit a new feature request


                  Consider it done

                  "marshall" wrote:
                  ... and of course, contributions are always welcome as well =).


                  I'm up for this - I'll contact you offline to discuss further.

                  "marshall" wrote:
                  Hopefully I'm doing a decent job of addressing them =).


                  Absolutely. Thanks a lot.