Attachment: Added: EsbProjectWithLib.esb

This is a configurable option in the ESB. For more information please refer to this wiki page: http://www.jboss.org/community/wiki/JBossAS5integrationforESB4x

Ok, makes sense.  I verified that if I put the .jar in a "jars" directory or in the base .esb archive directory, then it works.

However, I don't think that is an acceptable solution to this Jira for two reasons:

1.)  JBDS creates an ESB project with a lib directory where users have been and will continue to assume that .esb dependent jars will need to go.  By default, that's not going to work for them anymore.

2.)  Existing users (like myself) are going to have .esb archives where the jars are in the "lib" directory and they work on SOA-P 4.3, but will not work on SOA-P 5.0

I would recommend that the configuration default to "lib" instead of "jars".  If we want to allow both, that's fine too.  But until JBDS is changed, I think "MyEsb.esb/lib" needs to be a default location for jars that the esb services are dependent on.

We can certainly have both and more options if you have any other suggestions too. Please create a jira in the ESB project for this and I'll make sure it gets done. 

If this is a requirement for the platform then would updating deployers/esb.deployer/META-INF/esb-deployers-jboss-beans.xml be an option until we have updated the ESB project file:
 <property name="libs">
            <set elementClass="java.lang.String">
                <value>.</value>
                <value>jars</value>
                <value>lib</value>
            </set>
</property>

Thanks 

Link: Added: This issue related JBESB-2972

Link: Added: This issue is related to JBESB-2972

Link: Removed: This issue is related to JBESB-2972 

I've created the requested ESB jira (JBESB-2972) and linked to this Jira.  I really don't care as much what we decide to do on the ESB community side, I'm just trying to make sure SOA-P 5 is a smooth transition for my SOA-P 4.3 users.

Personally, I would just leave lib as the default unless there is a compelling reason to add a "jars" folder instead of a "lib" folder.  If there is a compelling reason for the change, then I would recommend leaving both of them until JBDS has been updated to create a "jars" folder in an ESB project instead of a "lib" folder.

Workaround Description: Added: Move .jar files to the root directory or "jars" directory of the .esb archive.

For new customers building new apps, the different "jar" name will not be a problem.

But - as Aaron says - for 4.3 users, the different name may cause confusion, and will require (manual) migration steps.

Why can't we have the default remain as 'lib' and document how users can define their own specific values?

The problem is that there never *was* a default location.  The as4 behaviour was to recursively discover jars/deployments and deal with them, whereas the as5 behaviour has changed.

This will 'break' all deployments which contained nested jars etc, and is a consequence of moving to as5.

There are other restrictions, besides this.

The other point to note is that the 'standard', as defined by our quickstarts, is to place the jars in the top level of the esb archive and this does work.

We could debate what defines "standard" in this case, but it would probably not be productive.  I just did a quick scan of the docs to see if our docs discuss this and I didn't see anything, so created this Jira:  JBESB-2974

Please note that this will still likely be an issue for new customers if they are using JBDS (which at least most of my new customers do).  When one creates an ESB project with JBDS, the ESB project has a "lib" directory automatically created.  I think most users will assume that is where JAR libraries go.  That's where I put my libraries before I started testing SOA-P 5 ER2.

One thing I haven't heard yet is the reason for the change to have a specific "jars" directory.  If the quickstarts put jars in the root directory and JBDS creates a "lib" dir for each ESB project, why did we create a different directory altogether for jars to go in?

Link: Added: This issue is related to JBESB-2974

Debating it is not the issue, but giving us your requirement is.  What we have is a starting point and, while it will definitely not suit everybody, it does fit with the examples as *we* provide them.

As this change is part of the underlying AS, I would hope that there is EAP documentation that describes it.  In any case we do describe it in our wiki, as pointed out by Daniel earlier, and I'm sure this can be incorporated into the platform docs if necessary.

The ESB issue has been changed into a Feature Request, please add all your requirements to that task.

My requirements would be twofold:

1.)  ESB archives that deploy successfully on SOA-P 4.3 should also deploy successfully on SOA-P 5.0 unless there was some absolutely necessary change that will not allow us to maintain backward compatibility and therefore we are going to advertise it as clearly and obviously as possible to ease customer migration pains.

2.)  Whether JBDS is part of the ESB "we" team or not, our customers use them together and we want them to use them together.  Therefore, the projects and conventions that are created by the JBDS ESB plugin should work with the SOA-P.  Concretely, if JBDS creates an ESB project by default containing a lib directory, SOA-P should by default load JARs that are placed in that lib directory. 

