Ice Docs

Creating Proxies

6 min read

6 min read

6 min read

5 min read

5 min read

4 min read

6 min read

4 min read

6 min read

This page describes all the ways an application can create a proxy.

The generated proxy class provides a constructor that constructs a proxy from a communicator and a stringified representation of the proxy, as shown in the following example:

C++
GreeterPrx greeter{communicator, "greeter:tcp -h localhost -p 4061"};

The generated helper class for a proxy provides a static factory method createProxy that creates a proxy from a communicator and a stringified representation of the proxy, as shown in the following example:

C#
GreeterPrx greeter = GreeterPrxHelper.createProxy(
    communicator,
    "greeter:tcp -h localhost -p 4061");

The generated proxy class provides a static factory method createProxy from a communicator and a stringified representation of the proxy, as shown in the following example:

Java
GreeterPrx greeter = GreeterPrx.createProxy(
    communicator,
    "greeter:tcp -h localhost -p 4061");

The constructor of the generated proxy class allows you to construct a proxy from a communicator and a stringified representation of the proxy, as shown in the following example:

JavaScript
const greeter = new GreeterPrx(
    communicator,
    "greeter:tcp -h localhost -p 4061");

The constructor of the generated proxy class allows you to construct a proxy from a communicator and a stringified representation of the proxy, as shown in the following example:

MATLAB
greeter = GreeterPrx(communicator, 'greeter:tcp -h localhost -p 4061');

The generated helper class for a proxy provides a static factory method createProxy that creates a proxy from a communicator and a stringified representation of the proxy, as shown in the following example:

PHP
$greeter = GreeterPrxHelper::createProxy(
    $communicator,
    'greeter:tcp -h localhost -p 4061');

The constructor of the generated proxy class allows you to construct a proxy from a communicator and a stringified representation of the proxy, as shown in the following example:

Python
greeter = GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061")

The constructor of the generated proxy class allows you to construct a proxy from a communicator and a stringified representation of the proxy, as shown in the following example:

Ruby
greeter = GreeterPrx.new(communicator, "greeter:tcp -h localhost -p 4061")

The Slice compiler generates a makeProxy function that allows you to construct a proxy from a communicator and a stringified representation of the proxy, as shown in the following example:

Swift
let greeter = try makeProxy(
    communicator: communicator,
    proxyString: "greeter:tcp -h localhost -p 4061",
    type: GreeterPrx.self)

Rather than hard-coding a stringified proxy as the previous example demonstrated, an application can gain more flexibility by externalizing the proxy in a configuration property. For example, we can define a property that contains our stringified proxy as follows:

Properties
Greeter.Proxy=greeter:tcp -h localhost -p 4061

We can use the propertyToProxy template function on Communicator to convert the property's value into a proxy. A null proxy (std::nullopt) is returned if no property is found with the specified name.

C++
std::optional<GreeterPrx> greeter =
    communicator->propertyToProxy<GreeterPrx>("Greeter.Proxy");

We can use the propertyToProxy method on Communicator to convert the property's value into a proxy. A null proxy is returned if no property is found with the specified name.

C#
ObjectPrx? greeter = communicator.propertyToProxy("Greeter.Proxy");

We can use the propertyToProxy method on Communicator to convert the property's value into a proxy. A null proxy is returned if no property is found with the specified name.

Java
ObjectPrx greeter = communicator.propertyToProxy("Greeter.Proxy");

We can use the propertyToProxy method on Communicator to convert the property's value into a proxy. A null proxy is returned if no property is found with the specified name.

JavaScript
const greeter = communicator.propertyToProxy("Greeter.Proxy");

We can use the propertyToProxy method on Communicator to convert the property's value into a proxy. An empty array (null proxy) is returned if no property is found with the specified name.

MATLAB
greeter = communicator.propertyToProxy('Greeter.Proxy');

We can use the propertyToProxy method on Communicator to convert the property's value into a proxy. A null proxy is returned if no property is found with the specified name.

PHP
$greeter = $communicator->propertyToProxy('Greeter.Proxy');

We can use the propertyToProxy method on Communicator to convert the property's value into a proxy. A null proxy is returned if no property is found with the specified name.

Python
greeter = communicator.propertyToProxy("Greeter.Proxy")

We can use the propertyToProxy method on Communicator to convert the property's value into a proxy. A null proxy is returned if no property is found with the specified name.

Ruby
greeter = communicator.propertyToProxy("Greeter.Proxy")

We can use the propertyToProxy method on Communicator to convert the property's value into a proxy. A null proxy (nil) is returned if no property is found with the specified name.

Swift
let greeter = try communicator.propertyToProxy("Greeter.Proxy")

As an added convenience, propertyToProxy allows you to define subordinate properties that configure the proxy's local settings. The properties below demonstrate this feature:

Properties
Greeter.Proxy=greeter:tcp -h localhost -p 4061
Greeter.Proxy.EndpointSelection=Ordered

These additional properties simplify the task of customizing a proxy (as you can with proxy methodsproxy methodsproxy methodsproxy methodsproxy methodsproxy methodsproxy methodsproxy methods) without the need to change the application's code. The properties shown above are equivalent to the following statements:

