[sword-devel] InstallMgr details.

[Greg Hellings]

Troy,

That does answer a lot of questions.  Just a few notes on why I think
that the remote source versions don't have to be different at all:

On Fri, May 15, 2009 at 12:58 AM, Troy A. Griffitts
<scribe at crosswire.org> wrote:
> "Until you understand the details, design always sounds simple."
>  --I'm sure, some famous architect near retirement.
>
>
> There is a basic and practical difference between a local and a remote
> installation, however abstract you want to get.
>
> Remote repositories have concepts like 'refresh from remote source' (apt-get
> update)

Of course this will still be needed and applicable.

>
> Local repositories usually aren't 'entered' in a list by a user, though I
> suppose they could be if it was useful.  Practically there is usually 1
> local source (a CD or USB drive) and the user can Browse... to the location.
>  This is not easily replicated for remote sources.  They are typically
> 'configured' and their configuration stored for future reference.
>
> So, while the difference between local and remote is there, a remote FTP
> source and a remote HTTP source will likely be much less different.
> Some I can think of:  We now have just added support in 1.6.0 for
> non-anonymous FTP, so the user can input username/password if necessary--
> useful for access to a private beta repository.  We have supported Passive
> FTP as an option.  With HTTP access, we might also add HTTP proxy features.
>  These all require frontend user preferences.

HTTP can also be username/password protected and is represented the
same way in a URL and could also be set with the same convenience
method.

Passive has no meaning to HTTP that I'm aware of.  So if the
InstallMgr/InstallSource is working from an HTTP respository and the
application tries to set the connection to passive, silently doing
nothing would probably be just fine here.

FTP and HTTP can both be run over the same set of proxy server
options, so it makes sense to expose the same options, if they are to
be supported by the library.  The same goes for SFTP, SCP, etc on into
the future.

>
> There will almost certainly be additional work for the frontends when we add
> HTTP support, though not as different as you fear might be.

I'm not convinced that there needs to be.  If the library handles the
connections, the fetching and the parsing of the HTTP document, I
don't see why the HTTP can't just be a transparent addition to the
remote version of the installer classes.

>
>
> To understand the design decisions for InstallMgr, you have to have a basic
> understanding of the SWORD API:
>
> Libraries of modules are exposed as SWMgr objects.
> An SWMgr object can be easily created from a local path:
>
> SWMgr localLibrary("/path");
>
> So for local sources, you don't need InstallMgr to obtain an SWMgr object.
>
> InstallMgr has a new object: InstallSource which houses the configuration
> information for a remote source and can give back an SWMgr object which
> represents that remote library.

Looking at the method list and documentation for InstallMgr, its
function names do assume FTP, for clearly historical reasons of that's
the only protocol that's been supported.  If the goal in 1.6 is to
avoid changing the API, then obviously the names shouldn't change, but
the functionality doesn't seem to me to need to change -- usernames,
passwords, getting the SWMgr for the source, copying the file to
locally -- it's all the same functionality that the HTTP version
needs.  Adding the extra handling underneath for a URL that specifies
the HTTP protocol seems to me like the essence of OOP information
hiding.  Then the app that builds against the 1.6.0 set of install
managers with FTP only can also build against the 1.6.x series with
HTTP added, (though it might need to change in 1.7 if the function
names are altered to be more protocol agnostic).

Added bonus: you don't have to convince application builders to add
handling for the HTTP case.  You can just add it to the library and
have done with it!

