32.11 Proxies

The introduction to proxies provided in Section 2.2.2 describes a proxy as a local artifact that makes a remote invocation as easy to use as a regular function call. In fact, processing remote invocations is just one of a proxy’s many responsibilities. A proxy also encapsulates the information necessary to contact the object, including its identity (see Section 32.5) and addressing details such as endpoints (see Section 32.11.3). Proxy methods provide access to configuration and connec­tion information, and act as factories for creating new proxies (see Section 32.11.2). Finally, a proxy initiates the establishment of a new connection when necessary (see Section 36.3).

32.11.1 Obtaining Proxies

An application can obtain a proxy in a number of ways.

Stringified Proxies

The communicator operation stringToProxy creates a proxy from its stringified representation, as shown in the following C++ example:

Ice::ObjectPrx p = communicator‑>stringToProxy("ident:tcp ‑p 5000");

See Appendix E for a description of stringified proxies and Section 32.2 for more information on the stringToProxy operation.

Proxy Properties

Rather than hard-coding a stringified proxy as the previous example demon­strated, 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:

MyApp.Proxy=ident:tcp ‑p 5000

We can use the communicator operation propertyToProxy to convert the prop­erty’s value into a proxy, as shown below in Java:

Ice.ObjectPrx p = communicator.propertyToProxy("MyApp.Proxy");

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

MyApp.Proxy=ident:tcp ‑p 5000
MyApp.Proxy.PreferSecure=1
MyApp.Proxy.EndpointSelection=Ordered

These additional properties simplify the task of customizing a proxy without the need to change the application’s code. The properties shown above are equivalent to the following statements:

Ice.ObjectPrx p = communicator.stringToProxy("ident:tcp ‑p 5000");
p = p.ice_preferSecure(true);
p = p.ice_endpointSelection(Ice.EndpointSelectionType.Ordered);

The list of supported proxy properties is presented in Section D.9. Note that the communicator prints a warning by default if it does not recognize a subordinate property. You can disable this warning using the property Ice.Warn.UnknownProperties (see Section D.3).

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

Ice.Default.Locator.Router.PreferSecure=1

Factory Methods

As we discuss in Section 32.11.2, proxy factory methods allow you to modify aspects of an existing proxy. Since proxies are immutable, factory methods always return a new proxy if the desired modification differs from the proxy’s current configuration. Consider the following C# example:

Ice.ObjectPrx p = communicator.stringToProxy("...");
p = p.ice_oneway();

ice_oneway is considered a factory method because it returns a proxy config­ured to use oneway invocations. If the original proxy uses a different invocation mode, the return value of ice_oneway is a new proxy object.

The checkedCast and uncheckedCast methods can also be considered factory methods because they return new proxies that are narrowed to a particular Slice interface. A call to checkedCast or uncheckedCast typically follows the use of other factory methods, as shown below:

Ice.ObjectPrx p = communicator.stringToProxy("...");
Ice.LocatorPrx loc =
    Ice.LocatorPrxHelper.checkedCast(p.ice_secure(true));

Invocations

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

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

Invoking the findAccount operation returns a proxy for an Account object. There is no need to use checkedCast or uncheckedCast on this proxy because it has already been narrowed to the Account interface. The C++ code below demon­strates how to invoke findAccount:

BankPrx bank = ...
AccountPrx acct = bank‑>findAccount(id);

Of course, the application must have already obtained a proxy for the bank object using one of the techniques shown above.

32.11.2 Proxy Methods

Although the core proxy functionality is supplied by a language-specific base class, we can describe the proxy methods in terms of Slice operations as shown below:

