Ice includes a number of helper classes to help you build robust Glacier2 clients.
Glacier2::Application
ClassYou 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:
Application()
Application(Ice::HandleSignals)
.Application(Ice::SignalPolicy policy)
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.int runWithSession(int argc, char* argv[])
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
. runWithSession
can call restart
to restart the session. This destroys the current session, creates a new session (by calling createSession
), and calls runWithSession
again. The Application
base class also restarts the session if runWithSession
raises (or allows to be raised) any of the following exceptions:
Ice::ConnectionLostException
Ice::ConnectionRefusedException
Ice::RequestFailedException
Ice::TimeoutException
Ice::UnknownLocalException
Glacier2::SessionPrx createSession()
createSession
is followed by a call to runWithSession
. The application terminates if createSession
raises (or allows to be raised) an Ice::LocalException
.void sessionDestroyed()
Glacier2::RouterPrx router()
Glacier2::SessionPrx session()
void restart()
Application
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 Application
.std::string categoryForClient()
SessionNotExistException
if no session is currently active.Ice::Identity createCallbackIdentity(const std::string& name)
Ice::ObjectPrx addWithUUID(const Ice::ObjectPtr& servant)
Ice::ObjectAdapterPtr objectAdapter()
The Ice distribution includes an example in |
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:
Glacier2.SessionFactoryHelper
connect
methods that support the two authentication styles (user name/password and SSL credentials) accepted by the Glacier2 router, and returns an instance of Glacier2.SessionHelper
for each new session.Glacier2.SessionHelper
Glacier2::Application
. The application must supply an instance of Glacier2.SessionCallback
when creating the session; SessionHelper
invokes this callback object when important events occur in the session's lifecycle.Glacier2.SessionCallback
The classes are discussed further in the subsections below.
You can find sample applications that make use of these classes in the |
SessionFactoryHelper
ClassThe 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:
SessionFactoryHelper(SessionCallback callback)
InitializationData
object and a new property set. The callback argument must not be null.SessionFactoryHelper(Ice.InitializationData initData, SessionCallback callback)
InitializationData
. The callback
argument must not be null.SessionFactoryHelper(Ice.Properties properties, SessionCallback callback)
void setRouterIdentity(Ice.Identity identity)
Ice.Identity getRouterIdentity()
Ice.Default.Router
is undefined.void setRouterHost(String hostname)
String getRouterHost()
Ice.Default.Router
is undefined.void setSecure(boolean secure)
boolean getSecure()
Ice.Default.Router
is undefined.void setTimeout(int timeoutMillisecs)
int getTimeout()
Ice.Default.Router
is undefined.void setPort(int port)
int getPort()
Ice.Default.Router
is undefined.Ice.InitializationData getInitializationData()
InitializationData
object that will be used during communicator initialization. If necessary, an application can make modifications to this object prior to calling connect
.void setConnectContext(java.util.Map<String, String> ctx)
connect
.SessionHelper connect()
SessionHelper
object. The connected
method is invoked on the session callback if the session was created successfully, otherwise the callback's connectFailed
method is invoked.SessionHelper connect(String username, String password)
SessionHelper
object. The connected
method is invoked on the session callback if the session was created successfully, otherwise the callback's connectFailed
method is invoked.SessionHelper
ClassThe 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:
void destroy()
SessionHelper
. This is a non-blocking method that spawns a background thread to perform potentially blocking activities. SessionHelper
invokes the disconnected
method on the application's callback object to indicate the completion of the destroy
request. A well-behaved application must wait for this call to disconnected
before it terminates.Ice.Communicator communicator()
SessionHelper
.String categoryForClient()
SessionNotExistException
if no session is currently active.Ice.ObjectPrx addWithUUID(Ice.Object servant)
SessionNotExistException
if no session is currently active.Glacier2.SessionPrx session()
SessionNotExistException
if no session is currently active.boolean isConnected()
Ice.ObjectAdapter objectAdapter()
SessionNotExistException
if no session is currently active. SessionCallback
InterfaceAn 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:
void createdCommunicator(SessionHelper session)
void connected(SessionHelper session)
SessionNotExistException
to force the new session to be destroyed.void disconnected(SessionHelper session)
void connectFailed(SessionHelper session, Throwable ex)