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

[Brett Wooldridge]

You rock. Thanks for the great summary and all the blood, sweat, and tears
over the refactor.

-Brett

On 8/12/07 8:58 PM, "Dylan White" <dwhite at alterpoint.com> wrote:

> 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/ConnectionPathForAdapterOperations
>  
> 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
> 
> 
> _______________________________________________
> Dev mailing list
> Dev at ziptie.org
> http://mailman.ziptie.org/listinfo/dev


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mailman.ziptie.org/pipermail/dev/attachments/20070812/854e3d1f/attachment.html