bool ice_isA(string id);
void ice_ping();
StringSeq ice_ids();
string ice_id();
int ice_getHash();
Communicator ice_getCommunicator();
string ice_toString();
Object* ice_identity(Identity id);
Identity ice_getIdentity();
Object* ice_adapterId(string id);
string ice_getAdapterId();
Object* ice_endpoints(EndpointSeq endpoints);
EndpointSeq ice_getEndpoints();
Object* ice_endpointSelection(EndpointSelectionType t);
EndpointSelectionType ice_getEndpointSelection();
Object* ice_context(Context ctx);
Context ice_getContext();
Object* ice_defaultContext();
Object* ice_facet(string facet);
string ice_getFacet();
Object* ice_twoway();
bool ice_isTwoway();
Object* ice_oneway();
bool ice_isOneway();
Object* ice_batchOneway();
bool ice_isBatchOneway();
Object* ice_datagram();
bool ice_isDatagram();
Object* ice_batchDatagram();
bool ice_isBatchDatagram();
Object* ice_secure(bool b);
bool ice_isSecure();
Object* ice_preferSecure(bool b);
bool ice_isPreferSecure();
Object* ice_compress(bool b);
Object* ice_timeout(int timeout);
Object* ice_router(Router* rtr);
Router* ice_getRouter();
Object* ice_locator(Locator* loc);
Locator* ice_getLocator();
Object* ice_locatorCacheTimeout(int seconds);
int ice_getLocatorCacheTimeout();
Object* ice_collocationOptimized(bool b);
bool ice_isCollocationOptimized();
Object* ice_connectionId(string id);
string ice_getConnectionId();
Connection ice_getConnection();
Connection ice_getCachedConnection();
Object* ice_connectionCached(bool b);
bool ice_isConnectionCached();
void ice_flushBatchRequests();
bool ice_invoke(string operation, OperationMode mode,
                ByteSeq inParams, out ByteSeq outParams);

These methods can be categorized as follows:

• Remote inspection: methods that return information about the remote object. These methods make remote invocations and therefore accept an optional trailing argument of type Ice::Context (see Section 32.12).

• Local inspection: methods that return information about the proxy’s local configuration.

• Factory: methods that return new proxy instances configured with different features.

• Request processing: methods that flush batch requests and send “dynamic” Ice invocations.

Proxies are immutable, so factory methods allow an application to obtain a new proxy with the desired configuration. Factory methods essentially clone the orig­inal proxy and modify one or more features of the new proxy.

Many of the factory methods are not supported by fixed proxies. Attempting to invoke one of these methods causes the Ice run time to raise FixedProxyExcep­tion. See page 12 for a description of fixed proxies and Section 36.7 for addi­tional details.

The core proxy methods are explained in greater detail in Table 32.1.

Table 32.1. The semantics of core proxy methods.

