Create a new endpoint listener configuration

An endpoint listener is the point (address) at which messages for an inbound service are received. The endpoint listeners that are supplied with WebSphere Application Server support SOAP over HTTP and SOAP over JMS bindings.

For every server or cluster that is to host an endpoint listener, you must install and configure a Service Data Objects (SDO) repository on the stand-alone server, or (for a server or cluster that is part of a managed cell) on the network deployment cell.

To change the default HTTP endpoint listener security role, do so before configuring the SOAP over HTTP endpoint listener.

Before you configure a SOAP over JMS endpoint listener, configure the associated JMS resources.

We can set up separate endpoint listeners for inbound and outbound requests. For more information, see Endpoint listeners and inbound ports: Entry points to the service integration bus.

Decide which method to use to configure these resources. We can create a new endpoint listener configuration using the console as described in this task, or using the createSIBWSEndpointListener command.

To create an endpoint listener configuration for our own endpoint listener application, rather than for one of the listeners supplied with WebSphere Application Server, use wsadmin.sh.

Endpoint listeners are a physical endpoint for receiving inbound service requests. An inbound service describes a bus destination as a logical web service. An inbound port associates a (logical) inbound service with an endpoint listener to provide a (physical) endpoint where the service can be invoked. Therefore you must have defined an endpoint listener before we can create an inbound port.

A request arrives at an endpoint listener. It is passed to an inbound port, at which point security and JAX-RPC handler lists can be applied, then sent on to the service destination. Responses follow the same path in reverse.

To configure a new endpoint listener for use with an inbound service is a two-stage process:

1. Configure the listener for a specific application server or cluster (as described in this task).

2. Configure an inbound service on the same bus to use the listener (as described in the task Making an internally-hosted service available as a web service).

To use the console to configure an endpoint listener...

1. Start the console.

2. In the navigation pane, click one of the following paths:

   • Servers -> Server Types -> WebSphere application servers -> server_name -> Endpoint listeners

   • Servers -> Clusters -> WebSphere application server clusters -> cluster_name -> Endpoint listeners

   The endpoint listeners collection form is displayed.

3. Click New. The New endpoint listener wizard is displayed.

4. Use the wizard to create the new endpoint listener configuration by completing the following steps. For more information about the properties set with the wizard, see Endpoint listeners [Settings]. We might want to use the values given in Example values for endpoint listener configuration.

   1. Select listener name and binding type.

      Endpoint listener name

      Type the name of the choice by which the endpoint listener is known. For example: wsgwsoaphttp; wsgwsoaphttp2; SOAPJMSChannel1; SOAPJMSChannel2.

      Binding type

      Select the type of binding that this endpoint listener supports. For a SOAP over HTTP or SOAP over HTTPS endpoint listener, select SOAP/HTTP or SOAP/HTTPS. For a SOAP over JMS endpoint listener select SOAP/JMS.

   2. Optional: Configure JMS settings.

      This panel is only displayed if selected SOAP/JMS in the previous panel.

      We can choose to deploy the endpoint listener application to use an activation specification or a listener port. Listener ports are stabilized. For more information, read the article on stabilized features. Wherever possible, you should deploy your endpoint listener application to use an activation specification. Use only activation specifications with the default messaging provider; we can use either activation specifications or listener ports with the WebSphere MQ messaging provider.

      Select from the drop-down lists the listener port, or the activation specification and queue connection factory that we have previously configured as described in Configure JMS resources for the synchronous SOAP over JMS endpoint listener.

   3. Configure required URLs. Configure web addresses for the application root and the WSDL serving root. We can either select pre-configured addresses based on the known virtual hosts, or create new values.

      URL root

      Select or type the address at which external clients access the endpoint listener endpoint. The URL root is the context root of the endpoint listener application, and provides the root of the web address used to build the endpoint addresses within WSDL files to direct requesters to this endpoint listener.

      An HTTP server can be used with a stand-alone application sever. Alternatively, if the endpoint listener is used by external clients to access a cluster providing high availability or workload management, the cluster usually employs a suitably configured HTTP server (or WebSphere proxy server) operating as an IP-sprayer. In either case, if external clients access the endpoint listener through an HTTP server or server cluster, using default port 80, then specify the HTTP server name and no port number. For example (for SOAP over HTTP endpoint listener 1):

      http://www.myco.com/wsgwsoaphttp1 For a stand-alone application server, the endpoint listener is typically configured for clients to connect directly to an individual application server. If the endpoint listener is used by external clients to access a cluster, we can configure the listener so that clients connect directly to an individual application server within the cluster as shown in the following example, but this might restrict the high availability or workload management capabilities of the cluster. However, if you allow external clients to connect direct to the application server (for example because it is a stand-alone server or in a development or test environment) then specify the application server host name and port number. For example (for SOAP over HTTP endpoint listener 1):

      http://your.server.name:9080/wsgwsoaphttp1 where the port number (specified as 9080 in this example) matches the WC_defaultHost port value for the application server concerned.

      WSDL serving HTTP URL root

      Type the root of the web address for the WSDL files of the inbound services that are available at this endpoint listener. This address comprises the root of the HTTP address at which external clients access the endpoint listener application, followed by /sibws. This represents the URL used when publishing the WSDL URL to a UDDI registry. The host and port name specified for the WSDL serving HTTP URL root typically match those specified for the URL root.

      If external clients access the endpoint listener through an HTTP server or server cluster, typically by using default port 80, then this URL root includes the HTTP server name and no port number. For example:

      http://www.myco.com/sibws

      However, if you allow external clients to connect direct to the application server (for example in a development or test environment) then this URL root includes the application server host name and port number. For example:

      http://your.server.name:9080/sibws

      The WSDL serving HTTP URL root is only used internally by other components of WAS (notably the IBM UDDI registry). For all other uses, you access the WSDL file through the endpoint listener endpoint for the inbound service. To get the location details for a given inbound service WSDL file, publish the WSDL file to a compressed file as described in Modify an existing inbound service configuration, then look up the location within the exported WSDL file.

   4. Select the service integration buses to which the new endpoint listener should be connected. Only buses of which the application server or cluster is a member are available for selection.

5. Click Finish.

Results

If the processing completes successfully, the list of endpoint listeners is updated to include the new endpoint listener. Otherwise, an error message is displayed.

What to do next

We are now ready to select this endpoint listener for use with an inbound service as described in Making an internally-hosted service available as a web service.

Subtopics

• Example values for endpoint listener configuration
  We can configure any number of endpoint listeners with values of our own choosing, including the example values given in this topic.

• Configure JMS resources for the synchronous SOAP over JMS endpoint listener
  Configure the synchronous SOAP over Java Message Service (JMS) endpoint listeners to use a JMS provider - either the default messaging provider, or another provider such as the WebSphere MQ messaging provider - to pass SOAP messages over JMS.

• Modify an existing endpoint listener configuration
  Modify the additional properties for an endpoint listener that has been configured for use with inbound services.

• Delete endpoint listener configurations
  Use this task to delete endpoint listener configurations using the console.

Related concepts

Endpoint listeners and inbound ports: Entry points to the service integration bus