EPP RTK for Java
User Guide

Version 0.4.0

Oct 3, 2001

Created by: Tucows Inc.

Revision History

Date	Person	Summary
May 27, 2001	Dan Manley	Initial Release
June 28, 2001	Dan Manley	Added more information to domain and contact creation. Added notes about new accessor methods in the epp_* classes and change references to data members to remove "m_" syntax. Updated all code examples to use the new accessor methods.
July 3, 2001	Dan Manley	Added notes on SSL and certificates.
July 27, 2001	Dan Manley	Creation of epp_ContactPhone and changes to contact fax and voice data members.
Oct 3, 2001	Dan Manley	Updates for Rel 0.4.0: Sync with IETF 04/02 drafts of EPP; introduction of EPPTransport set of classes. Also added a clickable table of contents and updated Appendix A.

1. Introduction

1.1 Scope

2. EPP Overview

3. EPP Java RTK Requirements

3.1 Packages
3.2 Open Source Packages
3.3 Protocal Familiarity

4. EPP IDL Use in the Java RTK

4.1 Overview
4.2 General EPP IDL Structs and Data Members

4.2.1 Repository Object Identifiers (ROID)
4.2.2 epp_Command
4.2.3 epp_AuthInfo
4.2.4 epp_TransferRequest
4.2.5 epp_TransferStatusType
4.2.6 epp_Response
4.2.7 epp_Result
4.2.8 epp_CheckResult
4.2.9 epp_Greeting
4.2.10 epp_LoginReq
4.2.11 epp_LogoutReq
4.2.12 epp_PollReq
4.2.13 epp_PollResData
4.2.14 epp_Session

5. API Class Summary

6. API Classes

6.1 General Classes

6.1.1 EPPClient
6.1.2 EPPGreeting
6.1.3 EPPLogin
6.1.4 EPPLogout
6.1.5 EPPPoll
6.1.6 RTKBase
6.1.7 EPPXMLBase
6.1.8 EPPTransport classes

6.2 EPP Contact

6.2.1 Common Contact Data Members
6.2.2 EPPContactCheck
6.2.3 EPPContactInfo
6.2.4 EPPContactCreate
6.2.5 EPPContactUpdate
6.2.6 EPPContactDelete
6.2.7 EPPContactTransfer

6.3 EPP Domain

6.3.1 Common Domain Data Members
6.3.2 EPPDomainCheck
6.3.3 EPPDomainInfo
6.3.4 EPPDomainCreate
6.3.5 EPPDomainUpdate
6.3.6 EPPDomainDelete
6.3.7 EPPDomainTransfer
6.3.8 EPPDomainRenew

6.4 EPP Host

6.4.1 Common Host Data Members
6.4.2 EPPHostCheck
6.4.3 EPPHostInfo
6.4.4 EPPHostCreate
6.4.5 EPPHostUpdate
6.4.6 EPPHostDelete

Appendix A: References

Appendix B: Session Example

1. Introduction

This document provides a description of the EPP (Extensible Provisioning Protocol) RTK (Registrar Toolkit) Java API. The description includes a high level overview of EPP, the requirements needed to use the Java Registrar Toolkit (RTK), a description of the general EPP IDL (Interface Definition Language) data members, a description of the major EPP classes with examples for usage containing syntax, inputs, outputs and exceptions. In addition, an example of a full EPP Java API session is provided. The document also provides URL references and referrals for further details.

1.1. Scope

The EPP RTK Java API documentation is a users guide to the RTK that is based on the IETF EPP Internet-Drafts and XML schemas. This document provides a description of the predominant EPP classes and their predominant methods with reference to the use of EPP IDL data members. The examples provided can be used as a guide to using the other classes of the API described in the Javadocs. The examples provided assume the use of a connection-oriented environment.

2. EPP Overview

The Extensible Provisioning Protocol (EPP) is a thick protocol providing complete information for all specified objects (Contacts, Domains and Hosts) using a shared central object repository. EPP can be layered over multiple transport protocols, where clients establish a secure connection with the server then exchange identification, authentication and information by engaging in a series of client-initiated response exchanges.
EPP commands operate in an Extensible Markup Language (XML) text protocol that allows multiple registrars to perform operations using a shared central object repository.
EPP provides seven basic services: hello/greeting, login, logout, poll, commands, responses and an extension framework.
EPP provides seven commands: check, info, create, update, delete, transfer, and renew. These commands may be performed in the context of three base EPP objects: domains, contacts and hosts (nameservers).
This version of the EPP RTK is based on the IETF Internet Drafts for EPP version 04. Along with this are the Drafts from the Contact, Domain and Host objects, all of which are at version 02. As the IETF releases updates to the Internet Draft documents, the RTK will be updated to follow the changes.
The remainder of this document will reference each EPP Internet-Draft by the abbreviated title enveloped in square brackets ([]) listed beside the appropriate document title below.
When referred to the EPP draft documents, you can find the versions implemented in this release of the RTK in the directory epp-rtk/epp of the release package.
[EPP] Extensible Provisioning Protocol
Version 04: draft-ietf-provreg-epp-04.txt

[EPP-C] Extensible Provisioning Protocol Contact Mapping
Version 02: draft-ietf-provreg-epp-contact-02.txt

[EPP-D] Extensible Provisioning Protocol Domain Name Mapping
Version 02: draft-ietf-provreg-epp-domain-02.txt

[EPP-H] Extensible Provisioning Protocol Host Mapping
Version 02: draft-ietf-provreg-epp-host-02.txt

[EPP-T] Extensible Provisioning Protocol Transport Over TCP
Version 02: draft-ietf-provreg-epp-tcp-02.txt

3. EPP Java RTK Requirements

This section describes the packages, programming language and protocol familiarity required to use the EPP RTK for Java. For more details please read the README provided in the RTK.
3.1 Packages

Java Standard Edition Software Development Kit (SDK) 1.3: This is used to change code and compile it. An earlier version should be adequate, but this has not been tested. The compiler jikes from IBM was used periodically in the development of the Java RTK, but it use has been commented out of the build.xml for distribution. Give it a try, it's really fast.

Java Runtime Environment (JRE) 1.3: This is used to run any type of java program.

Java Secure Socket Layer (SSL) Packages: These are for secure SSL and TLS connections to an EPP Server. By default, Sun's JSSE implementation is used. If the registrar does not prefer this JSSE implementation then installation of another JSSE package is required. To make changes to the EPPClient.java and compile it, at minimum the standard Sun JSSE implementation is required. This can be bypassed by removing the JSSE class and package import lines in EPPClient.java. Sun's JSSE can be obtained at http://java.sun.com/products/jsse although it is included in the 1.4 release of the SDK from Sun. If a registrar wishes to use a non-JSSE package, the Java RTK class provides the facilities to set an externally connected Socket. See the description of EPPClient and EPPTransports below for more information.
The registrar will also most likely need a valid SSL certficate in order to perform a successful handshake with an EPP registry. Depending on the implementation of the registry, the registrar might need to obtain a certificate from an company sanctioned by the registry. Also depending on the registry, the registrar might need to include the full certificate chain in the SSL handshake in order to succesfully connect. This is currently the case with the .info registry.
Please note that the "home-made" cert included with the RTK cannot be used in production environments. The registrar must purchase a new cert from a certified provider in order to use the RTK in a production setting. If the registrar is already a registrar with Verisign's com/net/org registry, those certs will likely be valid for most new EPP registries.

3.2 Open Source Packages

The following Open Source packages are required to build the EPP Java RTK. By default, the build process will use jar files included in the lib directory. The registrar may download the full packages from the respective web sites and override settings in the default build to use the full packages.

Xerces-J 1.3.0: This is used to parse XML source code. Xerces is chosen because it is robust, compliant with multiple XML standards (such as XML 1.0, DOM, SAX, etc.) and available in three programming languages: Java, C++ and Perl. Xerces.jar should be available in the CLASSPATH. Xerces-J can be obtained from http://xml.apache.org/xerces-j.

Ant 1.3: The RTK includes pre-built javadocs and jar files. If the registrar wishes to build the RTK, it is recommended to use Ant to build the application to change code or compile it. Targets include: all, dist, clean, javadoc, library and jar. If the registrar wishes to build the RTK, dist is the recommended target that will create the final java file and the javadocs (although you could get away with the target "jar" if all you want is the jar file). The single Ant jar file that is required to build is included in the lib directory. More information on Ant can be obtained from http://jakarta.apache.org/ant.
To build the RTK, copy the build files from the java/etc directory to java. Set your JAVA_HOME environment variable, then run either build.sh or build.bat depending on your operating system.

3.3 Protocol Familiarity

Extensible Provisioning Protocol (EPP): Recommended. The reference documents are included in epp-rtk/epp.

Extensible Markup Language (XML): Required if the registrar wishes to delve into the workings of the RTK coding.

4. EPP IDL Use in the Java RTK

4.1. Overview
The EPP RTK makes use of a set of IDLs (Interface Definition Language) based on EPP objects and actions. These IDLs, developed by a group of EPP registry operators, bridge the gap between the EPP XML schemas and EPP as an API. They specify data used in EPP and they also specify interfaces with which an RTK should comply. They also ensure that implementations of the EPP RTK in different languages follow a similar structure. Note that these IDLs do not imply any guarantee of CORBA functionality in the RTK or the EPP registry. They were used solely for their language-independancy.
For this RTK, the IDLs have been converted to Java classes (with idlj included in the J2SE). The RTK makes use of the general EPP, EPP Domain, EPP Host, and EPP Contact IDLs. The versions of the IDL files used in this release of the RTK are included in the RTK package for reference only.
The IDLs were compiled into Java classes in the following packages:
org.openrtk.idl.epp
org.openrtk.idl.epp.contact
org.openrtk.idl.epp.domain
org.openrtk.idl.epp.host
The IDL classes (all starting with "epp_") are used mostly as request and response data holders. The classes in the package com.tucows.oxrs.epp.rtk.xml (all starting with "EPP") are used to convert the IDL data to and from XML in communcation with an EPP registry.
In all EPP actions, there will be a trio of classes used: one for request data, one for response data, and a third for XML conversion. For example, for the action Domain Check, the three classes involved would be epp_DomainCheckReq, epp_DomainCheckRsp and EPPDomainCheck, respectively.
All of the data members, for epp_* classes which have some, are public and can be set directly (eg. domain_create_req.m_name = "domain.epp"). These member also have public set and get methods which make the epp_* classes more object oriented and friendly in EJB and JSP contexts. Throughout this document, these data attributes are enumerated and described. Where you see an attribute like "name", the actual data member is "m_name" and the set and get methods are "setName()" and "getName()", respectively. For an attribute like "postal-code", the data member is m_postal_code, the accessor methods are "setPostalCode()" and "getPostalCode()". So, the pattern is to prefix "m_" and change "-" to "_" for data members and to capitalize first letters of each word and to remove the dashes for accessors.
Refer to the Javadocs for information on all IDL data members.
4.2 General EPP IDL Data Members
4.2.1 Repository Object Identifiers (ROID)

A ROID is an identifier that uniquely identifies an object across registry repositories. ROIDs are created for all EPP objects. A ROID is generated by combining a unique server-assigned identifier with a registered value that globally identifies the repository. There use is mostly a registry formality and have no specific EPP usage when it comes to a registry as they can't be used to retrieve objects. They are useful in whois service because they allow the user to query an object without knowing what type of object it is (eg. contact, registrar, etc...).
ROIDs are formed as follows:
[1-80 characters] '-' [1-8 characters] (e.g. C120-LRMS)

