32.10 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.10.3). Proxy methods provide access to configuration and connec­tion information, and act as factories for creating new proxies (see Section 32.10.2). Finally, a proxy initiates the establishment of a new connection when necessary (see Section 36.3).

32.10.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 D 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 C.8. 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 C.3).

Note that proxy properties cannot themselves have proxy properties. For example, the following attempt to set the PreferSecure property on the default locator’s router is invalid:

Ice.Default.Locator.Router.PreferSecure=1 # Not legal!

Factory Methods

As we discuss in Section 32.10.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.10.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);
Object* ice_threadPerConnection(bool b);
bool ice_isThreadPerConnection();
Connection ice_getConnection();
Connection ice_getCachedConnection();
Object* ice_connectionCached(bool b);
bool ice_isConnectionCached();

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.11).

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

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

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 14 for a description of fixed proxies and Section 36.7.3 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 indicated by the id argument, otherwise false. This method can only be invoked on a twoway 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	No
ice_getCommunicator	Returns the communicator that was used to create this proxy.	No
ice_toString	Returns the string representation 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 Endpoint objects representing the proxy’s endpoints.	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.11 for more infor­mation on request contexts.	No
ice_getContext	Returns the request context asso­ciated with the proxy. See Section 32.11 for more infor­mation on request contexts.	No
ice_facet	Returns a new proxy having the given facet name. See Chapter 34 for more information 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 34 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 making oneway invocations (see Section 32.13).	No
ice_isOneway	Returns true if the proxy uses oneway invocations, otherwise false.	No
ice_batchOneway	Returns a new proxy for making batch oneway invocations (see Section 32.15).	No
ice_isBatchOneway	Returns true if the proxy uses batch oneway invocations, other­wise false.	No
ice_datagram	Returns a new proxy for making datagram invocations (see Section 32.14).	No
ice_isDatagram	Returns true if the proxy uses datagram invocations, otherwise false.	No
ice_batchDatagram	Returns a new proxy for making batch datagram invocations (see Section 32.15).	No
ice_isBatchDatagram	Returns true if the proxy uses batch datagram invocations, oth­erwise false.	No
ice_secure	Returns a new proxy whose end­points may be filtered depending on the boolean argument. If true, only endpoints using secure transports are allowed, otherwise all endpoints are allowed.	No
ice_isSecure	Returns true if the proxy uses only secure endpoints, otherwise false.	No
ice_preferSecure	Returns a new proxy whose end­points are filtered depending on the boolean argument. If true, endpoints using secure transports are given precedence over end­points using non-secure trans­ports. If false, the default behavior gives precedence to end­points using non-secure trans­ports.	No
ice_isPreferSecure	Returns true if the proxy pre­fers secure endpoints, otherwise false.	No
ice_compress	Returns a new proxy whose pro­tocol compression capability is determined by the boolean argu­ment. If true, the proxy uses protocol compression if it is sup­ported 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 tim­eouts. See Section 32.12 for more information on timeouts.	No
ice_router	Returns a new proxy configured with the given router proxy. See Chapter 42 for more information on routers.	No
ice_getRouter	Returns the router that is config­ured for the proxy (null if no router is configured).	No
ice_locator	Returns a new proxy configured with the given locator proxy. See Chapter 38 for more information on locators.	No
ice_getLocator	Returns the locator that is config­ured for the proxy (null if no locator is configured).	No
ice_locatorCacheTimeout	For indirect proxies, returns a new proxy with the specified locator cache timeout. The client side caches proxies returned by a locator for the specified time in seconds, before contacting the locator again. A value of 0 dis­ables caching entirely, and a value of -1 means that cached proxies never expire. For direct and fixed proxies, the operation is a no‑op and returns the same proxy that was passed to the oper­ation.	No
ice_getLocatorCacheTimeout	Returns the locator cache timeout value in seconds. For direct and fixed reference, this operation always returns zero.	No
ice_collocationOptimized	Returns a new proxy configured for collocation optimization. If true, collocated optimizations are enabled. The default value is true. For AMI invocations, the optimization setting is ignored—AMI invocations implicitly dis­able the collocation optimization.	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 informa­tion.	No
ice_threadPerConnection	Returns a new proxy configured with the desired threading model. If true, thread-per-connection is enabled. By default a proxy uses the communicator’s default threading model. See Section 32.9 for more informa­tion.	No
ice_isThreadPerConnection	Returns true if the proxy uses the thread-per-connection thread­ing model, otherwise false.	No
ice_getConnection	Returns an object representing the connection used by the proxy. If the proxy is not currently asso­ciated with a connection, 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 cur­rently associated with a connec­tion. 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 informa­tion	No
ice_isConnectionCached	Returns true if the proxy uses connection caching, otherwise false.	No

32.10.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 stringified proxy does not contain the ‑h option (that is, not host is speci­fied), invocations on the proxy attempt to locate the server using the host name returned by gethostname.

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.10.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 manipulate 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.10.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 C.7.

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 C.7.