28.3 Communicator Initialization

During the creation of a communicator, the Ice run time initializes a number of features that affect the communicator’s operation. Once set, these features remain in effect for the life time of the communicator, that is, you cannot change these features after you have created a communicator. Therefore, if you want to customize these features, you must do so when you create the communicator.

The following features can be customized at communicator creation time:

• the property set (see Chapter 26)

• the Logger interface (see Section 28.19)

• the Stats interface (see Section 28.20)

• the narrow and wide string converters (C++ only, see page 885)

• the thread notification hook (see page 817)

To establish these features, you initialize a structure or class of type InitializationData with the relevant settings. For C++ the structure is defined as follows:

namespace Ice {
    struct InitializationData {
        PropertiesPtr properties;
        LoggerPtr logger;
        StatsPtr stats;
        StringConverterPtr stringConverter;
        WstringConverterPtr wstringConverter;
        ThreadNotificationPtr threadHook;
    };
}

For languages other than C++, InitializationData is a class with all data members public. (The string converter fields are missing for these languages.)

For C++, Ice::initialize is overloaded as follows:

namespace Ice {
    CommunicatorPtr initialize(int&, char*[],
                const InitializationData& = InitializationData());
    CommunicatorPtr initialize(StringSeq&,
                const InitializationData& = InitializationData());
    CommunicatorPtr initialize(
                const InitializationData& = InitializationData());
}

The version of initialize that accepts an argc/argv pair looks for Ice-specific command-line options and removes them from the argument vector, as described on page 262. The version without an argc/argv pair is useful if you want to prevent property settings for a program to be changed from the command line (see Section 26.8).

To set a feature, you set the corresponding field in the InitializationData structure and pass the structure to initialize. For example, to establish a custom logger of type MyLogger, you can use:

Ice::InitializationData id;
id.logger = new MyLoggerI;
Ice::CommunicatorPtr ic = Ice::initialize(argc, argv, id);

For Java and C#, Ice.Util.initialize is overloaded similarly (as is Ice.initialize for Python and Ice::initialize for Ruby), so you can pass an InitializationData instance either with or without an argument vector. The version of initialize without an argument does not look for a configuration in the ICE_CONFIG environment variable. (See also Section 26.6.)