Method	Description	Remote
ice_isA	Returns true if the remote object supports the type indi­cated by the id argument, oth­erwise false. This method can only be invoked on a two­way proxy.	Yes
ice_ping	Determines whether the remote object is reachable. Does not return a value.	Yes
ice_ids	Returns the type ids of the types supported by the remote object. The return value is an array of strings. This method can only be invoked on a twoway proxy.	Yes
ice_id	Returns the type id of the most-derived type supported by the remote object. This method can only be invoked on a twoway proxy.	Yes
ice_getHash	Returns a hash value for the proxy for C++. For other lan­guage mappings, use the built-in hash method.	No
ice_getCommunicator	Returns the communicator that was used to create this proxy.	No
ice_toString	Returns the string representa­tion of the proxy.	No
ice_identity	Returns a new proxy having the given identity.	No
ice_getIdentity	Returns the identity of the Ice object represented by the proxy.	No
ice_adapterId	Returns a new proxy having the given adapter id.	No
ice_getAdapterId	Returns the proxy’s adapter id, or an empty string if no adapter id is configured.	No
ice_endpoints	Returns a new proxy having the given endpoints.	No
ice_getEndpoints	Returns a sequence of End­point objects representing the proxy’s endpoints. See Section 36.5.2 for more infor­mation.	No
ice_endpointSelection	Returns a new proxy having the given selection policy (random or ordered). See Section 36.3.1 for more information.	No
ice_getEndpointSelection	Returns the endpoint selection policy for the proxy.	No
ice_context	Returns a new proxy having the given request context. See Section 32.12 for more infor­mation on request contexts.	No
ice_getContext	Returns the request context associated with the proxy. See Section 32.12 for more infor­mation on request contexts.	No
ice_facet	Returns a new proxy having the given facet name. See Chapter 33 for more informa­tion on facets.	No
ice_getFacet	Returns the name of the facet associated with the proxy, or an empty string if no facet has been set. See Chapter 33 for more information on facets.	No
ice_twoway	Returns a new proxy for making twoway invocations.	No
ice_isTwoway	Returns true if the proxy uses twoway invocations, otherwise false.	No
ice_oneway	Returns a new proxy for mak­ing oneway invocations (see Section 32.14).	No
ice_isOneway	Returns true if the proxy uses oneway invocations, otherwise false.	No
ice_batchOneway	Returns a new proxy for mak­ing batch oneway invocations (see Section 32.16).	No
ice_isBatchOneway	Returns true if the proxy uses batch oneway invocations, oth­erwise false.	No
ice_datagram	Returns a new proxy for mak­ing datagram invocations (see Section 32.15).	No
ice_isDatagram	Returns true if the proxy uses datagram invocations, other­wise false.	No
ice_batchDatagram	Returns a new proxy for mak­ing batch datagram invocations (see Section 32.16).	No
ice_isBatchDatagram	Returns true if the proxy uses batch datagram invocations, otherwise false.	No
ice_secure	Returns a new proxy whose endpoints may be filtered depending on the boolean argu­ment. If true, only endpoints using secure transports are allowed, otherwise all end­points are allowed.	No
ice_isSecure	Returns true if the proxy uses only secure endpoints, other­wise false.	No
ice_preferSecure	Returns a new proxy whose endpoints are filtered depending on the boolean argument. If true, endpoints using secure transports are given precedence over endpoints using non-secure transports. If false, the default behavior gives prece­dence to endpoints using non-secure transports.	No
ice_isPreferSecure	Returns true if the proxy pre­fers secure endpoints, otherwise false.	No
ice_compress	Returns a new proxy whose protocol compression capability is determined by the boolean argument. If true, the proxy uses protocol compression if it is supported by the endpoint. If false, protocol compression is never used.	No
ice_timeout	Returns a new proxy with the given timeout value in millisec­onds. A value of ‑1 disables timeouts. See Section 32.13 for more information on timeouts.	No
ice_router	Returns a new proxy configured with the given router proxy. See Chapter 42 for more informa­tion on routers.	No
ice_getRouter	Returns the router that is con­figured for the proxy (null if no router is configured).	No
ice_locator	Returns a new proxy with the specified locator. See Chapter 38 for more informa­tion on locators.	No
ice_getLocator	Returns the locator that is con­figured for the proxy (null if no locator is configured).	No
ice_locatorCacheTimeout	Returns a new proxy with the specified locator cache time­out. When binding a proxy to an endpoint, the run time caches the proxy returned by the loca­tor and uses the cached proxy while the cached proxy has been in the cache for less than the timeout. Proxies older than the timeout cause the run time to rebind via the locator. A value of 0 disables caching entirely, and a value of ‑1 means that cached proxies never expire. The default value is ‑1.	No
ice_getLocatorCacheTimeout	Returns the locator cache time­out value in seconds.	No
ice_collocationOptimized	Returns a new proxy configured for collocation optimization. If true, collocated optimiza­tions are enabled. The default value is true.	No
ice_isCollocationOptimized	Returns true if the proxy uses collocation optimization, other­wise false.	No
ice_connectionId	Returns a new proxy having the given connection identifier. See Section 36.3.3 for more infor­mation.	No
ice_getConnectionId	Returns the connection id, or an empty string if no connection id has been configured.	No
ice_getConnection	Returns an object representing the connection used by the proxy. If the proxy is not cur­rently associated with a connec­tion, the Ice run time attempts to establish a connection first. See Section 36.5 for more information.	No
ice_getCachedConnection	Returns an object representing the connection used by the proxy, or null if the proxy is not currently associated with a con­nection. See Section 36.5 for more information.	No
ice_connectionCached	Enables or disables connection caching for the proxy. See Section 36.3.4 for more infor­mation	No
ice_isConnectionCached	Returns true if the proxy uses connection caching, otherwise false.	No
ice_flushBatchRequests begin_ice_flushBatchRequests	Sends a batch of operation invocations synchronously or asynchronously (see Section 32.16).	Yes
ice_invoke begin_ice_invoke	Allows dynamic invocation of an operation without the need for compiled Slice definitions. Requests can be sent synchro­nously (see Section 35.3.1) or asynchronously (see Section 35.4).	Yes

32.11.3 Endpoints

Proxy endpoints are the client-side equivalent of object adapter endpoints (see Section 32.4.6). A proxy endpoint identifies the protocol information used to contact a remote object, as shown in the following example:

tcp ‑h www.zeroc.com ‑p 10000

This endpoint states that an object is reachable via TCP on the host www.zeroc.com and the port 10000.

A proxy must have, or be able to obtain, at least one endpoint in order to be useful. As defined in Section 2.2.2, a direct proxy contains one or more endpoints:

MyObject:tcp ‑h www.zeroc.com ‑p 10000:ssl ‑h www.zeroc.com ‑p 10001

