/ 
XML-EPP-0.05_02
River stage zero No dependents
/ XML::EPP

NAME

XML::EPP - an implementation of the EPP XML language

SYNOPSIS

use XML::EPP;

my $foo_create = XML::EPP->new(
        message => XML::EPP::Command->new(
            action => "create",
            argument => XML::EPP::SubCommand->new(
                payload => XML::EPP::Obj::create->new(
                    ...
                ),
            ),
            clTRID => "xml_epp_".time."_$$",
        ),
);

print $foo_create->to_xml;

DESCRIPTION

This module is an implementation of the XML protocol used by most major domain registries around the world. This protocol was developed between 2002 and 2004, using XML standards which were at the time very new, such as XML Namespaces and XML Schema. It saw several incompatible revisions until the 1.0 version which became RFC3730.

This module hopes to create a Free Software, complete, user-friendly and standards compliant interface to both client and server sides of the EPP specification.

WARNING: SITE^WMODULE UNDER CONSTRUCTION

The classes which are present, while enough to be able to parse the RFC, are not fixed in API terms until they are documented and tested. Please consider any attribute which is not yet at least documented to be under review and subject to rename. This is thought to lead to a clearer implementation than fixing attribute names to the somewhat random (though well-known) names used in the EPP XML. Use of sub BUILDARGS { } to allow either may be considered; patches welcome.

Similarly with undocumented portions of the implementation. If you would like to make sure that the code you write against it doesn't need rewriting, please send a patch/pull request!

This module currently implements the XML part of the protocol only; converting this into an actual EPP session is currently TO-DO. Also, none of the mappings for essential registry types, such as domain, contact or host are yet implemented. This is a preview release.

PARSING AN EPP MESSAGE

This part currently works very well. Feed in some valid XML thusly;

use XML::EPP;
my $message = XML::EPP->parse( $xml );

If you can find any RFC5730-valid document (including RFC5731, RFC5732 or RFC5733) this doesn't parse, then you win a bag of chocolate fish. Similarly if you find an RFC-invalid document that this module accepts blindly. Please log an RT ticket and contact the author privately for delivery of the chocolate.

CREATING AN EPP MESSAGE

There is an example in the SYNOPSIS, but essentially the regular Moose constructor is all that is provided in this module.

HINTS

Look out for convenience construction interfaces. These are primarily useful coerce rules (see Moose::Util::TypeConstraints).

For example, instead of writing (in the middle of constructing a XML::EPP::DCP stack):

recipient => XML::EPP::DCP::Recipient->new(
        same => 1,
        ours => [
             XML::EPP::DCP::Ours->new( name => "SomeCo Ltd" ),
             XML::EPP::DCP::Ours->new( name => "Partner Ltd" ),
        ],
    ),

Coerce rules are defined to make this work:

recipient => [ qw(same), "SomeCo Ltd", "Partner Ltd" ];

Both construct the same stack of objects, and would serialize to:

<recipient xmlns="urn:ietf:params:xml:ns:epp-1.0">
  <ours><recDesc>SomeCo Ltd</recDesc></ours>
  <ours><recDesc>Parnet Ltd</recDesc></ours>
  <same/>
</recipient>

For this to be most useful, the rules are hand-written for each class.

GLOBALS / CLASS METHODS

@XML::EPP::epp_versions

The list of EPP versions implemented by this module. Default value is ("1.0", ).

@XML::EPP::epp_lang

The list of EPP languages implemented by this module. Default value is ("en", ).

register_obj_uri( $uri[, $namespace])

Register the namespace $namespace as corresponding to the $uri URI. Object types such as XML::EPP::Domain, etc will use this to register themselves. The loaded object types are available in the global variable @XML::EPP::obj_uris

register_ext_uri( $uri[, $namespace])

Exactly the same as the above, but the URI will be advertised as an extension, not an object type.

SOURCE, SUBMISSIONS, SUPPORT

Source code is available from Catalyst:

git://git.catalyst.net.nz/XML-EPP.git

And Github:

git://github.com/catalyst/XML-EPP.git

Please see the file SubmittingPatches for information on preferred submission formats.

Suggested avenues for support:

SEE ALSO

XML::EPP::Changes for what has most recently been added to XML::EPP.

XML::EPP::Domain - an implementation of the RFC5731 domain mapping

XML::EPP::Host - an implementation of the RFC5732 host mapping

XML::EPP::Contact - an implementation of the RFC5733 contact mapping

AUTHOR AND LICENCE

Development commissioned by NZ Registry Services, and carried out by Catalyst IT - http://www.catalyst.net.nz/

Copyright 2009, 2010, NZ Registry Services. This module is licensed under the Artistic License v2.0, which permits relicensing under other Free Software licenses.