4.2.2 epp_Command
This data member is used in all action requests to the EPP server. It is used in every check, info, create, update, query, transfer and renew command for any contact, domain or host object. It is also used in the Login and Poll commands.
client-trid
Optional. This is the client's transaction identifier. This element is optional for all actions, but it is recommended for use in transform actions (create, update, transfer, renew and delete) for request tracking purposes.
creds
Optional, depending on the context. This is an instance of epp_Credentials, which is a combination of the client's id, password, optional new password and options (protocol version and message language). According to [EPP], credentials are required for login in sessionful connections to the registry. If the EPP registry supports sesssion-less connections, then a login is not sent by the registrar and the credentials become mandatory for all commands. If a sessionful connection is obtained, then the registry will return an error if the credentials are included in subsequent commands.
unspec
Optional. This is a placeholder for registry-specific extensions to EPP. It uses the epp_Unspec interface. It can be used by the registrar in various requests to the registry, depending on the requirements of the registry.
4.2.3 epp_AuthInfo
This generic data member is associated with EPP Domain and Contact objects. It contains the authorization information required to authorize transfer requests to the EPP server. Presently, only one epp_AuthInfoType is permitted: PW (password). This attribute identifies the authorizing object's passphrase as the authorization information.
The roid member is only used if the auth info being used for the transfer belongs to another object. The restrictions to the use of another object's auth info is outlined as follows:

Another object's ROID can be supplied for a transfer only if the transferring object is a domain.

The authorizing object can only be a contact.

The contact must be one that is currently associated with the transferring domain.

For example, if a registrant wishes to transfer a domain, any one of the domain's associated contact authorization information can be used to authorize the transfer of the domain.
Not all registries will support this third-party authorization method.
type
This is the authorization information type. It is specified by constants in the epp_AuthInfoType class. The only allowed value is epp_AuthInfoType.PW. If left null, it will be defaulted to this value by the RTK.
roid
Optional. This is the authorizing object's ROID. Leave null if the authorizing object is the object being transferred.
value
This is the authorizing object's passphrase.
4.2.4 epp_TransferRequest
This data member is used in requests to transfer EPP objects. It is used for every transfer command for any contact or domain object. The minimum data elements required are the object's authorization information and the op attribute. Five epp_TransferOpType attributes are permitted: PENDING, APPROVE, CANCEL, QUERY, REJECT and REQUEST.
auth-info
This contains the authorization information required to authorize object transfers. It is an instance of epp_AuthInfo.
op
Optional. This is the transfer operation type. It is specified by constants in the epp_TransferOpType class (eg. epp_TransferOpType.QUERY). If left null, the RTK will default to QUERY.
4.2.5 epp_TransferStatusType

This data member responds with the transfer status for all object transfer requests to the EPP server. Six epp_TransferStatusType attributes are permitted: PENDING, CLIENT_APROVED, CLIENT_CANCELLED, CLIENT_REJECTED, SERVER_APPROVED and SERVER_CANCELLED.

4.2.6 epp_Response
This is a placeholder for standard EPP server response information (eg. code, message, etc.).
results
This is an array of epp_Result instances.
qcount
Optional. This is the size of the waiting message queue on the server. It is only present in Poll responses where there are messages waiting on the server.
trans-id
This is the returned transaction identifier (TRID), which includes the client's TRID used in the request (if it was supplied) and the server's TRID. It is an instance of epp_TransID.
unspec-string
Optional. This is a placeholder for registry-specific extensions to EPP. It can be used by the registry in response to various commands.
4.2.7 epp_Result
This is a placeholder for standard EPP server result information (eg. code, message, etc.).
code
This is the response code from the EPP Server.
msg
This is the response message from the EPP Server.
lang
This is the language of the response message.
id
This is the message id. It is only present in Poll responses where there are messages waiting on the server.
values
Optional String array. This is an array of descriptive messages to describe the error contained in the code and message in further detail.
4.2.8 epp_CheckResult
This data is the generic response to any EPP Check command. The data members state whether the checked object exists in the EPP server.
value
This is the name of the object being checked. It will be the object's ROID in the case of Contact Check.
exists
Boolean indicator. It is "true" if the object exists in the server or "false" if the object does not exist.
4.2.9 epp_Greeting
This is a service connection member that states the server's abilities. The greeting lists the languages and protocol versions supported by the EPP Server. It also lists the services offered by the server. Services are EPP objects, namespaces and XML schema locations. Please see [EPP] for more information.
server-id
This is the server generated id.
server-date
This is the current server date and time in UTC.
versions
This identifies the protocol versions supported by the server.
langs
This identifies the text response languages offered by the server.
services
This identifies the objects that the server is capable of managing.
4.2.10 epp_LoginReq
This is a session management member that establishes a session with the EPP server.
cmd
This is the generic request data member. It is an instance of epp_Command.
services
This identifies the objects that the server is capable of managing.
4.2.11 epp_LogoutReq
This is a session management member that ends a session with the EPP server.
client-trid
Optional. This is the client's transaction identifier.
unspec
Optional. This is a placeholder for registry-specific extensions to EPP. It uses the epp_Unspec interface.
4.2.12 epp_PollReq
This data member is used to discover and retrieve client service messages from the EPP server. The minimum data element required is the 'op' attribute. Two poll operations are permitted: REQ (request) and ACK (acknowledge).
cmd
This is the generic request data member. It is an instance of epp_Command.
op
Optional. This is the poll operation type. It is specified by constants in the epp_PollOpType class (eg. epp_PollOpType.REQ). If left null, the RTK will default to REQ.
msgID
Optional. This is the response message id from the EPP server. Only required if the op type is epp_PollOpType.ACK.
4.2.12 epp_PollResData

This structure contains data pertaining to the message that was polled. It has two members: 'data' which is the actual data that was returned in the poll request, and 'type' which indicates the type of data in the previous member. The 'data' member is actually a "union"-type of structure. The translation of a union IDL struture into Java makes for a class who's usage is not evident at first.
Currently, there are only two known types of PollResData (and even these are subject to change): epp_PollResDataType.DOMAIN_TRANSFER and epp_PollResDataType.CONTACT_TRANSFER. This will be set in the 'type' member of the epp_PollResData. If the type is CONTACT_TRANSFER, then you would call the method m_contact_transfer() on the 'data' member of epp_PollResData. This would return an instance of epp_PollContactTransfer. If the type is DOMAIN_TRANSFER, then you would call the data's m_domain_tranfer() method. This would return an instance of epp_PollDomainTransfer. The object contained in the 'data' member is trying to alert you to activity with regards to that object in the registry. i.e. If the type is DOMAIN_TRANSFER, then the domain in the data member is a domain that is going through the transfer process. To get the details, you would have to retrieve the domain name from epp_PollDomainTransfer and perform a Transfer Query.
PollResData details are registry specific. Be sure to read up on poll response information in the literature provided by your registry.
Please see the Javadocs on the classes mentioned here for more information. Please also see the section on EPPPoll below. If you are writing PollResData classes for a registry, then you'll probably want to take a look at the code and Javadocs for the classes EPPPoll, PollResData, and domaintransfer for information on the framework of poll response data in the Java RTK.

4.2.14 epp_Session

This IDL interface is implemented by the EPPClient class, which gives the developer access to working processAction() and processXML() methods. This interface also defines the complete list of EPP result codes in static class variables. Two additional result codes are declared that are not a part of the EPP specification:

2600 RTK_COMMUNICATIONS_FAILURE

2601 RTK_UNEXPECTED_SERVER_DISCONNECT
If the registrar wishes to test for specific EPP result codes, it is recommended to use the static members of epp_Session instead of the published [EPP] result code numeric values. This will reduce the coding impact if the result codes were to change in the future.

5 API Class Summary

The following API classes are described in this document. Refer to Javadocs for a complete set of API classes, methods and fields.

General EPP Classes

EPPClient
EPPGreeting
EPPLogin
EPPLogout
EPPPoll
RTKBase
EPPXMLBase
EPPTransport classes

EPP Contact

EPPContactCheck
EPPContactInfo
EPPContactCreate
EPPContactUpdate
EPPContactDelete
EPPContactTransfer

EPP Domain

EPPDomainCheck
EPPDomainInfo
EPPDomainCreate
EPPDomainUpdate
EPPDomainDelete
EPPDomainTranfer
EPPDomainRenew

EPP Host

EPPHostCheck
EPPHostInfo
EPPHostCreate
EPPHostUpdate
EPPHostDelete

6 API Classes

This section describes the API classes listed in the API Class Summary. These classes are used to provide a working relationship between the EPP Server and Client. Refer to the Javadocs for information regarding all Java API classes, methods and fields as well as IDL data members. Data members not explicitly stated as optional are required.
6.1 General EPP Classes
6.1.1 EPPClient
Description
This class encapsulates, through the use of helper classes, all connection and communication with the EPP Server. The main methods of the EPPClient are described below. For a full list of available methods, please refer to the Javadocs. This class also makes use of the rtk.properties file to determine run-time settings, such as the transport class to use in communications with the EPP Server. To find the propery file, EPPClient calls RTKBase's getRTKProperties() method, which in turn uses the system property "rtk.props.file" to retrieve the full path of the rtk.properties file. The scripts run_example.bat and .sh both set up the rtk.props.file to run the examples.
Method Summary
connect(), connectAndGetGreeting() and their variations:
The connect() methods vary, where the EPP Client ID, EPP Password, Host Name and Host Port can be optionally specified. To connect to the EPP Server, the EPPClient gets the RTK properties out of RTKBase.getRTKProperties(). If the "rtk.transport" property is defined and it points to a subclass of EPPTransportBase, then an instance of the class is created. The transport's connect() method is then called. If the property is not specified, then the value of DEFAULT_TRANSPORT_CLASS is used, which is set to "EPPTransportTCPTLS" (i.e. TLS/SSL over a TCP socket). If the class is not found or there are problems trying to dynamically instantiate the class, the an EPPTransportException is thrown. It is up to the user of the RTK to catch this exception.
The EPPTransportTCPTLS transport will by default use the JSSE to provide a secure connection (more on this in a moment). If a third party SSL package is preferred (i.e. not JSSE), no connect() methods should be called. In this case, the registrar should establish a connection with the package chosen. Then the registry should create an instance of EPPTransportTCP and pass the established and connected Socket (or another class that allows for getInputStream() and getOutputStream()) to the transport via the class constructor. This transport is provided to the EPPClient via the setTransport() method. The registrar then must call getGreeting() to retrieve the EPP greeting waiting on the Socket. At this point the EPPClient is ready to issue a login.
If SSL and the default JSSE is used, then the System parameter ssl.props.location must be specified. The EPPTransportTCPTLS class uses this parameter to find the ssl.properties file (which is in java/ssl in the distribution). Refer to the section on SSL connectivity for more information. The run_example.sh and .bat files show sample usage of this system property. Please also see the README file contained in the java/ssl directory for information on the Java keystore that holds the private key and certificates.
Please note that some registries require full certificate chains in the SSL handshake process. This means that all certs must be loaded by your SSL package, from your personal cert to the Certificate Authority's (CA) certificate. This may be any number of certficates, but is often limited to just two (i.e. yours and your CA's). To determine who is the authority for a certificate, do the following:
Using a package such as openSSL, read the certificate. Using openSSL, this is done with the following command (if the cert is in PEM format):
openssl x509 -inform PEM -in certfile.pem -text
Look for the line that starts with "Issuer". This is the Distinguished Name of the certficate's issuer. You must obtain a CA cert from them in order to continue the certificate chain. If the "Issuer" and the "Subject" line are the same, then you've reached the end of the chain (this is also sometimes referred to as the "root certificate"). On your certificate, the "Subject" should be you or your organization.
Usage Syntax
// For a custom socket connection.
EPPClient epp_client = new EPPClient(epp_host_name,
                                     epp_host_port,
                                     epp_client_id,
                                     epp_password);


