---
title: "Creating Proxies"
url: https://docs.zeroc.com/ice/3.8/runtime/invocation/creating-proxies
docs_index: https://docs.zeroc.com/llms.txt
---

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

# Creating Proxies

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/invocation/creating-proxies/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/runtime/invocation/creating-proxies/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/runtime/invocation/creating-proxies/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/runtime/invocation/creating-proxies/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/runtime/invocation/creating-proxies/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/runtime/invocation/creating-proxies/php.md), [Python](https://docs.zeroc.com/ice/3.8/runtime/invocation/creating-proxies/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/runtime/invocation/creating-proxies/ruby.md), and [Swift](https://docs.zeroc.com/ice/3.8/runtime/invocation/creating-proxies/swift.md).

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

## Creating a Proxy from a String

> **C++**
>
> The generated proxy class provides a constructor that constructs a proxy from a communicator and a [stringified representation](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) of the proxy, as shown in the following example:
>
> ```cpp
> GreeterPrx greeter{communicator, "greeter:tcp -h localhost -p 4061"};
> ```

> **C#**
>
> The generated helper class for a proxy provides a static factory method `createProxy` that creates a proxy from a communicator and a [stringified representation](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) of the proxy, as shown in the following example:
>
> ```csharp
> GreeterPrx greeter = GreeterPrxHelper.createProxy(
>     communicator,
>     "greeter:tcp -h localhost -p 4061");
> ```

> **Java**
>
> The generated proxy interface provides a static factory method `createProxy` from a communicator and a [stringified representation](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) of the proxy, as shown in the following example:
>
> ```java
> GreeterPrx greeter = GreeterPrx.createProxy(
>     communicator,
>     "greeter:tcp -h localhost -p 4061");
> ```

> **JavaScript**
>
> The constructor of the generated proxy class allows you to construct a proxy from a communicator and a [stringified representation](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) of the proxy, as shown in the following example:
>
> ```js
> const greeter = new GreeterPrx(
>     communicator,
>     "greeter:tcp -h localhost -p 4061");
> ```

> **MATLAB**
>
> The constructor of the generated proxy class allows you to construct a proxy from a communicator and a [stringified representation](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) of the proxy, as shown in the following example:
>
> ```matlab
> greeter = GreeterPrx(communicator, 'greeter:tcp -h localhost -p 4061');
> ```

> **PHP**
>
> The generated helper class for a proxy provides a static factory method `createProxy` that creates a proxy from a communicator and a [stringified representation](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) of the proxy, as shown in the following example:
>
> ```php
> $greeter = GreeterPrxHelper::createProxy(
>     $communicator,
>     'greeter:tcp -h localhost -p 4061');
> ```

> **Python**
>
> The constructor of the generated proxy class allows you to construct a proxy from a communicator and a [stringified representation](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) of the proxy, as shown in the following example:
>
> ```py
> greeter = GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061")
> ```

> **Ruby**
>
> The constructor of the generated proxy class allows you to construct a proxy from a communicator and a [stringified representation](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) of the proxy, as shown in the following example:
>
> ```ruby
> greeter = GreeterPrx.new(communicator, "greeter:tcp -h localhost -p 4061")
> ```

> **Swift**
>
> The Slice compiler generates a `makeProxy` function that allows you to construct a proxy from a communicator and a [stringified representation](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md) 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)
> ```

## Creating a Proxy from a Property

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:

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

> **C++**
>
> 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.
>
> ```cpp
> std::optional<GreeterPrx> greeter =
>     communicator->propertyToProxy<GreeterPrx>("Greeter.Proxy");
> ```

> **C#**
>
> 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.
>
> ```csharp
> GreeterPrx? greeter = GreeterPrxHelper.uncheckedCast(communicator.propertyToProxy("Greeter.Proxy"));
> ```

> **Java**
>
> 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
> GreeterPrx greeter = GreeterPrx.uncheckedCast(communicator.propertyToProxy("Greeter.Proxy"));
> ```

> **JavaScript**
>
> 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.
>
> ```js
> const greeter = GreeterPrx.uncheckedCast(communicator.propertyToProxy("Greeter.Proxy"));
> ```

> **MATLAB**
>
> 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 = GreeterPrx.uncheckedCast(communicator.propertyToProxy('Greeter.Proxy'));
> ```

> **PHP**
>
> 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. This proxy carries no type information: attach the type information of `Greeter` with [uncheckedCast](https://docs.zeroc.com/ice/3.8/slice/interfaces/php.md#attaching-type-information-to-a-proxy) before you invoke `greet` on it.
>
> ```php
> $greeter = GreeterPrxHelper::uncheckedCast($communicator->propertyToProxy('Greeter.Proxy'));
> ```

> **Python**
>
> 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.
>
> ```py
> greeter = GreeterPrx.uncheckedCast(communicator.propertyToProxy("Greeter.Proxy"))
> ```

> **Ruby**
>
> 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 = GreeterPrx.uncheckedCast(communicator.propertyToProxy("Greeter.Proxy"))
> ```