In this example the object with the identity MyObject is available at two sepa­rate endpoints, one using TCP and the other using SSL.

If a direct proxy does not contain the ‑h option (that is, no host is specified), the Ice run time uses the value of the Ice.Default.Host property (see Appendix D). If Ice.Default.Host is not defined, the localhost interface is used.

An indirect proxy uses a locator (see Chapter 38) to retrieve the endpoints dynamically. One style of indirect proxy contains an adapter identifier:

MyObject @ MyAdapter

When this proxy requires the endpoints associated with MyAdapter, it requests them from the locator.

32.11.4 Endpoint Filtering

A proxy’s configuration determines how its endpoints are used. For example, a proxy configured for secure communication will only use endpoints having a secure protocol, such as SSL.

The factory functions described in Table 32.2 allow applications to manipu­late endpoints indirectly. Calling one of these functions returns a new proxy whose endpoints are used in accordance with the proxy’s configuration.

Table 32.2. Proxy factory functions and their effects on endpoints.

Option	Description
ice_secure	Selects only endpoints using a secure protocol (e.g., SSL).
ice_datagram	Selects only endpoints using a datagram protocol (e.g., UDP).
ice_batchDatagram	Selects only endpoints using a datagram protocol (e.g., UDP).
ice_twoway	Selects only endpoints capable of making twoway invocations (e.g., TCP, SSL). For example, this dis­ables datagram endpoints.
ice_oneway	Selects only endpoints capable of making reliable oneway invocations (e.g., TCP, SSL). For example, this disables datagram endpoints.
ice_batchOneway	Selects only endpoints capable of making reliable oneway batch invocations (e.g., TCP, SSL). For exam­ple, this disables datagram endpoints.

Upon return, the set of endpoints in the new proxy is unchanged from the old one. However, the new proxy’s configuration drives a filtering process that the Ice run time performs during connection establishment, as described in Section 36.3.1.

The factory functions do not raise an exception if they produce a proxy with no viable endpoints. For example, the C++ statement below creates such a proxy:

proxy = comm‑>stringToProxy("id:tcp ‑p 10000")‑>ice_datagram();

It is always possible that a proxy could become viable after additional factory functions are invoked, therefore the Ice run time does not raise an exception until connection establishment is attempted. At that point, the application can expect to receive NoEndpointException if the filtering process eliminates all endpoints.

An application can also create a proxy with a specific set of endpoints using the ice_endpoints factory function, whose only argument is a sequence of Ice::Endpoint objects. At present, an application is not able to create new instances of Ice::Endpoint, but rather can only incorporate instances obtained by calling ice_getEndpoints on a proxy. Note that ice_getEndpoints may return an empty sequence if the proxy has no endpoints, as is the case with an indirect proxy.

32.11.5 Defaults and Overrides

It is important to understand how proxies are influenced by Ice configuration properties and settings. The relevant properties can be classified into two catego­ries: defaults and overrides.

Default Properties

Default properties affect proxies created as the result of an Ice invocation, or by calls to stringToProxy or propertyToProxy. These properties do not influence proxies created by factory methods.

For example, suppose we define the following default property:

Ice.Default.PreferSecure=1

We can verify that the property has the desired affect using the following C++ code:

Ice::ObjectPrx p = communicator‑>stringToProxy(...);
assert(p‑>ice_isPreferSecure());

Furthermore, we can verify that the property does not affect proxies returned by factory methods:

Ice::ObjectPrx p2 = p‑>ice_preferSecure(false);
assert(!p2‑>ice_isPreferSecure());
Ice::ObjectPrx p3 = p2‑>ice_oneway();
assert(!p3‑>ice_isPreferSecure());

The default properties are described in Section D.8.

Override Properties

Defining an override property causes the Ice run time to ignore any equivalent proxy setting and use the override property value instead. For example, consider the following property definition:

Ice.Override.Secure=1

This property instructs the Ice run time to use only secure endpoints, producing the same semantics as calling ice_secure(true) on every proxy. However, the property does not alter the settings of an existing proxy, but rather directs the Ice run time to use secure endpoints regardless of the proxy’s security setting. We can verify that this is the case using the following C++ code:

Ice::ObjectPrx p = communicator‑>stringToProxy(...);
p = p‑>ice_secure(false);
assert(!p‑>ice_isSecure()); // The security setting is retained.

The override properties are described in Section D.8.