epp_client.setLang("en");

// Establish an SSL-based socket with a
// third-party package.

....;
....;

// Completed establishing a connection.
// At this point, the EPP Server has sent a
// greeting for the registrar to pick up.

epp_client.setSocketToEPPServer(the_socket);
epp_Greeting greeting = epp_client.getGreeting();

// Now the EPP Server is ready to proceed with login.
login(String)
Issues a login command to the EPP Server. Note that it will send the RTK Version on login unless you call setVersionSentOnLogin() with false.
logout(String)
Issues a logout command to the EPP Server.
disconnect()
Closes the connection to the EPP Server.
setLang(String)
The default value is "en". To change locales use this method before logging into the EPP Server.
processAction(epp_Action)
This method takes the parameter epp_Action and invokes its toXML() method, which generates the EPP XML request string to the EPP server. The server response is then passed to the epp_Action's fromXML() method and the object is returned to the caller.
This method will throw an epp_Exception if there are problems in communicating with the EPP registry. It will also pass up any epp_XMLException thrown by the epp_Action's toXML() or fromXML(). Finally it will also pass any epp_Exception thrown by the epp_Action's fromXML() which would be triggered by a server response with a result code greater than or equal to 2000.
processXML(String)
This is an alternative method to processAction(epp_Action). This method takes an XML request and passes it to the EPP server. Then the server's XML response is returned to the caller. This method fulfills the second requirement of the epp_Action interface defined in the EPP RTK IDLs.
This method will throw an epp_Exception if there problems in communicating with the EPP registry.
setSocketToEPPServer(Socket)
Used to feed an externally connected Socket (or subclass) to an EPPClient instance. If this method of connection is used, the EPPClient will create a new instance of an EPPTransportTCP using the provided socket and the EPPClient's timeout value (use setEPPTimeout() to change this value).
setTransport(EPPTransportBase)
Allows an externally-created and -connected transport to be provided to the EPPClient. In this case the registrar should not call connect(), but only getGreeting(). Unlike setSocketToEPPServer(), the EPPClient will not override any settings (like timeout) on the transport before using it.
setVersionSentOnLogin(boolean)
isVersionSentOnLogin()
By default the RTK sends its version number in the "unspec" portion of the Login command. Some registries use this value if it is present in the login to validate the client's RTK and reject the login if the registry has not certified the version. See the class com.tucows.oxrs.epp.rtk.xml.unspec.RTKVersion for more information. To not send the RTK version on login, in case the registry does not like the extra data, use setVersionSentOnLogin() with a false value.
hello()
Used to force the server to send a greeting outside of the normal greeting at the time of connection.
6.1.2 EPPGreeting

Description
This class represents a greeting sent from the EPP Server. From it, the server id, languages/locales, available services, date, and supported versions can be determined.
This class is not usually instantiated by the registrar, but rather, the registrar gets an instance from EPPClient's getGreeting(), connectAndGetGreeting() or hello().

6.1.3 EPPLogin

Description
This class allows the registrar to establish a session with the EPP server after a greeting is issued by the server. If no login is used, then the session is deemed to be sessionless by the registry. Sessionless connections required credentials for each and every command. Sessionless connections might not be support by all EPP registries.

6.1.4 EPPLogout

Description
This class is used to end a session with the EPP server.

6.1.5 EPPPoll
Description
This action is used to discover and retrieve client service messages from the EPP server. The registrar should periodically issue an EPP Poll to the server. This serves a double purpose: 1) to keep an EPP session from timing out due to inactivity; 2) to query the EPP server for waiting notifications. If there are notifications, the registrar should poll REQ and poll ACK each message individually. A notification will stay on the server until ACK'ed. These notifications will contain such information as domain transfer notifications (i.e. another registrar has requested a transfer on one of the registrar's domains), low registry account balance messages or possibly anticipated server outage messages. A Poll message may be contructed like the other EPP action. This usage is detailed below. But the EPPClient contains the method poll() will various overloaded versions. This greatly simplifies the poll request process.
Usage Syntax
epp_PollReq poll_request = new epp_PollReq();
epp_Command command_data = new epp_Command();
command_data.setClientTrid( client_trid );

poll_request.setCmd( command_data );

// Set the Poll "op" to REQ (i.e. request).  This will
// query the message queue for the first message available.
// Note that the REQ op does not dequeue the message.
// The ACK op is required to acknowledge messages and 
// remove them from the waiting queue.
//
// Note that the Poll op type of REQ is the default, so
// it could have been left null here.
poll_request.setOp( epp_PollOpType.REQ );

