EPP RTK for Java
User Guide

Version 0.7.2

May 5, 2003

Created by: LibertyRMS Inc.

Revision History

Contents

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 (ROIDs)
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_ResultData
4.2.9 epp_StatusResultData
4.2.10 epp_CheckResult
4.2.11 epp_Greeting
4.2.12 epp_ServiceMenu
4.2.13 epp_DataCollectionPolicy
4.2.14 epp_dcpStatement
4.2.15 epp_LoginReq
4.2.16 epp_LogoutReq
4.2.17 epp_PollReq
4.2.18 epp_PollRsp
4.2.19 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.1.9 EPPStatus

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

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 over a TCP socket.

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 request-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 eight basic services: hello/greeting, login, logout, poll, object commands, responses and an extension framework.

EPP provides seven object 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). Registries may define further objects to EPP (GNR's .name registry has email forwarding, for example). The description of these additional objects is out of the scope of this document. You should be able to find information about these extra objects from the registries that offer or require them.

EPP has been evolving at the IETF since 2001. Over time, multiple internet drafts have been released and implemented by various domain name registries through out the world. EPP drafts versions are usually paired up with EPP Object drafts. The numbered is normally off by 2 (ie. EPP core spec at 07 object drafts at 05). The SourceForge EPP RTK supports multiple versions of EPP: "pre" 02 (used by the .info registry), 04/02 (used by .biz), 05/03 (used by .name), 06/04 (used by some ccTLD operators) and 07/05 (used by .org). As the IETF releases updates to the Internet Draft documents, the RTK is normally updated to follow the changes.

The remainder of this document will deal with EPP version 07/05 and 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 07: draft-ietf-provreg-epp-07.txt

[EPP-C] Extensible Provisioning Protocol Contact Mapping

Version 05: draft-ietf-provreg-epp-contact-05.txt

[EPP-D] Extensible Provisioning Protocol Domain Name Mapping

Version 05: draft-ietf-provreg-epp-domain-05.txt

[EPP-H] Extensible Provisioning Protocol Host Mapping

Version 05: draft-ietf-provreg-epp-host-05.txt

[EPP-T] Extensible Provisioning Protocol Transport Over TCP

Version 05: draft-ietf-provreg-epp-tcp-05.txt

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.4.x: This is used to change code and compile it. Earlier versions of the SDK will not likely work because of the changes to the JSSE in 1.4. 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.4.x: This is used to run any type of java program.

• Java Secure Socket Extension (JSSE) 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. Sun's JSSE is included in the 1.4 release of the SDK from Sun. It can be obtained for previous releases of the JDK at http://java.sun.com/products/jsse. If a registrar wishes to use a non-JSSE package, the Java RTK classes provide the facilities to set an externally connected Socket. See the description of EPPClient and EPPTransport 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.

  Also, the play cert included in the RTK is contained in a keystore in pkcs12 format. The Sun JSSE/JCE implementation cannot read keystores in this format. The BouncyCastle (http://www.bouncycastle.org/) provider is used to read this keystore. Version 1.15 of the bouncycastle jar is included in the RTK for this purpose. Bouncycastle is not being used for SSL/TLS encryption with an EPP server.

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. The new Xerces2 is not supported.

• Ant 1.5.2: 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://ant.apache.org/.

• As mentioned earlier, the BouncyCastle JSSE/JCE encryption provider is included to read the pkcs12 keystore format. The jar file is included in the RTK. More information about BouncyCastle can be obtained at http://www.bouncycastle.org/

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.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 from EPP 07/05. 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.epp0705
org.openrtk.idl.epp0705.contact
org.openrtk.idl.epp0705.domain
org.openrtk.idl.epp0705.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.epp0705.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 (ROIDs)

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, Poll and Status 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.

• extension

  Optional. This is a placeholder for registry-specific extensions to EPP. It uses the epp_Extension 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.

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. Please check with your registry for more information.

• type

  This is the authorization information type. It is specified by constants in the epp_AuthInfoType class. The allowed values are epp_AuthInfoType.PW and epp_AuthInfoType.EXT. If left null, the defaulted of PW will be applied 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. This class provides a toString() to transform a type instance to a human-readable string.

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.

• message-queue

  Optional. This is 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.

• extension-strings

  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.

• values

  Optional epp_ResultValue instances array. This is an array of request XML elements which caused the client request to fail in the server.

• ext-values

  Optional epp_ExtResultValue instances array. Some registries might use this instead of the values array because it can additionally contain a free-text reason for the error.

4.2.8 XXX

This was the plase for epp_ResultData. Replace it with something else. XXX

4.2.9 XXX

This was the plase for epp_StatusResultData. Replace it with something else. XXX

4.2.10 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 identifier (ie. domain name, contact id, etc...) of the object being checked.

• avail

  Boolean indicator. It is "true" if the object is available for creation in the registry, or "false" if the registry will not permit its creation. In normal circumstances (i.e. the object's name syntax is correct, etc...), then the check result will only be false if the object being queried already exists in the registry.

• reason

  Optional reason text to describe why the object is not available.

• lang

  Optional. The language of the reason text.

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

• svc-menu

  Instance of epp_ServiceMenu. This identifies the objects that the server is capable of managing. It also identifies the various response text languages and protocol versions that the server supports.

• dcp

  Optional instance of epp_DataCollectionPolicy. Identifies the server's policies regarding the collection and management of data sent by the client to the server. A client may wish to inspect these settings to verify compatibility with their own policies.

4.2.12 epp_ServiceMenu

The service menu presents the languages and protocol versions supported by the EPP Server. It also lists the services and service extensions offered by the server. Services are EPP objects, namespaces and XML schema locations. Please see [EPP] for more information. An instance of this class appears in the epp_Greeting.

• versions

  This identifies the protocol versions supported by the server.

• langs

  This identifies the text response languages offered by the server.

• services

  Array of object URI strings. This is the list of object services that the server supports. There are three "standard" well-known EPP object URIs^*:

  • urn:ietf:params:xml:ns:contact-1.0
  • urn:ietf:params:xml:ns:domain-1.0
  • urn:ietf:params:xml:ns:host-1.0

  Inquire with your registry to find the proper values for other object URIs they support.

• extensions

  Array of extension URI strings^*. This is the list of extensions that the server supports.

^* These URIs translate into meaningful values for XML parsers, especially in finding schema definitions for syntax validation. The Java EPP RTK does not currently support server XML validation, so these values are currently not interpreted by the RTK.

4.2.13 epp_DataCollectionPolicy

Class that contains data members used to describe the server's policy for data collection and management. For more information on the meaning of these fields, you should contact your registry.

• access

  Instance of epp_dcpAccessType. Access level given to client to data located in the server. Value is one of the following:

  • social -- Access is given to social data only
  • technical -- Access is given to technical data only
  • all -- Access is given to technical and socila data
  • noaccess -- not data access is granted
  • null -- data is not persistent, so access is irrelevant

• statements

  Array of epp_dcpStatement instances. Describes data collection purposes, data recipients, and data retention.

4.2.14 epp_dcpStatement

This class describes data collection purposes, data recipients, and data retention. An array of instances of this class is contained in epp_DataCollectionPolicy. For more information on the meaning of these fields, you should contact your registry.

• purposes

  Array of epp_dcpPurposeType instances. Values at least one of the following:

  • purpose -- Contact for marketing purposes
  • dnReg -- Domain name registration
  • ipReg -- IP address registration
  • other -- Other purpose
  • tmReg -- Trademark registration

• recipients

  Array of epp_dcpRecipientType instances. Values at least one of the following:

  • other -- Other entities following unknow practices
  • ours -- Server operator and/or server operator's agents
  • public -- Public forums
  • same -- Other entities following server practices
  • unrelated -- Unrelated third parties

• retention

  Instance of epp_dcpRetentionType. Value is one of the following:

  • purpose -- Contact for marketing purposes
  • dnReg -- Domain name registration
  • ipReg -- IP address registration
  • other -- Other purpose
  • tmReg -- Trademark registration

4.2.15 epp_LoginReq

This is a session management member that establishes a session with the EPP server. This class is not used in connectionless sessions (i.e. over SMTP).

• cmd

  This is the generic request data member. It is an instance of epp_Command.

• client-id

  This is the EPP client ID to be used for the session.

• password

  This is the client's password.

• new-password

  This is the client's new password, to be used for sessions opened after this one.

• options

  These are the options to be used for this session. It is an instance of epp_Options.

• services

  An array of object URIs (Strings) which identify the objects which the client wishes to manage in this session. Please see epp_ServiceMenu for more information.

• extensions

  Optional. An array of extension URIs which identify the extensions which the client wishes to use in this session. The server might return an error if these extensions were not present in the greeting. Please see epp_ServiceMenu for more information.

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

• extension

  Optional. This is a placeholder for registry-specific extensions to EPP. It uses the epp_Extension interface.

4.2.17 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.18 epp_PollRsp

This class contains the response data to a poll request. The actual data is variable according to the type of poll notification received from the server. The res-data member is the epp_PollResData interface and supports a getType() method call. You can programmatically use the String return value of this method to call the right code to extract the needed from the class implementing epp_PollResData. The string values are listed below in the description of the res-data member.

• rsp

  This is the generic response data member. It is an instance of epp_Response.

• res-data

  Instance of epp_PollResData interface. The actual poll response data. Contains such data as object transfer notifications. In the main RTK package, the interface could be an instance of one of the following classes (in brackets is the value returned by getType()):

  • epp_DomainTrnData ("domain:trnData")
  • epp_ContactTrnData ("contact:trnData")
  • epp_DomainPanData ("domain:panData")
  • epp_ContactPanData ("contact:panData")
  • epp_HostPanData ("host:panData")

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

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
  • EPPStatus

• EPP Contact
  • EPPContactCheck
  • EPPContactInfo
  • EPPContactCreate
  • EPPContactUpdate
  • EPPContactDelete
  • EPPContactTransfer

• EPP Domain
  • EPPDomainCheck
  • EPPDomainInfo
  • EPPDomainCreate
  • EPPDomainUpdate
  • EPPDomainDelete
  • EPPDomainTranfer
  • EPPDomainRenew

• EPP Host
  • EPPHostCheck
  • EPPHostInfo
  • EPPHostCreate
  • EPPHostUpdate
  • EPPHostDelete

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

Full Name

com.tucows.oxrs.epp0705.rtk.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 run_example.sh both set up the rtk.props.file to run the examples. The default rtk.properties file contains all of the possible properties and descriptions of each.

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 the Java constant 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, 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 Sun 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 EPPClient.connect() methods should be called. In this case, the registrar should establish a connection with the package chosen. Then the registrar should use an instance of EPPTransportTCP and pass the established and connected Socket to EPPTransportTCP 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 property 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.

EPPTransportTCP the_transport = new EPPTransportTCP(the_socket, read_timeout);
epp_client.setTransport(the_transport);
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 with the given client transaction id. Note that it will send the RTK Version on login if the rtk.property "rtk.login.sendversion" has a value of true. Some registries, especially those performing strict XML validation, might return an error if they are not expecting the RTK version in the extension of the login request.

logout(String)

Issues a logout command to the EPP Server using the given client transaction id.

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 (which includes "object not found" errors from the <info> command).

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()

EPPClient if asked to perform the login might include the RTK version number in the "extension" 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.epp0705.rtk.xml.extension.RTKVersion for more information.

These accessor methods can be used to set this property, but it is also changeable in the rtk.properties file.

Please note that some registries will return an error response to a login that contains extension data when the registry is not expecting it.

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().

The greeting optionally contains data collection policy information. This data is summarized in the epp_DataCollectionPolicy and related classes. The [EPP] spec is purposefully lacking details regarding the meaning of the DCP values. Please contact your registry to more information on these settings if they are present in the greeting.

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. In previous versions of EPP, sessionless connections were permitted (i.e. commands with a login and logout), though not necessarily supported by all registries. As of 07/05, this is not longer permitted.

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 is contructed like the other EPP actions. This usage is detailed below. But the EPPClient contains the method poll() with 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_MessageQueue results = response.getMessageQueue();

// In a subsequent Poll ACK, this is the message ID that
// would be used.
String message_id = results[0].getId();

epp_PollResData poll_res_data = poll_response.getResData();
String res_type = poll_res_data.getType();

if ( res_type.equals("domain:trnData") )
{
    // In this case, the poll response data is for
    // a domain transfer notification, which comes in the
    // same form as a domain transfer query response,
    // let's cast it and get what we need out of it.
    epp_DomainTrnData domain_trn_data = (epp_DomainTrnData)poll_res_data;
    String domain_name = domain_trn_data.getName();
    
    // And other attributes specified in the epp_DomainTrnData class
}
else if ..... // Cast to something else

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

Note that the debug level can also be specified in the rtk.properties file. Through static code, the RTKBase class loads the debug level from the rtk.properties file. 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 getAvailResultFor(epp_CheckResult[], String)

This method takes an epp_CheckResult array and looks for the given String identifier in the array and returns the Boolean object result.

This method replaces the older, deprecated, getCheckResultFor() method. These two methods return the opposite boolean for the same parameters. This is because of the changes made to the epp_CheckResult with regards to the "exists" member being replaced by an "avail" member, which is the boolean opposite. In a future release of the RTK, getCheckResultFor() might be removed. Please switch to getAvailResultFor().

Usage Syntax

Boolean domain_is_available = EPPXMLBase.getAvailResultFor(check_results,
                                                           "domain.info");

Input

org.openrtk.idl.epp.epp_CheckResult[]

An array of check results from the EPP registry.

java.lang.String

The object identifier (domain name, host name, contact id, etc...) 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 into an English String that represents the given transfer status (eg. "pendingTransfer"). The list of transfers statuses is maintained in [EPP].

This method is deprecated because of the addition of the toString() method to the epp_TransferStatusType class.

Usage Syntax

epp_TransferStatusType transfer_status_type = domain_transfer_query_rsp.getTransferStatus();
// This is deprecated...
String transfer_status = EPPXMLBase.transferStatusToString(transfer_status_type);
// This is better...
transfer_status = transfer_status_type.toString();

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.

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]).

• type

  Instance of epp_ContactPostalInfoType. Marks the type of the address: local (with UTF-8) or international (with 7-bit ASCII).

• 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_CREATE, PENDING_DELETE, PENDING_TRANSFER and PENDING_UPDATE.

epp_ContactStatus

• type

  Contains the contact's status type. It is an instance of epp_ContactStatusType. Can be converted to a String via the toString() method and form a String via 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 available = EPPXMLBase.getAvailResultFor(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.

addresses

The contact's addresses. Instances of epp_ContactNameAddress. Only up to two addresses can be present, one local and one international.

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 internaltionalized address is required (i.e. epp_ContactPostalInfoType.INT). This address data is limited to 7-bit ASCII characters.
• A localized address is optional (epp_ContactPostalInfoType.LOC). 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[1];
name_address[0] = new epp_ContactNameAddress();
name_address[0].setType( epp_ContactPostalInfoType.INT );
name_address[0].setName( "John Doe" );
name_address[0].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[0].setAddress( address );

// Now assign that name/address set to the contact's
// address set.  If you wish to also use UTF-8
// characters in the name/address data, supply an additional
// epp_ContactNameAddress instance with the type set
// to epp_ContactPostalInfoType.LOC.
contact_create_request.setAddresses( 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.

addresses

The contact's addresses. Instances of epp_ContactNameAddress. Only up to two addresses can be present, one local and one international.

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.

creation-date

The contact's create date in the registry. In UTC format.

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();

// The contact transfer data is contained in an sub-member of the response.
epp_ContactTrnData contact_trn_data = contact_transfer_response.getTrnData();

String transfer_status = contact_trn_data.getTransferStatus().toString();

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.

trn-data

The contact's transfer data. Instance of epp_ContactTrnData. Data members are as follows:

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 Delete Prohibited: Delete commands issued to the domain should be rejected.
• Client Renew Prohibited: Renew commands issued to the domain should be rejected.
• Client Transfer Prohibited: The domain must not be transferred by another registrar.
• Client Update Prohibited: Update commands issued to the domain should be rejected.

Along with each status, there can be a free-text reason specified (one per status).

6.3.1 Common 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 accepts the int type (the "default" data type is short).

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_CREATE
• PENDING_DELETE
• PENDING_RENEW
• PENDING_TRANSFER
• PENDING_UPDATE
• 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 a String via the toString() method and from a String via 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 available = EPPXMLBase.getAvailResultFor(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.

creation-date

The domain's create date in the registry. In UTC format.

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.

trn-data

The domain's transfer data. An instance of epp_DomainTrnData with the following data members.

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_CREATE
• PENDING_DELETE
• PENDING_TRANSFER
• PENDING_UPDATE
• 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 a String using the toString() method and from a String via 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 available = EPPXMLBase.getAvailResultFor(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.

creation-date

The host's create date in the registry. In UTC format.

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.

3rd-party Packages Used in the RTK

* Ant 1.5.2: http://ant.apache.org/

Java SSL Packages: http://java.sun.com/products/jsse

* Xerses-J 1.3.0: http://xml.apache.org/xerces-j

* BouncyCastle 1.15: http://www.bouncycastle.org

(*) 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 samples 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, PollExample, 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 parameter 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/0705

Ant Build Files, directory: epp-rtk/java/etc

EPP RTK Java, Xerces, BouncyCastle and Ant Jar Files, directory: epp-rtk/java/lib

Java Compiled IDLs (Top level Packages), directory: epp-rtk/java/src/org/openrtk/idl/epp0705

Documentation provided in the RTK

EPP Internet-Drafts versions 07/05, directory: epp-rtk/epp/0705

Javadocs, directory: epp-rtk/java/doc/api-doc

EPP Java API Documentation, directory: epp-rtk/java/doc

README, directory: epp-rtk/java

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.