>
> InstallMgr provides new SWMgr features useful when writing an install client
> like: compare 2 SWMgr objects and tell you which books are new, old,
> updated, etc.
>
> InstallMgr can install TO an SWMgr.  This sounded like a clever idea, as an
> SWMgr has the concept of a 'primary path', but in hindsite, we only will
> probably ever support installing TO a local directory, so this has added
> confusion.  The use case was:
>
> SWMgr defaultLocalSWORDLibrary;
> installMgr.installModule(&defaultLocalSWORDLibrary, "D:\\", "KJV");
>
> But this is too simplistic a use case to be practical.
>
>
> Due to backward compatibility, my least favourite interface in InstallMgr
> is:
>
> (for history, it used to be, at a time we only supported CD (well, local)
> installations:
>
> int InstallMgr::installModule(SWMgr *destMgr, const char *fromLocation,
> const char *modName);
> // which I don't hate
>
> )
>
>
> /** call to install a module from a local path (fromLocation) or remote
> InstallSource (is) (leave the other 0)
>  */
> int InstallMgr::installModule(SWMgr *destMgr, const char *fromLocation,
> const char *modName, InstallSource *is = 0);
>
>
> So, InstallMgr can either install FROM a local path (historically the
> initial impl), or remote InstallSource.
>
> When we decide to majorly break backward compatibility for the interface
> cleanup and remove all deprecated methods, InstallSource will probably get a
> c-tor(const char *path), and the 2nd parameter will just go away.

That makes perfect sense, as the local can be represented as just an
extension of the other protocols, using the file:// type of URI.  I
would also think that a few of the functions, like ftpCopy() could
also change their name to indicate that they're also supported from
other protocols (if, indeed, that's the case) at that time, also.

Overall, it sounds like, since the framework is already laid with
InstallMgr that the beauty of it should just be adding the support in
InstallMgr/InstallSource so that they can support http://, file://,
etc sources in addition to ftp:// already without the application
being the wiser.

--Greg

>
>
> Hope this alleviates some of your design concerns and helps you understand
> the historical thinking behind the decisions.
>
>
>        -Troy.
>
>
>
> Greg Hellings wrote:
>>
>> On Thu, May 14, 2009 at 11:29 PM, Matthew Talbert <ransom1982 at gmail.com>
>> wrote:
>>>>
>>>> Does it require a difference (for the C++ front ends) to add support
>>>> for FTP InstallMgr methods than it does for them to add a file://
>>>> version?  It seems that, if so, this is a problem with the design of
>>>> InstallMgr.  I would imagine that the interface between SWORD and the
>>>> application would be identical in all those cases -- all the
>>>> application needs is to retrieve the information and provide a way for
>>>> the user to input new locations.  I get the impression from your
>>>> previous messages that the front ends will need to change when you add
>>>> HTTP support to the library then front ends will need to add another
>>>> portion to their install manager that allows the user to create HTTP
>>>> install locations separate from FTP or file:// ones -- is that the
>>>> case?
>>>
>>> The interface is different for local installations than it is for FTP
>>> installations. For local installations, you must create an SWMgr that
>>> points to the location of the modules to be installed, then you can
>>> get a listing of the modules available (but you must be careful to not
>>> augment the path with HOME/.sword or other locations or it won't
>>> work). For FTP, it also creates an SWMgr, but it does it itself, and
>>> exposes the list of available modules. This difference is why Xiphos
>>> couldn't really use a local source until 3.0. No one had figured out
>>> how it was supposed to work :)
>>
>> I see -- it seems to me that method doesn't take nearly as much
>> abstraction as it should.  I should imagine that a client application
>> could simply create an InstallMgr object and pass it the string that
>> it ought to search for.  If the string is file://, ftp://, http://,
>> cifs:// or \\host or whatever shouldn't much matter in my mind.  The
>> URI should be parsed and the proper actions taken within InstallMgr.
>> Why was it done with a different class for each type, forcing the
>> client app to handle the parsing and take each experience differently?
>>  Inherently that will lead to different apps supporting or not
>> supporting certain of the features (the example that you just
>> mentioned, for instance).  If there was just the matter of "Create an
>> InstallMgr object, ask it what's available, tell it to install to
>> such-and-such a writable location" then as the library expanded
>> support for HTTP, SFTP, SomeFutureTP the applications would not even
>> need to know or care.
>>
>> --Greg
>>
>>> Matthew
>>>
>>> _______________________________________________
>>> sword-devel mailing list: sword-devel at crosswire.org
>>> http://www.crosswire.org/mailman/listinfo/sword-devel
>>> Instructions to unsubscribe/change your settings at above page
>>>
>>
>> _______________________________________________
>> sword-devel mailing list: sword-devel at crosswire.org
>> http://www.crosswire.org/mailman/listinfo/sword-devel
>> Instructions to unsubscribe/change your settings at above page
>
>
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page
>