Ice::Communicator

Overview

local interface Communicator

The central object in Ice. One or more communicators can be instantiated for an Ice application. Communicator instantiation is language specific, and not specified in Slice code.

addObjectFactory

void addObjectFactory(ObjectFactory factory,
    string id);

Add a servant factory to this communicator. Installing a factory with an id for which a factory is already registered throws AlreadyRegisteredException.

When unmarshaling an Ice object, the Ice run-time reads the most-derived type id off the wire and attempts to create an instance of the type using a factory. If no instance is created, either because no factory was found, or because all factories returned nil, the object is sliced to the next most-derived type and the process repeats. If no factory is found that can create an instance, the Ice run-time will slice the object to the type Ice::Object.

The following order is used to locate a factory for a type:

1. The Ice run-time looks for a factory registered specifically for the type.

2. If no instance has been created, the Ice run-time looks for the default factory, which is registered with an emtpy type id.

3. If no instance has been created by any of the preceding steps, the Ice run-time looks for a factory that may have been statically generated by the language mapping for non-abstract classes.

createObjectAdapter

ObjectAdapter createObjectAdapter(string name);

Create a new object adapter. The endpoints for the object adapter are taken from the property name.Endpoints.

createObjectAdapterWithEndpoints

ObjectAdapter createObjectAdapterWithEndpoints(string name,
    string endpoints);

Create a new object adapter with endpoints. This method sets the property name.Endpoints, and then calls createObjectAdapter. It is provided as a convenience function.

destroy

void destroy();

Destroy the communicator. This operation calls shutdown implicitly. Calling destroy cleans up memory, and shuts down this communicator's client functionality. Subsequent calls to destroy are ignored.

findObjectFactory

ObjectFactory findObjectFactory(string id);

Find a servant factory registered with this communicator.

flushBatchRequests

void flushBatchRequests();

Flush any pending batch requests for this communicator. This causes all batch requests that were sent via proxies obtained via this communicator to be sent to the server.

getDefaultLocator

Locator* getDefaultLocator();

Get the default locator this communicator.

getDefaultRouter

Router* getDefaultRouter();

Get the default router this communicator.

getLogger

Logger getLogger();

Get the logger for this communicator.

getPluginManager

PluginManager getPluginManager();

Get the plug-in manager for this communicator.

getProperties

Properties getProperties();

Get the properties for this communicator.

getStats

Stats getStats();

Get the statistics callback object for this communicator.

proxyToString

string proxyToString(Object* obj);

Convert a proxy into a string.

removeObjectFactory

void removeObjectFactory(string id);

Remove a servant factory from this communicator. Removing an id for which no factory is registered throws NotRegisteredException.

setDefaultLocator

void setDefaultLocator(Locator* loc);

Set a default Ice locator for this communicator. All newly created proxy and object adapters will use this default locator. To disable the default locator, null can be used. Note that this operation has no effect on existing proxies or object adapters.

You can also set a locator for an individual proxy by calling the operation ice_locator on the proxy, or for an object adapter by calling the operation setLocator on the object adapter.

setDefaultRouter

void setDefaultRouter(Router* rtr);

Set a default router for this communicator. All newly created proxies will use this default router. To disable the default router, null can be used. Note that this operation has no effect on existing proxies.

You can also set a router for an individual proxy by calling the operation ice_router on the proxy.

setLogger

void setLogger(Logger log);

Set the logger for this communicator.

setStats

void setStats(Stats st);

Set the statistics callback object for this communicator.

shutdown

void shutdown();

Shuts down this communicator's server functionality, including the deactivation of all object adapters. Subsequent calls to shutdown are ignored.

After shutdown returns, no new requests are processed. However, requests that have been started before shutdown was called might still be active. You can use waitForShutdown to wait for the completion of all requests.

stringToProxy

Object* stringToProxy(string str);

Convert a string into a proxy. For example, MyCategory/MyObject:tcp -h some_host -p 10000 creates a proxy that refers to the Ice object having an identity with a name "MyObject" and a category "MyCategory", with the server running on host "some_host", port 10000. If the string does not parse correctly, the operation throws ProxyParseException.

waitForShutdown

void waitForShutdown();

Wait until this communicator's server functionality has shut down completely. Calling shutdown initiates shutdown, and waitForShutdown only returns when all outstanding requests have completed. A typical use of this operation is to call it from the main thread, which then waits until some other thread calls shutdown. After shutdown is complete, the main thread returns and can do some cleanup work before it finally calls destroy to also shut down the client functionality, and then exits the application.