11.3.2. Service references

The JAX-RPC examples in Section 11.3.1, “A JAX-RPC client” all required manual configuration of the WSDL URL and knowledge of the XML nature of the web services in question. This can be a configuration nightmare, but if your code is a J2EE component there is another option. J2EE components can declare service references and look up preconfigured Service objects in JNDI without needing to hardcode any web service references in the code.
To show how this works, let's first look at a session bean that needs to make a call to the hello web service: 
package org.jboss.ws.example;

import javax.ejb.*;
import javax.naming.*;
import java.rmi.RemoteException;           
                
import javax.xml.rpc.Service;
import javax.xml.rpc.ServiceException;

import org.jboss.ws.hello.Hello;

public class ExampleBean
    implements SessionBean
{
    public String doWork()
    {
        try {
            Context ctx     = new InitialContext();

            Service service = (Service) ctx.lookup("java:comp/env/services/hello");
            Hello   hello   = (Hello)   service.getPort(Hello.class);
            
            return hello.hello("example bean");
        } catch (NamingException e) {
            throw new EJBException(e);
            
        } catch (ServiceException e) {
            throw new EJBException(e);
            
        } catch (RemoteException e) {
            throw new EJBException(e);
        }
    }

    public void ejbCreate() {};
    public void ejbRemove() {};

    public void ejbActivate() {}
    public void ejbPassivate() {}

    public void setSessionContext(SessionContext ctx) {}
}
ExampleBean invokes the hello web service in its doWork method. We've used the dynamic proxy invocation method here, but any of the JAX-RPC supported invocation methods would be fine. The interesting point here is that the bean has obtained the Service reference from a JNDI lookup in its ENC.
Web service references are declared using a service-ref element in inside an ejb-jar.xml file.
The service-ref content model

Figure 11.3. The service-ref content model

The following elements are supported by the service-ref:
  • service-ref-name: This is the JNDI name that the service object will be bound under in the bean's ENC. It is relative to java:comp/env/.
  • service-interface: This is the name of JAX-RPC service interface the client will use. Normally this is javax.xml.rpc.Service, but it's possible to provide your own service class.
  • wsdl-file: This is the location of the WSDL file. The WSDL file should be under META-INF/wsdl.
  • jaxrpc-mapping-file: This is the location of the JAX-RPC mapping file. It must be under the META-INF directory.
  • service-qname: This element specifies the name of the service in the web services file. It is only mandatory if the WSDL file defines multiple services. The value must by a QName, which means it needs to be a namespace qualified value such as ns:ServiceName where ns is an XML namespace valid at the scope of the service-qname element.
  • port-component-ref: This element provides the mapping between a service endpoint interface and a port in a web service.
  • handler: This allows the specification of handlers, which act like filters or interceptors on the current request or response.
The following service-ref declares a reference to the hello web service for the Example session bean. 
<session>
    <ejb-name>Example</ejb-name>
    <home>org.jboss.ws.example.ExampleHome</home>
    <remote>org.jboss.ws.example.Example</remote>
    <ejb-class>org.jboss.ws.example.ExampleBean</ejb-class>
    <session-type>Stateless</session-type>
    <transaction-type>Container</transaction-type>
    <service-ref>
        <service-ref-name>services/hello</service-ref-name>
        <service-interface>javax.xml.rpc.Service</service-interface>
        <wsdl-file>META-INF/wsdl/hello.wsdl</wsdl-file>
        <jaxrpc-mapping-file>META-INF/mapping.xml</jaxrpc-mapping-file>
        <service-qname xmlns:hello="http://hello.ws.jboss.org">
            hello:HelloService
        </service-qname>
    </service-ref>
</session>
This instructs the EJB deployer to make a Service object available for the bean in JNDI under the name java:comp/env/services/hello that talks to our hello web service. The session bean can then invoke normal web services operations on the service.
Since most of the web services configuration options are completely standard, there's little need to go into great depths here. However, JBoss does provide several additional web services configuration options through the service-ref element in the jboss.xml deployment descriptor. The content model for the service-ref element is shown in Figure 11.4, “The jboss.xml service-ref content model”.
The jboss.xml service-ref content model

Figure 11.4. The jboss.xml service-ref content model

The configurable elements are:
  • service-ref-name: This element should match the service-ref-name in the ejb-jar.xml file that is being configured.
  • port-component-ref: The port-component-ref element provides additional information for a specific port. This includes properties that should be associated with the JAX-RPC stub for the port.
  • wsdl-override: This provides an alternate location for the WSDL file. The value can be any valid URL. This can be used in co-ordination with the wsdl-publish-location to get the final WSDL file for a locally published web service. It could also be the URL of a remotely published WSDL that you don't want duplicated in the deployment file.
  • call-property: This sets properties on the JAX-RPC stub.
Since the WSDL file generated by wscompile doesn't contain the SOAP address of our web service, we'll use the WSDL override feature to dynamically download the correct WSDL file from the server. While this might not be the best technique to use in a production application, it does illustrate the WSDL override functionality very well. The following jboss.xml file links the published URL for the hello-servlet version of the hello web service.. 
<!DOCTYPE jboss PUBLIC
          "-//JBoss//DTD JBOSS 4.0//EN"
          "http://www.jboss.org/j2ee/dtd/jboss_4_0.dtd">
<jboss>
    <enterprise-beans>
        <session>
            <ejb-name>Example</ejb-name>
            <service-ref>
                <service-ref-name>services/hello</service-ref-name>
                <wsdl-override>http://localhost:8080/hello-servlet/Hello?wsdl</wsdl-override>
            </service-ref>
        </session>
    </enterprise-beans>
</jboss>
This example can be run as shown below: 
[examples]$ ant -Dchap=ws -Dex=3 run-example
...
run-example3:
     [echo] Waiting for 5 seconds for deploy...
     [copy] Copying 1 file to /tmp/jboss-4.0.4/server/production/deploy
     [echo] Waiting for 5 seconds for deploy...
     [java] output:Hello example bean!
The service-ref element is not limited to the ejb-jar.xml file. It's available to any J2EE component. A service reference can be placed in the web.xml file for use by web tier components or in the application-client.xml file for use by J2EE client applications.