> **Swift**
>
> 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
> guard let proxy = try communicator.propertyToProxy("Greeter.Proxy") else {
>     fatalError("the Greeter.Proxy property is not set")
> }
> let greeter = uncheckedCast(prx: proxy, type: GreeterPrx.self)
> ```

> **C#, Java, JavaScript, MATLAB, Python, Ruby, and Swift**
>
> `propertyToProxy` returns an `ObjectPrx`. Call [`uncheckedCast`](https://docs.zeroc.com/ice/3.8/slice/interfaces.md#uncheckedcast) on this base proxy to create a `GreeterPrx`.

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

```config
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 methods ([C++](https://code.zeroc.com/ice/3.8/api/cpp/classIce_1_1ObjectPrx.html), [C#](https://code.zeroc.com/ice/3.8/api/csharp/api/Ice.ObjectPrx.html), [Java](https://code.zeroc.com/ice/3.8/api/java/com.zeroc.ice/com/zeroc/Ice/ObjectPrx.html), [JavaScript](https://code.zeroc.com/ice/3.8/api/javascript/Ice/ObjectPrx.html), [Python](https://code.zeroc.com/ice/3.8/api/python/Ice.ObjectPrx.html), [Ruby](https://code.zeroc.com/ice/3.8/api/ruby/Ice/ObjectPrx.html), and [Swift](https://code.zeroc.com/ice/3.8/api/swift/documentation/ice/objectprx))) without the need to change the application's code. The properties shown above are equivalent to the following statements:

> **C++**
>
> ```cpp
> GreeterPrx greeter{communicator, "greeter:tcp -h localhost -p 4061"};
> greeter = greeter.ice_endpointSelection(EndpointSelectionType::Ordered);
> ```

> **C#**
>
> ```csharp
> var greeter = GreeterPrxHelper.createProxy(
>     communicator,
>     "greeter:tcp -h localhost -p 4061");
> greeter = GreeterPrxHelper.uncheckedCast(
>     greeter.ice_endpointSelection(EndpointSelectionType.Ordered));
> ```

> **Java**
>
> ```java
> var greeter = GreeterPrx.createProxy(
>     communicator,
>     "greeter:tcp -h localhost -p 4061");
> greeter = greeter.ice_endpointSelection(EndpointSelectionType.Ordered);
> ```

> **JavaScript**
>
> ```js
> let greeter = new GreeterPrx(
>     communicator,
>     "greeter:tcp -h localhost -p 4061");
> greeter = greeter.ice_endpointSelection(Ice.EndpointSelectionType.Ordered);
> ```

> **MATLAB**
>
> ```matlab
> greeter = GreeterPrx(communicator, 'greeter:tcp -h localhost -p 4061');
> greeter = greeter.ice_endpointSelection(Ice.EndpointSelectionType.Ordered);
> ```

> **PHP**
>
> ```php
> $greeter = GreeterPrxHelper::createProxy(
>     $communicator,
>     'greeter:tcp -h localhost -p 4061');
> $greeter = $greeter->ice_endpointSelection(Ice\EndpointSelectionType::Ordered);
> ```

> **Python**
>
> ```py
> greeter = GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061")
> greeter = greeter.ice_endpointSelection(Ice.EndpointSelectionType.Ordered)
> ```

> **Ruby**
>
> ```ruby
> greeter = GreeterPrx.new(communicator, "greeter:tcp -h localhost -p 4061")
> greeter = greeter.ice_endpointSelection(Ice::EndpointSelectionType::Ordered)
> ```

> **Swift**
>
> ```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](https://docs.zeroc.com/ice/3.8/property-reference/proxy-properties.md) page lists the properties you can define this way.

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

```config
Ice.Default.Locator.Router.EndpointSelection=Ordered
```

> **C++, C#, Java, JavaScript, Python, and Swift**
>
> ## Creating a Proxy from an Object Adapter
>
> An object adapter creates the proxies that clients use to call operations on the Ice objects it hosts. `createProxy` returns a proxy with the given identity, and `add`, `addFacet`, `addWithUUID` and `addFacetWithUUID` register a servant with the [Active Servant Map](https://docs.zeroc.com/ice/3.8/runtime/dispatch/active-servant-map.md) and return a proxy for the Ice object this servant implements. See ObjectAdapter ([C++](https://code.zeroc.com/ice/3.8/api/cpp/classIce_1_1ObjectAdapter.html), [C#](https://code.zeroc.com/ice/3.8/api/csharp/api/Ice.ObjectAdapter.html), [Java](https://code.zeroc.com/ice/3.8/api/java/com.zeroc.ice/com/zeroc/Ice/ObjectAdapter.html), [JavaScript](https://code.zeroc.com/ice/3.8/api/javascript/Ice/ObjectAdapter.html), [Python](https://code.zeroc.com/ice/3.8/api/python/Ice.ObjectAdapter.html), and [Swift](https://code.zeroc.com/ice/3.8/api/swift/documentation/ice/objectadapter)) in the API reference for all the methods that create proxies.
>
> These proxies use the options set by the object adapter's [ProxyOptions](https://docs.zeroc.com/ice/3.8/property-reference/object-adapter-properties.md) property, such as `-o` for oneway proxies.

> **C++, C#, Java, JavaScript, MATLAB, Python, and Swift**
>
> ## Creating a Proxy from a Connection
>
> `createProxy` on a connection returns a fixed proxy: invocations on this proxy use only this connection. A server uses such a proxy to call back a client over a [bidirectional connection](https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections.md).

## Receiving a Proxy from an Operation

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++**
>
> ```cpp
> std::optional<AccountPrx> account = bank.findAccount("WXY-123456");
> ```

> **C#**
>
> ```csharp
> AccountPrx? account = await bank.findAccountAsync("WXY-123456");
> ```

> **Java**
>
> ```java
> AccountPrx account = bank.findAccount("WXY-123456");
> ```

> **JavaScript**
>
> ```typescript
> let account: AccountPrx | null = await bank.findAccount("WXY-123456");
> ```

> **MATLAB**
>
> ```matlab
> account = bank.findAccount('WXY-123456');
> ```

> **PHP**
>
> ```php
> $account = $bank->findAccount('WXY-123456');
> ```

> **Python**
>
> ```py
> account = await bank.findAccountAsync("WXY-123456")
> ```

> **Ruby**
>
> ```ruby
> account = bank.findAccount('WXY-123456')
> ```

> **Swift**
>
> ```swift
> let account = try await bank.findAccount("WXY-123456")
> ```

## Proxy Factory Methods

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 ([C++](https://code.zeroc.com/ice/3.8/api/cpp/classIce_1_1ObjectPrx.html), [C#](https://code.zeroc.com/ice/3.8/api/csharp/api/Ice.ObjectPrx.html), [Java](https://code.zeroc.com/ice/3.8/api/java/com.zeroc.ice/com/zeroc/Ice/ObjectPrx.html), [JavaScript](https://code.zeroc.com/ice/3.8/api/javascript/Ice/ObjectPrx.html), [Python](https://code.zeroc.com/ice/3.8/api/python/Ice.ObjectPrx.html), [Ruby](https://code.zeroc.com/ice/3.8/api/ruby/Ice/ObjectPrx.html), and [Swift](https://code.zeroc.com/ice/3.8/api/swift/documentation/ice/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](https://docs.zeroc.com/ice/3.8/slice/interfaces.md) describes the type of the proxy that these factory methods return.

## Creating a Proxy of Another Type

`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. You use them when you hold a proxy of a more general type than the interface you want to call, such as the proxy returned by an operation whose return type is `Object*`.

> **C#, Java, JavaScript, MATLAB, PHP, Python, Ruby, and Swift**
>
> The [language mapping for interfaces](https://docs.zeroc.com/ice/3.8/slice/interfaces.md) shows these functions.

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

## Local Settings

A proxy has two kinds of settings. Ice marshals the identity, facet, invocation mode, encoding version, and endpoints or adapter ID of a proxy when it sends the proxy to another application. The other settings, such as the router, locator, locator cache timeout, endpoint selection type, connection caching, invocation timeout, context and connection ID, are local, and Ice does not marshal them.

A proxy that Ice unmarshals starts with the default value of each local setting, whatever the value of this setting in the application that sent the proxy.

## Proxy Defaults

The [Ice.Default.\*](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties.md) properties set the initial settings of the proxies you create from a string or a property, of the proxies an object adapter creates, and of the proxies Ice unmarshals from the payload of a request or response. A proxy property overrides the corresponding default for the proxy that `propertyToProxy` creates.

For example, the following property sets the endpoint selection type of these proxies to `Ordered`:

```config
Ice.Default.EndpointSelection=Ordered
```

## See Also

- [Communicator](https://docs.zeroc.com/ice/3.8/runtime/communicator.md)
- [Syntax for Stringified Proxies](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md)
- [Proxy Properties](https://docs.zeroc.com/ice/3.8/property-reference/proxy-properties.md)
