Ice Reference Documentation
<<< Previous | Slice Documentation | Next >>>

# `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.

### Used By

`::Freeze::Connection::getCommunicator`, `ObjectAdapter::getCommunicator`, `::IceBox::Service::start`

### See Also

`Logger`, `Stats`, `ObjectAdapter`, `Properties`, `ObjectFactory`

### Operation Index

`addObjectFactory`

  Add a servant factory to this communicator.

`createObjectAdapter`

  Create a new object adapter.

`createObjectAdapterWithEndpoints`

  Create a new object adapter with endpoints.

`destroy`

  Destroy the communicator.

`findObjectFactory`

  Find a servant factory registered with this communicator.

`flushBatchRequests`

  Flush any pending batch requests for this communicator.

`getDefaultContext`

  Get the currently-set default context.

`getDefaultLocator`

  Get the default locator this communicator.

`getDefaultRouter`

  Get the default router this communicator.

`getLogger`

  Get the logger for this communicator.

`getPluginManager`

  Get the plug-in manager for this communicator.

`getProperties`

  Get the properties for this communicator.

`getStats`

  Get the statistics callback object for this communicator.

`proxyToString`

  Convert a proxy into a string.

`removeObjectFactory`

  Remove a servant factory from this communicator.

`setDefaultContext`

  Set a default context on this communicator.

`setDefaultLocator`

  Set a default Ice locator for this communicator.

`setDefaultRouter`

  Set a default router for this communicator.

`setLogger`

  Set the logger for this communicator.

`setStats`

  Set the statistics callback object for this communicator.

`shutdown`

  Shuts down this communicator's server functionality, including the deactivation of all object adapters.

`stringToProxy`

  Convert a string into a proxy.

`waitForShutdown`

  Wait until this communicator's server functionality has shut down completely.

## `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 throws `NoObjectFactoryException`.

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.

### Parameters

`factory`

  The factory to add.

`id`

  The type id for which the factory can create instances, or an empty string for the default factory.

### See Also

`removeObjectFactory`, `findObjectFactory`, `ObjectFactory`

## `createObjectAdapter`

    ObjectAdapter createObjectAdapter(string name);

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

### Parameters

`name`

  The object adapter name.

### Return Value

The new object adapter.

### See Also

`createObjectAdapterWithEndpoints`, `ObjectAdapter`, `Properties`

## `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.

### Parameters

`name`

  The object adapter name.

`endpoints`

  The endpoints for the object adapter.

### Return Value

The new object adapter.

### See Also

`createObjectAdapter`, `ObjectAdapter`, `Properties`

## `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.

### See Also

`shutdown`

## `findObjectFactory`

    ObjectFactory findObjectFactory(string id);

Find a servant factory registered with this communicator.

### Parameters

`id`

  The type id for which the factory can create instances, or an empty string for the default factory.

### Return Value

The servant factory, or null if no servant factory was found for the given id.

### See Also

`addObjectFactory`, `removeObjectFactory`, `ObjectFactory`

## `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.

## `getDefaultContext`

    Context getDefaultContext();

Get the currently-set default context.

### Return Value

The currently established default context. If no default context is currently set, `getDefaultContext` returns an empty context.

## `getDefaultLocator`

    Locator* getDefaultLocator();

Get the default locator this communicator.

### Return Value

The default locator for this communicator.

### See Also

`setDefaultLocator`, `Locator`

## `getDefaultRouter`

    Router* getDefaultRouter();

Get the default router this communicator.

### Return Value

The default router for this communicator.

### See Also

`setDefaultRouter`, `Router`

## `getLogger`

    Logger getLogger();

Get the logger for this communicator.

### Return Value

This communicator's logger.

### See Also

`setLogger`, `Logger`

## `getPluginManager`

    PluginManager getPluginManager();

Get the plug-in manager for this communicator.

### Return Value

This communicator's plug-in manager.

### See Also

`PluginManager`

## `getProperties`

    Properties getProperties();

Get the properties for this communicator.

### Return Value

This communicator's properties.

### See Also

`Properties`

## `getStats`

    Stats getStats();

Get the statistics callback object for this communicator.

### Return Value

This communicator's statistics callback object.

### See Also

`setStats`, `Stats`

## `proxyToString`

    string proxyToString(Object* obj);

Convert a proxy into a string.

### Parameters

`obj`

  The proxy to convert into a string.

### Return Value

The "stringified" proxy.

### See Also

`stringToProxy`

## `removeObjectFactory`

    void removeObjectFactory(string id);

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

### Parameters

`id`

  The type id for which the factory can create instances, or an empty string for the default factory.

### See Also

`addObjectFactory`, `findObjectFactory`, `ObjectFactory`

## `setDefaultContext`

    void setDefaultContext(Context ctx);

Set a default context on this communicator. Once set, all proxies that do not explicitly override the context on a per-proxy or per-invocation basis send this context with every invocation. To clear a context, call `setContext` with an empty context.

### Parameters

`ctx`

  The default context to be set.

## `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.

### Parameters

`loc`

  The default locator to use for this communicator.

### See Also

`getDefaultLocator`, `Locator`, `ObjectAdapter::setLocator`

## `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.

### Parameters

`rtr`

  The default router to use for this communicator.

### See Also

`getDefaultRouter`, `Router`, `ObjectAdapter::addRouter`

## `setLogger`

    void setLogger(Logger log);

Set the logger for this communicator.

### Parameters

`log`

  The logger to use for this communicator.

### See Also

`getLogger`, `Logger`

## `setStats`

    void setStats(Stats st);

Set the statistics callback object for this communicator.

### Parameters

`st`

  The statistics callback object to use for this communicator.

### See Also

`getStats`, `Stats`

## `shutdown`

    void shutdown();

Shuts down this communicator's server functionality, including the deactivation of all object adapters. (Attempts to use a deactivated object adapter raise `ObjectAdapterDeactivatedException`.) 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.

### See Also

`destroy`, `waitForShutdown`, `ObjectAdapter::deactivate`

## `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`.

### Parameters

`str`

  The string to convert into a proxy.

### Return Value

The proxy.

### See Also

`proxyToString`

## `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.

### See Also

`shutdown`, `destroy`, `ObjectAdapter::waitForDeactivate`

<<< Previous | Home | Next >>>
`Ice::CollocationOptimizationException` | Up | `Ice::CommunicatorDestroyedException`