On Fri, 2014-04-04 at 10:48 +0000, Emiliano Heyns wrote:
> On 04/04/2014 10:52:15, "Patrick Ohly" <[email protected]> wrote:
>
> >
> >Let's break this apart, using SyncEvolution terminology.
> >
> >First, you don't have a local storage "which syncs". You have a local
> >storage, full stop here. A local storage gets synced, but that comes
> >later.
> >
> >So you define first what that local storage is:
> >
> >syncevolution --configure \
> > backend=file \
> > database=/tmp/my-vcards/ \
> > databaseFormat=text/vcard \
> > @default my-vcard-source
> >mkdir /tmp/my-vcards/
> >
> >This creates a new source called "my-vcard-source" which uses the file
> >backend to access files in /tmp/my-cards.
> When you say 'source', does that mean 'data source' from the terminology
> list? Is this structurally of the same kind as the <source> mentions in
> the synopsis section?
Yes.
> 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.
> From the synopsis section I am led to believe that @default is a
> <config>.
It is the name of a context.
> I take it this is a source config,
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.
> but (assuming this is a
> clean environment):
> 1. Is this source config created as a side-effect of creating this data
> source?
> 2. What does this config hold, and what, if anything, is it associated
> with?
The context is empty except for the things explicitly created inside
them.
> >SyncEvolution doesn't have a "remote 'device' of type 'google'",
> >because
> >"Google" is not something that SyncEvolution knows about. You need to
> >translate that into SyncEvolution concepts, and that depends on how you
> >want to achieve your goals. Google servers support(ed) SyncML,
> >ActiveSync and CalDAV/CardDAV. Let's focus on the latter, because that
> >is what is officially supported by Google.
> >
> >That means in SyncEvolution you have to define a source which accesses
> >one particular address book or calendar via CardDAV resp. CalDAV. For
> >the sake of consistency let's use a separate context for it (*). First
> >we need to pick the right database:
> When you say 'context' here, I take that to refer to the context as
> described in the terminology section; in that description, a sync or
> source config is defined inside a context. But if I look at the
> definition of the local source above, that seems to be defined properly
> before we ever got to a context. Unless the @default is the context, but
> that conflicts with the naming in the synopsis section.
<config> in the synopsis doesn't have to be a sync config. From the
README.rst:
COMMAND LINE CONVENTIONS
========================
The ``<config>`` and the ``<source>`` strings in the command line
synopsis are
used to find the sync resp. source configs. Depending on which
other parameters are given, different operations are executed.
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``.
The ``<peer>`` part identifies a specific sync or target config inside
the context. It is optional and does not have to be specified when not
needed, for example when configuring the shared settings of sources
(``--configure @default addressbook``) or accessing items inside a
source (``--print-items @work calendar``).
> >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".
> >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
> So: configuration of a *data source* 'main-google-addressbook', which
> creates(?) a config or a context called '@google', if my interpretation
> above is correct. (it needs a '\' after the database BTW). But I don't
> know whether I should label @google a config or a context here.
See above - it's context.
> >Configuring a target-config first would have helped a bit to reduce
> >typing, but not much. I'm skipping it because it is not required at
> >this
> >point and would have detracted from the core concepts.
> I also at this point cannot assume I properly understand what a
> target-config is, but if we can do without for now that's fine by me.
You can think of it as a special kind of sync config - one which is
used to receive a sync instead of initiating it.
> >Now that you have two sources defined, they can be used to access items
> >with --import/--export/--print-items/... etc:
> >
> >syncevolution --export - \
> > @google main-google-addressbook
> >
> >Now it is time to set up syncing. First we need the target-config. For
> >the sake of the example, let's set a non-default loglevel for
> >operations
> >on the target side and disable the printing of changes on the Google
> >side:
> >
> >syncevolution --configure \
> > printChanges=0 \
> > loglevel=3 \
> > syncURL=none \
> > target-config@google
> >
> >Remember that the command line is doing sanity checks when creating new
> >configs to catch typos, so we have to confirm explicitly that this new
> >config is meant to be created without a syncURL.
> OK, so this sets up a 'sync config' from the terminology section, a
> target config being "a special *kind* of sync config'. A 'sync config'
> is then intrinsically *one* side from a pair of entities involved in a
> synchronization. This sync config attaches itself in some way to the
> context @google; the properties it specifies do not attach to the
> context @google, but to the sync config 'target-config@google'. Correct?
Yeah! Correct :-)
> It sets this up as a sync config because either:
> 1. syncURL is present, or
> 2. target-config (literal) is present
The latter. syncURL is necessary of the extra sanity checks of what is
allowed to go into a sync config.
> On 'sync config' the terminology says: "A sync configuration defines how
> to access a peer: the protocol which is to be used, how to find the
> peer, credentials, etc. Peers might support more than one protocol, in
> which case multiple sync configs have to be created."
>
> But the data sources as defined above already seem to include all the
> information on how to find the peer, and includes the credentials, and
> also seems to include or uniquely imply the one protocol supported.
As I said above, "target-config" is a bit different from a normal sync
config in the sense that it doesn't need to connect to something to
initiate a sync.
> The
> README states that the part after 'target-config' must be a context, but
> as outlined above, it's not entirely clear when these contexts come into
> existence.
Contexts spring into existence once something is created in them.
> Also, when reading the 'target config' section, it says that it holds
> "sync properties that are necessary to access databases on the other
> side of the local sync".
Note that it does not say that there really *are* any such properties or
that they are needed in all cases.
In this case, instead of setting databaseUser and databasePassword, you
could also have set username and password in the target-config. The
WebDAV-based backends look at databaseUser/Password first and if not
set, fall back to the config with which they are used.
Note that I wrote earlier to Graham that "--print-items @some-context
webdav-source" would implicitly look for "target-config@some-context".
That was not correct, one would have to use "--print-items
target-config@some-context webdav-source" explicitly and is not limited
to using a sync or target config named "target-config" either.
> But:
> 1. It seems that this data is already included in the source set up
> earlier
> 2. Local sync is differentiated from a 'normal sync', but I don't know
> what a 'normal sync' is
> 3. the local sync syncs with a remote server/device?
A "normal sync" connects to some third party via SyncML. A local sync
connects to the same instance of SyncEvolution, which then may use a
backend which accesses data on a remote server.
> >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.
> So the @google *context* has a datasource 'main-google-addressbook'
> then?
Yes.
> And the context @google comes into existence upon first reference?
Yes.
> Then what data is held by the context?
Nothing except for the sync and source configs created inside it.
> How does SE know upon first
> reference what properties to attach to the context, and which to the
> data source?
Because a context has no properties of its own, it is always possible to
create one.
> >syncevolution --configure \
> > sync=two-way \
> > target-config@google main-google-addressbook
> OK, so this says: "Take sync config 'target-config@google', which is
> attached to context '@google'. This sync config tells you all you need
> to know how to access data source 'main-google-addressbook', apart from
> the actual backend/databaseUser/databasePassword/database, which you can
> take from data source 'main-google-addressbook'". But what does it take
> from the sync config that is not already included in the data source?
The loglevel and printDatabase settings.
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.
> >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.
> >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.
> >Then pair the sources. We are doing that for only one pair of sources
> >here, but it could also be done for more.
> >
> >syncevolution --configure \
> > sync=two-way \
> > uri=main-google-addressbook \
> > google@default my-vcard-source
> So, this pairs data source main-google-addressbook with
> my-vcard-source. Is the last datasource on this command line by
> necessity local, or would
>
> syncevolution --configure \
> sync=two-way \
> uri=my-vcard-source \
> default@google main-google-addressbook
> have accomplished the same?
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).
> >And now sync:
> >
> >syncevolution --sync slow google@default
> So this syncs *all* paired-up datasources in google@default?
Yes.
> what label
> from the terminology list would you give to 'google@default'?
sync config.
> >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.
> >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.
Each of these sources then needs to be paired with other sources at the
other end of a local sync or on a remote SyncML peer (this is where the
"uri" name comes from).
> >are named explicitly, SyncEvolution will enable
> >all sources which are usable. In this case the check could have been
> >skipped because the source wasn't going to be enabled in that step
> >anyway because of "sync=none". The code is just not intelligent enough
> >to take that into account. Later, when changing properties like "sync",
> >no such sanity checks are done anymore.
> >
> >The intention was to give users a single command that results in a
> >usable sync config without them having to say anything about particular
> >sources:
> >
> >syncevolution --configure \
> > template=Memotoo \
> > username=john password=bar \
> > memotoo
> OK, so this sets up a sync config *without* attaching it to a context?
Have a look at the explanation of the "config name": "@default" is
optional. So "memotoo" == "memotoo@default".
> >If nothing has been configured before, this will check for the default
> >"addressbook", "calendar", "memo", "todo" databases and enable those
> >sources which are usable. The default depends on how SyncEvolution was
> >compiled. At the moment, the default backend and databases are EDS.
> OK, so that means 'usable' in the sense that it if you give it a
> username and password, it knows which data sources are offered by
> memotoo, and can than figure out for itself for each:
> 1. the backend
> 2. the database
> 3. the database format
For the remote side (Memotoo), the template has that information. For
the local side defaults are used. For example, the source config for
"addressbook" in the memotoo template has only "backend = addressbook"
set. Then SyncEvolution looks for a backend providing access to
"addressbook" data, which happens to be the eds-contacts backend.
> but what is the meaning of the 'memotoo' at the end? It's not a data
> source I think, because the datasources memotoo contains will differ on
> these properties. Is it a context?
It is the <config> from the synopsis and happens to be a sync config in
this particular case.
> >> The way I see it, I have two peers: @Files
> >> and @Google. @Files would be a 'source config', and @Google a 'sync
> >> config' -- but @Google is not a 'sync config' as the Google 'device'
> >>has
> >> multiple 'sync configs': one for a calendar, one for a contacts
> >>folder.
> >> So I'm already lost at this point.
> >
> >That's because the first sentence is already wrong: @files and @google
> >are contexts, and the peer is the Google server.
> How do contexts and peers relate (if at all?)
It's convenient to use @default for local storage and then one context
per peer (see the username/password sharing explained above), but it
doesn't have to be that way. One could also define a data source
accessing Google Contacts and another data source accessing Yahoo
Calendar in the same "@foobar" context.
> >And you don't have sync
> >configs for a calendar or contacts folder, you have source configs for
> >them. Accessing data is different from syncing it. Syncing builds on
> >top
> >of data access.
> OK, so I think I have the terminology on 'data sources' clear. Just to
> reiterate: a data source would point to exactly one collection of
> exactly one kind; a data source would not hold both calendar and
> contacts items. Correct?
Correct.
--
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
