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

`destroy`

  Destroy the communicator.

`shutdown`

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

`waitForShutdown`

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

`stringToProxy`

  Convert a string into a proxy.

`proxyToString`

  Convert a proxy into a string.

`stringToIdentity`

  Convert a string into an identity.

`identityToString`

  Convert an identity into a string.

`createObjectAdapter`

  Create a new object adapter.

`createObjectAdapterWithEndpoints`

  Create a new object adapter with endpoints.

`createObjectAdapterWithRouter`

  Create a new object adapter with a router.

`addObjectFactory`

  Add a servant factory to this communicator.

`findObjectFactory`

  Find a servant factory registered with this communicator.

`getDefaultContext`

  Get the currently-set default context.

`getProperties`

  Get the properties for this communicator.

`getLogger`

  Get the logger for this communicator.

`getStats`

  Get the statistics callback object for this communicator.

`getDefaultRouter`

  Get the default router this communicator.

`setDefaultRouter`

  Set a default router for this communicator.

`getDefaultLocator`

  Get the default locator this communicator.

`setDefaultLocator`

  Set a default Ice locator for this communicator.

`getPluginManager`

  Get the plug-in manager for this communicator.

`flushBatchRequests`

  Flush any pending batch requests for this communicator.

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

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

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

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

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

## `stringToIdentity`

    Identity stringToIdentity(string str);

Convert a string into an identity.

### Parameters

`str`

  The string to convert into an identity.

### Return Value

The identity.

### See Also

`identityToString`

## `identityToString`

    string identityToString(Identity ident);

Convert an identity into a string.

### Parameters

`ident`

  The identity to convert into a string.

### Return Value

The "stringified" identity.

### See Also

`stringToIdentity`

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

## `createObjectAdapterWithRouter`

    ObjectAdapter createObjectAdapterWithRouter(string name,
        Router* rtr);

Create a new object adapter with a router. This operation creates a routed object adapter.

### Parameters

`name`

  The object adapter name.

`router`

  The router.

### Return Value

The new object adapter.

### See Also

`createObjectAdapter`, `ObjectAdapter`, `Properties`

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

`findObjectFactory`, `ObjectFactory`

## `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`, `ObjectFactory`

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

## `getProperties`

    Properties getProperties();

Get the properties for this communicator.

### Return Value

This communicator's properties.

### See Also

`Properties`

## `getLogger`

    Logger getLogger();

Get the logger for this communicator.

### Return Value

This communicator's logger.

### See Also

`Logger`

## `getStats`

    Stats getStats();

Get the statistics callback object for this communicator.

### Return Value

This communicator's statistics callback object.

### See Also

`Stats`

## `getDefaultRouter`

    Router* getDefaultRouter();

Get the default router this communicator.

### Return Value

The default router for this communicator.

### See Also

`setDefaultRouter`, `Router`

## `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`, `createObjectAdapterWithRouter`, `Router`

## `getDefaultLocator`

    Locator* getDefaultLocator();

Get the default locator this communicator.

### Return Value

The default locator for this communicator.

### See Also

`setDefaultLocator`, `Locator`

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

## `getPluginManager`

    PluginManager getPluginManager();

Get the plug-in manager for this communicator.

### Return Value

This communicator's plug-in manager.

### See Also

`PluginManager`

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

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