com.ausregistry.jtoolkit2.session

Interface Session

All Known Implementing Classes:

TLSSession

public interface Session

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 synchronise 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.

Method Summary

Modifier and Type	Method and Description
void	acquire() Acquire the session for exclusive use.
void	changePassword(java.lang.String newPassword) Change the client password to the given value.
void	close() EPP sessions are closed cleanly by sending an EPP logout command, awaiting a response from the server, then acknowledging the close of the underlying transport mechanism initiated by the server upon completion of sending the logout response.
void	configure(SessionProperties properties) Configure EPP session parameters such as server host name, port, client identifier, password and authentication sources.
Greeting	getGreeting() EPP service discovery is implemented by the greeting service element.
StatsManager	getStatsManager() Get the StatsManager as described in the class documentation.
boolean	isAvailable() Determine whether a call to acquire would block.
boolean	isInvalid() Determine whether a call to read or write would result in an IOException.
boolean	isOpen() Determine whether a call to open has previously succeeded.
void	keepAlive() Keep the Session open, as described in the class documentation.
void	open() An EPP session is opened by first establishing a connection using the server location information and authentication sources provided in configure, then issuing a login command with further authentication data and options provided in configure.
java.lang.String	read() Read a single EPP service element from the transport layer.
void	read(Response response) Read a single EPP service element from the transport layer and assign values to the attributes of the given Response instance appropriately, according to the received XML document content.
XMLDocument	readToDocument() Read a single EPP service element from the transport layer, then construct an XMLDocument instance from the element read.
void	release() Release the Session for use by another user.
void	write(Command command) Write an EPP service element to the transport layer service, with the intention of sending the command to the connected EPP server.
void	write(java.lang.String xml) Write an EPP service element to the transport layer service, with the intention of sending the command to the connected EPP server.

Method Detail

configure

void configure(SessionProperties properties)
        throws SessionConfigurationException

Configure EPP session parameters such as server host name, port, client identifier, password and authentication sources.

Parameters:

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.

open

void open()
   throws SessionOpenException

An EPP session is opened by first establishing a connection using the server location information and authentication sources provided in configure, then issuing a login command with further authentication data and options provided in configure. 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 getCause() 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.

changePassword

void changePassword(java.lang.String newPassword)
             throws SessionOpenException

Change the client password to the given value. This must be implemented in EPP by logging in with the newPW value set, then logging out.

Parameters:

newPassword - The new client password.

Throws:

SessionOpenException

close

void close()

EPP sessions are closed cleanly by sending an EPP logout command, awaiting a response from the server, then acknowledging the close of the underlying transport mechanism initiated by the server upon completion of sending the logout response. This method guarantees that the session is closed and the resources used to maintain the connection are freed. This may require forcing the underlying transport mechanism to close in the event that the logout fails (for any reason). Any errors which occur during the close operation are not presented to the caller, but may be logged.

getGreeting

Greeting getGreeting()

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.

read

java.lang.String read()
               throws java.io.IOException

Read a single EPP service element from the transport layer.

Throws:

java.io.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.

read

void read(Response response)
   throws java.io.IOException,
          ParsingException

Read a single EPP service element from the transport layer and assign values to the attributes of the given Response instance appropriately, according to the received XML document content. Typically, the latter can be achieved by invoking the given Response instance’s toXML method.

Throws:

java.io.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.

ParsingException - The XML parser reported an error while trying to construct an XMLDocument instance from the data received from the server.

readToDocument

XMLDocument readToDocument()
                    throws java.io.IOException,
                           ParsingException

Read a single EPP service element from the transport layer, then construct an XMLDocument instance from the element read.

Throws:

java.io.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.

ParsingException - The XML parser reported an error while trying to construct an XMLDocument instance from the data received from the server.

write

void write(java.lang.String xml)
    throws java.io.IOException

Write an EPP service element to the transport layer service, with the intention of sending the command to the connected EPP server.

Throws:

java.io.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.

write

void write(Command command)
    throws java.io.IOException,
           ParsingException

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 Command instance. The XML representation of the service element is obtained from the toXML method of the Command instance.

Throws:

java.io.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.

ParsingException - See the description of Command.toXML().

isOpen

boolean isOpen()

Determine whether a call to open has previously succeeded.

isInvalid

boolean isInvalid()

Determine whether a call to read or write would result in an IOException.

isAvailable

boolean isAvailable()

Determine whether a call to acquire would block.

acquire

void acquire()
      throws java.lang.InterruptedException,
             TimeoutException

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:

TimeoutException - The acquire timeout period elapsed while waiting to acquire exclusive use of the session.

java.lang.InterruptedException - The thread was interrupted while waiting to acquire the lock on the session.

See Also:

SessionProperties.getAcquireTimeout()

release

void release()

Release the Session for use by another user. This should only be used after the session has been acquired.

keepAlive

void keepAlive()
        throws java.io.IOException

Keep the Session open, as described in the class documentation.

Throws:

java.io.IOException

getStatsManager

StatsManager getStatsManager()

Get the StatsManager as described in the class documentation.