EPPPoll poll = new EPPPoll();
poll.setRequestData(poll_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
poll = (EPPPoll) epp_client.processAction(poll);

// or, alternatively, this method can be used...
//poll.fromXML(epp_client.processXML(poll.toXML()));

epp_PollRsp poll_response = poll.getResponseData();
epp_Response response = poll_response.getRsp();

// This is the number of messages in the registry queue,
// including the currently REQ'd message
short message_count = response.getQcount();

epp_Result[] results = response.getResults();

// In a subsequent Poll ACK, this is the message ID that
// would be used.
String message_id = results[0].getId();
Input
epp_PollReq
cmd
Generic EPP request data member.
op
Optional. This is the poll operation type. It is specified by constants in the epp_PollOpType class. If not specified, REQ is default.
msgID
This is the response message id from the EPP server. Only required if the op type is epp_PollOpType.ACK.
XML Converter Class
EPPPoll
Output
epp_PollRsp
rsp
Generic EPP response data member.
res-data
Instance of epp_PollResData. Please see the section regarding epp_PollResData where the common IDL classes are described.
6.1.6 RTKBase
Description
This abstract class is the base of the Registrar Toolkit (RTK). All RTK classes inherit from this one. This class defines the debug method, constrains and date formats. Note that despite this class extending a CORBA Object class, it does not make any promises of CORBA functionality. Extension of the CORBA ObjectImpl was required because of the methods required by the RTK IDL interfaces.
Static Member Summary
DateFormat UTC_FMT = new DateFormat("yyyy-MM-dd'T'hh:mm:ss.0'Z'")
This is the format returned by the EPP Server in timestamps (eg. expiration date, last modified date, etc.). It can be used to convert String dates into Date objects. eg: UTC_FMT.parse(date_string).
DateFormat DATE_FMT = new DateFormat("yyyy-MM-dd")
This is the format used by the DomainRenew command. As with UTC_FMT, it can also be used to convert String dates into Date objects. eg: DATE_FMT.parse(date_string).

Static Method Summary
setDebugLevel(int)
There are four debug settings that may be used. The higher debug levels include output from the lower levels. All output is sent to System.err.

DEBUG_NONE: Debug level for no debug output.

DEBUG_LEVEL_ONE: Debug level for any exceptions that might be thrown. Include stack trace output.

DEBUG_LEVEL_TWO: Debug level for debugging points of interest throughout the RTK code, including display of XML messages to and from the EPP Server.

DEBUG_LEVEL_THREE: Debug level for showing all debugging output, which includes entry and exit of most method calls.
Usage syntax
import com.oxrs.epp.rtk.RTKBase;

// Setting debug level to ONE to see exception reporting in
// System.err.
RTKBase.setDebugLevel(RTKBase.DEBUG_LEVEL_ONE);
Input
Debug level as described above.

DEBUG_NONE
DEBUG_LEVEL_ONE
DEBUG_LEVEL_TWO
DEBUG_LEVEL_THREE

Output
None.
6.1.7 EPPXMLBase
Description
This abstract class is the base of the XML parsing and rendering classes in the com.tucows.oxrs.epp.rtk.xml package. It should also be the parent class to the RTK add-on classes that deal with extension to EPP. EPPXMLBase defines common protected methods used by the child classes. It also defines some public static utility methods that are very useful.
Static Method Summary
Object[] convertListToArray(java.lang.Class, java.util.List)
This method facilitates the conversion of any type of list to an array of objects. The class of the object array is defined by parameter Class. The returned value is an array of the class Object. This can be cast into the required object array.
Usage Syntax
List ip_list = (List)new ArrayList();
ip_list.add(new epp_HostAddress(epp_HostAddressType.IPV4, "100.103.44.151"));
ip_list.add(new epp_HostAddress(epp_HostAddressType.IPV4, "100.103.45.151"));
host_create_request.setAddresses( (epp_HostAddress[])
            EPPXMLBase.convertListToArray((new epp_HostAddress()).getClass(),
                                          ip_list) );
Input
java.lang.Class
The class of the array that you wish to have returned.
java.util.List
The list of object that can be cast to the class of the first parameter.
Output
None.
Return
Object array that must be cast into an array of the desired Class.
String[] convertListToStringArray(java.util.List)
This method is a variation on convertListToArray. It can only convert lists of String objects in String arrays.
Usage Syntax
List nameserver_list = (List)new ArrayList();
nameserver_list.add("ns1.domain.info");
nameserver_list.add("ns2.domain.info");
domain_create_request.setNameServers( EPPXMLBase.convertListToStringArray(nameserver_list) );
Input
java.util.List
A List of String objects.
Output
None.
Return
The resulting String array.
Boolean getCheckResultFor(epp_CheckResult[], String)
This method takes an epp_CheckResult array and looks for the given String identifier in the array and return the Boolean object result.
Usage Syntax
Boolean domain_exists = EPPXMLBase.getCheckResultFor(check_results,
                                                     "domain.info");
Input
org.openrtk.idl.epp.epp_CheckResult[]
An array of check results from the EPP registry.
java.lang.String
The identifier (domain name, host name, contact ROID) you expect to find in the check results array.
Output
None.
Return
The Boolean object value for the given String identifier.
Returns null if the object is not found.
java.lang.String transferStatusToString(epp_TransferStatusType)
This method converts an epp_TransferStatusType in an English String that represents the given transfer status (eg. "pendingTransfer"). The list of transfers statuses is maintained in [EPP].
Usage Syntax
epp_TransferStatusType transfer_status_type = domain_transfer_query_rsp.getTransferStatus();
String transfer_status = EPPXMLBase.transferStatusToString(transfer_status_type);
Input
org.openrtk.idl.epp.epp_TransferStatusType
The transfer status type.
Output
None.
Return
The English String representation of the transfer status type.
Returns null if the transfer status is not found.
6.1.8 EPPTransport Classes

Description
The set of classes that start with "EPPTransport" make up the transport layer handlers in the EPP protocol. The root class is EPPTransportBase. This abstract class defines the general methods that most, if not all, of the transport subclasses should implement.
Current subclasses include:

EPPTransportTCP -- Transport layer over a simple TCP socket. One session per connection.

EPPTransportTCPTLS -- Adds encryption to the standard TCP connection.

EPPTransportSMTP -- Only a demonstration class at this time, but would eventually send EPP commands to the server via email messages.
Developments to come: a BEEP transport implementor. Some of the subclasses provide additional methods or construtors to allow setting of attributes for the particular transport. See the Javadocs of the individual transport for more information.
EPPTransportBase Method Summary
setEPPHostName(String)
getEPPHostName()
Accessors for the EPP Host name data member.
setEPPHostPort(int)
getEPPHostPort()
Accessors for the EPP Host port data member.
setTimeout(int)
getTimeout()
Accessors for the EPP timeout data member.
initialize(String,int,int)
Allows the user to set the EPP Host name, port and timeout values all in a single call.
connect()
disconnect()
Abstract methods to manage the connection to the EPP host. Must be overriden by subsclasses of EPPTransportBase. If a connection is not relevant to the transport used, then the subclass should make these empty methods.
writeToServer(String)
String readFromServer()
Abstract methods to manage communications wth the EPP host. Must be overriden by subsclasses of EPPTransportBase.
6.2 EPP Contact
An EPP contact represents registrant information: either a person or an organization or group. A contact object may be viewed or modified by the registrar, on behalf of the registrant. Contacts can be associated with Domain objects through the Domain command. [EPP-C] allows the following commands to be performed: check, info, create, update, delete and transfer.
6.2.1 Common Contact Data Members
epp_ContactNameAddress
Contains complete postal address information for a contact. Depending on its usage in contact actions (create, update, info), it can contain either ASCII (7-bit ASCII as defined in [US-ASCII]) or UTF-8 data (UTF-8 as defined in [RFC2279]).
name
Contains the name of the individual or the role represented by the contact. (Character string)
org
Optional. Contains the name of the organization with which the contact is affiliated. (Character string)
address
This is the epp_ContactAddress sub-structure. Contains one, two or three street addresses, city, state or province, postal code and country code.
epp_ContactAddress
Structure for pure postal address information.
street1
Contains the contact's first street address. (Character string)
street2
Optional. Contains the contact's second street address. (Character string)
street3
Optional. Contains the contact's third street address. (Character string)
city
Contains the contact's city. (Character string)
state-province
Optional. Contains the contact's state or province. (Character string)
postal-code
Optional. Contains the contact's postal code. (Character string)
country-code
Contains the contact's country code. (Two-character ISO country code)
epp_ContactPhone
Structure which holds a telephone number as defined in [EPP-C]. Used for both the contact voice and fax data members.
Previously this was named epp_ContactVoice. This class still exists but is now a subclass of epp_ContactPhone. In a further release, epp_ContactVoice will be removed.
extension
Optional. Contains the telephone number extension. (Character string)
value
Contains the actual telephone number. (Character string that must begin with a plus '+' sign, followed by a country code, followed by a dot, followed by a sequence of digits representing the telephone number. Dashes or other characters are not permitted.)
epp_ContactStatusType
This data member responds with the contact's status for all contact info, create, update and transfer requests to the EPP server. Six epp_ContactStatusType attributes exist: SERVER_DELETE_PROHIBITED, CLIENT_DELETE_PROHIBITED, SERVER_TRANSFER_PROHIBITED, CLIENT_TRANSFER_PROHIBITED, SERVER_UPDATE_PROHIBITED, CLIENT_UPDATE_PROHIBITED, LINKED, OK, PENDING_DELETE, and PENDING_TRANSFER.
epp_ContactStatus
type
Contains the contact's status type. It is an instance of epp_ContactStatusType. Can be converted to and form a String via EPPContactBase.contactStatusToString() and EPPContactBase.contactStringToStatus().
lang
This is the language of the response message.
value
Optional. If present, this is the reason text for the presence of the status on the contact object.
6.2.2 EPPContactCheck
Description
This action is used to determine if a list of contact IDs are known to the server. The check results are in an array of epp_CheckResult. The order of the check results is not guaranteed to be in the same order as the requested IDs. Please see the section on epp_CheckResult for more information.
IDs for contacts are assigned by the registrar in the contact create request. The ID of a new contact must not already exist in the registry for any registrar. The registrar has the choice of generating the ID itself (eg. from a DB sequence, or maybe from hashing the contact's name and email address). These kinds of IDs might not be very user friendly or easy to remember if the registrant wants to recall a previously created contact. So the registrar could rely on the registrants to generate an ID themselves.
Note that contact IDs are case sensitive.
Usage syntax
epp_ContactCheckReq contact_check_request = new epp_ContactCheckReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
contact_check_request.setCmd( command_data );

// The Contact Check request can accept an array of contact
// IDs.  In this example, an ArrayList is used to dynamically
// create the List of IDs and then EPPXMLBase's
// utility method convertListToStringArray() is used
// to convert the List to a String array.
List contact_list = (List)new ArrayList();
contact_list.add("contact1");
contact_list.add("contact2");
contact_list.add("contact3");
contact_check_request.setIds( EPPXMLBase.convertListToStringArray(contact_list) );

EPPContactCheck contact_check = new EPPContactCheck();
contact_check.setRequestData(contact_check_request);

contact_check = (EPPContactCheck) epp_client.processAction(contact_check);

// or, alternatively, this method can be used...
//contact_check.fromXML(epp_client.processXML(contact_check.toXML()));

epp_ContactCheckRsp contact_check_response = contact_check.getResponseData();
epp_Response response = contact_check_response.getRsp();
epp_Result[] results = response.getResults();

epp_CheckResult[] check_results = contact_check_response.getResults();

Boolean exists = EPPXMLBase.getCheckResultFor(check_results,
                                              "contact1");
Input
epp_ContactCheckReq
cmd
Generic EPP request data member.
ids
The array of contact IDs.
XML Converter Class
EPPContactCheck
Output
epp_ContactCheckRsp
rsp
Generic EPP response data member.
results
The array of generic check results (epp_CheckResult).
6.2.3 EPPContactInfo
Description
This action is used to retrieve detailed information associated with a contact. The response to this command returns information regarding the current state of a contact in the registry.
The response will include authorization information if the issuing registrar is the current owner of the contact object in the registry.
Note that an epp_Exception will be thrown by EPPContactInfo's fromXML() method or by EPPClient's processAction() method if the info'd contact is not found in the registry.
Usage syntax
epp_ContactInfoReq contact_info_request = new epp_ContactInfoReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.m_client_trid = client_trid;
contact_info_request.setCmd( command_data );

contact_info_request.setId( "contact1" );

EPPContactInfo contact_info = new EPPContactInfo();
contact_info.setRequestData(contact_info_request);

contact_info = (EPPContactInfo) epp_client.processAction(contact_info);

// or, alternatively, this method can be used...
//contact_info.fromXML(epp_client.processXML(contact_info.toXML()));

epp_ContactInfoRsp contact_info_response = contact_info.getResponseData();
epp_Response response = contact_info_response.getRsp();
epp_Result[] results = response.getResults();

String client_id = contact_info_response.getClientId();
String created_by = contact_info_response.getCreatedBy();
String create_data_string = contact_info_response.getCreatedDate();

// You can also save the auth info from an info where
// the calling registrar is the sponsoring client for the
// object.
epp_AuthInfo contact_auth_info = contact_info_response.getAuthInfo();
Input
epp_ContactInfoReq
cmd
Generic EPP request data member.
id
The contact's ID.
XML Converter Class
EPPContactInfo
Output
epp_ContactInfoRsp
rsp
Generic EPP response data member.
id
The contact's ID.
roid
The contact's ROID.
ascii-address
The contact's address in 7-bit US-ASCII. Instance of epp_ContactNameAddress.
i15d-address
The contact's address in UTF-8. Instance of epp_ContactNameAddress.
voice
Optional. The contact's voice telephone number. Instance of epp_ContactPhone.
fax
Optional. The contact's facsimile telephone number. Instance of epp_ContactPhone.
email
The contact's e-mail address.
status
Array of epp_ContactStatus objects.
client-id
The contact's current sponsoring client id.
created-by
The client id of the of the contact creator.
created_date
The date and time the contact was created. In UTC format.
updated-by
Optional. The client id of the last contact updater. Is null if the contact has never been modified.
updated-date
Optional. The date and time the contact was last updated. Is null if the contact has never been modified.
transfer-date
Optional. The date and time the contact was transferred. Is null if the contact has never been transferred.
auth-info
Optional. The authorization information of the contact object. Instance of epp_AuthInfo. It will be null if the querying registrar is not the sponsoring registrar.
6.2.4 EPPContactCreate
Description
This action allows a registrar to create a contact object. This is one of two actions that require the most member data.
See the section on EPPContactCheck for information on generating contact IDs.

Contact ID is required (must not already exist in the registry).
Name is required.
Organization (Org) is optional.
A street value is required. A maximum of 3 street addresses can be provided.
City is required.
State/Province is optional.
Postal Code is required.
Country Code is required.
Voice is optional.
Fax is optional.
Email is required.
These values may be subject to format validation at the server side. For efficiency, it is recommended that the registrar validate values according to the [EPP-C] specification before sending the command to the server.

An ASCII address is required. This address data is limited to 7-bit ASCII characters.
An "i15d" address is optional. This address allows for UTF-8 characters.
The class epp_ContactAddress is used to represent this data. See the description of epp_ContactAddress at the beginning of this section for more information.
Usage syntax
epp_ContactCreateReq contact_create_request = new epp_ContactCreateReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
contact_create_request.setCmd( command_data );

// The ID used here should have been shown as
// available in a contact:check issued immediately
// before the create.
contact_create_request.setId( "contact2953" );

epp_ContactNameAddress name_address = new epp_ContactNameAddress();
name_address.setName( "John Doe" );
name_address.setOrg( "ACME Solutions" );

epp_ContactAddress address = new epp_ContactAddress();

// Up to three street values may be specified.
address.setStreet1( "100 Centre St" );
address.setCity( "Townsville" );
address.setStateProvince( "County Derry" );
address.setPostalCode( "Z1Z1Z1" );

// The country code must be a valid ISO country code.
address.setCountryCode( "CA" );

name_address.setAddress( address );

// Now assign that name/address set to the contact's
// ASCII address.  If you wish to also use UTF-8
// characters in the name/address data, set the 
// i15d-address data member.
contact_create_request.setAsciiAddress( name_address );

// The voice, fax and the email values can only be in ASCII.
// The voice value may contain an optional extension.

// Ceate a voice value with an extenstion.
contact_create_request.setVoice( new epp_ContactPhone("1234", "+1.4165559999") );
contact_create_request.setFax( new epp_ContactPhone(null, "+1.4165558888") );
contact_create_request.setEmail( "jdoe@acmesolutions.info" );

EPPContactCreate contact_create = new EPPContactCreate();
contact_create.setRequestData(contact_create_request);

contact_create = (EPPContactCreate) epp_client.processAction(contact_create);

// or, alternatively, this method can be used...
//contact_create.fromXML(epp_client.processXML(contact_create.toXML()));

epp_ContactCreateRsp contact_create_response = contact_create.getResponseData();
epp_Response response = contact_create_response.getRsp();
Input
epp_ContactCreateReq
cmd
Generic EPP request data member.
id
The new contact's registry-unique ID.
ascii-address
The contact's address in 7-bit US-ASCII. Instance of epp_ContactNameAddress.
i15d-address
Optional. The contact's address in UTF-8. Instance of epp_ContactNameAddress.
voice
Optional. The contact's voice telephone number. Instance of epp_ContactPhone.
fax
Optional. The contact's facsimile telephone number. Instance of epp_ContactPhone.
email
The contact's e-mail address.
auth-info
The authorization information specified by the registrant. Instance of epp_AuthInfo.
XML Converter Class
EPPContactCreate
Output
epp_ContactCreateRsp
rsp
Generic EPP response data member.
id
The contact's ID.
6.2.5 EPPContactUpdate
Description
This action allows a registrar to modify the fields of a contact object. Only the sponsoring registrar is allowed to update the contact object. The flexibility of this command makes it one of the more complex.
EPPContactUpdate data validations apply the same rules as in EPP Contact Create. Please see EPPContactCreate for more information.
The update command must contain at least one of two lists:

Items to add or remove: Contains contact child elements that can be added or removed. EPP currently limits this element to the contact's status.
Items to change: Contains contact child elements that can be changed. These elements include the contact's name, org, addresses (either ASCII or "i15d" and their child elements), voice, fax, email and authorization information.
In a contact change request, the registrar must only explicitly specify the values that are changing; leaving the remaining values set to null (although, there is no harm in sending the complete contact information). If an optional value is to be removed, then the registrar must specify an empty string as the new value.
Usage syntax
epp_ContactUpdateReq contact_update_request = new epp_ContactUpdateReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
contact_update_request.setCmd( command_data );

contact_update_request.setId( "contact2" );

epp_ContactUpdateChange contact_update_change = new epp_ContactUpdateChange();

epp_ContactNameAddress name_address = new epp_ContactNameAddress();

// In a contact change request, you only need to explicitly
// specify the values that are changing, leaving the remain
// values set to null (although, there is no harm in sending the
// complete contact information).  If an optional value is
// to be removed, then specify an empty string for the new value.
name_address.setName( "Jane Doe" );
name_address.setOrg( "ACME Systems" );

epp_ContactAddress address = new epp_ContactAddress();

// Up to three street values may be specified.
address.setStreet1( "999 Front St" );
// The postal is optional, so could have been set to "" here.
address.setPostalCode( "A9A9A9" );

name_address.setAddres( address );

// The contact update operation allows changes to both
// the ASCII and "i15d" name/address information.
contact_update_change.setAsciiAddress( name_address );

// The voice and email values are not changing, but we want
// to remove the fax value. Can't just use null here
// because then it would not be present in the request XML,
// so the server would affect no change to the fax
contact_update_change.setFax( new epp_ContactPhone("", "") );

contact_update_request.setChange( contact_update_change );

EPPContactUpdate contact_update = new EPPContactUpdate();
contact_update.setRequestData(contact_update_request);

contact_update = (EPPContactUpdate) epp_client.processAction(contact_update);

// or, alternatively, this method can be used...
//contact_update.fromXML(epp_client.processXML(contact_update.toXML()));

epp_ContactUpdateRsp contact_update_response = contact_update.getResponseData();
epp_Response response = contact_update_response.getRsp();
Input
epp_ContactUpdateReq
cmd
Generic EPP request data member.
id
The ID of the contact to update.
add
Optional. Items to add to the contact. Instance of epp_ContactUpdateAddRemove.
status
Optional. Registrar-usable statuses. Array of epp_ContactStatus objects.
remove
Optional. Items to remove from the contact. Instance of epp_ContactUpdateAddRemove.
status
Optional. Registrar-usable statuses. Array of epp_ContactStatus objects.
change
Optional. Contact data to change. Instance of epp_ContactUpdateChange.
ascii-address
Optional. The contact's address in 7-bit US-ASCII. Instance of epp_ContactNameAddress.
i15d-address
Optional. The contact's address in UTF-8. Instance of epp_ContactNameAddress.
voice
Optional. The contact's voice telephone number. Instance of epp_ContactPhone.
fax
Optional. The contact's facsimile telephone number. Instance of epp_ContactPhone.
email
Optional. The contact's e-mail address.
auth-info
Optional. The authorization information specified by the registrant. Instance of epp_AuthInfo.
XML Converter Class
EPPContactUpdate
Output
epp_ContactUpdateRsp
rsp
Generic EPP response data member.
6.2.6 EPPContactDelete
Description
This action allows a registrar to delete a contact object. A contact cannot be deleted if it is associated with any domains in the registry. A registrar can only delete the contact for which they are the sponsor.
Usage syntax
epp_ContactDeleteReq contact_delete_request = new epp_ContactDeleteReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
contact_delete_request.setCmd( command_data );

contact_delete_request.setRoid( "contact3" );

EPPContactDelete contact_delete = new EPPContactDelete();
contact_delete.setRequestData(contact_delete_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
contact_delete = (EPPContactDelete) epp_client.processAction(contact_delete);

// or, alternatively, this method can be used...
//contact_delete.fromXML(epp_client.processXML(contact_delete.toXML()));

epp_ContactDeleteRsp contact_delete_response = contact_delete.getResponseData();
epp_Response response = contact_delete_response.getRsp();
Input
epp_ContactDeleteReq
cmd
Generic EPP request data member.
id
The contact's ID.
XML Converter Class
EPPContactDelete
Output
epp_ContactDeleteRsp
rsp
Generic EPP response data member.
6.2.7 EPPContactTransfer
Description
This action allows a registrar to transfer the sponsorship of a contact object.
Five transfer operations are permitted: approve, cancel, query, reject and request. If none is specified, then "query" is defaulted.
Six transfer statuses exist in the registry: pending, approved, cancelled, rejected, auto-approved, auto-cancelled.
A transfer query allows the registrar to query the state of a current pending transfer or of the last approved, cancelled or rejected transfer. If the contact being queried has never been transferred, this command will throw an epp_Exception because of the error code return by the registry.
A transfer request initiates the transfer process in the registry. The server will notify the losing registrar of the pending transfer (through the Poll mechanism). The losing registrar then has the opportunity to explicitly approve or reject the transfer. The requesting registrar also has the option of canceling the transfer before it is completed. If the losing registrar fails to act on the transfer notification, the registry will automatically approve or reject the transfer within certain period of days. Check with the registry with which you will be dealing to find out the default behaviour.
Usage syntax
epp_ContactTransferReq contact_transfer_request = new epp_ContactTransferReq();

command_data = new epp_Command();

// The client trid is optional.  it's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
contact_transfer_request.setCmd( command_data );

// The Contact Transfer request is an EPP "transfer" request,
// meaning it requires an "op" value and the object's
// current auth info for successful processing.
epp_TransferRequest transfer_request = new epp_TransferRequest();

// A transfer query will only query the status of the current
// pending transfer or the last completed/cancelled/rejected
// transfer.  To request a transfer, the "op" should be set to
// REQUEST.
//
// QUERY is the default transfer op type, so it 
// could have been left null here.
transfer_request.setOp( epp_TransferOpType.QUERY );
transfer_request.setAuthInfo( contact_auth_info );
contact_transfer_request.setTrans( transfer_request );

contact_transfer_request.setId( "contact4" );

EPPContactTransfer contact_transfer = new EPPContactTransfer();
contact_transfer.setRequestData(contact_transfer_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
contact_transfer = (EPPContactTransfer) epp_client.processAction(contact_transfer);

// or, alternatively, this method can be used...
//contact_transfer.fromXML(epp_client.processXML(contact_transfer.toXML()));

epp_ContactTransferRsp contact_transfer_response = contact_transfer.getResponseData();
epp_Response response = contact_transfer_response.getRsp();

String transfer_status = EPPXMLBase.transferStatusToString(contact_transfer_response.getTransferStatus());
Input
epp_ContactTransferReq
cmd
Generic EPP request data member.
trans
Generic EPP transfer request data member. Instance of epp_TransferRequest.
id
The contact's ID.
XML Converter Class
EPPContactTransfer
Output
epp_ContactTransferRsp
rsp
Generic EPP response data member.
id
The contact's ID.
transfer-status
The state of the contact's most recent transfer request. Instance of epp_TransferStatusType.
request-client-id
The client id of the registrar requesting (or "which had requested") the contact transfer.
request-date
The date and time the transfer was requested.
action-client-id
The client id that should act upon the transfer request.
action-date
The date and time that a pending transfer will be automatically completed by the registry. For a completed, cancelled or rejected transfer, this is the date the transfer was completed.
6.3 EPP Domain
A domain represents a namespace in the Internet which is used to group computers together. Domains can have contacts and nameservers associated with them. A domain object has fields that may be viewed or modified by the registrar, on behalf of the registrant. EPP allows the following commands to be performed: check, info, create, update delete, transfer and renew.
Client-Managed Status Values
A domain name always has at least one associated status value. The EPP specification allows the client to manage only three domain statuses. The registrar can only add or remove the client-manageable statuses.

Client Hold: The domain must not be published in a zone for DNS resolution.
Client Lock: The domain must not be modified through any action of epp_DomainCreate, or epp_DomainUpdate.
Client Transfer Prohibited: The domain must not be transferred by another registrar.
Along with each status, there can be a reason specified (one per status).

6.3.1Common Domain Data Members
epp_DomainPeriodUnitType

YEAR
MONTH
Note that some registries might not permit periods specified in months.
epp_DomainPeriod
unit
Contains the value of the registration period in years or months. Instance of epp_DomainPeriodUnitType.
value
The numeric period as a java short primitive. The setValue() accessor method has an overloaded version which accept the int type.
epp_DomainContactType

ADMIN
BILLING
TECH
epp_DomainContact
type
Contains the type of domain contact. Instance of epp_DomainContactType.
id
The contact's ID.
epp_DomainStatusType

CLIENT_DELETE_PROHIBITED
CLIENT_HOLD
CLIENT_RENEW_PROHIBITED
CLIENT_TRANSFER_PROHIBITED
CLIENT_UPDATE_PROHIBITED
INACTIVE
OK
PENDING_DELETE
PENDING_TRANSFER
PENDING_VERIFICATION
SERVER_DELETE_PROHIBITED
SERVER_HOLD
SERVER_RENEW_PROHIBITED
SERVER_TRANSFER_PROHIBITED
SERVER_UPDATE_PROHIBITED
epp_DomainStatus
type
Contains the domain's status type. Instance of epp_DomainStatusType. Can be converted to and from a String via EPPDomainBase.domainStatusToString() and EPPDomainBase.domainStringToStatus().
lang
Optional. This is the language of the response message.
value
Optional. If present, this is the reason text for the presence of the status on the domain object.
6.3.2 EPPDomainCheck
Description
This action is used to determine if a list of domain names are known to the server. The check results are in an array of epp_CheckResult. The order of the check results is not guaranteed to be in the same order as the requested domain names. Please see the section on epp_CheckResult for more information.
Usage syntax
epp_DomainCheckReq domain_check_request = new epp_DomainCheckReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
domain_check_request.setCmd( command_data );

// The Domain Check request can accept an array of domain
// names.  In this example, an ArrayList is used to dynamically
// create the List of domain names and then EPPXMLBase's
// utility method convertListToStringArray() is used
// to convert the List to a String array.
List domain_list = (List)new ArrayList();
domain_list.add("domain1.info");
domain_list.add("domain2.info");
domain_check_request.setNames( EPPXMLBase.convertListToStringArray(domain_list) );

EPPDomainCheck domain_check = new EPPDomainCheck();
domain_check.setRequestData(domain_check_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
domain_check = (EPPDomainCheck) epp_client.processAction(domain_check);

// or, alternatively, this method can be used...
//domain_check.fromXML(epp_client.processXML(domain_check.toXML()));

epp_DomainCheckRsp domain_check_response = domain_check.getResponseData();
epp_Response response = domain_check_response.getRsp();

epp_CheckResult[] check_results = domain_check_response.getResults();

Boolean exists = EPPXMLBase.getCheckResultFor(check_results,
                                              "domain.info");
Input
epp_DomainCheckReq
cmd
Generic EPP request data member.
names
The array of fully qualified domain names.
XML Converter Class
EPPDomainCheck
Output
epp_DomainCheckRsp
rsp
Generic EPP response data member.
results
The array of generic check results (epp_CheckResult).
6.3.3 EPPDomainInfo
Description
This action is used to retrieve detailed information associated with a domain. The response to this command returns information regarding the current state of a domain in the registry.
The response will include authorization information if the issuing registrar is the current owner of the domain object in the registry.
Note that an epp_Exception will be thrown by EPPDomainInfo's fromXML() method or by EPPClient's processAction() method if the info'd domain is not found in the registry.
Usage syntax
epp_DomainInfoReq domain_info_request = new epp_DomainInfoReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
domain_info_request.setCmd( command_data );

// The only domain-specific parameter is the domain name itself.
domain_info_request.setName( "domain.info" );

EPPDomainInfo domain_info = new EPPDomainInfo();
domain_info.setRequestData(domain_info_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
domain_info = (EPPDomainInfo) epp_client.processAction(domain_info);

// or, alternatively, this method can be used...
//domain_info.fromXML(epp_client.processXML(domain_info.toXML()));

epp_DomainInfoRsp domain_info_response = domain_info.getResponseData();
epp_Response response = domain_info_response.getRsp();

// You can also save the auth info from an info where
// the calling registrar is the sponsoring client for the
// object.
epp_AuthInfo domain_auth_info = domain_info_response.getAuthInfo();

// The Info command returns some standard information like
// the current sponsoring client id, the creator client id,
// the create time and the last update time.
// For a Domain Info, the domain's nameservers, hosts,
// last transfer client id, last transfer date, and
// expiration date are returned.
String client_id = domain_info_response.getClientId();
String created_by = domain_info_response.getCreatedBy();
String create_data_string = domain_info_response.getCreatedDate();

// Save the expiration date for the renew command later.
Date domain_exp_date = 
		RTKBase.UTC_FMT.parse(domain_info_response.getExpirationDate());
Input
epp_DomainInfoReq
cmd
Generic EPP request data member.
name
The fully qualified domain name.
XML Converter Class
EPPDomainInfo
Output
epp_DomainInfoRsp
rsp
Generic EPP response data member.
name
The fully qualified domain name.
roid
The domain object's ROID.
registrant
Optional, depending on the registry. The registrant's contact ID that is associated with the domain.
contacts
Optional, depending on the registry. Any number of contact IDs that are associated with the domain. Array of epp_DomainContact.
name-servers
Optional, depending on the registry. Array of the fully qualified host names that are associated with the domain.
hosts
Optional. Array of the fully qualified host names that exist under the domain's hierarchy.
status
Array of epp_DomainStatus objects.
client-id
The domain's current sponsoring client id.
created-by
The client id of the of the domain creator.
created-date
The date and time the domain was created. In UTC format.
updated-by
Optional. The client id of the last domain updater. Is null if the domain has never been modified.
updated-date
Optional. The date and time the domain was last updated. Is null if the domain has never been modified.
transfer-date
Optional. The date and time the domain was transferred. Is null if the domain has never been transferred.
auth-info
Optional. The authorization information of the domain object. Instance of epp_AuthInfo. It will be null if the querying registrar is not the sponsoring registrar.
6.3.4 EPPDomainCreate
Description
This action allows a registrar to create a domain object.
When creating a domain, the information required is the domain name itself and the authorization information. By the definitions in [EPP-D], no nameservers or contacts are required. Note that some registries might require contact information or a minimum number of hosts at creation time.
The period is optional. If omitted, the server will assign a default value. This value is registry-specific. A period maximum is also registry specific. Note that some registries might not allow registration periods in months.
Contacts and hosts listed in a domain create must previously exist in the registry. EPP provides four valid types of contacts for a domain. There is a special field for the domain's registrant's ROID. Three other domain contacts may be identified: administrative, billing and technical.
Usage syntax
epp_DomainCreateReq domain_create_request = new epp_DomainCreateReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid;
domain_create_request.setCmd( command_data );

domain_create_request.setName( "domain.info" );

// The domain's period is optional.  It is specified with
// an object that contains the unit of measurement (years or 
// months) and the actual period value.
epp_DomainPeriod period = new epp_DomainPeriod();
period.setUnit( epp_DomainPeriodUnitType.YEAR );
period.setValue( 2 );
domain_create_request.setPeriod( period );

// From an EPP perspective, nameserver associations are
// optional for a domain, so we're not specifying them
// here.  We will add them later in the domain update.

EPPDomainCreate domain_create = new EPPDomainCreate();
domain_create.setRequestData(domain_create_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
domain_create = (EPPDomainCreate) epp_client.processAction(domain_create);

// or, alternatively, this method can be used...
//domain_create.fromXML(epp_client.processXML(domain_create.toXML()));

epp_DomainCreateRsp domain_create_response = domain_create.getResponseData();
epp_Response response = domain_create_response.getRsp();

epp_Result[] results = response.getResults();

// The domain's ROID and expiration date are returned on a
// successful domain creation.
String domain_roid = domain_create_response.getRoid();

// Save the expiration date for a renew command later
Date domain_exp_date = RTKBase.UTC_FMT.parse(domain_create_response.getExpirationDate());
Input
epp_DomainCreateReq
cmd
Generic EPP request data member.
name
The fully qualified domain name.
period
The initial registration period of the domain. Instance of epp_DomainPeriod. Optional, default value is registry-specific.
registrant
The registrant's contact ID that is associated with the domain. Optional by [EPP-D], but may be required by some registries.
contacts
Any number of contact IDs to associate with the domain. Array of epp_DomainContact. Optional by [EPP-D], but may be required by some registries.
name-servers
Array of the fully qualified host names to associate with the domain. Optional by [EPP-D], but may be required by some registries.
auth-info
The authorization information specified by the registrant. Instance of epp_AuthInfo.
XML Converter Class
EPPDomainCreate
Output
epp_DomainCreateRsp
rsp
Generic EPP response data member.
name
The fully qualified domain name.
expiration-date
The domain's initial expiration date. In UTC format.
6.3.5 EPPDomainUpdate
Description
This action allows a registrar to modify the fields of a domain object.
EPPDomainUpdate data validations apply the same rules as EPPDomainCreate. Please see EPPDomainCreate for more details.
The update command must contain at least one of two lists:

Items to add or remove: Contains domain child elements that can be added or removed. These elements may include the domain's name servers, contacts and statuses.
Items to change: Contains domain child elements that can be changed. These elements include the domain's: registrant and authorization information.
The registry imposes restrictions on the addition and removal of statuses. Refer to the top of the domain section in this document or the [EPP-D] specification for more details.
Usage syntax
epp_DomainUpdateReq domain_update_request = new epp_DomainUpdateReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid;
domain_update_request.setCmd( command_data );

domain_update_request.setName( "domain.info" );

epp_DomainUpdateAddRemove add = new epp_DomainUpdateAddRemove();

// Here is a list of nameservers to add to the domain.
// An array is expected here, but to avoid using Java native
// arrays, we're using an ArrayList and then converting it to a 
// String array.
List name_server_list = (List)new ArrayList();
name_server_list.add("new-ns1.domain.info");
name_server_list.add("new-ns2.domain.info");
add.setNameServers( EPPXMLBase.convertListToStringArray(name_server_list) );

// We also want to add the CLIENT-HOLD status to the domain.
// This time we'll create an array of epp_DomainStatus 
// directly.  EPP allows for registrar notes in the 
// status field.  EPP even allows for a language specifier.
epp_DomainStatus status = new epp_DomainStatus[1];
status[0] = new epp_DomainStatus();
status[0].setType( epp_DomainStatusType.CLIENT_HOLD );
status[0].setLang( "fr" );
status[0].setValue( "Le client n'as pas envoyé de l'argent" );

add.setStatus( status );

// Set the add information.
domain_update_request.setAdd( add );

epp_DomainUpdateAddRemove remove = new epp_DomainUpdateAddRemove();

// Now to remove 1 nameserver.
name_server_list = (List)new ArrayList();
name_server_list.add("old-ns1.domain.info");
remove.setNameServers( EPPXMLBase.convertListToStringArray(name_server_list) );

// Set the remove information.
domain_update_request.setRemove( remove );

// We're also specifying the information to change.
// Only the registrant information can be changed.
epp_DomainUpdateChange change = new epp_DomainUpdateChange();
change.setRegistrant( "contact1" );
domain_update_request.setChange( new epp_DomainUpdateChange() );

EPPDomainUpdate domain_update = new EPPDomainUpdate();
domain_update.setRequestData(domain_update_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
domain_update = (EPPDomainUpdate) epp_client.processAction(domain_update);

// or, alternatively, this method can be used...
//domain_update.fromXML(epp_client.processXML(domain_update.toXML()));

epp_DomainUpdateRsp domain_update_response = domain_update.getResponseData();
epp_Response response = domain_update_response.getRsp();
Input
epp_DomainUpdateReq
cmd
Generic EPP request data member.
name
The fully qualified name of the domain to update.
add
Optional. Items to add to the domain. Instance of epp_DomainUpdateAddRemove.
status
Optional. Registrar-usable statuses. Array of epp_DomainStatus objects.
name-servers
Optional. Array of name servers to add to this domain.
contacts
Optional. Array of epp_DomainContact objects to add to the domain.
remove
Optional. Items to remove from the domain. Instance of epp_DomainUpdateAddRemove.
status
Optional. Registrar-usable statuses. Array of epp_DomainStatus objects.
name-servers
Optional. Array of name servers to remove from this domain.
contacts
Optional. Array of epp_DomainContact objects to remove from the domain.
change
Optional. Domain data to change. Instance of epp_DomainUpdateChange.
auth-info
Optional. The authorization information specified by the registrant. Instance of epp_AuthInfo.
XML Converter Class
EPPDomainUpdate
Output
epp_DomainUpdateRsp
rsp
Generic EPP response data member.
6.3.6 EPPDomainDelete
Description
This action allows a registrar to delete a domain object.
A domain cannot be deleted if one of its child servers is associated with any domains in the registry. Child hosts will be deleted with the domain because of their subordinate relationship.
Usage syntax
epp_DomainDeleteReq domain_delete_request = new epp_DomainDeleteReq();

command_data = new epp_Command();
// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
domain_delete_request.setCmd( command_data );

domain_delete_request.setName( "domain.info" );

EPPDomainDelete domain_delete = new EPPDomainDelete();
domain_delete.setRequestData(domain_delete_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
domain_delete = (EPPDomainDelete) epp_client.processAction(domain_delete);

// or, alternatively, this method can be used...
//domain_delete.fromXML(epp_client.processXML(domain_delete.toXML()));
Input
epp_DomainDeleteReq
cmd
Generic EPP request data member.
name
The fully qualified name of the domain to delete.
XML Converter Class
EPPDomainDelete
Output
epp_DomainDeleteRsp
rsp
Generic EPP response data member.
6.3.7 EPPDomainTransfer
Description
This action allows a registrar to transfer the sponsorship of a domain object. When a domain is transferred, all Host objects for which this domain is the parent domain will also be transferred to the gaining registrar.
Five transfer operations are permitted: approve, cancel, query, reject and request. If none is specified, the RTK will default to query.
Six transfer statuses exist: pending, approved, cancelled, rejected, auto-approved, auto-cancelled.
A transfer query allows the registrar to query the state of a current pending transfer or of the last approved, cancelled or rejected transfer. A transfer query on an object that has never been transffered yet will cause an exception to be thrown by EPPClient's processAction() or EPPDomainTranfer's fromXML() because of the error code being returned by the registry.
A transfer request initiates a transfer process in the registry. The server will notify the losing registrar of the pending transfer (through the EPP Poll mechanism). The losing registrar then has the opportunity to explicitly approve or reject the transfer. The requesting registrar also has the option of canceling the transfer before it is completed. If the losing registrar fails to act on the transfer notification, the registry will automatically approve or reject the transfer within certain period of days. Check with the registry with which you will be dealing to find out the default behaviour.
Domain transfers automatically include a 1 year renewal in the operation (some registries might impement a different renewal period). A period may be specified in the transfer request to override the default value. Note that some registries might not allow renewal in months.
Some registries might also disallow transfers on new domain. A domain may be considered new for anytime from a week to a few months within its creation date. Check with each registry for the particular implementation.
Usage syntax
epp_DomainTransferReq domain_transfer_request = new epp_DomainTransferReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
domain_transfer_request.setCmd( command_data );

// The Domain Transfer request is an EPP "transfer" request,
// meaning it requires an "op" value and the object's
// current auth info for successful processing.
epp_TransferRequest transfer_request = new epp_TransferRequest();

// A transfer query will only query the status of the current
// pending transfer or the last completed/cancelled/rejected
// transfer.  To request a transfer, the "op" should be set to
// REQUEST.
//
// QUERY is the default transfer op type, so it 
// could have been left null here.
transfer_request.setOp( epp_TransferOpType.QUERY );
// 
transfer_request.setAuthInfo( domain_auth_info );
domain_transfer_request.setTrans( transfer_request );

domain_transfer_request.setName( "domain.info" );

// On a transfer request, EPP allows for a domain renewal
// to be bundled into a domain transfer.
// If the period is not specified, 1 year is the default.
//
// So if this was a transfer request, we could do this.
/*
epp_DomainPeriod period = new epp_DomainPeriod();
period.setUnit( epp_DomainPeriodUnitType.YEAR );
period.setValue( (short) 2 );
domain_transfer_request.setPeriod( period );
*/

EPPDomainTransfer domain_transfer = new EPPDomainTransfer();
domain_transfer.setRequestData(domain_transfer_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
domain_transfer = (EPPDomainTransfer) epp_client.processAction(domain_transfer);

// or, alternatively, this method can be used...
//domain_transfer.fromXML(epp_client.processXML(domain_transfer.toXML()));

epp_DomainTransferRsp domain_transfer_response = domain_transfer.getResponseData();
epp_Response response = domain_transfer_response.getRsp();

String transfer_status = EPPXMLBase.transferStatusToString(domain_transfer_response.getTransferStatus());
Input
epp_DomainTransferReq
cmd
Generic EPP request data member.
trans
Generic EPP transfer request data member. Instance of epp_TransferRequest.
name
The fully qualified name of the domain.
period
Optional, default value is registry-specific. The renewal period to apply to domain if the transfer succeeds.
XML Converter Class
EPPDomainTransfer
Output
epp_DomainTransferRsp
rsp
Generic EPP response data member.
name
The fully qualified name of the domain.
transfer-status
The state of the domain's most recent transfer request. Instance of epp_TransferStatusType.
request-client-id
The client id of the registrar requesting (or "which had requested") the domain transfer.
request-date
The date and time the transfer was requested.
action-client-id
The client id that should act upon the transfer request.
action-date
The date and time that a pending transfer will be automatically completed by the registry. For a completed, cancelled or rejected transfer, this is the date the transfer was completed.
expiration-date
The domain's new expiration date once the current pending transfer is successful. This field is meaningless if the transfer has completed. In that case, please use the expiration date from the Domain Info command.
6.3.8 EPPDomainRenew
Description
This action allows a registrar to extend the validity period of a domain object. A registrar can only renew domains for which they are the sponsoring registrar. The domain's current expiration date is required for this command. A renewal period can be optionally specified at the time of renewal. If the period is omitted, the server will apply a default, which will often be 1 year. Please check with your registry to determine the default.
If the registry has a maximum registration period for a domain, only a limited number of renewals can be applied.
Usage syntax
epp_DomainRenewReq domain_renew_request = new epp_DomainRenewReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.setClientTrid( client_trid );
domain_renew_request.setCmd( command_data );

domain_renew_request.setName( "domain.info" );

// As in the domain create operation, the domain period
// may be specified here also.
epp_DomainPeriod period = new epp_DomainPeriod();
period.setUnit( epp_DomainPeriodUnitType.YEAR );
period.setValue( (short) 2 );
domain_renew_request.setPeriod( period );

// The domain's current expiration must also be specified
// to avoid unintentional multiple renew request from succeeding.
// The format of the expiration date must be "yyyy-MM-dd"
// Here, domain_exp_date is an instance of java.util.Date.
domain_renew_request.setCurrentExpriationDate( RTKBase.DATE_FMT.format(domain_exp_date) );

EPPDomainRenew domain_renew = new EPPDomainRenew();
domain_renew.setRequestData(domain_renew_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
domain_renew = (EPPDomainRenew) epp_client.processAction(domain_renew);

// or, alternatively, this method can be used...
//domain_renew.fromXML(epp_client.processXML(domain_renew.toXML()));

epp_DomainRenewRsp domain_renew_response = domain_renew.getResponseData();
epp_Response response = domain_renew_response.getRsp();
Input
epp_DomainRenewReq
cmd
Generic EPP request data member.
name
The fully qualified name of the domain.
current-expiration-date
The domain's current expiration date, in the format "yyyy-MM-dd". The object RTKBase.DATE_FMT is available to format date objects.
period
Optional, default value is registry-specific. The renewal period to apply to domain.
XML Converter Class
EPPDomainRenew
Output
epp_DomainRenewRsp
rsp
Generic EPP response data member.
name
The fully qualified name of the domain.
roid
The domain object's ROID.
expiration-date
The domain's new expiration date. In UTC format.
6.4 EPP Host
A host is machine on a network. Their primary usage in EPP is to be assigned as nameservers to domains. A host object has fields that may be viewed or modified by the registrar, on behalf of the registrant. EPP allows the following commands to be performed: check, info, create, update and delete. Note: The syntax examples for the Host actions show the population of the IDL data members directly, instead of using the traditional OO accessor methods. Both are valid in the Java RTK.
6.4.1 Common Host Data Members
epp_HostAddressType

IPV4
IPV6
Note that some registries might not permit the use of IPV6 address formats.
epp_HostAddress
type
The address' type. It is an instance of epp_HostAddressType.
ip
The host's actual IP address in IPV4 or IPV6 formats.
epp_HostStatusType

CLIENT_DELETE_PROHIBITED
CLIENT_UPDATE_PROHIBITED
LINKED
OK
PENDING_DELETE
PENDING_TRANSFER
SERVER_DELETE_PROHIBITED
SERVER_UPDATE_PROHIBITED
epp_HostStatus
type
Contains the host's status type. It is an instance of epp_HostStatusType. Can be converted to and from a String via EPPHostBase.hostStatusToString(j) and EPPHostBase.hostStringToStatus().
lang
This is the language of the response message.
value
Optional. If present, this is the reason text for the presence of the status on the domain object.
6.4.2 EPPHostCheck
Description
This action is used to determine if a host name is known to the server. The check results are in an array of EPP_CheckResult. The order of the check results is not guaranteed to be in the same order as the requested host names. Please see the section on epp_CheckResult for more information.
Usage syntax
epp_HostCheckReq host_check_request = new epp_HostCheckReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.m_client_trid = client_trid;
host_check_request.m_cmd = command_data;

// The Host Check request can accept an array of host
// names.  In this example, an ArrayList is used to dynamically
// create the List of host names and then EPPXMLBase's
// utility method convertListToStringArray() is used
// to convert the List to a String array.
List host_list = (List)new ArrayList();
host_list.add("ns1.domain.info");
host_list.add("ns2.domain.info");
host_check_request.m_names = EPPXMLBase.convertListToStringArray(host_list);

EPPHostCheck host_check = new EPPHostCheck();
host_check.setRequestData(host_check_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
host_check = (EPPHostCheck) epp_client.processAction(host_check);

// or, alternatively, this method can be used...
//host_check.fromXML(epp_client.processXML(host_check.toXML()));

epp_HostCheckRsp host_check_response = host_check.getResponseData();
epp_Response response = host_check_response.m_rsp;
epp_Result[] results = response.m_results;

epp_CheckResult[] check_results = host_check_response.m_results;

Boolean exists = EPPXMLBase.getCheckResultFor(check_results,
                                              "ns2.domain.info");
Input
epp_HostCheckReq
cmd
Generic EPP request data member.
names
The array of fully qualified host names.
XML Converter Class
EPPHostCheck
Output
epp_HostCheckRsp
rsp
Generic EPP response data member.
results
The array of generic check results (epp_CheckResult).
6.4.3 EPPHostInfo
Description
This action is used to retrieve detailed information associated with a host. The response to this command returns information regarding the current state of a host in the registry.
IPs for a host can be in either IPV4 or IPV6 formats. Note that some registries might not allow IPV6 address formats.
Usage syntax
epp_HostInfoReq host_info_request = new epp_HostInfoReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.m_client_trid = client_trid;
host_info_request.m_cmd = command_data;

host_info_request.m_name = "ns1.domain.info";

EPPHostInfo host_info = new EPPHostInfo();
host_info.setRequestData(host_info_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
host_info = (EPPHostInfo) epp_client.processAction(host_info);

// or, alternatively, this method can be used...
//host_info.fromXML(epp_client.processXML(host_info.toXML()));

epp_HostInfoRsp host_info_response = host_info.getResponseData();
epp_Response response = host_info_response.m_rsp;

epp_Result[] results = response.m_results;

epp_HostAddress[] addresses = host_info_response.m_addresses;
Input
epp_HostInfoReq
cmd
Generic EPP request data member.
name
The fully qualified host name.
XML Converter Class
EPPHostInfo
Output
epp_HostInfoRsp
rsp
Generic EPP response data member.
name
The fully qualified host name.
roid
The host object's ROID.
linked
Set to true if the host has been assigned as a nameserver to a domain. False otherwise.
addresses
Optional. Array of the host's addresses. Instances of epp_HostAddress.
status
Array of epp_HostStatus objects.
client-id
The host's current sponsoring client id.
created-by
The client id of the of the host creator.
created-date
The date and time the host was created. In UTC format.
updated-by
Optional. The client id of the last host updater. Is null if the host has never been modified.
updated-date
Optional. The date and time the host was last updated. Is null if the host has never been modified.
6.4.4 EPPHostCreate
Description
This action allows a registrar to create a host object.
When creating a domain, a list of IP address may be specified. The formats of the IPs must be either IPV4 or IPV6. Note that some registries may not allow the use of IPV6 addresses. EPP imposes restrictions on cases where an IP is required or not allowed. EPP also imposes rules regarding the requirement of a host's parent domain. Refer to [EPP-H] specification for more details.
Usage syntax
epp_HostCreateReq host_create_request = new epp_HostCreateReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.m_client_trid = client_trid;
host_create_request.m_cmd = command_data;

host_create_request.m_name = "ns1.domain.info";

// When creating a host in a TLD for which the registry is authoritative,
// at least one IP address is required.  An array is expected here,
// but to avoid using Java native arrays, we're using an ArrayList
// and then converting it to an epp_HostAddress array using the EPPXMLBase.
List ip_list = (List)new ArrayList();
ip_list.add(new epp_HostAddress(epp_HostAddressType.IPV4, "100.103.44.151"));
ip_list.add(new epp_HostAddress(epp_HostAddressType.IPV6,
					"1080:0:0:0:8:800:200C:417A"));
host_create_request.m_addresses = 
(epp_HostAddress[])EPPXMLBase.convertListToArray(
         (new epp_HostAddress()).getClass(), ip_list);

EPPHostCreate host_create = new EPPHostCreate();
host_create.setRequestData(host_create_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
host_create = (EPPHostCreate)  epp_client.processAction(host_create);

// or, alternatively, this method can be used...
//host_create.fromXML(epp_client.processXML(host_create.toXML()));

epp_HostCreateRsp host_create_response =host_create.getResponseData();
epp_Response response = host_create_response.m_rsp;
Input
epp_HostCreateReq
cmd
Generic EPP request data member.
name
The fully qualified host name.
addresses
Optional. Array of IP addresses. Instances of epp_HostAddress.
XML Converter Class
EPPHostCreate
Output
epp_HostCreateRsp
rsp
Generic EPP response data member.
name
The fully qualified host name.
roid
The host object's ROID.
6.4.5 EPPHostUpdate
Description
This action allows a registrar to modify the fields of a host object.
EPPHostUpdate data validations apply the same rules as EPPHostCreate. Please see EPPHostCreate for more details.
The update command must contain at least one of two lists:

Items to add or remove: Contains host child elements that can be added or removed. These elements may include the host's addresses and statuses.

Items to change: Contains the host child element that can be changed. EPP currently limits this element to the host's name.
When updating a host, a new host name may be optionally specified. Changing the host name can allow the registrar to move a host from one domain to another. For example, going from "host-a.domain-a.info" to "host-a.domain-b.info". EPP imposes restrictions on changing the host name. Refer to [EPP-H] specification for more details.
Usage syntax
epp_HostUpdateReq host_update_request = new epp_HostUpdateReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.m_client_trid = client_trid;
host_update_request.m_cmd = command_data;

host_update_request.m_name = "ns1.domain.info";

epp_HostUpdateAddRemove add = new epp_HostUpdateAddRemove();

// Here is a list of addresses to add to the host.
// An array is expected, here, like in the host create,
// we're using an ArrayList and then converting to a 
// String array.
List ip_list = (List)new ArrayList();
ip_list.add(new epp_HostAddress(epp_HostAddressType.IPV4, "101.22.55.99"));
add.m_addresses = (epp_HostAddress[])EPPXMLBase.convertListToArray(
	(new epp_HostAddress()).getClass(), ip_list);

// Set the add information.
host_update_request.m_add = add;

epp_HostUpdateAddRemove remove = new epp_HostUpdateAddRemove();

// Now to remove 1 address.
ip_list = (List)new ArrayList();
ip_list.add(new epp_HostAddress
(epp_HostAddressType.IPV6, "1080:0:0:0:8:800:200C:417A"));
remove.m_addresses = (epp_HostAddress[])EPPXMLBase.convertListToArray
                      ((new epp_HostAddress()).getClass(), ip_list);

// Set the remove information.
host_update_request.m_remove = remove;

// We're also specifying the information to change.
// Only the host's name can be changed.
host_update_request.m_change = new epp_HostUpdateChange();
host_update_request.m_change.m_name = "ns99.domain.info";

EPPHostUpdate host_update = new EPPHostUpdate();
host_update.setRequestData(host_update_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
host_update =     (EPPHostUpdate) epp_client.processAction(host_update);

// or, alternatively, this method can be used...
//host_update.fromXML(epp_client.processXML(host_update.toXML()));

epp_HostUpdateRsp host_update_response = host_update.getResponseData();
epp_Response response = host_update_response.m_rsp;
Input
epp_HostUpdateReq
cmd
Generic EPP request data member.
name
The fully qualified name of the host to update.
add
Optional. Items to add to the host. Instance of epp_HostUpdateAddRemove.
status
Optional. Registrar-usable statuses. Array of epp_HostStatus objects.
addresses
Optional. Array of IP addresses to add to the host. Instances of epp_HostAddress.
remove
Optional. Items to remove from the host. Instance of epp_HostUpdateAddRemove.
status
Optional. Registrar-usable statuses. Array of epp_HostStatus objects.
addresses
Optional. Array of IP addresses to remove from the host. Instances of epp_HostAddress.
change
Optional. Host data to change. Instance of epp_HostUpdateChange.
name
Optional. The host's new fully qualified host name.
XML Converter Class
EPPHostUpdate
Output
epp_HostUpdateRsp
rsp
Generic EPP response data member.
6.4.6 EPPHostDelete
Description
This action allows a registrar to delete a host object.
A host cannot not be deleted if it is assigned to serve any domains in the registry.
Usage syntax
epp_HostDeleteReq host_delete_request = new epp_HostDeleteReq();

command_data = new epp_Command();

// The client trid is optional.  It's main use
// is for registrar tracking and logging of requests,
// especially for data creation or modification requests.
command_data.m_client_trid = client_trid;
host_delete_request.m_cmd = command_data;

host_delete_request.m_name = "ns1.domain.info";

EPPHostDelete host_delete = new EPPHostDelete();
host_delete.setRequestData(host_delete_request);

// Now ask the EPPClient to process the request and retrieve 
// a response from the server.
host_delete = (EPPHostDelete) epp_client.processAction(host_delete);

// or, alternatively, this method can be used...
//host_delete.fromXML(epp_client.processXML(host_delete.toXML()));
Input
epp_HostDeleteReq
cmd
Generic EPP request data member.
name
The fully qualified name of the host to delete.
XML Converter Class
EPPHostDelete
Output
epp_HostDeleteRsp
rsp
Generic EPP response data member.

Appendix A: References

3rd-party Packages Used in the RTK
* Ant 1.3: http://jakarta.apache.org/ant
Java SSL Packages: http://java.sun.com/products/jsse
* Xerses-J 1.3.0: http://xml.apache.org/xerces-j
(*) Minimum jars required are already included in the RTK in epp-rtk/java/lib.
EPP Java API Examples provided in the RTK
All sample code is kept in the following directory of the EPP RTK distribution: epp-rtk/java/src/com/tucows/oxrs/epp/rtk/example
The sample code should be runnable against a working registry, although currently, some of the sample have hardcoded values (like contact ID's and domain names) that will make the sample fail if the objects already exist in the database. Samples include: DomainExample, ContactExample, HostExample, and SessionExample.
The SessionExample is interactive and will ask the users for contact IDs, auth info, and a domain name. This allows the sample to be run multiple times. It even allows you to try a real transfer of a domain.
The samples are best run by the run_example.bat|sh scripts. The syntax to run the scripts is (à la UNIX):
./run_example.sh {example class name} epp_host epp_port client_id password [domain registrant_contact tech_contact]
The domain is required only for the SessionExample. The registrant_contact, and tech_contact are optional for the SessionExample and if provided, will be used as the contact IDs for the domain.
Source Code provided in the RTK
IDL Source Code, directory: epp-rtk/idl
Ant Build Files, directory: epp-rtk/java/etc
EPP RTK Java, Xerces and Ant Jar Files, directory: epp-rtk/java/lib
Java Compiled IDLs (Top level Packages), directory: epp-rtk/java/src/org/openrtk/idl/epp
Documentation provided in the RTK
EPP Internet-Drafts versions 04/02, directory: epp-rtk/epp
Javadocs, directory: epp-rtk/java/doc/api-doc
EPP Java API Documentation, directory: epp-rtk/java/doc
README, directory: epp-rtk/java

Appendix B: Documentation License

OpenContent License (OPL)
Version 1.0, July 14, 1998.
This document outlines the principles underlying the OpenContent (OC) movement and may be redistributed provided it remains unaltered. For legal purposes, this document is the license under which OpenContent is made available for use.
The original version of this document may be found at http://opencontent.org/opl.shtml
LICENSE
Terms and Conditions for Copying, Distributing, and Modifying
Items other than copying, distributing, and modifying the Content with which this license was distributed (such as using, etc.) are outside the scope of this license.
1. You may copy and distribute exact replicas of the OpenContent (OC) as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the OC a copy of this License along with the OC. You may at your option charge a fee for the media and/or handling involved in creating a unique copy of the OC for use offline, you may at your option offer instructional support for the OC in exchange for a fee, or you may at your option offer warranty in exchange for a fee. You may not charge a fee for the OC itself. You may not charge a fee for the sole service of providing access to and/or use of the OC via a network (e.g. the Internet), whether it be via the world wide web, FTP, or any other method.
2. You may modify your copy or copies of the OpenContent or any portion of it, thus forming works based on the Content, and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
a) You must cause the modified content to carry prominent notices stating that you changed it, the exact nature and content of the changes, and the date of any change.
b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the OC or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License, unless otherwise permitted under applicable Fair Use law.
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the OC, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the OC, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Exceptions are made to this requirement to release modified works free of charge under this license only in compliance with Fair Use law where applicable.
3. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to copy, distribute or modify the OC. These actions are prohibited by law if you do not accept this License. Therefore, by distributing or translating the OC, or by deriving works herefrom, you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or translating the OC.
NO WARRANTY
4. BECAUSE THE OPENCONTENT (OC) IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE OC, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE OC "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK OF USE OF THE OC IS WITH YOU. SHOULD THE OC PROVE FAULTY, INACCURATE, OR OTHERWISE UNACCEPTABLE YOU ASSUME THE COST OF ALL NECESSARY REPAIR OR CORRECTION.
5. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MIRROR AND/OR REDISTRIBUTE THE OC AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE OC, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

EPP RTK for Java User Guide

Version 0.4.0

Oct 3, 2001

Created by: Tucows Inc.

Revision History

Contents

1. Introduction

2. EPP Overview

3. EPP Java RTK Requirements

3.1 Packages

3.2 Open Source Packages

3.3 Protocol Familiarity

4. EPP IDL Use in the Java RTK

4.1. Overview

4.2 General EPP IDL Data Members

4.2.1 Repository Object Identifiers (ROID)

4.2.2 epp_Command

4.2.3 epp_AuthInfo

4.2.4 epp_TransferRequest

4.2.5 epp_TransferStatusType

4.2.6 epp_Response

4.2.7 epp_Result

4.2.8 epp_CheckResult

4.2.9 epp_Greeting

4.2.10 epp_LoginReq

4.2.11 epp_LogoutReq

4.2.12 epp_PollReq

4.2.12 epp_PollResData

4.2.14 epp_Session

5 API Class Summary

6 API Classes

6.1 General EPP Classes

6.1.1 EPPClient

6.1.2 EPPGreeting

6.1.3 EPPLogin

6.1.4 EPPLogout

6.1.5 EPPPoll

6.1.6 RTKBase

6.1.7 EPPXMLBase

6.1.8 EPPTransport Classes

6.2 EPP Contact

6.2.1 Common Contact Data Members

6.2.2 EPPContactCheck

6.2.3 EPPContactInfo

6.2.4 EPPContactCreate

6.2.5 EPPContactUpdate

6.2.6 EPPContactDelete

6.2.7 EPPContactTransfer

6.3 EPP Domain

6.3.1Common Domain Data Members

6.3.2 EPPDomainCheck

6.3.3 EPPDomainInfo

6.3.4 EPPDomainCreate

6.3.5 EPPDomainUpdate

6.3.6 EPPDomainDelete

6.3.7 EPPDomainTransfer

6.3.8 EPPDomainRenew

6.4 EPP Host

6.4.1 Common Host Data Members

6.4.2 EPPHostCheck

6.4.3 EPPHostInfo

6.4.4 EPPHostCreate

6.4.5 EPPHostUpdate

6.4.6 EPPHostDelete

Appendix A: References

Appendix B: Documentation License

EPP RTK for Java
User Guide