Preliminary documentation for Ice 3.7.1 Beta. Do not use in production applications. Refer to the space directory for other releases.

The "main loop" design imposed by the Glacier2 Application class is usually not suitable for graphical applications. Ice provides additional helper classes that better accommodate the needs of such applications:

  • SessionHelper
    This class encapsulates a Glacier2 session and provides much of the same functionality as Glacier2 Application. The application must supply an instance of SessionCallback when creating the session; SessionHelper invokes this callback object when important events occur in the session's lifecycle.
  • SessionFactoryHelper
    This class simplifies the task of creating a Glacier2 session. It provides overloaded connect methods that support the two authentication styles (user name/password and SSL credentials) accepted by the Glacier2 router, and returns an instance of SessionHelper for each new session.
  • SessionCallback
    You implement this interface to receive notifications about session lifecycle events.

These classes are provided in the Glacier2 namespace or package. We discuss them further in the subsections below.

Example

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

Back to Top ^

The SessionHelper Class

The SessionHelper class encapsulates a Glacier2 session and keeps the session alive by periodically sending a hearbeat to the Glacier2 router. SessionHelper also provides several convenience functions or methods for common session-related actions:

namespace Glacier2
{    
    class SessionHelper
    {
    public:
        virtual ~SessionHelper();

        virtual void destroy() = 0;
        virtual std::shared_ptr<Ice::Communicator> communicator() const = 0;
        virtual std::string categoryForClient() const = 0;
        virtual std::shared_ptr<Ice::ObjectPrx> addWithUUID(const std::shared_ptr<Ice::Object>&) = 0;
        virtual std::shared_ptr<SessionPrx> session() const = 0;
        virtual bool isConnected() const = 0;
        virtual std::shared_ptr<Ice::ObjectAdapter> objectAdapter() = 0;
    };
}

namespace Glacier2
{    
    class SessionHelper : public virtual IceUtil::Shared
    {
    public:
        virtual ~SessionHelper();

        virtual void destroy() = 0;
        virtual Ice::CommunicatorPtr communicator() const = 0;
        virtual std::string categoryForClient() const = 0;
        virtual Ice::ObjectPrx addWithUUID(const Ice::ObjectPtr&) = 0;
        virtual SessionPrx session() const = 0;
        virtual bool isConnected() const = 0;
        virtual Ice::ObjectAdapterPtr objectAdapter() = 0;
 
        bool operator==(const SessionHelper&) const;
        bool operator!=(const SessionHelper&) const;
    };
    typedef IceUtil::Handle<SessionHelper> SessionHelperPtr;
}
namespace Glacier2
{
    public class SessionHelper
    {
        public void destroy() { ... }
    
        public Ice.Communicator communicator() { ... }
   
        public string categoryForClient() { ... }
        public Ice.ObjectPrx addWithUUID(Ice.Object servant) { ... }
        public SessionPrx session() { ... }
        public bool isConnected() { ... }
        public Ice.ObjectAdapter objectAdapter() { ... }
  
        ...
    }
}
package com.zeroc.Glacier2;

public class SessionHelper
{
    public void destroy() { ... }

    public com.zeroc.Ice.Communicator communicator() { ... }

    public String categoryForClient() throws SessionNotExistException { ... }
    public com.zeroc.Ice.ObjectPrx addWithUUID(com.zeroc.Ice.Object servant) throws SessionNotExistException { ... }
    public SessionPrx session() { ... }
    public boolean isConnected() { ... }
    public com.zeroc.Ice.ObjectAdapter objectAdapter() throws SessionNotExistException { ... }
    
    ...
}
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 SessionPrx session() { ... }
    public boolean isConnected() { ... }
    public Ice.ObjectAdapter objectAdapter() throws SessionNotExistException { ... }
    
    ...
}

This class provides the following functions or methods:

  • destroy
    Initiates the destruction of the Glacier2 session, including the communicator created by the SessionHelper. This is a non-blocking method that starts 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. If the session has already been destroyed when destroy is called, destroy does nothing.
  • communicator
    Returns the communicator created by the SessionHelper.
  • categoryForClient
    Returns the category that must be used in the identities of all callback objects. Raises SessionNotExistException if no session is currently active.
  • addWithUUID
    Adds a servant to the callback object adapter using a UUID for the identity name. Raises SessionNotExistException if no session is currently active.
  • session
    Returns a proxy for the Glacier2 session. Returns a nil proxy if no session is currently active.
  • isConnected
    Returns true if the session is currently active, false otherwise.
  • objectAdapter
    Returns the callback object adapter. This object adapter is only created if the session factory was configured to do so using setUseCallbacks. Raises SessionNotExistException if no session is currently active.

The Java implementation of SessionHelper installs a JVM shutdown hook that calls destroy when the application is about to exit.