C++
GreeterPrx greeter{communicator, "greeter:tcp -h localhost -p 4061"};
greeter = greeter.ice_endpointSelection(EndpointSelectionType::Ordered);
C#
var greeter = GreeterPrxHelper.createProxy(
    communicator,
    "greeter:tcp -h localhost -p 4061");
greeter = GreeterPrxHelper.uncheckedCast(
    greeter.ice_endpointSelection(EndpointSelectionType.Ordered));
Java
var greeter = GreeterPrx.createProxy(
    communicator,
    "greeter:tcp -h localhost -p 4061");
greeter = greeter.ice_endpointSelection(EndpointSelectionType.Ordered);
TypeScript
let greeter = new GreeterPrx(
    communicator,
    "greeter:tcp -h localhost -p 4061");
greeter = greeter.ice_endpointSelection(Ice.EndpointSelectionType.Ordered);
MATLAB
greeter = GreeterPrx(communicator, 'greeter:tcp -h localhost -p 4061');
greeter = greeter.ice_endpointSelection(Ice.EndpointSelectionType.Ordered);
PHP
$greeter = GreeterPrxHelper::createProxy(
    $communicator,
    'greeter:tcp -h localhost -p 4061');
$greeter = $greeter->ice_endpointSelection(Ice\EndpointSelectionType::Ordered);
Python
greeter = GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061")
greeter = greeter.ice_endpointSelection(Ice.EndpointSelectionType.Ordered)
Ruby
greeter = GreeterPrx.new(communicator, "greeter:tcp -h localhost -p 4061")
greeter = greeter.ice_endpointSelection(Ice::EndpointSelectionType::Ordered)
Swift
var greeter = try makeProxy(
    communicator: communicator,
    proxyString: "greeter:tcp -h localhost -p 4061",
    type: GreeterPrx.self)


greeter = greeter.ice_endpointSelection(.Ordered)

The proxy properties cover the proxy settings that a stringified proxy cannot express, except the compression setting (ice_compress), the connection ID (ice_connectionId) and a fixed connection (ice_fixed). propertyToProxy throws PropertyException if it finds a subordinate property that is not one of these proxy properties.

Note that proxy properties can themselves have proxy properties. For example, the following sets the EndpointSelection property on the default locator's router:

Properties
Ice.Default.Locator.Router.EndpointSelection=Ordered

An object adapter can create a proxy for any identity, whether or not it hosts an Ice object with this identity.

  • createProxy returns a proxy with the given identity. If the object adapter has an AdapterId, the proxy is an indirect proxy that refers to the object adapter's ReplicaGroupId, or to its AdapterId when no replica group ID is set. Otherwise, the proxy is a direct proxy that holds the object adapter's published endpoints.
  • createDirectProxy returns a direct proxy that holds the object adapter's published endpoints.
  • createIndirectProxy returns an indirect proxy that refers to the object adapter's AdapterId, or a well-known proxy when the object adapter has no adapter ID.

createProxy and createDirectProxy both return a direct proxy that holds the object adapter's published endpoints.

add, addFacet, addWithUUID and addFacetWithUUID register a servant with the Active Servant Map and return the proxy that createProxy creates for the identity of this servant, with its facet.

All these proxies use the options set by the object adapter's ProxyOptions property, such as -o for oneway proxies.

createProxy on a connection returns a fixed proxy with the given identity: invocations on this proxy use only this connection. A server uses such a proxy to call back a client over a bidirectional connection.

An application can also receive a proxy as the result of an Ice invocation. Consider the following Slice definitions:

Slice
interface Account { ... }
interface Bank
{
    Account* findAccount(string id);
}

Invoking the findAccount operation returns a proxy for an Account object.

For example:

C++
std::optional<AccountPrx> account = bank.findAccount("WXY-123456");
C#
AccountPrx? account = await bank.findAccountAsync("WXY-123456");
Java
AccountPrx account = bank.findAccount("WXY-123456");
TypeScript
let account: AccountPrx | null = await bank.findAccount("WXY-123456");
MATLAB
account = bank.findAccount('WXY-123456');
PHP
$account = $bank->findAccount('WXY-123456');
Python
account = await bank.findAccountAsync("WXY-123456")
Ruby
account = bank.findAccount('WXY-123456')
Swift
let account = try await bank.findAccount("WXY-123456")

A proxy is immutable. Its factory methods, such as ice_oneway, ice_facet and ice_invocationTimeout, return a proxy with the requested setting, and leave the original proxy unchanged. See ObjectPrx in the API reference for the complete list of factory methods and the accessors that return the current settings.

The language mapping for interfaces describes the type of the proxy that these factory methods return.

uncheckedCast and checkedCast create a proxy of the desired type from an existing proxy, for the same Ice object. Despite their names, these functions are not casts: they return a new proxy and leave the original proxy unchanged. uncheckedCast creates the new proxy without contacting the target object. checkedCast first calls ice_isA on the target object to verify that it implements the requested interface, and returns a null proxy if it does not.

You rarely need these functions. In new code, you create a typed proxy directly with one of the methods described above, and an application that converts a proxy of one type into a proxy of another type is uncommon.

The language mapping for interfaces shows these functions.

In C++, these functions are the Ice::uncheckedCast and Ice::checkedCast function templates, for example Ice::checkedCast<GreeterPrx>(proxy).