---
title: "Configuring IceBox Services"
url: https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services
language: java
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Configuring IceBox Services

Programming language: Java. Other languages: [C++](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/csharp.md), [JavaScript](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/php.md), [Python](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/swift.md).

## Installing an IceBox Service

A service is configured into an IceBox server using a single [IceBox.Service](https://docs.zeroc.com/ice/3.8/property-reference/icebox-properties/java.md#icebox.service.name) property. This property serves several purposes: it defines the name of the service, it provides the server with the service entry point, and it defines properties and arguments for the service.

The format of the property is shown below:

```config
IceBox.Service.name=entry_point [args]
```

The `name` component of the property key is the service name. This name is passed to the service's `start` operation, and must be unique among all services configured in the same IceBox server. It is possible, though rarely necessary, to load two or more instances of the same service under different names.

The first argument in the property value is the entry point specification. IceBox converts an argument of the form `--name=value` that follows the entry point specification into a property of the communicator passed to the service's `start` operation when `name` starts with a [reserved prefix](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration/properties-overview/java.md), such as `Ice.`, or with the service's name followed by a period. It passes the remaining arguments to the `start` operation in the `args` parameter.

## IceBox Service Configuration

For a Java service, the [entry point](https://docs.zeroc.com/ice/3.8/property-reference/icebox-properties/java.md) is typically the class name (including any package) of the service implementation class, but may also include a leading path to a class directory or JAR file. The class must define a public constructor.

To create the service, the IceBox server first checks to see if the service defines a constructor taking an argument of type `com.zeroc.Ice.Communicator`. If so, the server invokes this constructor and passes the server's communicator, which should only be used for administrative purposes. For example, the constructor could use this communicator's logger to display log messages. For a service's normal operations, it must use the communicator that it receives as an argument to its `start` method.

If the service does not define a constructor taking a `com.zeroc.Ice.Communicator` argument, the server invokes the service's default constructor.

Here is a sample configuration for our [Java example](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/java.md):

```config
IceBox.Service.Greeter=com.example.icebox.greeter.service.GreeterService --Ice.Trace.Network=1 hello there
```

This configuration results in the creation of a service named `Greeter`. The service is expected to reside in the class `com.example.icebox.greeter.service.GreeterService`. The IceBox server converts `--Ice.Trace.Network=1` into a property of the service's communicator and passes `hello` and `there` to `start` in `args`.

You can use a configuration file to configure your IceBox service by specifying `--Ice.Config`. For example:

```config
IceBox.Service.Greeter=<entry point> --Ice.Config=/etc/greeter.cfg
```

## Load Order for IceBox Services

By default, the server loads the configured services in an undefined order, meaning services in the same IceBox server should not depend on one another. If services must be loaded in a particular order, the [IceBox.LoadOrder](https://docs.zeroc.com/ice/3.8/property-reference/icebox-properties/java.md#icebox.loadorder) property can be used:

```config
IceBox.LoadOrder=Service1,Service2
```

In this example, `Service1` is loaded first, followed by `Service2`. Any remaining services are loaded after `Service2`, in an undefined order. Each service mentioned in `IceBox.LoadOrder` must have a matching `IceBox.Service` property.

During shutdown, services are stopped in the reverse of the order in which they were loaded.

## Using a Shared Communicator

IceBox creates a separate communicator instance for each service by default in order to minimize the chances of accidental conflicts among services. You can optionally specify that certain services use a shared communicator instead by setting [IceBox.UseSharedCommunicator.*name*](https://docs.zeroc.com/ice/3.8/property-reference/icebox-properties/java.md#icebox.usesharedcommunicator.name) properties in the server's configuration:

```config
IceBox.Service.Hello=...
IceBox.Service.Printer=...
IceBox.UseSharedCommunicator.Hello=1
IceBox.UseSharedCommunicator.Printer=1
```

> **Tip**
>
> A common use case for sharing a communicator between two or more services is enabling the use of [collocation optimizations](https://docs.zeroc.com/ice/3.8/runtime/collocated-invocation-and-dispatch/java.md) for invocations among those services. This optimization is not possible with the default behavior that creates a new communicator for each service.

IceBox prepares the property set of this shared communicator as follows:

- If services [inherit the server's properties](#inheriting-properties-from-the-icebox-server), the property set initially contains the IceBox server's properties, except those whose names start with `IceBox.` or `Ice.Admin.`; otherwise the property set starts out empty.

- For each service that uses the shared communicator:

  - Merge its properties into the shared property set, overwriting any existing properties with the same names
  - Remove any properties from the shared property set that the service explicitly clears. For example, the definition `Ice.Trace.Network=` clears any existing setting of `Ice.Trace.Network` in the shared property set.
  - Translate service-specific command-line settings into properties (e.g., `--Hello.Debug=1`)

Service properties are merged in the same order as the [services are loaded](#load-order-for-icebox-services). As a result, the final value of a property that is defined by multiple services depends on the order in which those services are loaded. Let's expand our example to demonstrate this behavior:

```config
# File: server.cfg
IceBox.Service.Hello=... --Ice.Config=hello.cfg --Hello.Debug=1
IceBox.Service.Printer=... --Ice.Config=printer.cfg
IceBox.UseSharedCommunicator.Hello=1
IceBox.UseSharedCommunicator.Printer=1
IceBox.InheritProperties=1
IceBox.LoadOrder=Hello,Printer
Ice.Trace.Network=1

# File: hello.cfg
Ice.Trace.Network=2

# File: printer.cfg
Ice.Trace.Network=3
```

The two services `Hello` and `Printer` use the shared communicator, and all services inherit the server's properties. As IceBox prepares the shared property set, the initial value of `Ice.Trace.Network` is `1` as defined in the (inherited) server's configuration. The `IceBox.LoadOrder` property specifies that the `Hello` service should be loaded first, therefore the `Ice.Trace.Network` property momentarily has the value `2` but ultimately has the value `3` after the properties for the `Printer` service are merged.

If we change the value of `IceBox.LoadOrder` so that IceBox loads `Printer` first, the value for `Ice.Trace.Network` in the shared communicator will be `2` instead because the setting in `hello.cfg` overrides all previous values.

## Inheriting Properties from the IceBox Server

By default, a service does not inherit the IceBox server's configuration properties. For example, consider the following server configuration:

```config
IceBox.Service.Weather=... --Ice.Config=svc.cfg
Ice.Trace.Network=1
```

The `Weather` service only receives the properties that are defined in its [IceBox.Service](https://docs.zeroc.com/ice/3.8/property-reference/icebox-properties/java.md#icebox.service.name) property. In the example above, the service's communicator is initialized with the properties from the file `svc.cfg`.

If services need to inherit the IceBox server's configuration properties, define the [IceBox.InheritProperties](https://docs.zeroc.com/ice/3.8/property-reference/icebox-properties/java.md#icebox.inheritproperties) property in the IceBox server's configuration:

```config
IceBox.Service.Weather=... --Ice.Config=svc.cfg
Ice.Trace.Network=1
IceBox.InheritProperties=1
```

All services inherit the server's properties when `IceBox.InheritProperties` is set to a non-zero value. The service inherits all the properties of the IceBox server, except those whose names start with `IceBox.` or `Ice.Admin.`.

> **Note**
>
> The properties of the [shared communicator](#using-a-shared-communicator) are also affected by this setting.

## Logging Considerations for IceBox Services

IceBox sets [Ice.ProgramName](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/java.md#ice.programname) in each service communicator to the service name, or to `SharedCommunicator` for the shared communicator. When the IceBox server's `Ice.ProgramName` is not empty, IceBox prefixes this name with the server's `Ice.ProgramName` and a hyphen.

The IceBox server only configures a logger for a service if that service has not already specified its own logger via the [Ice.LogFile](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/java.md#ice.logfile) or [Ice.UseSyslog](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/java.md#ice.usesyslog) properties.

## See Also

- [IceBox.\*](https://docs.zeroc.com/ice/3.8/property-reference/icebox-properties/java.md)
- [Developing IceBox Services](https://docs.zeroc.com/ice/3.8/services/icebox/developing-icebox-services/java.md)
- [IceStorm](https://docs.zeroc.com/ice/3.8/services/icestorm.md)
- [Collocated Invocation and Dispatch](https://docs.zeroc.com/ice/3.8/runtime/collocated-invocation-and-dispatch/java.md)
- [Miscellaneous Ice.\* Properties](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/java.md)
