218 lines
8.7 KiB
C++
218 lines
8.7 KiB
C++
#ifndef __SESSION_H
|
|
#define __SESSION_H
|
|
|
|
#include "xml/ParsingException.hpp"
|
|
#include "session/EPPIOException.hpp"
|
|
#include "session/EPPInterruptedException.hpp"
|
|
#include "session/SessionOpenException.hpp"
|
|
#include "session/SessionConfigurationException.hpp"
|
|
|
|
class SessionProperties;
|
|
class StatsManager;
|
|
class Greeting;
|
|
class XMLDocument;
|
|
class Command;
|
|
class ReceiveSE;
|
|
|
|
/**
|
|
* EPP is a session-oriented service - all commands (except session management)
|
|
* are only accepted by an EPP server if within a session context. The Session
|
|
* interface provides the necessary operations to negotiate and use an EPP
|
|
* session; open, close, read and write being the primary operations.
|
|
* The state of a session is maintained internally; state conditions considered
|
|
* relevant to users of a session are visible through the isOpen, isInvalid and
|
|
* isAvailable methods. The acquire and release methods can be used to
|
|
* synchronize use of a Session if the implementation requires this. EPP
|
|
* allows for servers to close idle connections after a server policy defined
|
|
* period. In order to keep a session open in this situation, it is necessary
|
|
* to poll the server with valid EPP commands at regular intervals; the
|
|
* keepAlive method provides this functionality. Upon successfully negotiating
|
|
* a connection to a server, an EPP greeting service element is sent to the
|
|
* client; a representation of that greeting is available using getGreeting. A
|
|
* session must publish operational data to a StatsManager which is sufficient
|
|
* for the StatsManager to meet its interface obligations. That StatsManager
|
|
* is made available via getStatsManager().
|
|
*
|
|
*/
|
|
|
|
class EPPTimeoutException : public EPPException
|
|
{
|
|
public:
|
|
EPPTimeoutException(const std::string& msg)
|
|
: EPPException(msg) { }
|
|
EPP_EXCEPTION(EPPTimeoutException);
|
|
};
|
|
|
|
|
|
class Session
|
|
{
|
|
public:
|
|
virtual ~Session(void) { }
|
|
/**
|
|
* Configure EPP session parameters such as server hostname, port, client
|
|
* identifier, password and authentication sources.
|
|
*
|
|
* @param properties Properties as defined in the SessionProperties
|
|
* interface, which govern the behaviour of a Session.
|
|
*
|
|
* @throws SessionConfigurationException Session configuration failed to
|
|
* prepare the session for being opened. The cause of the failure should
|
|
* be available by calling getCause() on the thrown exception.
|
|
*/
|
|
virtual void configure(SessionProperties* properties)
|
|
throw (SessionConfigurationException) = 0;
|
|
|
|
/**
|
|
* An EPP session is opened by first establishing a connection using the
|
|
* server location information and authentication sources provided in
|
|
* <code>configure</code>, then issuing a login command with further
|
|
* authentication data and options provided in <code>configure</code>.
|
|
* Service information provided immediately upon connection establishment
|
|
* may affect options provided in the login command.
|
|
*
|
|
* @throws SessionOpenException The session failed to open. The cause MUST
|
|
* be made available by calling <code>getCause()</code> on the exception
|
|
* object thrown. Required causes are LoginException (such as is caused by
|
|
* invalid username/password combination) and IOException (such as would
|
|
* result from the server being unavailable at the configured location).
|
|
* Other causes may include ParsingException and SSLHandshakeException.
|
|
*/
|
|
virtual void open() throw (SessionOpenException) = 0;
|
|
|
|
/**
|
|
* Formally close the EPP sessions with a logout command. This method
|
|
* closes the session and releases the internal resources used to maintain
|
|
* the connection. The transport mechanism will be forcefully closed and
|
|
* released even if the logout communication fails. Any errors which occur
|
|
* during the close operation should not be presented to the caller, but
|
|
* may be logged depending upon the implementation. The session can not be
|
|
* used for further operations once closed.
|
|
*/
|
|
virtual void close() = 0;
|
|
|
|
/**
|
|
* EPP service discovery is implemented by the greeting service element.
|
|
* Upon successfully negotiating a connection to a server, a greeting is
|
|
* sent to the client, describing the services offered by the EPP server.
|
|
* That information is encapsulated in a Greeting object, which may be
|
|
* retrieved using this method.
|
|
*/
|
|
virtual const Greeting* getGreeting() const = 0;
|
|
|
|
/**
|
|
* Change the clients password. Session must already be opened.
|
|
*/
|
|
virtual void changePassword(const std::string& newPW) = 0;
|
|
|
|
/**
|
|
* Read a single EPP service element from the transport layer.
|
|
*
|
|
* @throws IOException There was a failure in the transport layer in
|
|
* attempting to receive data from the server. The cause of the exception
|
|
* should be described in the exception message.
|
|
*/
|
|
virtual std::string read() throw (EPPIOException) = 0;
|
|
|
|
/**
|
|
* Read a single EPP service element from the transport layer and assign
|
|
* values to the attributes of the given ReceiveSE instance appropriately,
|
|
* according to the received XML document content. Typically, the latter
|
|
* can be achieved by invoking the given ReceiveSE instance's toXML
|
|
* method.
|
|
*
|
|
* @throws IOException There was a failure in the transport layer in
|
|
* attempting to receive data from the server. The cause of the exception
|
|
* should be described in the exception message.
|
|
*
|
|
* @throws ParsingException The XML parser reported an error while trying
|
|
* to construct an XMLDocument instance from the data received from the
|
|
* server.
|
|
*/
|
|
virtual void read(ReceiveSE& receivedElement) throw (EPPIOException, ParsingException) = 0;
|
|
|
|
/**
|
|
* Read a single EPP service element from the transport layer, then
|
|
* construct an XMLDocument instance from the element read.
|
|
*
|
|
* @throws IOException There was a failure in the transport layer in
|
|
* attempting to receive data from the server. The cause of the exception
|
|
* should be described in the exception message.
|
|
*
|
|
* @throws ParsingException The XML parser reported an error while trying
|
|
* to construct an XMLDocument instance from the data received from the
|
|
* server.
|
|
*/
|
|
virtual XMLDocument* readToDocument()
|
|
throw (EPPIOException, ParsingException) = 0;
|
|
|
|
/**
|
|
* Write an EPP service element to the transport layer service, with the
|
|
* intention of sending the command to the connected EPP server.
|
|
*
|
|
* @throws IOException The transport layer was unable to send the data to
|
|
* the server. This condition is considered permanent and causes the
|
|
* session state to become invalid, as indicated by isInvalid.
|
|
*/
|
|
virtual void writeXML(const std::string &xml) throw (EPPIOException, ParsingException) = 0;
|
|
|
|
/**
|
|
* Write an EPP service element to the transport layer service, with the
|
|
* intention of sending the command to the connected EPP server. The
|
|
* service element is modelled by the specified {@link Command} instance.
|
|
* The XML representation of the service element is obtained from the toXML
|
|
* method of the Command instance.
|
|
*
|
|
* @throws IOException The transport layer was unable to send the data to
|
|
* the server. This condition is considered permanent and causes the
|
|
* session state to become invalid, as indicated by isInvalid.
|
|
*
|
|
* @throws ParsingException See the description of Command.toXML().
|
|
*/
|
|
virtual void write(Command& command) throw (EPPIOException, ParsingException) = 0;
|
|
|
|
/**
|
|
* Determine whether a call to open has previously succeeded.
|
|
*/
|
|
virtual bool isOpen() const = 0;
|
|
|
|
/**
|
|
* Determine whether a call to read or write would result in an
|
|
* IOException.
|
|
*/
|
|
virtual bool isInvalid() const = 0;
|
|
|
|
/**
|
|
* Determine whether a call to <code>acquire</code> would block.
|
|
*/
|
|
virtual bool isAvailable() const = 0;
|
|
|
|
/**
|
|
* Acquire the session for exclusive use. Further requests to acquire
|
|
* the session before it is released should block until release is called.
|
|
* The correct usage sequence if contention is expected is acquire,
|
|
* (write, read)+, release.
|
|
*
|
|
* @throws InterruptedException The thread was interrupted while waiting
|
|
* to acquire the lock on the session.
|
|
*/
|
|
virtual void acquire() throw (EPPInterruptedException, EPPTimeoutException) = 0;
|
|
|
|
/**
|
|
* Release the Session for use by another user. This should only be used
|
|
* after the session has been <code>acquire</code>d.
|
|
*/
|
|
virtual void release() = 0;
|
|
|
|
/**
|
|
* Keep the Session open, as described in the class documentation.
|
|
*/
|
|
virtual void keepAlive() throw (EPPIOException) = 0;
|
|
|
|
/**
|
|
* Get the StatsManager as described in the class documentation.
|
|
*/
|
|
virtual StatsManager* getStatsManager() = 0;
|
|
};
|
|
|
|
#endif // __SESSION_H
|