#269 J2EE client application deployment support added

[Scott M Stark]

Support for j2ee client application jars has been added
to the 3.2.3RC2 release
codebase. The default and all deploy directories
contain a client-deployer-service.xml
which handles jars containing a
META-INF/application-client.xml descriptor.

An application client jar basically defines an
enterprise naming context (java:comp/env)
for use by remote clients. The purpose is the same as
the server side ENC;
isolation of code from hard-coded deployment time JNDI
name bindngs.

To create an application client jar you need to:

1. Code the standard application-client.xml descriptor
to define the ejb-refs,
resource-refs, resource-env-refs the client application
will use. The
JAAS callback-handler element is not yet supported but
will be soon.

2. Code a jboss-client.xml descriptor which maps the
ENC references to the
deployed resource JNDI bindings. This is basically the
same as the current
jboss-web.xml descriptor, with the addition of a
jndi-name element which
specifies the location in the sever JNDI namespace to
which the client
ENC bindings will be store. If the
jboss-client/jndi-name is not specified
then the JNDI name will default to the required
application-client/display-name
value.

To use an application client jar you include it the ear
along with any other
j2ee components and deploy the ear as normal. The java
client code then
needs to create an InitialContex with two new settings
in order to be
able to lookup a meaningful java:comp/env context.

1. The Context.URL_PKG_PREFIXES must specify the
org.jboss.naming.client
package prefix to pickup the java URL context factory
for client applications.

2. A custom j2ee.clientName property must specify the
jndi name of the
application ENC bindings on the server. This is either
the jboss-client/jndi-name
or the application-client/display-name.

The following fragment from the
org.jboss.test.client.test.AppClientUnitTestCase
illustrates these steps.

private Context getENC() throws NamingException
{
Properties env = new Properties();
env.setProperty(Context.INITIAL_CONTEXT_FACTORY,
"org.jnp.interfaces.NamingContextFactory");
env.setProperty(Context.URL_PKG_PREFIXES,
"org.jboss.naming.client");
env.setProperty(Context.PROVIDER_URL,
"jnp://localhost:1099");
env.setProperty("j2ee.clientName", "test-client");
InitialContext ctx = new InitialContext(env);
Context enc = (Context) ctx.lookup("java:comp/env");
return enc;
}

Attached is a sample app-client.jar used by the
AppClientUnitTestCase
which contains sample application-client.xml and
jboss-client.xml
descriptors.

[starksm@banshee testsuite]$ jar -tf
output/lib/app-client.jar
META-INF/
META-INF/MANIFEST.MF
META-INF/application-client.xml
META-INF/jboss-client.xml

[Scott M Stark]

sample app-client.jar