Routers

3 min read

3 min read

3 min read

3 min read

3 min read

3 min read

3 min read

3 min read

3 min read

A router is an Ice object that forwards requests between clients and servers. On this page, the client is the application that connects to the router, and the server is the application the router forwards to, whichever of them sends a request. A proxy configured to use a router is a routed proxy: Ice sends its requests to the router, which forwards them to the target server. Ice connects to the router rather than to the endpoints of the routed proxy, and typically opens a single connection to a router for all the routed proxies that use it.

A router implements the Ice::Router interface. Ice includes two routers:

  • Glacier2 forwards the requests of authenticated clients to servers on another network, typically behind a firewall, and forwards callbacks to these clients over their existing connections. It finds the target of each request by its identity, so the objects that a client reaches through Glacier2 need unique identities.
  • IceBridge forwards requests to a single target server that the clients cannot reach directly, for example because they do not support its transport.

A communicator can have a default router. Every proxy this communicator creates, from a string, from a property, or by unmarshaling a proxy returned by an operation, is a routed proxy that uses this router. The Ice.Default.Router property sets the default router; the value is a proxy for the router:

Properties
Ice.Default.Router=Glacier2/router:tcp -h routerhost -p 4063

setDefaultRouter on the communicator sets the default router of the proxies created afterwards, and getDefaultRouter returns it. The default router does not apply to object adapters.

The ice_router proxy factory method returns a routed proxy:

C++
Ice::RouterPrx router{...};
GreeterPrx greeter{...}; // normal proxy
GreeterPrx routedGreeter = greeter.ice_router(router);
C#
var router = RouterPrxHelper.createProxy(...);
var greeter = GreeterPrxHelper.createProxy(...); // normal proxy
var routedGreeter = GreeterPrxHelper.uncheckedCast(greeter.ice_router(router));
Java
var router = RouterPrx.createProxy(...);
var greeter = GreeterPrx.createProxy(...); // normal proxy
var routedGreeter = greeter.ice_router(router);
JavaScript
const router = new Ice.RouterPrx(...);
const greeter = new VisitorCenter.GreeterPrx(...); // normal proxy
const routedGreeter = greeter.ice_router(router);
MATLAB
router = Ice.RouterPrx(...)
greeter = visitorcenter.GreeterPrx(...) % normal proxy
routedGreeter = greeter.ice_router(router)
PHP
$router = Ice\RouterPrxHelper::createProxy(...);
$greeter = VisitorCenter\GreeterPrxHelper::createProxy(...); // normal proxy
$routedGreeter = $greeter->ice_router($router);
Python
router = Ice.RouterPrx(...)
greeter = VisitorCenter.GreeterPrx(...) # normal proxy
routedGreeter = greeter.ice_router(router)
Ruby
router = Ice::RouterPrx.new(...)
greeter = VisitorCenter::GreeterPrx.new(...) # normal proxy
routedGreeter = greeter.ice_router(router)
Swift
let router = try makeProxy(
communicator: communicator, proxyString: "...",
type: RouterPrx.self)
let greeter = try makeProxy(
communicator: communicator, proxyString: "...",
type: GreeterPrx.self)
let routedGreeter = greeter.ice_router(router)

The Router proxy property sets the router of the proxy that propertyToProxy creates:

Properties
MyProxy.Router=Glacier2/router:tcp -h routerhost -p 4063

A client that receives callbacks through a router creates an object adapter associated with this router, with the adapter.Router property or by calling createObjectAdapterWithRouter. A communicator can have only one object adapter associated with a given router.

This object adapter does not accept incoming connections, and you must not set its Endpoints property: it receives requests over the bidirectional connection between the client and the router. The proxies it creates carry the endpoints of the router's server proxy, returned by getServerProxygetServerProxygetServerProxygetServerProxygetServerProxygetServerProxy: a server that makes an invocation with such a proxy sends the request to the router, which forwards it to the client.

See Callbacks Through Glacier2 for an example.