Adding Web service references

Starting with the J2EE 1.3 specification, application components (application clients, Web modules, EJB modules) can define references to external Web services by using "logical" names called Web service references. In J2EE 1.3, the references are added to a webservicesclient.xml in a module. Beginning with J2EE 1.4, the reference is included in the deployment descriptor.

At deployment, the Web service references are bound to the Web service interfaces in the target operational environment.

For each Web service reference that you define, a service-ref element is added to that application component. Web service references are scoped to the application component or enterprise bean where they are defined, so they are not accessible to other application components or beans during run time. Other components can define Web service references with the same name without causing a name conflict.

Note: For project levels previous to the J2EE 1.4 specification level, the workbench allows you to define Web service references, but the service-ref elements are not added to the deployment descriptors (the application-client.xml, web.xml, or ejb-jar.xml). Rather, the Web service references are declared in a webservicesclient.xml file in the META-INF folder of the module. For example, if you add a Web service reference to a J2EE 1.3 application client, the reference is added to webservicesclient.xml. If you add a Web service reference to a J2EE 1.4 application client, the reference is added to application-client.xml.

Tip: The EJB specification recommends that you organize all Web service references in the service sub-context of the bean’s environment, the java:comp/env/service JNDI context.

To define a Web service reference:

  1. Open the Add Reference wizard from the deployment descriptor editor for your J2EE module.

  2. Select Service reference and click Next.

  3. From the list of Web services in your workspace, select the Web service that you want to reference.

  4. In the Name field, specify a name for the reference, or accept the default name provided by the wizard (recommended). The value entered in the Name field is used in the service-ref-name entry in the deployment descriptor. The value for the name is the environment entry name used in the enterprise bean code.

  5. Click Next.

  6. In the Description text area, enter a description for the reference.

  7. In the Namespace URI field, enter a new namespace URI or accept the value entered by the wizard. The value entered in this field is used as the xmlns:prefix attribute in the service-qname entry in the deployment descriptor.

  8. In the Local part field, indicate whether the message destination consumes or produces messages. The value entered in this field is used as the value in the service-qname entry in the deployment descriptor:
    <service-qname xmlns:prefix="http://service.directory">
        prefix:EmployeeDirectoryService
</service-qname>

  9. Click Finish.

 

Related concepts

Client Deployment Descriptor editor

 

Related tasks

Defining references in J2EE modules
Adding EJB references
Adding message destination references
Adding resource manager connection factory references
Adding resource environment references
Adding security role references