On Tue, 2014-04-08 at 14:31 +0000, Emiliano Heyns wrote: > On 04/04/2014 14:33:27, "Patrick Ohly" <[email protected]> wrote: > > > > >> So such a (data?) source ties a few elements together: > >> 1. A backend, as described in the terminology section: the technical > >> kind of container > >> 2. A database, as described in the terminology section: the location > >>of > >> the container > > > >The "backend" is literally a backend module in SyncEvolution that > >provides access to certain storage systems (EDS, Akonadi, files, but > >also remote servers). The "database" is one set of items in that > >storage > >system. > > > >> 3. a database format (not described in the terminology section): the > >> format of the things *in* the container > > > >There might be more than that. For example, the database format is > >fairly specific to the file backend. The more general concept is that a > >data source combines all properties (including, but not limited to > >backend, database and databaseFormat) required to access a set of > >items. > > > but a data source consists of *exactly* these 3 things, right? Even if > one of them is implied by the backend.
The settings of a data source are not limited to just three properties. Currently defined are: syncevolution --source-property ? | grep -v '^ ' sync (disabled, unshared, required) uri (no default, unshared) backend (select backend, shared) syncFormat (no default, unshared) forceSyncFormat (FALSE, unshared) database = evolutionsource (no default, shared) databaseFormat (no default, shared) databaseUser = evolutionuser (no default, shared), databasePassword = evolutionpassword (no default, shared) Some of these (the unshared ones) are only relevant as part of a sync, the others (the shared ones) are also relevant for just the data access. Backends could even add more properties. However, that's not currently done. Instead different backends interpret the existing properties according to their needs. > >> From the synopsis section I am led to believe that @default is a > >> <config>. > > > >It is the name of a context. > Here's where it gets tricky. I think I understand now why you say this, > but where the synopsis says: > > syncevolution --configure <options> [--] <config> [<source> ...] > > And I map this to > > syncevolution --configure backend=carddav > [email protected] databasePassword=foobar > database=https://www.googleapis.com:443/carddav/v1/principals/john.doe%40googlemail.com/lists/default/ > > @google main-google-addressbook > > where it says '@google' in that command line that is a config which just > happens to contain nothing but the name of a context, namely google. Correct. <config> basically is a place holder for lots of things. > When you say later > > A config name has the format ``[<peer>][@<context>]``. When the context > is not specified explicitly, SyncEvolution first searches for an > existing configuration with the given name. If not found, it uses the > ``@default`` context as fallback. Thus the empty config name is an alias > for ``@default``. > > I now understand that '@google' is a config, which omits the peer part, > and thus only names the context 'google'. > > So what you're saying isn't wrong, but the way it was expressed was very > confusing to me. The synopsis also implies that if I would have written > > syncevolution --configure backend=carddav > [email protected] databasePassword=foobar > database=https://www.googleapis.com:443/carddav/v1/principals/john.doe%40googlemail.com/lists/default/ > > main-google-addressbook > this would have been equivalent to Except that the <config> has to be given, even if it is empty. That's because the position of the non-keyword parts of the command line matter: the first non-keyword is the config, the rest are source names. As I said to Graham, I am aware that depending on the positional syntax is one of the drawbacks of the command line. I'm just not sure whether the alternative (for example, an explicit --config <config>) would have been better because neat, short invocations like "syncevolution google" wouldn't be possible anymore. > syncevolution --configure backend=carddav > [email protected] databasePassword=foobar > database=https://www.googleapis.com:443/carddav/v1/principals/john.doe%40googlemail.com/lists/default/ > > @default main-google-addressbook > which might be great for experienced syncevolutionists but is hard to > piece out from the synopsis. Perhaps more examples would help. <shrug> > >No. "my-vcard-source" is the source config in the "@default" context. > >Think of the context as a folder in a file system which can contain > >items of different types: source configs, sync configs. > > > OK, so config names (sync and source) are unique within a context, and > source config names always identify a single data source. If there is a > one-on-one correspondence between data sources and source configs, why > do these exist as separate concepts? There is no real difference. As the terminology entry says, "data source" is "primarily used for the configuration which combines backend and database settings". > >The context is empty except for the things explicitly created inside > >them. > Which is only sync configs and source configs/data sources. A context > holds no properties, just entities of one of these two kinds. Right. > > >Now we need to enable access to the main-google-addressbook. It > >would > >> >be > >> >inactive otherwise. This is useful when configuring a peer in a > >>context > >> >which has many different sources defined, but you only want the peer > >>to > >> >have access to a certain subset of them. Any "sync" value other than > >> >"none" is okay here. > >> What does 'peer' mean here? How do I differentiate between a 'peer' > >>and > >> a 'context'? > > > >The "peer" is an abstract entity somewhere (like a Google server). > >Strictly speaking, SyncEvolution only has sync configs (with a name in > >front of the optional @) and contexts (the part after the @). I am a > >bit > >lax about this and sometimes call a sync config also "peer config". > So a "peer" isn't really a SE concept, then? SyncEvolution did not invent the term, yes. It gets defined anyway, to make it clear in which meaning it is used. > We just have contexts, data > sources and sync configs. What is meant with "enable access" above BTW? Consider a SyncML client talking to SyncEvolution as a SyncML server. Which data sources is that particular client allowed to access via SyncML? The answer may be different for different clients, so that's "enable access" via the sync property of the client controls. > >It's a somewhat arbitrary choice that some properties only exist for > >sync configs and not for source configs. I once posted a proposal for > >allowing any property to be set anywhere, with more specific locations > >overriding the less specific ones, but that was considered too > >complicated. > I can tell you from first-hand experience that the current > implementation is complicated for me. Having a clear hierarchical lookup > would have been a lot easier to grok for me. Fair enough. But then try to describe how these hierarchical lookup would be configured and debugged ("Where did this value of loglevel come from?"). I suspect that it would get more complex elsewhere. > >> >The next step is to set up the actual connection between @default > >>and > >> >@google. > >> So contexts are connected in a sync scenario? Not data sources? > > > >I misspoke a bit. In this example, the contexts were chosen such one > >context has the local set of sources and the other all sources in a > >specific peer ("Google"). The actual sync connection exists between a > >sync config and the target config, not between the contexts. > Could they all have been defined in a single context? What would have > been the pros/cons of that? They could have. The advantage of a single context is that one can do "syncevolution --remove @google" and get rid of everything related to Google. The disadvantage is that in a setup where you have one local system address book that gets synced with multiple peers, having the data source for that address book under "@google" would be inconsistent for the other peers. > >> >We want to choose sources explicitly, so disable all sources > >> >which might be defined in the @default context: > >> > > >> >syncevolution --configure \ > >> > syncURL=local://@google \ > >> > peerIsClient=1 \ > >> > sync=none \ > >> > google@default > >> This uses the magic word 'syncURL', so this sets up a sync config? > >Yes. > And because it doesn't have a target-config, right? Otherwise it would > have set up a target-config instead. Or is it the peerIsClient? Because > it looks very similar to the command > > syncevolution --configure printChanges=0 loglevel=3 syncURL=none > target-config@google > > which set up the target-config. What exactly makes SE decide to do one > or the other? Primarily the usage. A sync config is what you use when triggering a sync. That config then has to be set up correctly: 1. Must have a valid syncURL. 2. For a local sync, currently only peerIsClient=1 is valid. There is no meaning defined for peerIsClient=0 yet, but that might change, and therefore it is needed. > >It would not have been the same, because the connection has to be set > >as > >part of the sync config. There's only a forward mapping, not a reverse > >mapping (ignore aliases for the moment). > OK, so if I do remote@local for simplification I can't go wrong? I don't follow here. > >> >When following these steps, you will notice that creating the > >> >target-config included a check whether main-google-addressbook is > >> >usable. > >> I didn't notice that that is what it was for :) Is this why the > >>access > >> data repeats between setting up the data source and the sync config? > >I'm not sure what you mean with "the access data". Probably a full > >example session of the commands with output would have been useful. > > > Sorry; I meant to say "is this why I repeat the credentials in the setup > of the datasource and of the sync config"? Repeating the Google credentials in the target-config is not necessary if they were already set as databaseUser/Password for the individual source(s). > >> >This is part of some special semantic for creating new sync > >> >configs: if no sources > >> Sources? Plural? > > > >Yes, of course. Each context and thus sync config can have multiple > >sources. This could be multiple different calendars or one calendar, > >one > >address book, one task list, one memo list. > Ah no I understand that, but can a single command set up multiple data > sources? Yes. I think I mentioned the syntax already in this thread, but I don't remember when. --configure backend=eds-events @default calender and --configure backend=eds-contacts @default addressbook can be combined into --configure calendar/eds-event \ addressbook/backend=eds-contacts \ @default addressbook calendar -- Best Regards, Patrick Ohly The content of this message is my personal opinion only and although I am an employee of Intel, the statements I make here in no way represent Intel's position on the issue, nor am I authorized to speak on behalf of Intel on this matter. _______________________________________________ SyncEvolution mailing list [email protected] https://lists.syncevolution.org/mailman/listinfo/syncevolution
