The configuration process begins in the web.xml for a web application, or ejb-jar.xml for an EJB. In either case, a service-ref element is added for each web service. The XML is the same for both web applications and EJBs, the only difference is that a service reference is added at the top level of a web application, but scoped to a single EJB in an EJB JAR.

A service-ref typically looks like this:

<web-app xmlns:ger="geronimo-book:reviews"
   ...
  <service-ref>
    <service-ref-name>service/ProductReviews</service-ref-name>
    <service-interface>
      reviews.client.ProductReviewsService
    </service-interface>
    <wsdl-file>WEB-INF/ProductReviews.wsdl</wsdl-file>
    <jaxrpc-mapping-file>
      WEB-INF/ProductReviewsMapping.xml
    </jaxrpc-mapping-file>
    <service-qname>ger:ProductReviewsService</service-qname>
  </service-ref>

The elements here are:

The standard service-ref element is sufficient to contact the remote web service under normal circumstances. However, there are some cases where it's necessary to add additional settings to the Geronimo deployment plan for the service reference:

The Geronimo deployment plan can select a port and/or binding, provide a URL to the service, and identify additional credentials configured for a Geronimo user that should be used to authenticate to the service. The specific syntax used to complete a service-ref in the Geronimo plan is described in more detail in Section 11.3.4.5, “Web Service References” and Section 12.3.6.7, “Web Service References”.

For example, a block used to override the URI specified in the WSDL for the service-ref above might look like this:

<service-ref>
  <service-ref-name>service/ProductReviews</service-ref-name>
  <port>
    <port-name>ProductReviews</port-name>
    <protocol>http</protocol>
    <host>server.domain.com</host>
    <port>80</port>
    <uri>/new/path/to/ProductReviews</uri>
  </port>
</service-ref>

The Geronimo web service client infrastructure is capable of authenticating to a remote web service that requires it. However, Geronimo does not save a user's password by default, so it does not have enough information to pass a username and password to the remote service. For this to work, the calling application must use a security realm specially configured to save the user's username and password, and then the Geronimo deployment plan for the service-ref must describe how to find those credentials.

<configuration configId="MyRealm"
        xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0">
  <gbean name="MyRealm"
 class="org.apache.geronimo.security.realm.GenericSecurityRealm">
    <attribute name="realmName">MyRealm</attribute>
    <reference name="ServerInfo">
      <gbean-name>geronimo.server:J2EEApplication=null,
        J2EEModule=geronimo/j2ee-system/1.0/car,
        J2EEServer=geronimo,j2eeType=GBean,name=ServerInfo
      </gbean-name>
    </reference>
    <reference name="LoginService">
      <gbean-name>geronimo.server:J2EEApplication=null,
        J2EEModule=geronimo/j2ee-security/1.0/car,
        J2EEServer=geronimo,j2eeType=JaasLoginService,
        name=JaasLoginService
      </gbean-name>
    </reference>
    <xml-reference name="LoginModuleConfiguration">
      <log:login-config
   xmlns:log="http://geronimo.apache.org/xml/ns/loginconfig-1.0">
        <log:login-module control-flag="REQUIRED"
                   server-side="true" wrap-principals="false">
          <log:login-domain-name>
            MainDomain
          </log:login-domain-name>
          <log:login-module-class>
            org.apache.geronimo.security.realm.providers.
                                       PropertiesFileLoginModule
          </log:login-module-class>
          <log:option name="usersURI">
            var/security/users.properties
          </log:option>
          <log:option name="groupsURI">
            var/security/groups.properties
          </log:option>
        </log:login-module>
        <log:login-module control-flag="REQUIRED"
                   server-side="true" wrap-principals="false">
          <log:login-domain-name>
            NamedDomain
          </log:login-domain-name>
          <log:login-module-class>
   org.apache.geronimo.security.jaas.NamedUPCredentialLoginModule
          </log:login-module-class>
          <log:option
name="org.apache.geronimo.jaas.NamedUPCredentialLoginModule.Name"
                     >
            WebServices
         </log:option>
        </log:login-module>
      </log:login-config>
    </xml-reference>
  </gbean>
</configuration>

<service-ref>
  <service-ref-name>service/ProductReviews</service-ref-name>
  <port>
    <uri>/path/to/ProductReviews</uri>
    <credentials-name>WebServices</credentials-name>
  </port>
</service-ref>

In order for a web service client to work, the WAR or EJB JAR must contain:

Beyond that, there are no particular packaging or deployment issues -- the WAR or EJB JAR can be deployed like normal, either standalone or as part of an EAR.

A J2EE component can look up the client service interface in JNDI (at the location configured in the service-ref), use that to get an instance of the service endpoint interface, and use that to communicate with the service. For example, based on the configuration above:

Context ctx = new InitialContext();
Object obj = ctx.lookup("java:comp/env/service/ProductReviews");
ProductReviewsService service = (ProductReviewsService) obj;
ProductReviews port = service.getProductReviews();
String[] reviewers = port.getReviewers(productId);
...