Generated config in quickstarts considered harmful?

[kcbabo]

I'm beginning to think so?  Even though we have tooling support to view generated config, there's still an issue with viewing the switchyard.xml for a quickstart in a text editor (or on GitHub) and not seeing the "whole picture".  As we have discussed previously, we're moving more and more away from generation as a primary option anyway.  The tooling creates source config for everything you do, so maybe we should just update all the quickstarts to make sure there's no generated config.  Note that generated config will still be a feature, just not one that we emphasize in our quickstarts.

Thoughts?

[jeffdelong]

It would be helpful to be able to look at the entire switchyard.xml to understand the quickstart without having to import the project into Eclipse and build it. It would also be great if there were a png file of the visual editor model to give the developer a quick graphical display of the model. A lot of times I don't want to run the quickstart, I just want ot see how some feature is used / configured.

[kcbabo]

It would be helpful to be able to look at the entire switchyard.xml to understand the quickstart without having to import the project into Eclipse and build it.

Yep.

It would also be great if there were a png file of the visual editor model to give the developer a quick graphical display of the model. A lot of times I don't want to run the quickstart, I just want ot see how some feature is used / configured.

I went through all the quickstarts and added this a while back, but quite a few have been added since and not everyone has followed this practice. :-)  I will look to fix this up by the end of 0.8.

[dward]

You don't have to import into Eclipse to generate the full switchyard.xml.  Simply cd'ing into the project and typing "mvn install" will create the full switchyard.xml in target/classes/META-INF/switchyard.xml.  No Eclipse necessary.  But that's me just being nit-picky on that point.

I do admit that I am respsonsible for creating several of the quickstarts that do xml generation based on annotations (rules, bpm, security, ...).  I did this because, as is their purpose, it's easier to have the xml generated for you than coding it, and less error-prone.  I started doing this long before our Eclipse tooling matured.  Now that it has caught up, I can see less need to depend on the annotations to generate config.

I'm okay with us updating the quickstarts so that the full switchyard.xml is in src/main/resources/META-INF/switchyard.xml.  May I suggest, though, that whoever does this work (we might split it up) first run "mvn install", then copy target/classes/META-INF/switchyard.xml on top of src/main/resources/META-INF/switchyard.xml, BEFORE the annotations are removed?  That will streamline the conversion process and make sure nothing gets missed.

[tadayosi]

+1 for Keith's suggestion. I found some beginners (including me) first get confused with those very simplistic switchyard.xml for many of the quickstarts, wondering about how those services and components are wired with each other for some time. We finally notice that the SwitchYard Maven plugin (and scanners) do this for us as David explained above, but it would be much easier for beginners to understand if src/main/resources/switchyard.xml is provided in its entire form from the beginning.

I personally like less-configuration styles, however if you would take this path of less configuration, I'd expect it to go to more extreme like Ruby on Rails' convention-over-configuration style. Just my two cents' worth.

[kcbabo]

OK, here it is for 0.8:

https://issues.jboss.org/browse/SWITCHYARD-1274

I agree with David that the switchyard.xml simply needs to be copied from the target directory onto the src version.