---
title: "Bidirectional Connections"
url: https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Bidirectional Connections

This page is written for C++, C#, Java, JavaScript, Python, and Swift.

Parts of this page are for some programming languages only, and name them. For one language's text alone, see [C++](https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections/js.md), [Python](https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections/python.md), and [Swift](https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections/swift.md).

## Use Cases for Bidirectional Connections

By default, requests flow over an Ice connection in one direction: from the client that establishes the connection to the server that accepts it. If the server needs to call back the client, it usually establishes a new connection to that client to send these callback requests, as shown below:

![The client opens a connection to send requests to the server. The server opens a separate connection to send callbacks to the client.](https://docs.zeroc.com/images/ice/3.8/bidirectional-connections/callback1.svg)

*Callbacks in an open network.*

A firewall in front of the client, however, typically blocks this connection:

![The client can open a connection to the server through its firewall, but the firewall blocks a separate incoming callback connection from the server.](https://docs.zeroc.com/images/ice/3.8/bidirectional-connections/callback2.svg)

A bidirectional connection solves this: requests flow over it in both directions, so the server can send callbacks over the connection the client established. This page calls the side that opened the connection the client and the side that accepted it the server, including when the server sends a callback and is therefore the [client](https://docs.zeroc.com/ice/3.8/basics/terminology.md#clients-and-servers) of this request.

## Configuring a Client for Bidirectional Connections

A client needs to perform the following steps in order to configure a bidirectional connection:

1. [Create an object adapter](https://docs.zeroc.com/ice/3.8/runtime/dispatch/creating-an-object-adapter.md) to receive callback requests.
2. Set this object adapter as the default object adapter on the communicator. The communicator associates its default object adapter with the outgoing connections it creates afterward.
3. [Register the callback object](https://docs.zeroc.com/ice/3.8/runtime/dispatch/object-adapter-activation-and-deactivation.md) or objects with the object adapter.

> **Tip**
>
> We recommend a dedicated object adapter for the callbacks. Such an object adapter needs no name or endpoints, and you don't need to activate it, since it accepts no connection: it only dispatches the callbacks received over the bidirectional connections. You can also use an object adapter with endpoints: it then dispatches the requests received over its own incoming connections as well as the callbacks.

The code below illustrates these steps:

> **C++**
>
> ```cpp
> Ice::ObjectAdapterPtr adapter = communicator->createObjectAdapter("");
> communicator->setDefaultObjectAdapter(adapter);
> auto mockAlarmClock = make_shared<Client::MockAlarmClock>();
> adapter->add(mockAlarmClock, Ice::stringToIdentity("alarmClock"));
> ```

> **C#**
>
> ```csharp
> Ice.ObjectAdapter adapter = communicator.createObjectAdapter("");
> communicator.setDefaultObjectAdapter(adapter);
> var mockAlarmClock = new Client.MockAlarmClock();
> adapter.add(mockAlarmClock, new Ice.Identity { name = "alarmClock" });
> ```

> **Java**
>
> ```java
> ObjectAdapter adapter = communicator.createObjectAdapter("");
> communicator.setDefaultObjectAdapter(adapter);
> var mockAlarmClock = new MockAlarmClock();
> adapter.add(mockAlarmClock, new Identity("alarmClock", ""));
> ```

> **JavaScript**
>
> ```typescript
> const adapter = await communicator.createObjectAdapter("");
> communicator.setDefaultObjectAdapter(adapter);
> const mockAlarmClock = new MockAlarmClock();
> adapter.add(mockAlarmClock, new Ice.Identity("alarmClock"));
> ```

> **Python**
>
> ```py
> adapter = communicator.createObjectAdapter("")
> communicator.setDefaultObjectAdapter(adapter)
> mockAlarmClock = MockAlarmClock()
> adapter.add(mockAlarmClock, Ice.Identity(name="alarmClock"))
> ```

> **Swift**
>
> ```swift
> let adapter = try communicator.createObjectAdapter("")
> communicator.setDefaultObjectAdapter(adapter)
> let mockAlarmClock = MockAlarmClock()
> try adapter.add(servant: mockAlarmClock, id: Ice.Identity(name: "alarmClock"))
> ```

The callback object (`mockAlarmClock` in the code above) will handle incoming requests for identity `alarmClock`.

To set an object adapter on a connection created before you set the default object adapter, or to give a connection a different object adapter, call `setAdapter` on this outgoing connection, for example the connection returned by a proxy's `ice_getConnection`. A connection without an object adapter rejects incoming requests with `ObjectNotExistException`.

These two approaches differ in scope. With a default object adapter, every outgoing connection that the communicator creates afterward dispatches the requests it receives to this adapter, so any server the client connects to can send callbacks to it. With `setAdapter`, only the connections you choose accept callbacks.

## Configuring a Server for Bidirectional Connections

> **C++, C#, Java, Python, and Swift**
>
> A server sends callbacks over the incoming connection with a *fixed proxy*, a proxy bound to this connection. The connection is the `con` member of the `Current` object passed to the operation implementation. You create a fixed proxy in one of two ways:
>
> - Call `createProxy` on the connection with the identity of the callback object, as the code below does.
> - Call `ice_fixed` with the connection on a proxy that the client sent, for example a callback proxy passed as an operation argument. The fixed proxy keeps the identity, facet, and other settings of this proxy.

> **C++**
>
> ```cpp
> void
> Server::BidirWakeUpService::wakeMeUp(
>     int64_t timeStamp,
>     const Ice::Current& current)
> {
>     // The connection from the client to the server.
>     Ice::ConnectionPtr connection = current.con;
>     if (!connection)
>     {
>         // Unexpected colloc call.
>         throw std::invalid_argument{...};
>     }
>
>     // alarmClock is a fixed proxy.
>     auto alarmClock = connection->createProxy<AlarmClockPrx>(
>         Ice::stringToIdentity("alarmClock"));
>     ...
> }
> ```
>
> The [Ice bidir demo](https://github.com/zeroc-ice/ice-demos/tree/3.8/cpp/Ice/bidir) provides a complete client and server in C++ that communicate over a bidirectional connection.

> **C#**
>
> ```csharp
> internal class BidirWakeUpService : WakeUpServiceDisp_
> {
>     public override void WakeMeUp(long timeStamp, Ice.Current current)
>     {
>         // The connection from the client to the server.
>         Ice.Connection? connection = current.con;
>         if (connection is null)
>         {
>             // Unexpected colloc call.
>             throw new NotImplementedException("...");
>         }
>
>         // alarmClock is a fixed proxy.
>         AlarmClockPrx alarmClock = AlarmClockPrxHelper.uncheckedCast(
>             connection.createProxy(new Ice.Identity { name = "alarmClock" }));
>         ...
> ```
>
> The [Ice bidir demo](https://github.com/zeroc-ice/ice-demos/tree/3.8/csharp/Ice/Bidir) provides a complete client and server in C# that communicate over a bidirectional connection.

> **Java**
>
> ```java
> class BidirWakeUpService implements WakeUpService {
>     @Override
>     public void wakeMeUp(long timeStamp, Current current)
>        throws FeatureNotSupportedException {
>          // The connection from the client to the server.
>          Connection connection = current.con;
>           if (connection == null) {
>               // Unexpected colloc call.
>               throw new FeatureNotSupportedException("...");
>           }
>
>           // alarmClock is a fixed proxy.
>           AlarmClockPrx alarmClock = AlarmClockPrx.uncheckedCast(
>               connection.createProxy(new Identity("alarmClock", "")));
>           ...
> ```
>
> The [Ice bidir demo](https://github.com/zeroc-ice/ice-demos/tree/3.8/java/Ice/bidir) provides a complete client and server in Java that communicate over a bidirectional connection.

> **JavaScript**
>
> > **Note**
> >
> > Ice for JavaScript cannot accept incoming connections, so a JavaScript application is always the client of a bidirectional connection: it establishes the connection and receives callbacks over it, as described in [Configuring a Client for Bidirectional Connections](https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections/js.md#configuring-a-client-for-bidirectional-connections).
>
> The [Ice bidir demo](https://github.com/zeroc-ice/ice-demos/tree/3.8/js/Ice/bidir) provides a complete JavaScript client that receives callbacks over a bidirectional connection, from a bidir demo server written in another language.

> **Python**
>
> ```py
> class BidirWakeUpService(WakeUpService):
>     def wakeMeUp(self, timeStamp: int, current: Ice.Current) -> None:
>         assert current.con is not None, "Unexpected colloc call."
>         # alarmClock is a fixed proxy.
>         alarmClock = AlarmClockPrx.uncheckedCast(
>           current.con.createProxy(Ice.Identity(name="alarmClock")))
>         ...
> ```
>
> The [Ice bidir demo](https://github.com/zeroc-ice/ice-demos/tree/3.8/python/Ice/bidir) provides a complete client and server in Python that communicate over a bidirectional connection.

> **Swift**
>
> ```swift
> struct BidirWakeUpService: WakeUpService {
>     func wakeMeUp(timeStamp: Int64, current: Ice.Current) throws {
>         // The connection from the client to the server.
>         guard let connection = current.con else {
>             // Unexpected colloc call.
>             throw Ice.FeatureNotSupportedException("...")
>         }
>
>         // alarmClock is a fixed proxy.
>         let alarmClock = try uncheckedCast(
>             prx: connection.createProxy(
>                 Ice.Identity(name: "alarmClock")), type: AlarmClockPrx.self)
>         ...
> ```
>
> The [Ice bidir demo](https://github.com/zeroc-ice/ice-demos/tree/3.8/swift/Ice/Bidir) provides a complete client and server in Swift that communicate over a bidirectional connection.

> **C++, C#, Java, Python, and Swift**
>
> A fixed proxy ceases to work once its connection is closed. Ice does not retry an invocation on a fixed proxy: once the connection is closed, invocations on the proxy fail with the exception that closed the connection, such as `CloseConnectionException` when the client closed it gracefully.

## Limitations of Bidirectional Connections

Bidirectional connections have certain limitations:

- They can only be configured for connection-oriented transports such as TCP and SSL.
- A fixed proxy is bound to an existing connection: you cannot change the settings that select a connection, such as its endpoints or its router, and you cannot marshal it or convert it to proxy properties. You can still change its invocation mode, for example to oneway.

> **C++, C#, Java, Python, and Swift**
>
> ## Threading Considerations for Bidirectional Connections
>
> Over a bidirectional connection, each side sends requests and dispatches the requests it receives, but the thread pool does not depend on the direction of a request: the client thread pool services an outgoing connection, even when the callback object adapter has its own thread pool, and the thread pool of the object adapter that accepted the connection services an incoming connection. This pool dispatches the requests and processes the replies received over the connection; see [Thread Pools](https://docs.zeroc.com/ice/3.8/runtime/threading-model/thread-pools.md).

## See Also

- [Callbacks through Glacier2](https://docs.zeroc.com/ice/3.8/services/glacier2/callbacks-through-glacier2.md)
- [Creating an Object Adapter](https://docs.zeroc.com/ice/3.8/runtime/dispatch/creating-an-object-adapter.md)
- [Object Adapter Activation and Deactivation](https://docs.zeroc.com/ice/3.8/runtime/dispatch/object-adapter-activation-and-deactivation.md)
- [Object Identity](https://docs.zeroc.com/ice/3.8/runtime/object-identity.md)
- [Nested Invocations](https://docs.zeroc.com/ice/3.8/runtime/threading-model/nested-invocations.md)
- [The Ice Threading Model](https://docs.zeroc.com/ice/3.8/runtime/threading-model.md)
- [Object Adapter Thread Pools](https://docs.zeroc.com/ice/3.8/runtime/threading-model/object-adapter-thread-pools.md)
