[Dev] Massive Check-In/Changes To Adapters (Must Read For Adapter Developers)

[Dylan White]

All,
 
I have just successfully committed a massive amount of changes regarding
adapters and the data used when invoking a backup adapter operations.
Most of this stuff happens behind the scenes, but it is still important
to explain.  This is ESPECIALLY important to understand if you are
currently developing a new adapter.
 
Previously when invoking a backup adapter operation, an XML was
specified that not only contained all the credential information needed
to authenticate with a device, but it contained a URI/URL that tried its
best to encapsulate all of the protocol and file server information
needed to connect to and communicate with/from a device.  We referred to
this URI/URL as the Connection Path URI to a device.  As time went on,
we ran into many issues regarding the limitations of a URI to describe
all the data we needed to have passed over the wire and into Perl for an
adapter operation, particularly a backup operation.  There were issues
regarding the encoding of the data and to make a long story short, it
just wasn't very flexible.
 
This has all changed, for the better.  Now the XML that is passed into a
backup adapter operation contains an element of a "connectionPath" type
that represents a connection path to a device.  A single
"connectionPath" type stores the hostname or IP address of a device, all
of the credential information needed to authenticate with the device,
all of the protocols needed to connect to and communicate with/from the
device, and all of the information for external file servers that the
device may need to connect to (such as a TFTP or FTP server).
 
Some of the benefits of this format is that there is now a single type
that can encapsulate all of this precious connection and communication
information.  It is also extremely readable and flexible.  An in-depth
explanation of all this is provided in the following wiki page:
http://wiki.ziptie.org/bin/view/Developer/ConnectionPathForAdapterOperat
ions
 
The reason that the changes are so massive regarding this is that most
of the adapters have been updated to deal with these changes.  Here are
a few of the main changes:

*	With in an adapter and any of its associated modules, there
isn't a need to parse out a ZipTie::Credentials object from the XML that
is passed into an adapter operation.  All of this information can be
parsed and stored into a ZipTie::ConnectionPath object by passing the
XML into the ZipTie::ConnectionPath::from_xml subroutine.
*	Since there isn't a need to pass around a ZipTie::Credentials
object explicitly, any module that had subroutines and/or methods that
expected a ZipTie::Credentials object as an argument have been modified
to take in a ZipTie::ConnectionPath argument instead.
*	External file server information is much easier to access now.
The ZipTie::ConnectionPath::TransferProtocolURI has been removed in
favor of the ZipTie::ConnectionPath::FileServer module.  Any file server
information specified within the connection path XML can be retrieved
from a ZipTie:ConnectionPath object, which will return a
ZipTie::ConnectionPath::FileServer instance.  The same also applies to
protocol information which is can be accessed and returns an instance of
the ZipTie::ConnectionPath::Protocol module.

I have made sure to update not only all of the existing adapters and
their associated modules, but all of the skeleton templates used by the
ZipTie Development Environment (ZDE) as well.  This means that any new
adapter generated by the ZDE will start out being constructed properly.
 
***WARNING***
 
If you are currently developing an adapter, then you may experience some
major headaches.  The ZipTie::ConnectionPath module is essentially a new
module and only shares the same name to its former counterpart that was
used to parse a URI.  If you reference any existing adapter, you should
be able to see how the new ZipTie::ConnectionPath module is leveraged.
If you are stumped, feel free to contact me.
 
There are some issues with the ZDE with all of these changes, but that
will be ironed out in the next day or two at most; I am also making sure
that there is solid Perldoc for all of the Perl modules used by our
adapters and I am also working on updating the ZipTie and ZDE
documentation to reflect all the changes that have been made.  As with
any major changes/refactoring, there is a chance that there may be some
issues to still iron out.  If anyone runs into anything, feel free to
respond to this e-mail, e-mail me directly at dylamite at ziptie.org, come
to the #ziptie IRC channel to tell us, post on our forums, or open a
bug.
 
- Dylan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mailman.ziptie.org/pipermail/dev/attachments/20070812/ad355a80/attachment-0001.html