Back to Top ^

The SessionFactoryHelper Class

The SessionFactoryHelper class provides convenience functions or 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 overloaded connect functions or methods to initialize a communicator, create 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 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 used in connect to create the new communicator.

namespace Glacier2
{
    class SessionFactoryHelper : public std::enable_shared_from_this<SessionFactoryHelper>
    {
    public:

        SessionFactoryHelper(const std::shared_ptr<SessionCallback>& callback);
        SessionFactoryHelper(const Ice::InitializationData&, const std::shared_ptr<SessionCallback>&);
        SessionFactoryHelper(const std::shared_ptr<Ice::Properties>&, const std::shared_ptr<SessionCallback>&);

        ~SessionFactoryHelper();

        void destroy();

        void setRouterIdentity(const Ice::Identity&);
        Ice::Identity getRouterIdentity() const;

        void setRouterHost(const std::string&);
        std::string getRouterHost() const;

        void setProtocol(const std::string&);
        std::string getProtocol() const;

        void setTimeout(int);
        int getTimeout() const;

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

        Ice::InitializationData getInitializationData() const;

        void setConnectContext(const std::map<std::string, std::string>& context);

        void setUseCallbacks(bool);
        bool getUseCallbacks() const;

        SessionHelperPtr connect();
        SessionHelperPtr connect(const std::string& username,  const std::string& password);
 
        ...
    };
}
namespace Glacier2
{
    class SessionFactoryHelper : public virtual IceUtil::Shared
    {
    public:

        SessionFactoryHelper(const SessionCallbackPtr& callback);
        SessionFactoryHelper(const Ice::InitializationData&, const SessionCallbackPtr&);
        SessionFactoryHelper(const Ice::PropertiesPtr&, const SessionCallbackPtr&);

        ~SessionFactoryHelper();

        void destroy();

        void setRouterIdentity(const Ice::Identity&);
        Ice::Identity getRouterIdentity() const;

        void setRouterHost(const std::string&);
        std::string getRouterHost() const;

        void setProtocol(const std::string&);
        std::string getProtocol() const;

        void setTimeout(int);
        int getTimeout() const;

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

        Ice::InitializationData getInitializationData() const;

        void setConnectContext(const std::map<std::string, std::string>& context);

        void setUseCallbacks(bool);
        bool getUseCallbacks() const;

        SessionHelperPtr connect();
        SessionHelperPtr connect(const std::string& username,  const std::string& password);
 
        ...
    };
}
namespace Glacier2
{
    public class SessionFactoryHelper
    {
        public SessionFactoryHelper(SessionCallback callback) { ... }
        public SessionFactoryHelper(Ice.InitializationData initData, SessionCallback callback) { ... }
        public SessionFactoryHelper(Ice.Properties properties, SessionCallback callback) { ... }
   
        public void setRouterIdentity(Ice.Identity identity) { ... }
        public Ice.Identity getRouterIdentity() { ... }
  
        public void setRouterHost(string hostname) { ... }
        public string getRouterHost() { ... }
    
        public void setProtocol(string protocol) { ... }
        public string getProtocol() { ... }
   
        public void setTimeout(int timeoutMillisecs) { ... }
        public int getTimeout() { ... }
   
        public void setPort(int port) { ... }
        public int getPort() { ... }
   
        public Ice.InitializationData getInitializationData() { ... }
        public void setConnectContext(Dictionary<string, string> context) { ... }
   
        public void setUseCallbacks(bool useCallbacks) { ... }
        public bool getUseCallbacks() { ... }

        public SessionHelper connect() { ... }
        public SessionHelper connect( string username,  string password) { ... }
 
        ...
    }
}
package com.zeroc.Glacier2;

public class SessionFactoryHelper
{
    public SessionFactoryHelper(SessionCallback callback) throws com.zeroc.Ice.InitializationException;
    public SessionFactoryHelper(com.zeroc.Ice.InitializationData initData, SessionCallback callback) throws com.zeroc.Ice.InitializationException;
    public SessionFactoryHelper(com.zeroc.Ice.Properties properties, SessionCallback callback) throws com.zeroc.Ice.InitializationException;

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

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

    public void setProtocol(String protocol);
    public String getProtocol();

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

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

    public com.zeroc.Ice.InitializationData getInitializationData();

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

    public void setUseCallbacks(boolean useCallbacks);
    public boolean getUseCallbacks();

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

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 setProtocol(String protocol);
    public String getProtocol();

    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 void setUseCallbacks(boolean useCallbacks);
    public boolean getUseCallbacks();

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

This class provides the following functions or methods:

