37.5 Obtaining a Connection

Applications can gain access to an Ice object representing an established connection.

37.5.1 The Ice::Connection Interface

The Slice definition of the Connection interface is shown below:

module Ice {
    local interface Connection {
        void close(bool force);
        Object* createProxy(Identity id);
        void setAdapter(ObjectAdapter adapter);
        ObjectAdapter getAdapter();
        void flushBatchRequests();
        string type();
        int timeout();
        string toString();
    };
};

As indicated in the Slice definition, a connection is a local object, similar to a communicator or an object adapter. A connection object therefore is only usable within the process and cannot be accessed remotely.

The Connection interface supports the following operations:

• void close(bool force)

Explicitly closes the connection. The connection is closed gracefully if force is false, otherwise the connection is closed forcefully. See Section 37.5.4 for more information.

• Object* createProxy(Identity id)

Creates a special proxy that only uses this connection. See Section 37.7 for more information.

• void setAdapter(ObjectAdapter adapter)

Enables callbacks over this connection. See Section 37.7 for more information.

• ObjectAdapter getAdapter()

Returns the object adapter associated with this connection, or nil if no association has been made.

• void flushBatchRequests()

Flushes any pending batch requests for this connection.

• string type()

Returns the connection type as a string, such as "tcp".

• int timeout()

Returns the timeout value used when the connection was established.

• string toString()

Returns a readable description of the connection.

37.5.2 Clients

Clients obtain a connection by calling ice_getConnection or ice_getCachedConnection on a proxy (see Section 32.11.2). If the proxy does not yet have a connection, the ice_getConnection method attempts to establish one. As a result, the caller must be prepared to handle connection failure exceptions as described in Section 37.3.2. Furthermore, if the proxy denotes a collocated object and collocation optimization is enabled, calling ice_getConnection results in a CollocationOptimizationException.

If you wish to obtain the proxy’s connection without the potential for triggering connection establishment, call ice_getCachedConnection; this method returns null if the proxy is not currently associated with a connection or if connection caching is disabled for the proxy.

As an example, the C++ code below illustrates how to obtain a connection from a proxy and print its type:

Ice::ObjectPrx proxy = ...
try
{
    Ice::ConnectionPtr conn = proxy‑>ice_getConnection();
    cout << conn‑>type() << endl;
}
catch(const Ice::CollocationOptimizationException&)
{
    cout << "collocated" << endl;
}

37.5.3 Servers

Servers can access a connection via the con member of the Ice::Current parameter passed to every operation (see Section 32.6). For collocated invocations, con has a nil value.

For example, this Java code shows how to invoke toString on the connection:

public int add(int a, int b, Ice.Current curr)
{
    if (curr.con != null)
    {
        System.out.println("Request received on connection:\n" +
                           curr.con.toString());
    }
    else
    {
        System.out.println("collocated invocation");
    }
    return a + b;
}

Although the mapping for the Slice operation toString results in a Java method named _toString, the Ice run time implements toString to return the same value.

37.5.4 Closing a Connection

Applications should rarely need to close a connection explicitly, but those that do must be aware of its implications. Since there are two ways to close a connection, we discuss them separately.

Graceful Closure

Passing an argument of false to the close operation initiates graceful connection closure, as discussed in Section 37.6. The operation blocks until all pending outgoing requests on the connection have completed.

Forceful Closure

A forceful closure is initiated by passing an argument of true to the close operation, causing the peer to receive a ConnectionLostException.

A client must use caution when forcefully closing a connection. Any outgoing requests that are pending on the connection when close is invoked will fail with a ForcedCloseConnectionException. Furthermore, requests that fail with this exception are not automatically retried.

Forceful closure can be useful as a defense against hostile clients. For example, the Glacier2 router implementation forcefully closes a connection from a client that has not first created a session.

The Ice run time interprets a CloseConnectionException to mean that it is safe to retry the request without violating at‑most-once semantics (see Section 32.23). If automatic retries are enabled, a client must only initiate a graceful close when it knows that there are no outgoing requests in progress on that connection, or that any pending requests can be safely retried.