Using Callbacks to Notify Clients of Events

Callbacks are used to notify a client of your web service that some event has occurred. For example, you may wish to notify a client when the results of that client's request are ready.

You can easily add callbacks to your web service's interface using the Add Callback action in Design View. However, you should be aware that doing so places demands on the client that not all potential client applications will be able to meet.

# Callbacks Are Messages to the Client

When you add a method to a web service, you are defining a message that a client can send to you to request that some operation be performed. When you define a callback, you are defining a message that the web service will send to the client to notify the client of an event that has occurred in your web service. These are completely symmetrical. WebLogic Server allows your web service to receive XML and SOAP messages and will route them automatically to your web service. In order to receive callbacks, the client must be operating in an environment that provides the same services. This typically means the client must be running in an application server or web server.

If the client is not running in an environment that provides the necessary infrastructure, it will likely not be capable of receiving callbacks from your web service.

Note: The notion that callbacks are messages to the client is important if you want to apply XML maps to callback parameters or return values. The parameters to a callback go into the outgoing message to the client, and the return value is converted from the resulting incoming message from the client. This can seem strange, because programmers typically associate all parameters with incoming data and return values with outgoing data.

Note: In a conversational web service, it's possible that a callback will not return when you expect it to. Because method calls that are part of the same conversation are serialized, a callback that is invoked during the conversation will not happen until the current method returns. If that method takes a long time, the callback result may not be available when you expect it. If your code relies on the callback result, you can add a Timer control to your web service to check for the callback result, and decide on an appropriate action if the callback has not yet occurred.

# Callbacks Can Appear to be Unsolicited

As stated in the previous section, callbacks are messages to the client. Since callbacks are by definition separated from the original request to which the callback is a response, they appear as unsolicited messages to the client's host. Many hosts do not allow receipt of unsolicited network traffic, either by directly rejecting such traffic or by nature of being protected by firewalls or other network security apparatus. Clients that run in such an environment will therefore not be capable of receiving callbacks.

# Callback Protocol is Inferred

The protocol and message format used for callbacks is always the same as the protocol and message format used by the start method that started the current conversation. It is an error to attempt to override the protocol or message format of a callback.

# What If Clients of My Web Service Can't Receive Callbacks?

If clients of your web service cannot receive callbacks for the reasons described in the preceding sections (or for any reason), but you still want to design your web service to be asynchronous, you may implement a polling interface.

To learn about asynchronous web services, see Asynchronous Web Services.

To learn about polling interfaces, see Using Polling as an Alternative to Callbacks.

Related Topics

Using Asynchrony to Enable Long-Running Operations

Maintaining State with Conversations