The mapping of Slice interfaces revolves around the idea that, to invoke a remote operation, you call a member function on a local class instance that is a proxy for the remote object. This makes the mapping easy and intuitive to use because making a remote procedure call is no different from making a local procedure call (apart from error semantics).

On this page:

Proxy Classes and Proxy Handles

...

In the client's address space, an instance of IceProxy::M::Simple is the local ambassador for a remote instance of the Simple interface in a server and is known as a proxy class instance. All the details about the server-side object, such as its address, what protocol to use, and its object identity are encapsulated in that instance.

Inheritance from Ice::Object

...

One of the overloaded member functions has a trailing parameter of type Ice::Context. This parameter is for use by the Ice run time to store information about how to deliver a request; normally, you do not need to supply a value here and can pretend that the trailing parameter does not exist. (The parameter is also used by IceStorm.)

Proxy Handles

Client-side application code never manipulates proxy class instances directly. In fact, you are not allowed to instantiate a proxy class directly. The following code will not compile because Ice::Object is an abstract base class with a protected constructor and destructor:

...

Because the application code always uses proxy handles and never touches the proxy class directly, we usually use the term proxy to denote both proxy handle and proxy class. This reflects the fact that, in actual use, the proxy handle looks and feels like the underlying proxy class instance. If the distinction is important, we use the terms proxy class, proxy class instance, and proxy handle.

ProxyType and PointerType

...

{zcode:cpp}
template<typename T>
class ProxyWrapper {
public:
    T::ProxyType proxy() const;
    // ...
};
{zcode}

Methods on Proxy Handles

As we saw for the preceding example, the handle is actually a template of type IceInternal::ProxyHandle that takes the proxy class as the template parameter. This template has the usual default constructor, copy constructor, and assignment operator.

...

{zcode:cpp}
try {
    SimplePrx s;        // Default?constructed proxy
    s?->op();            // Call via nil proxy
    assert(0);          // Can't get here
} catch (const IceUtil::NullHandleException&) {
    cout << "As expected, got a NullHandleException" << endl;
}
{zcode}

Copy constructor

The copy constructor ensures that you can construct a proxy handle from another proxy handle. Internally, this increments a reference count on the proxy; the destructor decrements the reference count again and, once the count drops to zero, deallocates the underlying proxy class instance. That way, memory leaks are avoided:

...

Note the assertion in this example: proxy handles support comparison.

Assignment operator

You can freely assign proxy handles to each other. The handle implementation ensures that the appropriate memory-management activities take place. Self-assignment is safe and you do not have to guard against it:

...

Implicit narrowing conversions result in a compile error, so the usual C++ semantics are preserved: you can always assign a derived type to a base type, but not vice versa.

Checked cast

Proxy handles provide a checkedCast method:

...

The reply from the server is communicated to the application code in form of a successful (non-null) or unsuccessful (null) result. Sending a remote message is necessary because, as a rule, there is no way for the client to find out what the actual run-time type of a proxy is without confirmation from the server. (For example, the server may replace the implementation of the object for an existing proxy with a more derived one.) This means that you have to be prepared for a checkedCast to fail. For example, if the server is not running, you will receive a ConnectFailedException; if the server is running, but the object denoted by the proxy no longer exists, you will receive an ObjectNotExistException.

Unchecked cast

In some cases, it is known that an object supports a more derived interface than the static type of its proxy. For such cases, you can use an unchecked down-cast:

...

Despite its dangers, uncheckedCast is still useful because it avoids the cost of sending a message to the server. And, particularly during initialization, it is common to receive a proxy of static type Ice::Object, but with a known run-time type. In such cases, an uncheckedCast saves the overhead of sending a remote message.

Stream insertion and stringification

...

{zcode:cpp}
Ice::ObjectPrx p = ...;
cout << p?->ice_toString() << endl;
{zcode}

...

{zcode:cpp}
Ice::ObjectPrx p = ...;
cout << communicator?->proxyToString(p) << endl;
{zcode}

The advantage of using the ice_toString member function instead of proxyToString is that you do not need to have the communicator available at the point of call.

Using Proxy Methods in C++

...

The only exceptions are the factory methods ice_facet and ice_identity. Calls to either of these methods may produce a proxy for an object of an unrelated type, therefore they return a base proxy that you must subsequently down-cast to an appropriate type.

Object Identity and Proxy Comparison in C++

Proxy handles support comparison using the following operators:

• operator==
operator!=
  These operators permit you to compare proxies for equality and inequality. To test whether a proxy is null, use a comparison with the literal 0, for example:

  Wiki Markup
  {zcode:cpp} if (proxy == 0)     // It's a nil proxy else     // It's a non?nil proxy {zcode}

• operator<
operator<=
operator>
operator>=
  Proxies support comparison. This allows you to place proxies into STL containers such as maps or sorted lists.

• Boolean comparison
  Proxies have a conversion operator to bool. The operator returns true if a proxy is not null, and false otherwise. This allows you to write:

  Wiki Markup
  {zcode:cpp} BasePrx base = ...; if (base)         // It's a non?nil proxy else         // It's a nil proxy {zcode}

...

{zcode:cpp}
Ice::ObjectPrx p1 = ...;        // Get a proxy...
Ice::ObjectPrx p2 = ...;        // Get another proxy...

if (!Ice::proxyIdentityEqual(p1, p2) {
    // p1 and p2 denote different objects       // Correct
} else {
    // p1 and p2 denote the same object         // Correct
}
{zcode}

See Also

• Interfaces, Operations, and Exceptions
• Proxies
• C++ Mapping for Operations
• Example of a File System Client in C++
• Using Proxies
• Facets and Versioning
• IceStorm