Writing Your Application

Connection Management API Definition

The FUSE Services Framework JCA Connector connection management API is packaged in org.apache.cxf.jca.outbound and consists of two interfaces:

CXFConnectionFactory
CXFConnection

The API is packaged in InstallDir/modules/integration/cxf-integration-jca-Version-fuse.jar.

The CXFConnectionFactory interface provides the methods to create a CXFConnection object that represents a Web service defined by the supplied parameters. It is the type returned from an environment naming context lookup of the FUSE Services Framework JCA Connector by a J2EE component and is the entry point to gaining access to a Web service.

The CXFConnection interface provides a handle to a connection managed by the J2EE application server. It is the super interface of the Web service proxy returned by the CXFConnectionFactory interface.

Usage pattern

To use the CXFConnectionFactory your application needs to:

Look up a CXFConnectionFactory object in the application server's JNDI registry.
Use the CXFConnectionFactory.getConnection() method to get a CXFConnection object.
The CXFConnectionFactory.getConnection() method takes one parameter, a CXFConnectionSpec object, which the has following fields:
- serviceName — the QName of the service. This is required.
- endpointName — the QName of the endpoint; i.e. the port name. This is required.
- wsdlURL — the URL of the WSDL file. Note that the URL can point to a WSDL file located in the application WAR file or to a location outside the application WAR file, such as a file location on a file system. For more information, see Finding WSDL at Runtime in Developing Applications Using JAX-WS.
- serviceClass — the service interface class. This is required.
- busConfigURL — the URL of FUSE Services Framework configuration, if such configuration exists. It allows you to configure directly the FUSE Services Framework runtime. This is optional.
  For more information on how to configure the Artix bus, see Configuring and Deploying Endpoints.
  For information on how to configure Artix security, see Security Guide.
  The busConfigURL setting overrides any configuration that has been set using the FUSE Services Framework JCA Connector busConfigLocation activation configuration property ( See Inbound Activation Configuration for more detail).
- address — the transport address. This is optional.
Use the CXFConnection.getService() method to obtain a Web service client.
Close the CXFConnection object.
Invoke on the service.
The Web service client can still be used after the CXFConnection object is closed.

Example of using the Connection Management API

The code shown in Example 3.1 shows how to use the FUSE Services Framework JCA Connector connection management API.

Example 3.1. HelloWorldServlet—Outbound Connections

Context ctx = new InitialContext();
CXFConnectionFactory factory = (CXFConnectionFactory)ctx.lookup(EIS_JNDI_NAME);

CXFConnectionSpec spec = new CXFConnectionSpec();
    spec.setServiceClass(Greeter.class);
    spec.setServiceName(new QName("http://apache.org/hello_world_soap_http", "SOAPService"));
    spec.setEndpointName(new QName("http://apache.org/hello_world_soap_http", "SoapPort"));
    spec.setWsdlURL(getClass().getResource("/wsdl/hello_world.wsdl"));
    CXFConnection connection = null;
    try {
          connection = getConnection(spec);
           
          Greeter greeter = connection.getService(Greeter.class);
          
          connection.close();
          
          greeter.sayHi();
...      
         }

The code shown in Example 3.1 does the following:

	Retrieves the connection factory from JNDI.
	Creates the connection and uses a `CXFConnectionSpec` object to specify: The service class. A QName that identifies which service in the WSDL file to use. A QName that identifies which port in the WSDL file to use The WSDL file URL.
	Obtains a Web service client.
	Closes the connection to the service and return to the application server connection pool. Remember you can close the connection and continue using the client.
	Invokes methods on the service.

Accessing request/response contexts

The outbound samples show how you can use message contexts.

For more information on message contexts, see Working with Contexts in Developing Applications Using JAX-WS.