7 Replies Latest reply on Jul 23, 2010 9:05 PM by alrubinger

    Revisiting the WebArchive API

    dan.j.allen

      I still don't think we have the WebArchive API right. SHRINKWRAP-186 (META-INF target in a WebArchive) was just the tip of an iceburg. I think we need to step back and make sure we address the whole picture. What indicates to me that we are missing something is that there are still standard locations in a web archive that don't map to a method in the API.

       

      Here's the story. While addManifestResource() now maps to:

       

      /WEB-INF/classes/META-INF/

       

      addResource() maps to:

       

      /

       

      That's not intuitive. To be consistent with addManfiestResource(), I would expect addResource() to map to:

       

      /WEB-INF/classes/

       

      But I recognize that if that were the case, then there would be no way to put anything in the root, such as a web page.

       

      IMO, we are changing the definition of what the word "resource" means when we move from a Java archive to a web archive. We really have three types of resources:

       

      • classpath
      • web root
      • WEB-INF

       

      We need to address each of them.

       

      I propose three options (or perhaps some permutation of them):

       

      1. Let addResource map to / and introduce addClasspathResource that maps to /WEB-INF/classes
      2. Make addResource map to /WEB-INF/classes and introduce addWebRootResource that maps to /
      3. Make addResource map to /WEB-INF/classes, make addWebResource map to / and introduce addWebInfResource to map to /WEB-INF

       

      These reflect how my brain worked through this problem. I realized that the "web resource" is more suggestive of the web archive root (where resources accessible via the web go). A "resource" should continue to mean a classpath resource, which is WEB-INF/classes (I don't think we should do #1, because then it would be inconsistent with JavaArchive). And since we've used the word "web" for root resources, then we need to use "WebInf" (or perhaps WebConfig) to refer to WEB-INF.

       

      If you are hell-bent on keeping addWebResource mapped to WEB-INF, then let's use addWebRootResource to map to /.

       

      While there are several different options here, nothing is not one of them

        • 1. Re: Revisiting the WebArchive API
          aslak

          Similar suggestion/discussion:  http://community.jboss.org/message/546915#546915

          • 2. Re: Revisiting the WebArchive API
            alrubinger

            I like 1) very much.

             

            To that end, I've never much liked refitting "addResource" to different mapping locations depending upon the wrapped archive type.  I know Aslak and I debated this near-endlessly before.   In my mind the "Containers" are still there to specify inputs, not remap to impl-specific endpoints.  Currently they do both (ie. ClassContainer accepts inputs of type class and impls of ClassContainer can put them anywhere).

             

            How do we feel about a larger overhaul?

             

            • addResource, addClass, etc *always* goes to /
            • We add new method names which specify exactly what's gonna happen (ie. addWebInfResource, addMetaInfResource)
            • In other words, the output locations are doc'd as part of the method names and Container impls will never redirect anything

             

            S,

            ALR

            • 3. Re: Revisiting the WebArchive API
              aslak

              Andrew Rubinger wrote:

               

              In my mind the "Containers" are still there to specify inputs, not remap to impl-specific endpoints.  Currently they do both (ie. ClassContainer accepts inputs of type class and impls of ClassContainer can put them anywhere).

              Yes we have had this discussion many times.. and still I completely disagree.. ref: http://community.jboss.org/message/524027#524027

               

              The only reason they do both as you say, is because no one has been bugged enough to add addClass(File|URL) etc methods to the ClassContainer.

               

              addClass(Class) is a convenience method for the ClassContainer because the location to where the Container is mapped is based on Classes. It's where the reading party will look for classes.

               

              There is nothing wrong with having ResourceContainer.addResource(Class), it just makes little sense to have a Class as a resource in a archive.

               

               

              In a WebArchive there is absolutely no point in adding Classes to /. Nor is there any point in a WebArchive to add META-INF files in /META-INF. It's NOT where the reading party will be looking for that kinda of Assets.

               

              A Container is set of  convenience method for adding Assets to a specific location within the output Archive. The Container is named and it's convenience methods reflect the expected Assets for the Reader, not Writer.

              • 4. Re: Revisiting the WebArchive API
                alrubinger

                Aslak Knutsen wrote:

                 

                Yes we have had this discussion many times.. and still I completely disagree.. ref: http://community.jboss.org/message/524027#524027

                My issue with your argument isn't technical.  It's because the API's method names imply something about the action, and makes for what we see here - unexpected results.  This is made worse because the documentation currently leaks through down to the Container level JavaDoc, which says nothing (and can not say anything) about the target location.  So when you do "WebArchive.addResource" in the IDE, the docs that pop up don't say where it's gonna go.

                 

                If we're clear in the method names about the final output location, then the Containers will serve as both an input mechanism *and* an obvious key to where artifacts will go.  What is your disagreement with that approach?

                In a WebArchive there is absolutely no point in adding Classes to /. Nor is there any point in a WebArchive to add META-INF files in /META-INF. It's NOT where the reading party will be looking for that kinda of Assets.

                ShrinkWrap is a generic archive utility.  What's wrong with having WebArchive *not* implement ClassContainer as it stands (ie. no "addClass"), but instead provide for "addWebInfResource(Class<?>)" ?  That in my mind says a lot more about what's going to happen from both an input and output perspective.


                S,

                ALR

                • 5. Re: Revisiting the WebArchive API
                  aslak

                  Andrew Rubinger wrote:

                   

                  My issue with your argument isn't technical.  It's because the API's method names imply something about the action, and makes for what we see here - unexpected results.  This is made worse because the documentation currently leaks through down to the Container level JavaDoc, which says nothing (and can not say anything) about the target location.  So when you do "WebArchive.addResource" in the IDE, the docs that pop up don't say where it's gonna go.

                  I can agree that JavaDoc wise it could be confusing. We can add a lot more documentation to the Archive types explaining in detail how it works. We can put mapping tables etc in docs.

                  ( maybe we could write a JavaDoc processor to add the stuff we need? in worst case we can override the Container method in the Type archive just to add javadoc. )

                   

                  The unexpected results with WebArchive comes from Missing containers. The current design does not cover all the location within a WebArchive.

                   

                  Option 3 is the correct approach according to the initial design. Layout of option 3 is described in detail here: http://community.jboss.org/message/546915#546915

                   

                   

                  Andrew Rubinger wrote:

                  In a WebArchive there is absolutely no point in adding Classes to /. Nor is there any point in a WebArchive to add META-INF files in /META-INF. It's NOT where the reading party will be looking for that kinda of Assets.

                  ShrinkWrap is a generic archive utility.  What's wrong with having WebArchive *not* implement ClassContainer as it stands (ie. no "addClass"), but instead provide for "addWebInfResource(Class<?>)" ?  That in my mind says a lot more about what's going to happen from both an input and output perspective.

                   

                  Because from a generic perspective, a WebArchive can hold classes so it _is_ a ClassContainer.

                  • 6. Re: Revisiting the WebArchive API
                    dan.j.allen

                    Aslak Knutsen wrote:

                     

                    Andrew Rubinger wrote:

                     

                    My issue with your argument isn't technical.  It's because the API's method names imply something about the action, and makes for what we see here - unexpected results.  This is made worse because the documentation currently leaks through down to the Container level JavaDoc, which says nothing (and can not say anything) about the target location.  So when you do "WebArchive.addResource" in the IDE, the docs that pop up don't say where it's gonna go.

                    I can agree that JavaDoc wise it could be confusing. We can add a lot more documentation to the Archive types explaining in detail how it works. We can put mapping tables etc in docs.

                     

                    While it may be correct from a strictly dogmatic perspective to not do any remapping, one of the major appeals of ShrinkWrap--as I have observed from showing it to people--is that it "does the expected thing" per archive. For instance, classes in a WebArchive happen to be under WEB-INF/classes rather than at the root. I'm a pragmatist, and from a pragmatic perspective, this is the right thing to do.

                     

                    The unexpected results with WebArchive comes from Missing containers. The current design does not cover all the location within a WebArchive.

                     

                    Precisely. That's all I'm talking about here.

                     

                    Option 3 is the correct approach according to the initial design. Layout of option 3 is described in detail here: http://community.jboss.org/message/546915#546915

                     

                    Ah, I had lost track of that thread. Makes perfect sense.

                     

                    One thing I don't see in that table is what the method names will be. (Unless I'm missing something).

                     

                    I've always liked addManifestResource for adding to META-INF (though the manfiest can also refer to MANIFEST.MF). I don't think that addWebResource should point to WEB-INF though. I can't figure out what name I like for that directory, but I suppose from a purely practical perspective, addWebInfResource() gets the point across.

                     

                    Since WebArchive is a classpath container, I agree with having addResource() map to /WEB-INF/classes. And I think that opens the door for addWebResource() mapping to the root, since that is where the "web accessible resources" are located.

                     

                    In fact, according to the web archive "spec":

                     

                    Web components and static Web content files are called Web resources.

                     

                    But don't let me hold up the process. As long as there is something that covers these locations, I can live with it:

                     

                    • /
                    • /WEB-INF
                    • /WEB-INF/classes
                    • /WEB-INF/classes/META-INF
                    • /WEB-INF/lib

                     

                    The situation with /META-INF is actually a bit ambiguous. There seems to be disagreement about whether it's allowed at the root or not. For instance, Tomcat will look for a context.xml at /META-INF/context.xml. But this path is not part of the "standard", as far as I can gather. So I think it's reasonable to assume that this path can simply be created manually, if needed, as a root resource path. (Meaning, we shouldn't represent it's location in an archive spec).

                     

                    (Interesting to note that the /META-INF/resources directory of a JAR in /WEB-INF/lib is also considered part of the web application root. Again, not a path I think we should represent in an archive spec).

                     

                    Andrew Rubinger wrote:

                    In a WebArchive there is absolutely no point in adding Classes to /. Nor is there any point in a WebArchive to add META-INF files in /META-INF. It's NOT where the reading party will be looking for that kinda of Assets.

                    ShrinkWrap is a generic archive utility.  What's wrong with having WebArchive *not* implement ClassContainer as it stands (ie. no "addClass"), but instead provide for "addWebInfResource(Class<?>)" ?  That in my mind says a lot more about what's going to happen from both an input and output perspective.

                     

                    Because from a generic perspective, a WebArchive can hold classes so it _is_ a ClassContainer.

                     

                    I'm with Aslak here.

                    • 7. Re: Revisiting the WebArchive API
                      alrubinger

                      I caught Dan online one night after Aslak's bedtime, and we hashed things out a bit in real-time.  I think we've come closer to a workable proposal addressing all concerns.

                       

                      Bottom-line proposal:

                       

                      (08:16:06 PM) ALR: 1) We'll let archive spec types re-map locations (as they are now)
                      (08:16:35 PM) ALR: 2) We add explicitly the type of output location to the method name (ie. "addToWebRoot", "addToClasspath")
                      (08:16:59 PM) ALR: 3) Input type is determined by Java type system (String==ClassLoader resource, File==File, etc)

                       

                      The full text:

                       

                      (07:14:11 PM) ALR: mojavelinux: You know what's funny?
                      (07:16:10 PM) ALR: sarah: You know what's funny?
                      (07:16:27 PM) mojavelinux: hahaha
                      (07:16:47 PM) mojavelinux: busted
                      (07:19:18 PM) ALR: Hehe
                      (07:19:35 PM) ALR: mojavelinux: With regards to the ShrinkWrap remapping stuff.
                      (07:19:46 PM) ALR: mojavelinux: We agree in ideology mostly.
                      (07:19:55 PM) ALR: And interpret it very differently.
                      (07:22:52 PM) lightguard_jp left the room (quit: Ping timeout: 276 seconds).
                      (07:23:16 PM) mojavelinux: oh yeah?
                      (07:23:19 PM) mojavelinux: go on
                      (07:24:55 PM) ALR: mojavelinux: Well, it boils down to "the correct thing".
                      (07:25:06 PM) jdcasey left the room (quit: Remote host closed the connection).
                      (07:25:09 PM) ALR: Excuse me, "the expected thing".
                      (07:25:18 PM) ALR: Quoth mojavelinux: "While it may be correct from a strictly dogmatic perspective to not do any remapping, one of the major appeals of ShrinkWrap--as I have observed from showing it to people--is that it "does the expected thing" per archive"
                      (07:25:49 PM) ALR: To me:
                      (07:26:08 PM) ALR: WebArchive.addClass() is not as explicit as to what it's gonna do as:
                      (07:26:22 PM) ALR: WebArchive.addWebResource(Class)
                      (07:26:58 PM) ALR: Where everything in "addWebResource" always goes to "WEB-INF/classes", assuming (that may be poor naming for this example, but stay with me)
                      (07:27:34 PM) ALR: So we say like "addResource always goes to root, addManifestResource always goes to META-INF", etc.
                      (07:28:03 PM) ALR: Which in my view is both pragmatic (addresses all needs) and dogmatic (does so consistently).
                      (07:28:15 PM) ALR: And of course, the documentation would always say exactly what's to happen.
                      (07:28:31 PM) ALR: As opposed to the current docs, which at the class level say the action will be impl-specific
                      (07:29:08 PM) ALR: Aslak's last argument: "Because from a generic perspective, a WebArchive can hold classes so it _is_ a ClassContainer."
                      (07:29:18 PM) ALR: That's just naming.
                      (07:29:43 PM) ALR: It doesn't say anything about the desired postconditions of each action.
                      (07:30:30 PM) ALR: Under my proposal, we'd kill the notion of the container impls dictating the output locations.
                      (07:30:35 PM) ALR: And I could say:
                      (07:30:52 PM) ALR: "From a generic perspective, a WebArchive can hold classes, so it does."
                      (07:31:23 PM) ALR: addWebInfClassesResource(Class) // There's no question as to where this goes
                      (07:31:54 PM) mojavelinux: yikes, but there's no way developers will like that
                      (07:32:09 PM) mojavelinux: now, I do see this
                      (07:32:17 PM) mojavelinux: addResource(Class) -> /WEB-INF/classes
                      (07:32:24 PM) mojavelinux: cause that's the only place a class can go in a web archive
                      (07:32:29 PM) mojavelinux: however, it breaks down when you want to do
                      (07:32:41 PM) mojavelinux: addResource(String)
                      (07:33:01 PM) mojavelinux: because then it's not as obvious what the right thing to do is...if you are trying to stay generic
                      (07:33:08 PM) mojavelinux: now, I do see the case for being explicit there
                      (07:33:15 PM) mojavelinux: which is essentially what I'm requesting
                      (07:33:19 PM) mojavelinux: so like
                      (07:33:24 PM) mojavelinux: addWebResource goes to /
                      (07:33:32 PM) ALR: Can we back up?
                      (07:33:44 PM) ALR: Why won't developers like "addWebInfClassesResource(Class)" ?
                      (07:33:55 PM) ALR: You hit ".", the IDE pops up all available stuff.
                      (07:34:15 PM) ALR: Which essentially amounts to a list of output locations, overloaded with the types of things you can put in there.
                      (07:34:34 PM) mojavelinux: cause it's way too explicit...in that case it seems like ShrinkWrap is trying to be too detailed
                      (07:34:51 PM) ALR: Or just "addWebInfClasses(Class)"
                      (07:35:09 PM) mojavelinux: my reaction would be...hmm "you could have just said "add classes" cause yes, that's where it goes
                      (07:35:10 PM) ALR: mojavelinux: *Too* explicit?
                      (07:35:26 PM) mojavelinux: it's like "well where else would it go?" kind of reaction
                      (07:35:30 PM) ALR: addClass to you says where it goes?
                      (07:35:36 PM) mojavelinux: i'm just saying, let's not be too ridiculous
                      (07:35:42 PM) mojavelinux: in a web archive, yes
                      (07:35:54 PM) ALR: addClass to me says what you're adding.
                      (07:36:12 PM) mojavelinux: I think we want to leave fundamental understanding to some degree...if there is even a bit of fuzziness, then I'm with you, we need to be more explicit in the naming
                      (07:36:26 PM) ALR: Yeah, I've always been fuzzy on this.
                      (07:36:29 PM) mojavelinux: ah
                      (07:36:31 PM) ALR: Even when implementing the code.
                      (07:36:36 PM) mojavelinux: I see where we are disconnecting
                      (07:36:37 PM) ALR: Like I've done it totally backwards
                      (07:36:42 PM) mojavelinux: okay, so this goes back to what I was saying before
                      (07:36:44 PM) ALR: Then had to rethink it.
                      (07:36:50 PM) mojavelinux: sorry, at the top of the post
                      (07:36:56 PM) mojavelinux: what do we call that target?
                      (07:37:02 PM) mojavelinux: and I say, it's the classpath
                      (07:37:04 PM) ALR: Which target?
                      (07:37:05 PM) mojavelinux: so, it would be
                      (07:37:09 PM) mojavelinux: /WEB-INF/classes
                      (07:37:13 PM) mojavelinux: so I would say that's the classpath
                      (07:37:16 PM) mojavelinux: so, it would be
                      (07:37:19 PM) ALR: You're closer.
                      (07:37:20 PM) mojavelinux: addClasspathResource(Class)
                      (07:37:26 PM) mojavelinux: or addClasspathResource(String)
                      (07:37:29 PM) mojavelinux: clear where it goes
                      (07:37:30 PM) ALR: IDK about the word "classpath"
                      (07:37:32 PM) ALR: But Yes.
                      (07:37:45 PM) mojavelinux: classes resource I guess you could do as well
                      (07:37:49 PM) ALR: (Just because "ClassPath" to me means --classpath, ie. appCL
                      (07:38:04 PM) ALR: But that could be getting out of hand.
                      (07:38:12 PM) ALR: Let's call it "classpath" for now.
                      (07:38:22 PM) mojavelinux: I mean, if you sat a developer down
                      (07:38:28 PM) mojavelinux: pointed at the folder and said "what do you call that"
                      (07:38:32 PM) mojavelinux: they would more than likely say
                      (07:38:33 PM) mojavelinux: "classpath"
                      (07:38:37 PM) ALR: OK: addClasspathResource
                      (07:38:49 PM) ALR: addClasspathResource(String); // What does this do?
                      (07:39:09 PM) mojavelinux: let's assume it's "com/acme/messages.properties"
                      (07:39:17 PM) mojavelinux: -> /WEB-INF/classes/com/acme/messages.properties
                      (07:39:29 PM) ALR: Where is "com/acme/messages.properties" ?
                      (07:39:53 PM) ALR: (ie. where is the input?)
                      (07:40:08 PM) mojavelinux: in the root of the project classpath
                      (07:40:14 PM) mojavelinux: either src/main/resources
                      (07:40:17 PM) mojavelinux: or src/test/resources
                      (07:40:19 PM) mojavelinux: in Maven project
                      (07:40:29 PM) ALR: So it's adding a ClassLoader resource as a classpath resource to the archive.
                      (07:40:35 PM) mojavelinux: yep
                      (07:40:43 PM) mojavelinux: exactly
                      (07:40:48 PM) ALR: Now we can't overload the method to accept the String denoting a File.
                      (07:40:48 PM) mojavelinux: or you could say
                      (07:40:56 PM) ALR: ^ Is what I'm getting at
                      (07:41:10 PM) mojavelinux: adding a resource which is located by the ClassLoader and adding it to the classpath of the web archive
                      (07:41:32 PM) asgeirf [~asgeirf@redhat/jboss/asgeirf] entered the room.
                      (07:42:10 PM) mojavelinux: not sure which example you are citing...you are more familiar with the overloads than me
                      (07:42:18 PM) mojavelinux: btw, when we have addClasspathResource
                      (07:42:24 PM) mojavelinux: then addWebResource is so obvious
                      (07:42:29 PM) mojavelinux: no one would misunderstand that
                      (07:42:32 PM) mojavelinux: if I said
                      (07:42:32 PM) ALR: addClasspathResource(String); // String cannot be a filename
                      (07:42:37 PM) mojavelinux: addWebResource("index.html")
                      (07:43:47 PM) mojavelinux: are you saying that today
                      (07:43:55 PM) mojavelinux: addResource(String) can be sourced from a file name?
                      (07:44:12 PM) mojavelinux: I would seek to change what it does today
                      (07:44:13 PM) ALR: IMO it should be able to.
                      (07:44:14 PM) mojavelinux: so I would say
                      (07:44:26 PM) ALR: "addXXX" methods should be able to accept any input
                      (07:44:27 PM) mojavelinux: adding a resource which is a relative file path or located by the ClassLoader and adding it to the classpath of the web archive
                      (07:44:31 PM) ALR: And always put 'em in the same place
                      (07:44:37 PM) ALR: Which to me is the most deterministic.
                      (07:45:07 PM) mojavelinux: right, so the locator algorithm doesn't change
                      (07:45:26 PM) ALR: I wish that determinism didn't come at the expense of concision.
                      (07:46:49 PM) ALR: addClassAsClassPath(Class)
                      (07:47:03 PM) ALR: addFileAsClassPath(String)  addFileAsClassPath(File)
                      (07:47:14 PM) ALR: addClassLoaderResourceAsClassPath(String)
                      (07:47:23 PM) ALR: I know what's happening with each of those.
                      (07:47:47 PM) ALR: *And* because the naming is so obvious I can see WebArchive putting em in a different place from JavaArchive
                      (07:48:05 PM) ALR: "addClass" to me definitely reads:
                      (07:48:11 PM) ALR: "Add this class to the archive"
                      (07:52:16 PM) mojavelinux: oh, I see
                      (07:52:26 PM) mojavelinux: you are say we should be explicit about the source
                      (07:52:38 PM) mojavelinux: but if it's a file
                      (07:52:39 PM) ALR: Otherwise you don't know what the source is.
                      (07:52:43 PM) mojavelinux: why not just require that it be a File
                      (07:52:48 PM) ALR: Because a source can be typed in N ways
                      (07:52:52 PM) mojavelinux: and assume that a string is a classpath resource
                      (07:52:59 PM) ALR: I don't think that
                      (07:53:05 PM) ALR: 's a safe assumption.
                      (07:53:06 PM) mojavelinux: so like
                      (07:53:24 PM) mojavelinux: addClasspathResource(new File("relativepath/foo.xml"), "foo.xml")
                      (07:53:39 PM) ALR: Haha, still that grammar kills me.
                      (07:53:57 PM) ALR: "addClasspathResource" isn't adding a classpath resource
                      (07:54:10 PM) ALR: It's adding it *as* a classpath resource
                      (07:54:29 PM) ALR: Like when I'm following a receipe:
                      (07:54:33 PM) ALR: "Add salt"
                      (07:54:43 PM) ALR: I add salt *to* the pot.
                      (07:54:55 PM) ALR: I don't add something which then the pot turns into salt.
                      (07:55:07 PM) ALR: A silly analogy, perhaps.
                      (07:55:36 PM) ALR: But honestly I wouldn't bring it up if I didn't mess this up while working w/ SW really often.
                      (07:55:43 PM) ALR: I've always found there to be some disconnect.
                      (07:57:06 PM) mojavelinux: I'd be okay with addAs
                      (07:57:29 PM) ALR: Let's see what I can get away with then:
                      (07:57:32 PM) mojavelinux: addAsClasspathResource
                      (07:57:34 PM) ALR: "addAsClass" ?
                      (07:57:37 PM) ALR: Right
                      (07:57:40 PM) mojavelinux: well, in that case
                      (07:57:43 PM) ALR: I like addAsClasspathResource
                      (07:57:44 PM) mojavelinux: there is a 1-to-1 mapping
                      (07:57:49 PM) mojavelinux: and then the addAs isn't needed
                      (07:57:52 PM) mojavelinux: because it isn't changing
                      (07:57:54 PM) ALR: "addAsClass" was my example of what Not To Do
                      (07:58:10 PM) mojavelinux: right, we need "As"
                      (07:58:17 PM) mojavelinux: when we are translating one thing's purpose to another
                      (07:58:24 PM) ALR: addAsClassPathResource(Class)
                      (07:58:25 PM) mojavelinux: that implies
                      (07:58:31 PM) mojavelinux: that it is going through a shift
                      (07:58:39 PM) ALR: addAsClassPathResource(String) // CL resource input
                      (07:58:45 PM) mojavelinux: right
                      (07:58:49 PM) ALR: addAsClasspathResource(File) // File
                      (07:58:55 PM) mojavelinux: I think that addClass() can certainly be a shorthand
                      (07:59:01 PM) mojavelinux: for addAsClasspathResource()
                      (07:59:08 PM) mojavelinux: oops
                      (07:59:13 PM) mojavelinux: addAsClasspathResource(Class)
                      (07:59:17 PM) ALR: Now it's *expected* that the spec archive impl will shift the definition of "classpath resource" to the appropriate output location.
                      (07:59:23 PM) mojavelinux: addToClasspath(Class) ?
                      (07:59:29 PM) mojavelinux: right
                      (07:59:36 PM) mojavelinux: addAsWebResource
                      (07:59:41 PM) mojavelinux: you know, this really starts to make sense
                      (07:59:44 PM) mojavelinux: because if I say
                      (07:59:47 PM) mojavelinux: addWebResource()
                      (07:59:51 PM) ALR: addClass() // Still not down with it changing output locations.
                      (08:00:06 PM) mojavelinux: you could look at that and say, wait, where is the web resource that I'm adding?
                      (08:00:13 PM) mojavelinux: I have a web thing?
                      (08:00:17 PM) ALR: Which I always have
                      (08:00:20 PM) mojavelinux: but no, it's addAsWebResource()
                      (08:00:26 PM) mojavelinux: and then you say
                      (08:00:28 PM) mojavelinux: now that makes sense
                      (08:00:38 PM) ALR: Yep.
                      (08:00:40 PM) mojavelinux: or
                      (08:00:43 PM) mojavelinux: you could use addTo
                      (08:00:48 PM) mojavelinux: that would be okay w/ me as well
                      (08:00:54 PM) mojavelinux: addAs and addTo pretty much the same
                      (08:00:58 PM) ALR: I liked "addTo" because it's shorter
                      (08:00:59 PM) mojavelinux: just how you look at it
                      (08:01:00 PM) ALR: But the term:
                      (08:01:05 PM) ALR: "addToClassPath"
                      (08:01:15 PM) ALR: To me sounds like you're altering the CP of the TCCL
                      (08:01:25 PM) ALR: Even though that would make no sense.
                      (08:01:31 PM) mojavelinux: not to me
                      (08:01:33 PM) mojavelinux: cause it's
                      (08:01:35 PM) ALR: Especially if it's archive.addToClassPath
                      (08:01:37 PM) mojavelinux: .addToClasspath
                      (08:01:48 PM) ALR: Yeah, the archive. adds some good context.
                      (08:01:56 PM) mojavelinux: it's "add to classpath of this archive"
                      (08:01:59 PM) ALR: Yep.
                      (08:02:02 PM) ALR: I'm with you there.
                      (08:02:04 PM) mojavelinux: so get this
                      (08:02:08 PM) ALR: "addTo" is a nice convention.
                      (08:02:08 PM) mojavelinux: on the radio today
                      (08:02:17 PM) mojavelinux: the DJ says they were interviewing some studio head
                      (08:02:19 PM) mojavelinux: and he said
                      (08:02:26 PM) mojavelinux: how do you know when I song is going to make it
                      (08:02:29 PM) mojavelinux: and he said
                      (08:02:35 PM) mojavelinux: you just get that tingly feeling
                      (08:02:42 PM) mojavelinux: I have that tingly feeling now
                      (08:03:17 PM) ALR: Hehe.
                      (08:03:25 PM) ALR: I'm looking through to see if this covers all cases.
                      (08:03:26 PM) mojavelinux: there's only one thing to reconcile here
                      (08:03:32 PM) mojavelinux: .addToWebResource()
                      (08:03:41 PM) ALR: Essentially what we're agreeing on is adding the word "To" to everything in the API.
                      (08:03:42 PM) mojavelinux: that sorts of reads better as .addAsWebResource()
                      (08:03:44 PM) mojavelinux: though
                      (08:03:46 PM) mojavelinux: you could say
                      (08:03:49 PM) ALR: And also specifying where.
                      (08:03:51 PM) mojavelinux: addToWebRoot()
                      (08:03:52 PM) ALR: I guess that's the key
                      (08:03:55 PM) mojavelinux: and that would make a ton of sense
                      (08:03:57 PM) ALR: We'll start specifying where.
                      (08:04:10 PM) mojavelinux: .addToManifest
                      (08:04:10 PM) ALR: And the Java type system defines the input.
                      (08:04:15 PM) mojavelinux: .addToWebInf
                      (08:04:16 PM) ALR: String == ClassLoader resource
                      (08:04:20 PM) ALR: File == File
                      (08:04:32 PM) ALR: Class == ClassLoader resource with some String namipulation magic
                      (08:04:36 PM) ALR: *manipulation
                      (08:04:51 PM) ALR: URL = contents of the stuff at URL location
                      (08:05:08 PM) mojavelinux: I think class gets a special case
                      (08:05:09 PM) mojavelinux: in that
                      (08:05:14 PM) mojavelinux: you have addClass(String)
                      (08:05:28 PM) ALR: Why break the convention?
                      (08:05:28 PM) mojavelinux: citing your String manipulation logic comment
                      (08:06:48 PM) mojavelinux: I don't know what it is
                      (08:07:01 PM) ALR: I'm unclear about that last bit?
                      (08:07:13 PM) mojavelinux: but some part of me holds on to the addClass() (and maybe even addResource()) to be convenience APIs
                      (08:07:25 PM) mojavelinux: basically, keep those two existing methods
                      (08:07:34 PM) mojavelinux: first, it would help not shock the hell out of people
                      (08:07:46 PM) mojavelinux: and two, well, I can't describe it
                      (08:07:52 PM) mojavelinux: that bit has always made sense
                      (08:08:09 PM) mojavelinux: it's when we start getting into specific types of archives, that we move past those methods
                      (08:08:22 PM) mojavelinux: to me
                      (08:08:33 PM) mojavelinux: addClass() says take this class reference, which I have and put it in the right place
                      (08:08:48 PM) mojavelinux: the only time that would breakdown
                      (08:08:54 PM) ALR: I could maybe be convinced.
                      (08:08:54 PM) mojavelinux: is if the archive had two places where classes could go
                      (08:09:11 PM) ALR: Lemme think some more on that bit?
                      (08:09:17 PM) mojavelinux: and in a sense, "resource" would be classpath resource
                      (08:09:18 PM) mojavelinux: though
                      (08:09:19 PM) mojavelinux: though
                      (08:09:23 PM) mojavelinux: I would still change the name
                      (08:09:24 PM) ALR: Also we have to get this right this time.
                      (08:09:27 PM) mojavelinux: to addClasspathResource()
                      (08:09:37 PM) mojavelinux: because resource never made any sense anyway...well, except that
                      (08:09:40 PM) mojavelinux: Maven uses that term
                      (08:09:44 PM) mojavelinux: src/main/resources
                      (08:09:49 PM) mojavelinux: really, it's src/main/classpathResources/
                      (08:10:00 PM) mojavelinux: but Maven was lazy, maybe it's just the "understood" thing
                      (08:10:19 PM) mojavelinux: oh, I know how maven was able to do that
                      (08:10:20 PM) mojavelinux: because
                      (08:10:23 PM) mojavelinux: it really reads
                      (08:10:28 PM) mojavelinux: src/mainClasspath/resources
                      (08:10:33 PM) mojavelinux: src/mainClasspath/classes
                      (08:10:36 PM) mojavelinux: main == classpath
                      (08:11:09 PM) mojavelinux: so anyway, I'm just thinking that for those two cases, we hold on to them
                      (08:11:10 PM) mojavelinux: now
                      (08:11:12 PM) mojavelinux: addWebResource()
                      (08:11:19 PM) ALR: I think my mind shut off.
                      (08:11:20 PM) mojavelinux: that is where we get into trouble and we don't want that
                      (08:11:24 PM) mojavelinux: because
                      (08:11:29 PM) mojavelinux: there is no direct translation
                      (08:11:39 PM) mojavelinux: you are somehow assuming that you yourself are a web archive
                      (08:11:52 PM) mojavelinux: in fact, someone could be confused to think
                      (08:12:01 PM) mojavelinux: that addWebResource takes a file from src/main/webapp
                      (08:12:04 PM) mojavelinux: when in fact it doesn't
                      (08:12:04 PM) mojavelinux: so
                      (08:12:08 PM) mojavelinux: addToWebRoot()
                      (08:12:10 PM) mojavelinux: is a +1
                      (08:13:02 PM) mojavelinux: on a sidenote
                      (08:13:08 PM) mojavelinux: to actually add a file from src/main/webapp
                      (08:13:12 PM) mojavelinux: I guess you would have to do
                      (08:13:23 PM) mojavelinux: addToWebRoot("src/main/webapp/index.html", "index.html")
                      (08:13:34 PM) mojavelinux: or did you say it needed to be a file?
                      (08:13:46 PM) mojavelinux: addToWebRoot(new File("src/main/webapp/index.html"), "index.html")
                      (08:13:51 PM) mojavelinux: doesn't bother me either way, really
                      (08:13:55 PM) ALR: I'm still following.
                      (08:13:55 PM) mojavelinux: I trust you on that
                      (08:14:35 PM) ALR: First off, I don't factor Maven in anything we do.
                      (08:15:00 PM) ALR: Because pragmatic or not, this is a generic archive utility.
                      (08:15:09 PM) ALR: Pragmatism changes with context
                      (08:15:22 PM) ALR: Right now our context is "Maven-based builds targeting Arquillian"
                      (08:15:31 PM) ALR: But that could change the second someone comes up with another use.
                      (08:15:55 PM) ALR: I'd like to sum up some general rules:
                      (08:16:06 PM) ALR: 1) We'll let archive spec types re-map locations (as they are now)
                      (08:16:35 PM) ALR: 2) We add explicitly the type of output location to the method name (ie. "addToWebRoot", "addToClasspath")
                      (08:16:59 PM) ALR: 3) Input type is determined by Java type system (String==ClassLoader resource, File==File, etc)
                      (08:17:21 PM) ALR: Then all methods will follow those 3 rules.
                      (08:17:46 PM) ALR: It becomes a hybrid of what we have now.
                      (08:18:29 PM) ALR: mojavelinux: Confirm those and I'll type up a forum response to let Aslak weigh in?
                      (08:18:43 PM) ALR: At which point we'll probably do this all over again and come up with new rules.
                      (08:18:52 PM) ALR: In any case this is a sweeping change we can only get right once.
                      (08:18:59 PM) ALR: Else piss off everyone again. Hehe
                      (08:19:28 PM) mojavelinux: yes, confirmed
                      (08:19:39 PM) mojavelinux: and while this is a big change, we had a big moment
                      (08:19:45 PM) mojavelinux: that made us realize that we had a big hole
                      (08:19:53 PM) ALR: It was a moment for me too.
                      (08:20:08 PM) mojavelinux: cause we scrambled to start mapping things, realizing that there was uncertainty
                      (08:20:12 PM) ALR: Though for the longest time I was not properly communicating this hole.
                      (08:20:43 PM) ALR: Probably, I mean, Aslak and I have discussed this to death.
                      (08:21:05 PM) ALR: He probably near fainted when we saw my reply today bringing it up again.
                      (08:21:07 PM) ALR: Poor kid.