---
title: "Developing IceBox Services"
url: https://docs.zeroc.com/ice/3.8/services/icebox/developing-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).

# Developing IceBox Services

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

## The IceBox `Service` Interface

Writing an IceBox service requires implementing the [IceBox Service](https://code.zeroc.com/ice/3.8/api/java/com.zeroc.icebox/com/zeroc/IceBox/Service.html) interface or abstract base class.

Your service implements two methods, `start` and `stop`. IceBox calls `start` after loading the service and `stop` when shutting down a running service. An administrator can also stop and restart the service through the [service manager](https://docs.zeroc.com/ice/3.8/services/icebox/icebox-administration.md). IceBox reuses the same service object, communicator, and arguments for each restart.

The `start` method initializes the service, typically by creating an object adapter and servants. The `name` and `args` parameters supply information from the service's [configuration](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/java.md), and the `communicator` parameter supplies a communicator that IceBox creates for the service. Services that [share a communicator](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/java.md) must use distinct names for their object adapters.

`start` must return once the service is initialized, because IceBox waits for it before starting the next service and before activating its admin object.

The `stop` method must release the resources owned by the service and destroy the [object adapters](https://docs.zeroc.com/ice/3.8/runtime/dispatch/object-adapter-activation-and-deactivation/java.md) it created.

IceBox owns the communicator it passes to `start` and destroys it when the server shuts down.

## IceBox Service Example

The example we present here is taken from the `IceBox/greeter` demo program.

The class definition for our service is quite straightforward:

```java
package com.example.icebox.greeter.service;

import com.zeroc.Ice.Communicator;
import com.zeroc.Ice.Identity;
import com.zeroc.Ice.ObjectAdapter;
import com.zeroc.IceBox.Service;

public class GreeterService implements Service {
    private ObjectAdapter _adapter;

    @Override
    public void start(String name, Communicator communicator, String[] args) {
        _adapter = communicator.createObjectAdapterWithEndpoints(
            "GreeterAdapter",
            "tcp -p 4061");

        _adapter.add(new Chatbot(), new Identity("greeter", ""));
        _adapter.activate();
        System.out.println("Listening on port 4061...");
    }

    @Override
    public void stop() {
        System.out.println("Shutting down...");

        assert _adapter != null;
        _adapter.destroy();
        _adapter = null;
    }
}
```

The `start` method creates an object adapter “GreeterAdapter”, activates a single servant of type `Chatbot` (not shown), and activates the object adapter. The `stop` method simply destroys the object adapter.

### Java Service Entry Point

The last piece of the puzzle is the *entry point*, which the IceBox server calls to create an instance of the service.

IceBox requires a service implementation to have a public parameterless constructor or a public constructor with a single `Communicator` parameter. This is the Java entry point for IceBox: the IceBox server dynamically loads the service implementation class and calls this public constructor to create an instance of the service.

[Configuring IceBox Services](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/java.md) provides more information on entry points and describes how to configure your service into an IceBox server.

## IceBox Service Failures

A service implementation can indicate a failure by throwing an exception. IceBox handles the exception according to when it occurs:

- **Initial startup** If the service's entry point or initial `start` call throws, the server terminates as described in [Starting the IceBox Server](https://docs.zeroc.com/ice/3.8/services/icebox/starting-the-icebox-server/java.md#icebox-server-failures).
- **Administrative start** If `start` throws during `ServiceManager.startService`, IceBox logs a warning, records the service as stopped, and returns normally from `startService`.
- **Administrative stop** If `stop` throws during `ServiceManager.stopService`, IceBox logs a warning, records the service as started, and returns normally from `stopService`.
- **Server shutdown** If `stop` throws, IceBox logs a warning and continues stopping the remaining services and destroying their communicators.

Because `startService` and `stopService` return normally in these cases, use `ServiceManager.isServiceRunning` to check whether the service started or stopped.

If `start` fails, the service must release resources it acquired during that attempt before propagating the exception. IceBox calls `stop` only for services it records as started.

## See Also

- [Configuring IceBox Services](https://docs.zeroc.com/ice/3.8/services/icebox/configuring-icebox-services/java.md)
- [Starting the IceBox Server](https://docs.zeroc.com/ice/3.8/services/icebox/starting-the-icebox-server/java.md)
