28.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 28.5) and addressing details such as endpoints (see Section 28.10.3). Proxy methods provide access to configuration and connection information, and act as factories for creating new proxies (see Section 28.10.2). Finally, a proxy initiates the establishment of a new connection when necessary (see Section 33.3).

28.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 28.2 for more information on the stringToProxy operation.

Proxy Properties

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:

MyApp.Proxy=ident:tcp ‑p 5000

We can use the communicator operation propertyToProxy to convert the property’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 demonstrate 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.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 C.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 28.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 configured 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 demonstrates 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.

28.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_hash();
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);
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 28.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 original 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 FixedProxyException. See page 16 for a description of fixed proxies and Section 33.7 for additional details.

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

28.10.3 Endpoints

28.10.4 Endpoint Filtering

28.10.5 Defaults and Overrides

Default Properties

Override Properties