42.5.1 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.)
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();
};
}
This constructor allows you to indicate whether the class should handle signals. The
SignalPolicy enumeration contains two enumerators:
HandleSignals and
NoSignalHandling. If you specify
HandleSignals, the class automatically shuts down or destroys its communicator upon receipt of certain signals. Refer to the
Ice::Application documentation in the relevant language mapping chapter for more information on signal handling.
This method must be overridden by a subclass and represents the “main loop” of the application. It is called after the communicator has been initialized and the Glacier2 session has been established. The argument vector passed to this method contains the arguments passed to
Application::main with all Ice-related options removed. The implementation of
runWithSession must return zero to indicate success and non-zero to indicate failure; the value returned by
runWithSession becomes the return value of
Application::main.
Causes the Application class to destroy the current session, create a new session (by calling
createSession), and start a new main loop (in
runWithSession). This method does not return but rather raises a
RestartSessionException that is trapped by the
Application class.
The Ice distribution includes an example in demo/Glacier2/callback that shows how to use the
Glacier2::Application class.
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 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):
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 SessionHelper connect();
public SessionHelper connect(String username,
String password);
}
Returns a reference to the InitializationData object that will be used during communicator initialization. If necessary, an application can make modifications to this object prior to calling
connect.
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 (shown below in 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;
}
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 (shown below in 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);
}
