A common interface to the different registries is necessary because each registry may use a different API. It is very difficult for you and your developers to learn a new API each time a new Registry goes public. By using the GRI you do not need to learn a new API. As more developers use the GRI it may even become unnecessary for everyone to write new tools to access that registry. Instead developers can share registry implementations and thus focus on developing tools and services which add value to their Registrar.
The Generic Registry Interface (GRI) is a standard interface which provides base-line functionality for communicating with domain name registries. It is assumed that all registries will support at least domain name and host commands (create, modify, status, delete). Some registries may also support contact commands, although this is not required.
The main interface for the GRI is the com.signaturedomains.gri.Registry interface. This interface defines the methods which registries should support. The contact methods are optional and will through an UnsupportedOperationException if they are invoked on a Registry which does not support contact operations.
The GRIDomain, GRIHost, GRIRegistrant and GRIContact interfaces must be implemented by concrete classes which represent concrete implementations of each of these concepts. The GRI provides basic concrete implementations of these interfaces called BasicDomain, BasicHost, BasicRegistrant, and BasicContact.
Developers incorporating the GRI into their applications can access Registry implementations in two ways.
The first method is to aquire an instance of the RegistryManager class and then use the methods in the RegistryManager class to communicate with a Registry. When you use the GRI in this manner you do not need to specify the Registry to use (except when dealing with contacts). The RegistryManager will determine the correct Registry to use, based on the domain name or host name. The RegistryFactory must be initialized prior to the first request sent to the RegistryManager.
The second method is to create an instance of a particular Registry and communicate with that registry through the Registry interface. You can aquire an instance of a particular registry through the RegistryFactory class if your configuration occurs at startup, by creating an instance of a particular Registry directly if you want to be able to configure each Registry individually, or through the RegistryClassLoader if you want to dynamically load Registry implementations from a specified directory.
Each command sent to a Registry will result in either a RegistryResponse or an Exception. The RegistryResponse interface provides a generic system for accessing Registry results. You can access the Registry results directly through the RegistryResponse.getResponse() method. In addition you can get the response code or text message through getCode() and getMessage(), respectively. You can also use the isSuccessful() method to determine if the command was executed sucessfully. Registry errors which are returned by the server should be wrapped in a RegistryResponse, while network and other low level exceptions can be thrown as Exceptions.
When working with a RegistryResponse, it is best to use the isSuccessful() method first, then the getCode() and getMessage() methods, and finally the getResponse() method if absolutely necessary. By sticking with the first three methods your client code should be easier to maintain and you will avoid uncessary class casting.
Check command responses extend the basic RegistryResponse by including the method isAvailable(). This method will return true if the domain, host, or contact is available or false if not. Each registry can use a different code to signal an available domain, host or contact. Using this method allows you to remain independent of any particular registry.
You should always call RegistryFactory.loadConfiguration() at the start of your application to load the GRI configuration if you plan on using the RegistryManager class or aquiring Registry instances from the RegistryFactory. The loadConfiguration() method can take a File argument, an InputStream, or a JDOM Element:
RegistryFactory.loadConfiguration(new File("gri.xml"));
To check for the availability of a name using the RegistryManager:
String domainName = "yourdomain.com";
RegistryResponse res = RegistryManager.getInstance().checkDomain(domainName);
if(!res.isSuccessful()){
System.err.println("Error: " + res.getMessage());
} else {
if(res.isAvailable()){
System.out.println(domainName + " is available");
} else {
System.out.println(domainName + " is NOT available");
}
}
To use the RegistryManager class to create a domain name:
String domainName = "yourdomain.com";
int period = 2;
String registryIdentifier = RegistryFactory.getRegistryIdentifierForName(domainName);
BasicRegistrant registrant = new BasicRegistrant();
registrant.setHandle(registryIdentifier, "URC-AE1");
BasicContact contact = BasicContact();
contact.setHandle(registryIdentifier, "URC-AE1");
BasicDomain domain = new BasicDomain();
domain.setName(domainName);
domain.setRegistrant(registrant);
domain.setAdministrativeContact(contact);
domain.setBillingContact(contact);
domain.setTechnicalContact(contact);
domain.setSecurityPhrase("password");
domain.addNameServer("ns1.nameserver.com");
domain.addNameServer("ns2.nameserver.com");
RegistryResponse res = RegistryManager.getInstance().createDomain(domain, period);
if(!res.isSuccessful()){
System.err.println("Error: " + res.getMessage());
} else {
System.out.println(domainName + " registered.");
System.out.println(" Creation Date: " + domain.getCreationDate());
System.out.println(" Expiration Date: " + domain.getExpirationDate());
}
Review the JavaDocs for information on all of the methods available in the RegistryManager class.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
This product includes software developed by the JDOM Project (http://www.jdom.org/).
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The Generic Registry Interface and Universal Registry Client are available on the web at http://urc.sf.net/.