As to the documentation, I hope we do not expect SOA-P users to look at EAP docs to figure out how to deploy JARs in .esb archives.  So yes, please incorporate this documentation into the platform docs. 

1 - If it is something which is directly under our control then that should be the case

2- Not sure what JBDS is doing but, as far as I am aware, the version targeted for SOA 5 is still under development.

Please add your requirements to the JBESB issue so that we can flesh it out and investigate a way forward.

This sounds like a backward compatibility issue therefore it needs to be documented at a minimum in the SOA-P5 docs.   I have asked Brian F to provide comment on the JBDS side of things.

Okay, it seems that what I am trying to say is not clear enough so let me try again.

In many respects JBDS and lib/*.jar are irrelevant to this discussion.  AS4 allows any user of ESB the ability to use any structure they wish, and it works.  As 5 does not allow this as we currently have to be explicit.

If we just do what has been asked, 'fixing lib/*.jar' then something else will undoubtedly come up.  If we are going to enforce a structure, without people needing to add a simple xml file, then we need to step back and document what is *really* needed.

There are many structure being used out there, and nearly all of them will fail in some way with the move to as5.

as5 is a very different base from as4, with different requirements.

We need to gather broad requirements about what is needed, not just a single facet.

from my pov 90% of this is purely a runtime issue not specific to JBDS.

That being said I always had a really weird feeling about .esb archives since I haven't been able to find 
any good explanation of the classloader logic for .esb's  (i.e. why aren't it just following standard EAR or Jar packaging
instead of mixing them both ?)

anyway, the current structure is based on the ESB docs and based on how the quickstarts looked for ESB 4.x afaik.

If we need something different for SOA-P 5 (and it's matching ESB?) we need to be told - but why change from lib to jars ? lib is the standard name used in EAR's for jar's that should be automatically added. Why another ?

In my opinion stick with having /lib since that is what worked and were used before ?

Max, I completely agree with you that this should be a runtime issue and this would be the case, if we had a proper (enforceable) structure.

Unfortunately the as4 deployer did not disable the app server's 'russian doll' behaviour and this is why we are having this discussion.

As for the /lib structure, we have never had that.  It only worked for the JBDS deployments until now *because of* the 'russian doll' behaviour of the application server.  In the same manner, many other users of ESB have *their own* structure which also works as a consequence of that behaviour.

As I said earlier, focussing on /lib/*.jar is the *wrong problem*.

Ok, but could we then be told what structure we should use instead ? Preferably one that works both on SOA 4 and SOA 5 so we dont have to maintain redundant behavior 

Saying you don't have /lib structure might be true for the core runtime not knowing specifically about it but both docs, examples, the tooling and the actual execution worked with /lib.

Our docs and examples definitely do not deploy a lib directory, not sure about the JBDS ones.

Irrespective of that, what I am trying to get people to realise is that this issue extends well beyond adding /lib/*.jar to the classpath, for JBDS or otherwise.  I have already asked for explicit requirements to be attached to JBESB-2972 but so far nothing has been added.  My concern is that what is being asked for is not properly understood and that this will keep rolling on unless we take the time and address it properly.

Failing that the fallback options are as already described, adding a jboss-structure.xml to the deployment or changing the ESB deployer configuration.  I don't want to do the latter without full agreement of what is required.

Link: Added: This issue related SOA-1835

Link: Added: This issue related SOA-1837

Adding as a migration issue in the SOA 5.0.0 Release Notes:

The JBoss Enterprise SOA Platform 5.0 requires that JAR files in ESB archives are placed in either the
root directory of the archive or in the jars directory. Previous versions did not have this restriction.

JBoss Developer Studio creates ESB projects with a lib directory. Do not use this directory to store JAR files.

Link: Added: This issue related JBIDE-5740

Sorry Darrin, the comment about the lib directory is now out of date.

JBESB-2972 has recently added jars in the lib directory to the classpath, explicitly for supporting JBDS.

ok, migration issue note updated to:

The JBoss Enterprise SOA Platform 5.0 requires that JAR files in ESB archives are placed in the root directory of the archive, the /jars directory, or the /lib directory . Previous versions did not have this restriction.  

Len is going to create a separate issue for the doc changes, just to track separately.

This is now just representing the code changes.

Link: Added: This issue depends SOA-1927

Verified in CR1 build.