1 2 Previous Next 21 Replies Latest reply on May 3, 2010 12:27 PM by dan.j.allen

    ARQ-33: General Configuration Module

    germanescobar

      I've been working on the General Configuration Module (ARQ-33) and I just want to open the discussion to the community for feedback. First, here is a class diagram of the configuration module:

       

      arquillian-config-classes.png

       

      The Configuration class holds the global Arquillian configuration and a Map of ContainerConfiguration implementations (the specific containers configuration). The Configuration is created by the ConfigurationBuilder and used by the different DeployableContainer implementations (i.e. JbossRemoteContainer, GlassFishEmbeddedContainer, etc.) to configure themselves. A simplified sequence diagram of the configuration would be like this (using the JBossRemoteContainer as an example):

       

      arquillian-config-sequence.png

       

      It is a typesafe and extensible mechanism of configuring Arquillian and the different containers.

       

      I'm also working on the XmlConfigurationBuilder that will lookup for an arquillian.xml file in the root of the classpath. For example:

       

      <?xml version="1.0"?>
       
      <arquillian xmlns="http://jboss.com/products/arquillian"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xmlns:jboss="urn:java:org.jboss.arquillian.jboss"
          xsi:schemaLocation="
              http://jboss.com/products/arquillian ...xsd
              urn:java:org.jboss.arquillian.jboss ...xsd">
       
       
        <jboss:container>
          <jboss:bind address="localhost" port="8181" />
        </jboss:container>
       
       
      </arquillian>
      

       

      The jboss:container XML fragment would be mapped to the following class:

       

      public class JBossConfiguration implements ContainerConfiguration {
      
        private String bindAddress = "localhost"; // default value
        private int bindPort = 8080; // default value
      
        // getters and setters not shown
      }
      

       

      To do the mapping, XmlConfigurationBuilder uses an extension mechanism where it first loads all the ContainerConfiguration implementations (using the ServiceLoader) and then it tries to match the Namespace URI (that holds the package) with one of the ContainerConfiguration implementations. If found, it will map the child elements to the object properties and add the object to the Configuration object.

       

      The mapping of the container tag child elements and the object can be as complex as we want it to be (i.e. support collections, arrays, etc.) but I thing we need to limit it for the alpha-2 release.

       

      Finally, I have some questions:

       

      1. In the meeting, we talked about a <container id="..." /> tag (would be mapped to Configuration.containerId). However, this makes sense if we allow multiple containers on the classpath and we have some sort of mechanism to programatically retrieve the name of each container. What are the plans for this?
      2. Currently, I'm passing the Configuration object to the container through the DeployableContainer.start() method. Wouldn't it be better if we provide a DeployableContainer.setup() method to pass this information?
      3. A small detail. I'm naming the JBoss configuration JbossConfiguration, with a lower "b" because other classes use that standard. However, wouldn't it be better to name all those classes with a capital "B", like JBossConfiguration for example?
        • 1. Re: ARQ-33: General Configuration Module
          aslak

          German Escobar wrote:

           

          1. A small detail. I'm naming the JBoss configuration JbossConfiguration, with a lower "b" because other classes use that standard. However, wouldn't it be better to name all those classes with a capital "B", like JBossConfiguration for example?

          I agree,  https://jira.jboss.org/jira/browse/ARQ-99

          • 2. Re: ARQ-33: General Configuration Module
            dan.j.allen

            German, this is a really great start. Finally something concrete that we can build on

             

            When I look at the ContainerConfiguration class, I can't help but to draw a correlation with CDI (maybe because I am thinking about it every day). Arquillian would inspect all classpath entries with beans.xml (or arquillian.xml) as a marker and pick up the ContainerConfiguration implementations and put them in a map of "beans". This is similar to what you are suggesting, but uses the scan approach rather than the service loader approach. The benefit comes when we get into the matching XML.

             

            I think the XML should closely match the syntax that is used in the Seam XML bean config module. This syntax is going to be familiar to Seam users and we are trying to standardize it as a way to configure bean properties and provide metadata (e.g., annotation) overrides. We don't have to go this way, but we should at least cite a reason for ruling it out.

             

            What's the benefit?

             

            • the container providers are alleviated of the burden of having to provide an XSD schema for mapping XML elements and attributes to types and properties, respectively.
            • the user is going to be familiar with the XML syntax from using Seam

             

            We can still keep the root element <arquillian> since the Seam XML bean config module is looking inside the root element.

             

            In the case you provide, here's what the XML might look like. (Notice I have switched jboss.com to jboss.org and dropped "products" from the namespace. I've also added "AS" to the configuration class name since we should never use JBoss by itself to refer to JBoss AS).

             

            <?xml version="1.0"?>
            <arquillian xmlns="http://jboss.org/arquillian"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xmlns:jboss="urn:java:org.jboss.arquillian.jboss"
                xsi:schemaLocation="http://jboss.org/arquillian-config-1.0.xsd">
              <jboss:JBossASConfiguration>
                <jboss:bindAddress value="localhost"/>
                <jboss:bindPort value="8080"/>
              </jboss:JBossASConfiguration>
            
            </arquillian>
            

             

            To preserve the type-safety when selecting the active container, we can reference the configuration class again:

             

            <container>
               <jboss:JBossASConfiguration/>
            </container>
            

             

            If we happen to have two JBoss AS configurations, and we need to disambiguate them, then perhaps then we do need a string (because we can't rely on qualifiers, though that would be the best choice!)

             

            <container>
               <jboss:JBossASConfiguration id="container1"/>
            </container>
            
            <jboss:JBossASConfiguration id="container1">
                ...
            </jboss:JBossASConfiguration>
            

             

            An alternate approach to container selection is to use the activation framework that Maven uses, where profiles can have activation triggers (including one activeByDefault). This would provide commandline control virtually for free. I suppose the activation would have to be mutually exclusive, unless we support repeating the suite for each active container.

            • 3. Re: ARQ-33: General Configuration Module
              dan.j.allen

              There is one other configuration need that I would like to address. We have been saying that Arquillian requires no configuration to use right now. Just add the container JAR on the classpath. However, that's not entirely true.

               

              To connect to a remote JBoss AS instance, we need to have a jndi.properties file on the classpath. This is a cryptic configuration file that is hard to justify and explain. I'd like to see this get wrapped up into the configuration somehow or auto-generated so that the user does not have to worry about it.

               

              Just something to keep on the radar.

              • 4. Re: ARQ-33: General Configuration Module
                germanescobar

                Dan,

                 

                Thanks for the feedback!

                Arquillian would inspect all classpath entries with beans.xml (or arquillian.xml) as a marker and pick up the ContainerConfiguration implementations and put them in a map of "beans". This is similar to what you are suggesting, but uses the scan approach rather than the service loader approach.

                 

                If we use the Seam XML syntax, there is no need to scan for the ContainerConfiguration implementations (or having the Service Loader approach) as you have the package and class name in the XML itself.

                 

                 

                I think the XML should closely match the syntax that is used in the Seam XML bean config module. This syntax is going to be familiar to Seam users and we are trying to standardize it as a way to configure bean properties and provide metadata (e.g., annotation) overrides. We don't have to go this way, but we should at least cite a reason for ruling it out.

                 

                I like the Seam XML syntax and I thought about it. However, I have the following concerns:

                 

                • The user would need to know the ContainerConfiguration implementation class name and properties which, IMO, should be kept for the container implementation itself (and be able to change without affecting the users).
                • If we want to override the XML configuration (say with system properties), we would need to "teach" the users how to do the mapping.
                • In general, I would think is better to give the options directly. That way, we can deprecate and add properties easily (providing new schema versions and changing the documentation for the system properties).

                 

                That explains some of my design decisions. I always use the tag "container" (i.e. <jboss:container ...>) instead of the class name. And, as I don´t have the class name in the XML, I used the Service Loader approach. I do map the Xml "container" tag child elements to the class properties (with a slightly different approach than the Seam XML module but it can be changed to match).

                 

                WDYT?

                 

                 

                In the case you provide, here's what the XML might look like. (Notice I have switched jboss.com to jboss.org and dropped "products" from the namespace. I've also added "AS" to the configuration class name since we should never use JBoss by itself to refer to JBoss AS).

                Thanks, I'll change this.

                • 5. Re: ARQ-33: General Configuration Module
                  dan.j.allen


                  Arquillian would inspect all classpath entries with beans.xml (or arquillian.xml) as a marker and pick up the ContainerConfiguration implementations and put them in a map of "beans". This is similar to what you are suggesting, but uses the scan approach rather than the service loader approach.

                   

                  If we use the Seam XML syntax, there is no need to scan for the ContainerConfiguration implementations (or having the Service Loader approach) as you have the package and class name in the XML itself.

                   

                  We'll, not necessarily. The XML is for customization. You still need to know what container configurations you have on the classpath so you know which containers to activate. I think you guys were talking about multiple test runs, where you can hit each available container, so again, that's when you need to have discovery.

                   

                  I think the XML should closely match the syntax that is used in the Seam XML bean config module. This syntax is going to be familiar to Seam users and we are trying to standardize it as a way to configure bean properties and provide metadata (e.g., annotation) overrides. We don't have to go this way, but we should at least cite a reason for ruling it out.

                   

                  I like the Seam XML syntax and I thought about it. However, I have the following concerns:

                   

                  • The user would need to know the ContainerConfiguration implementation class name and properties which, IMO, should be kept for the container implementation itself (and be able to change without affecting the users).
                  • If we want to override the XML configuration (say with system properties), we would need to "teach" the users how to do the mapping.
                  • In general, I would think is better to give the options directly. That way, we can deprecate and add properties easily (providing new schema versions and changing the documentation for the system properties).

                   

                  That explains some of my design decisions. I always use the tag "container" (i.e. <jboss:container ...>) instead of the class name. And, as I don´t have the class name in the XML, I used the Service Loader approach. I do map the Xml "container" tag child elements to the class properties (with a slightly different approach than the Seam XML module but it can be changed to match).

                   

                  Knowing the built-in class name is the direction that Seam 3 is going. Now, you could have an abstraction, but an abstraction is just a layer of indirection. The important part is that the package names are consistent and the class name is stable.

                   

                  I still think we can get what you want and use the Seam XML Bean Config syntax. I think if you see a limitation, it's a limitation in that syntax, not in the idea of using it. I'd like to patch Stuart Douglas into this thread and just see if he has any feelings about it.

                   

                  At the end of the day, I do want to have a very nice looking XML syntax. I just also want to do the due diligence of having a consistent user experience before we introduce another XML dialect.

                  • 6. Re: ARQ-33: General Configuration Module
                    pmuir

                    In general I would prefer to avoid a direct mapping between XML configuration and class/bean names in a framework like this. It can, if used unchecked impose a burden on the user, and also can cause problems if a refactor is needed in the future.

                     

                    Instead, in general, I think developing a domain-specific configuration is preferable, and keeps the syntax simplier.

                    • 7. Re: ARQ-33: General Configuration Module
                      pmuir

                      If we can:

                       

                      1. restrict the configuration to just a few interfaces
                      2. have those interfaces only for configuration
                      3. remove the urn:java: stuff from the schema name
                      4. rename JBossAsConfiguration to Container and allow for it to be lower case
                      5. change bindAddress back to how German originally had it

                       

                      then my objections go away.

                       

                      IOW I don't think we should tie the XML syntax to a bean configuration language.

                      • 8. Re: ARQ-33: General Configuration Module
                        swd847

                        I don't think we should use seam-xml for this purpose. It does not really buy you anything in terms of reduced learning curve as you still need to document the classes that are actually being configured.

                         

                        Also you will probably find that you end up working around the syntax, in seam-xml you wire up complex object graphs using injection, which is not applicable here.

                        • 9. Re: ARQ-33: General Configuration Module
                          pmuir

                          Also, with my depedency police hat on, it's another dep for Arquillian core, which I think is worth avoiding. Writing a parser using the built in XML support in Java is ugly but possible for a limited XML format.

                          • 10. Re: ARQ-33: General Configuration Module
                            dan.j.allen

                            Fair enough. After giving it more thought, a nice clean XML dialect seems to be the best approach.

                             

                            So I see a couple of open questions at this point:

                             

                            1. Does an XML stanza for a container need to be present to make it usable?
                            2. What's the best way to refer to a container configuration from the <container> element? By string id? (What if there's no XML for it, see #1?)
                            3. Do we want to consider having an activation framework?

                             

                            By the last comment, what I mean is something like this:

                             

                            <jbossremote:container>
                               ...
                               <activation>
                                  <property>
                                     <name>jbasremote</name>
                                  </property>
                               </activation>
                            </jbossremote:container>
                            

                             

                            Although namespace prefixes are chosen by the user, in the examples we should be sure to keep them clear, as I have done, for the type of container. For example:

                             

                            • jbossremote
                            • jbossembeded
                            • gfembeded
                            • 11. Re: ARQ-33: General Configuration Module
                              germanescobar

                              Thanks Pete and Stuart for the feedback. Dan, great, it was really important to have your approval.

                              1. Does an XML stanza for a container need to be present to make it usable?

                              No. There will be always defaults. You don't even need an arquillian.xml file at all.

                              1. What's the best way to refer to a container configuration from the <container> element? By string id? (What if there's no XML for it, see #1?)
                              2. Do we want to consider having an activation framework?

                              Not sure about these. It will become really important when we support multiple containers on the classpath.

                               

                              I've attached a first patch of my original proposal with some minor changes:

                               

                              1. Changed XML namespace from http://www.jboss.org/products/arquillian to http://www.jboss.org/arquillian as Dan suggested.
                              2. Changed urn:java:... to urn:arq:... for the container configurations XML namespace; java has nothing to do with it (is not a a bean configuration language!).

                               

                              The junit and testng examples already contain the arquillian.xml file so that you can start playing with it ... you can also  remove it if you want (it is optional).

                               

                              TODO:

                               

                              • Only jbossas-remote-60 and glassfish-embedded-30 have a ContainerConfiguration implementation with really simple attributes. However, creating a ContainerConfiguration implementation or adding a property to an existing one is trivial.
                              • Provide a schema for each ContainerConfiguration implementation.

                               

                              Pete, it has no additional dependencies.

                              • 12. Re: ARQ-33: General Configuration Module
                                pmuir

                                Dan Allen wrote:

                                 

                                1. Do we want to consider having an activation framework?

                                 

                                By the last comment, what I mean is something like this:

                                 

                                <jbossremote:container>
                                   ...
                                   <activation>
                                      <property>
                                         <name>jbasremote</name>
                                      </property>
                                   </activation>
                                </jbossremote:container>

                                The idea here is that the user can do -Djbasremote to have the container activated?

                                 

                                Personally, I think this might be overkill unless we hear from users they really want this. I also think that it would be cleaner to have the user do -Darquillian.conf=~/project/deathstar/arquillian.xml to activate different configurations.

                                 


                                Dan Allen wrote:


                                Although namespace prefixes are chosen by the user, in the examples we should be sure to keep them clear, as I have done, for the type of container. For example:

                                 

                                • jbossremote
                                • jbossembeded
                                • gfembeded

                                 

                                Definitely.

                                • 13. Re: ARQ-33: General Configuration Module
                                  alrubinger

                                  I've started to implement the JBossAS Embedded Container for Arquillian and have a few initial impressions.

                                   

                                  @Deployment on the test case allows for a user to supply the archive intended for deployment.  Similarly, many backing containers (JBossAS included) have an object metadata model which provides configuration, and it'd be nice to allow the user to supply this.

                                   

                                  So if I may mock up at a high (ie. user) level:

                                   

                                  @Configuration
                                  public static ContainerConfiguration getConfig()
                                  {
                                    return new JBossASContainerConfiguration(  // Arquillian wrapper config class
                                       JBossASServerConfigFactory.createConfig().bindPort(8080).serverName("all").bindAddress("localhost")
                                    );
                                  }
                                  
                                  

                                  Then we might have typed configurations per container and give users the native DSL underlying (as I think Pete's getting at).  Mandating a config in schema is IMO unnecessary in some places.

                                   

                                  But I'll probably have to catch some of you guys in IRC to flesh this out further; I haven't fully delved into the new Container SPI changes.

                                   

                                  S,

                                  ALR

                                  • 14. Re: ARQ-33: General Configuration Module
                                    dan.j.allen

                                    Pete Muir wrote:

                                    Dan Allen wrote:

                                     

                                    1. Do we want to consider having an activation framework?

                                     

                                    By the last comment, what I mean is something like this:

                                     

                                    <jbossremote:container>
                                       ...
                                       <activation>
                                          <property>
                                             <name>jbasremote</name>
                                          </property>
                                       </activation>
                                    </jbossremote:container>

                                    The idea here is that the user can do -Djbasremote to have the container activated?

                                     

                                    Yes, just like with Maven. In fact, I was thinking of mimicking Maven's rules (for consistency).

                                     

                                    Personally, I think this might be overkill unless we hear from users they really want this. I also think that it would be cleaner to have the user do -Darquillian.conf=~/project/deathstar/arquillian.xml to activate different configurations.

                                     

                                    Ah! I like this idea too. The only issue is that the user must then divide up the configurations into multiple files, which is more difficult to maintain.

                                     

                                    Perhaps we can reach a common ground by having a built-in property that activates the container by id.

                                     

                                    -Darquillian.container=jbossas1

                                     

                                    That way, all the configurations can be in a single file (or even defined in Java). Each container configuration must have an id and the commandline tells Arquillian which container to use.

                                    1 2 Previous Next