  • SessionFactoryHelper constructor with SessionCallback parameter
    This constructor is useful when your application has no other configuration requirements. The constructor allocates an InitializationData object and a new property set. The callback argument must not be null.
  • SessionFactoryHelper constructor with InitializationData and SessionCallback parameters
    Use this constructor when you want to provide your own instance of InitializationData. The callback argument must not be null.
  • SessionFactoryHelper constructor with Properties and SessionCallback parameters
    This constructor is convenient when you want to supply an initial set of properties. The callback argument must not be null.

  • setRouterIdentity
    getRouterIdentity
    Sets or gets the object identity of the Glacier2 router. If you don't call setRouterIdentity to provide an identity, the factory discovers the router's proxy by contacting the RouterFinder object using the endpoint information you've configured for the factory (host, port and so on).

    The factory ignores this setting if you configure Ice.Default.Router.

  • setRouterHost
    getRouterHost
    Sets or gets the host name of the Glacier2 router. The default router host is localhost.

    The factory ignores this setting if you configure Ice.Default.Router.

  • setProtocol
    getProtocol
    Sets or gets the Ice protocol used for communications with the Glacier2 router. protocol can be tcp, ssl, ws or wss; the default protocol is ssl.

    The factory ignores this setting if you configure Ice.Default.Router.

  • setTimeout
    getTimeout
    Sets or gets the timeout in milliseconds for the connection to the Glacier2 router. No timeout is used if the argument is less than or equal to zero. The default timeout is 10,000 ms.

    The factory ignores this setting if you configure Ice.Default.Router.

  • setPort
    getPort
    Sets or gets the port on which the Glacier2 router is listening. The default is 4063 when the protocol is tcp or ws, and 4064 when the protocol is ssl or wss.

    The factory ignores this setting if you configure Ice.Default.Router.

  • getInitializationData
    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.
  • setConnectContext
    Sets the request context to be used when creating a session. This function or method must be invoked prior to connect.
  • setUseCallbacks
    getUseCallbacks
    Determines whether the session helper automatically creates an object adapter for callback servants. The default behavior is to create the object adapter.
  • connect with no parameters
    Initializes a communicator, creates a Glacier2 session using SSL credentials, and returns a new SessionHelper object. The connected function or method is called on the session callback if the session was created successfully, otherwise the callback's connectFailed function or method is called.
  • connect with username and password parameters
    Initializes a communicator, creates a Glacier2 session using the given username and password, and returns a new SessionHelper object. The connected function or method is called on the session callback if the session was created successfully, otherwise the callback's connectFailed function or method is called.

Back to Top ^

The SessionCallback Interface

You need to 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:

namespace Glacier2
{
    class SessionCallback
    {
    public:
        virtual ~SessionCallback();
        virtual void createdCommunicator(const std::shared_ptr<SessionHelper>& session) = 0;
        virtual void connected(const std::shared_ptr<SessionHelper>&) = 0;
        virtual void disconnected(const std::shared_ptr<SessionHelper>&) = 0;
        virtual void connectFailed(const std::shared_ptr<SessionHelper>&, const Ice::Exception&) = 0;
    };
}
namespace Glacier2
{
    class SessionCallback : public virtual IceUtil::Shared
    {
    public:
        virtual ~SessionCallback();
        virtual void createdCommunicator(const SessionHelperPtr& session) = 0;
        virtual void connected(const SessionHelperPtr&) = 0;
        virtual void disconnected(const SessionHelperPtr&) = 0;
        virtual void connectFailed(const SessionHelperPtr&, const Ice::Exception&) = 0;
    };
    typedef IceUtil::Handle<SessionCallback> SessionCallbackPtr;
}
namespace Glacier2
{
    public interface SessionCallback
    {
        void createdCommunicator(SessionHelper session);
        void connected(SessionHelper session);
        void disconnected(SessionHelper session);
        void connectFailed(SessionHelper session, Exception ex);
    }
}
package com.zeroc.Glacier2;

public interface SessionCallback
{
    void createdCommunicator(SessionHelper session);
    void connected(SessionHelper session) throws SessionNotExistException;
    void disconnected(SessionHelper session);
    void connectFailed(SessionHelper session, Throwable ex);
}
package com.zeroc.Glacier2;

public interface SessionCallback
{
    void createdCommunicator(SessionHelper session);
    void connected(SessionHelper session) throws SessionNotExistException;
    void disconnected(SessionHelper session);
    void connectFailed(SessionHelper session, Throwable ex);
}

The following callback notifications are supported:

  • createdCommunicator
    Called after successfully initializing a communicator.
  • connected
    Called after successfully establishing the Glacier2 session. Your implementation of connected can raise SessionNotExistException to force the destruction of the new session.
  • disconnected
    Called after the Glacier2 session is destroyed.
  • connectFailed
    Called if a failure occurred while attempting to establish a Glacier2 session.

Back to Top ^

See Also

  • No labels

Copyright © 2018 ZeroC, Inc.
Home   Terms of Use   Privacy