Ice includes a number of helper classes to help you build robust Glacier2 clients.

The Glacier2::Application Class

You may already be familiar with the Ice::Application class, which encapsulates some basic Ice functionality such as communicator initialization, communicator destruction, and proper handling of signals and exceptions. The Glacier2::Application extends Ice::Application to add functionality that is commonly needed by Glacier2 clients:

The C++ definition of Glacier2::Application is shown below. (The Java and C# versions offer identical functionality so we do not show them here.)

{zcode:cpp}
namespace Glacier2 {

class Application : public Ice::Application {
public:
    Application();
    Application(Ice::SignalPolicy policy);

    virtual int runWithSession(int argc, char* argv[]) = 0;

    virtual Glacier2::SessionPrx createSession() = 0;

    virtual void sessionDestroyed();

    static Glacier2::RouterPrx router();

    static Glacier2::SessionPrx session();

    void restart();

    std::string categoryForClient();

    Ice::Identity createCallbackIdentity(const std::string& name);

    Ice::ObjectPrx addWithUUID(const Ice::ObjectPtr& servant);

    Ice::ObjectAdapterPtr objectAdapter();
};

}
{zcode}

The following methods are supported:

The Ice distribution includes an example in demo/Glacier2/callback that shows how to use the Glacier2::Application class.

GUI Helper Classes

The "main loop" design imposed by the Glacier2::Application class is not suitable for graphical applications, therefore Ice also includes a collection of Java and C# classes that better accommodate the needs of GUI programs:

The classes are discussed further in the subsections below.

You can find sample applications that make use of these classes in the demo/Glacier2/chat directory of your Ice distribution.

The SessionFactoryHelper Class

The SessionFactoryHelper class provides convenience methods for configuring the settings that are commonly used to create a Glacier2 session, such as the router's host and port number. Once the application has completed its configuration, it calls one of the connect methods to initialize a communicator, establish a Glacier2 session, and receive a SessionHelper object with which it can manage the new session. An application should create a new SessionFactoryHelper object for each router instance that it uses.

SessionFactoryHelper creates an Ice.InitializationData object if the application does not pass one to the SessionFactoryHelper constructor. SessionFactoryHelper also creates a new property set if necessary, and then sets some configuration properties required by Glacier2 clients. The resulting InitializationData object is eventually used in connect to initialize a new communicator.

The Java definition of SessionFactoryHelper is shown below (the C# version is nearly identical and is not shown here):

{zcode:java}
package Glacier2;

public class SessionFactoryHelper {

    public SessionFactoryHelper(SessionCallback callback)
        throws Ice.InitializationException;

    public SessionFactoryHelper(Ice.InitializationData initData, SessionCallback callback)
        throws Ice.InitializationException;

    public SessionFactoryHelper(Ice.Properties properties, SessionCallback callback)
        throws Ice.InitializationException;

    public void setRouterIdentity(Ice.Identity identity);
    public Ice.Identity getRouterIdentity();

    public void setRouterHost(String hostname);
    public String getRouterHost();

    public void setSecure(boolean secure);
    public boolean getSecure();

    public void setTimeout(int timeoutMillisecs);
    public int getTimeout();

    public void setPort(int port);
    public int getPort();

    public Ice.InitializationData getInitializationData();

    public void setConnectContext(java.util.Map<String, String> ctx);

    public SessionHelper connect();
    public SessionHelper connect(String username, String password);
}
{zcode}

The following methods are supported:

The SessionHelper Class

The SessionHelper class encapsulates a Glacier2 session and keeps the session alive by periodically "pinging" the router. SessionHelper also provides several convenience methods for common session-related actions:

{zcode:java}
package Glacier2;

public class SessionHelper {

    public void destroy();

    public Ice.Communicator communicator();

    public String categoryForClient()
        throws SessionNotExistException;

    public Ice.ObjectPrx addWithUUID(Ice.Object servant)
        throws SessionNotExistException;

    public Glacier2.SessionPrx session()
        throws SessionNotExistException;

    public boolean isConnected();

    public Ice.ObjectAdapter objectAdapter()
        throws SessionNotExistException;
}
{zcode}

The following methods are supported:

The SessionCallback Interface

An application must supply an instance of SessionCallback when instantiating a SessionFactoryHelper object. The callback methods allow the application to receive notification about events in the lifecycle of the session:

{zcode:java}
package Glacier2;

public interface SessionCallback {

    void createdCommunicator(SessionHelper session);

    void connected(SessionHelper session)
        throws SessionNotExistException;

    void disconnected(SessionHelper session);

    void connectFailed(SessionHelper session, Throwable ex);
}
{zcode}

The following callback methods are supported:

See Also