Applications can gain access to an Ice object representing an established connection.
On this page:
The Slice definition of the
Connection interface is shown below:
As indicated in the Slice definition, a connection is a local interface, similar to a communicator or an object adapter. A connection therefore is only usable within the process and cannot be accessed remotely.
Connection interface supports the following operations:
void close(bool force)
Explicitly closes the connection. The connection is closed gracefully if
forceis false, otherwise the connection is closed forcefully.
Object* createProxy(Identity id)
Creates a special proxy that only uses this connection. This operation is primarily used for bidirectional connections.
void setAdapter(ObjectAdapter adapter)
Associates this connection with an object adapter to enable a bidirectional connection.
Returns the object adapter associated with this connection, or nil if no association has been made.
Flushes any pending batch requests for this connection.
void setCallback(ConnectionCallback callback)
Associates a callback with this connection that is invoked whenever the connection receives a heartbeat message or is closed. Passing a nil value clears the current callback.
void setACM(optional(1) int timeout, optional(2) ACMClose close, optional(3) ACMHeartbeat heartbeat)
Configures Active Connection Management settings for this connection. All arguments are optional, therefore you can change some of the settings while leaving the others unaffected. Refer to your language mapping for more details on optional parameters.
Returns the connection's current settings for Active Connection Management.
Returns the connection type as a string, such as
Returns the timeout value used when the connection was established.
Returns a readable description of the connection.
This operation returns a
ConnectionInfoclass defined as follows:
incomingmember is true if the connection is an incoming connection and false, otherwise. If
adapterNameprovides the name of the object adapter that accepted the connection. Note that the object returned by
getInfoimplements a more derived interface, depending on the connection type. You can down-cast the returned class instance and access the connection-specific information according to the type of the connection.
Flushing Batch Requests for a Connection
flushBatchRequests operation blocks the calling thread until any batch requests that are queued for a connection have been successfully written to the local transport. To avoid the risk of blocking, you can also invoke this operation asynchronously using the
begin_flushBatchRequests method (in those language mappings that support it).
Since batch requests are inherently oneway invocations, the
begin_flushBatchRequests method does not support a request callback. However, you can use the exception callback to handle any errors that might occur while flushing, and the sent callback to receive notification that the batch request has been flushed successfully.
For example, the code below demonstrates how to flush batch requests asynchronously in C++:
For more information on asynchronous invocations, please see the relevant language mapping chapter.
Connection::getEndpoint operation returns an interface of type
getInfo operation returns an
EndpointInfo instance. Note that the object returned by
getInfo implements a more derived interface, depending on the endpoint type. You can down-cast the returned class instance and access the endpoint-specific information according to the type of the endpoint, as returned by the
timeout member provides the timeout in milliseconds. The
compress member is true if the endpoint uses compression (if available). The
datagram operation returns true if the endpoint is for a datagram transport, and the
secure operation returns true if the endpoint uses SSL.
The derived classes provide further detail about the endpoint according to its type.
An application may receive a proxy that contains an endpoint whose type is unrecognized by the Ice run time. In this situation, Ice preserves the endpoint in its encoded (opaque) form so that the proxy remains intact, but Ice ignores the endpoint for all connection-related activities. Preserving the endpoint allows an application to later forward that proxy with all of its original endpoints to a different program that might support the endpoint type in question.
Although a connection will never return an opaque endpoint, it is possible for a program to encounter an opaque endpoint when iterating over the endpoints returned by the proxy method
As a practical example, consider a program for which the IceSSL plug-in is not configured. If this program receives a proxy containing an SSL endpoint, Ice treats it as an opaque endpoint such that calling
getInfo on the endpoint object returns an instance of
Note that the
type operation of the
OpaqueEndpointInfo object returns the actual type of the endpoint. For example, the operation returns the value
2 if the object encodes an SSL endpoint. As a result, your program cannot assume that an
EndpointInfo object whose type is
2 can be safely down-cast to
IceSSL::EndpointInfo; if the IceSSL plug-in is not configured, such a down-cast will fail because the object is actually an instance of
Client-Side Connection Usage
Clients obtain a connection by using one of the proxy methods
ice_getCachedConnection. If the proxy does not yet have a connection, the
ice_getConnection method immediately attempts to establish one. As a result, the caller must be prepared for this method to block and raise connection failure exceptions. (Use the asynchronous version of this method to avoid blocking.) If the proxy denotes a collocated object and collocation optimization is enabled, calling
ice_getConnection returns null.
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:
Server-Side Connection Usage
Servers can access a connection via the
con member of the
Ice::Current parameter passed to every operation. For collocated invocations,
con has a nil value.
For example, this Java code shows how to invoke
toString on the connection:
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.
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.
Passing an argument of
false to the
close operation initiates graceful connection closure, as discussed in Connection Closure. The operation blocks until all pending outgoing requests on the connection have completed.
A forceful closure is initiated by passing an argument of
true to the
close operation, causing the peer to receive a
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.
In a server context, forceful closure can be useful as a defense against hostile clients.
The Ice run time interprets a
CloseConnectionException to mean that it is safe to retry the request without violating at-most-once semantics. 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.