← Back to branch summary

~ubuntu-branches/ubuntu/quantal/folks/quantal

« back to all changes in this revision

Viewing changes to folks/individual-aggregator.vala

  • Committer: Package Import Robot
  • Author(s): Robert Ancell
  • Date: 2012-09-12 09:48:10 UTC
  • mfrom: (1.6.2)
  • Revision ID: package-import@ubuntu.com-20120912094810-6zlx8889hcovxj7p
Tags: 0.7.4.1-0ubuntu1
* New upstream bugfix release
* debian/control:
  - Bump build-depends on libglib2.0-dev, valac-0.18, libvala-0.18-dev
* debian/libfolks-eds25.symbols:
* debian/libfolks25.symbols:
  - Updated

Show diffs side-by-side

added added

removed removed

Lines of Context:
folks/individual-aggregator.vala
134
134
   * quiescent state.
135
135
   *
136
136
   * It's guaranteed that this property's value will only ever change after
137
 
   * {@link IndividualAggregator.is_prepared} has changed to `true`.
 
137
   * {@link IndividualAggregator.is_prepared} has changed to ``true``.
138
138
   *
139
139
   * @since 0.6.2
140
140
   */
150
150
   * by:
151
151
   *
152
152
   * - the FOLKS_PRIMARY_STORE env var (mostly for debugging)
153
 
   * - the GSettings key set in `_PRIMARY_STORE_CONFIG_KEY` (system set store)
154
 
   * - going with the `key-file` or `eds` store as the fall-back option
 
153
   * - the GSettings key set in ``_PRIMARY_STORE_CONFIG_KEY`` (system set store)
 
154
   * - going with the ``key-file`` or ``eds`` store as the fall-back option
155
155
   *
156
156
   * @since 0.5.0
157
157
   */
237
237
   * mappings from the old individuals to the single new individual which
238
238
   * replaces them (i.e. each of the old individuals will map to the same new
239
239
   * individual). This new individual is the one which will be specified as the
240
 
   * `replacement_individual` in the {@link Individual.removed} signal for the
 
240
   * ``replacement_individual`` in the {@link Individual.removed} signal for the
241
241
   * old individuals.
242
242
   *
243
243
   * Individuals which have been unlinked will be listed in the multi-map as
245
245
   * which replace it.
246
246
   *
247
247
   * Individuals which have been added will be listed in the multi-map as a
248
 
   * mapping from `null` to the set of added individuals. If `null` doesn't
 
248
   * mapping from ``null`` to the set of added individuals. If ``null`` doesn't
249
249
   * map to anything, no individuals have been added to the aggregator.
250
250
   *
251
251
   * Individuals which have been removed will be listed in the multi-map as
252
 
   * mappings from the removed individual to `null`.
 
252
   * mappings from the removed individual to ``null``.
253
253
   *
254
254
   * This will not be emitted until after {@link IndividualAggregator.prepare}
255
255
   * has been called.
328
328
              this._configured_primary_store_id = "";
329
329
            }
330
330
 
331
 
          var settings = new Settings (this._FOLKS_GSETTINGS_SCHEMA);
332
 
          var val = settings.get_string (this._PRIMARY_STORE_CONFIG_KEY);
 
331
          var settings = new Settings (IndividualAggregator._FOLKS_GSETTINGS_SCHEMA);
 
332
          var val = settings.get_string (IndividualAggregator._PRIMARY_STORE_CONFIG_KEY);
333
333
          if (val != null && val != "")
334
334
            {
335
335
              debug ("Setting primary store IDs from GSettings.");
611
611
   * @param matchee the individual to find matches for
612
612
   * @param min_threshold the threshold for accepting a match
613
613
   * @return a map from matched individuals to the degree with which they match
614
 
   * `matchee` (which is guaranteed to at least equal `min_threshold`);
 
614
   * ``matchee`` (which is guaranteed to at least equal ``min_threshold``);
615
615
   * if no matches could be found, an empty map is returned
616
616
   *
617
617
   * @since 0.5.1
645
645
   * @return a map from each individual in the aggregator to a map of the
646
646
   * other individuals in the aggregator which can be matched with that
647
647
   * individual, mapped to the degree with which they match the original
648
 
   * individual (which is guaranteed to at least equal `min_threshold`)
 
648
   * individual (which is guaranteed to at least equal ``min_threshold``)
649
649
   *
650
650
   * @since 0.5.1
651
651
   */
744
744
          if (this._quiescent_timeout_id == 0)
745
745
            {
746
746
              this._quiescent_timeout_id =
747
 
                  Timeout.add_seconds (this._QUIESCENT_TIMEOUT,
 
747
                  Timeout.add_seconds (IndividualAggregator._QUIESCENT_TIMEOUT,
748
748
                      this._quiescent_timeout_cb);
749
749
            }
750
750
        }
761
761
 
762
762
      /* We use the configured PersonaStore as the primary PersonaStore.
763
763
       *
764
 
       * If the type_id is `eds` we *must* know the actual store
 
764
       * If the type_id is ``eds`` we *must* know the actual store
765
765
       * (address book) we are talking about or we might end up using
766
766
       * a random store on every run.
767
767
       */
827
827
          if (this._quiescent_timeout_id == 0)
828
828
            {
829
829
              this._quiescent_timeout_id =
830
 
                  Timeout.add_seconds (this._QUIESCENT_TIMEOUT,
 
830
                  Timeout.add_seconds (IndividualAggregator._QUIESCENT_TIMEOUT,
831
831
                      this._quiescent_timeout_cb);
832
832
            }
833
833
        }
1004
1004
          PersonaStoreTrust trust_level = persona.store.trust_level;
1005
1005
 
1006
1006
          /* These are the Individuals whose Personas will be linked together
1007
 
           * to form the `final_individual`.
 
1007
           * to form the ``final_individual``.
1008
1008
           * Since a given Persona can only be part of one Individual, and the
1009
1009
           * code in Persona._set_personas() ensures that there are no duplicate
1010
1010
           * Personas in a given Individual, ensuring that there are no
1011
 
           * duplicate Individuals in `candidate_inds` (by using a
 
1011
           * duplicate Individuals in ``candidate_inds`` (by using a
1012
1012
           * HashSet) guarantees that there will be no duplicate Personas
1013
 
           * in the `final_individual`. */
 
1013
           * in the ``final_individual``. */
1014
1014
          HashSet<Individual> candidate_inds = new HashSet<Individual> ();
1015
1015
 
1016
1016
          var final_personas = new HashSet<Persona> ();
1698
1698
    }
1699
1699
 
1700
1700
  /**
1701
 
   * Add a new persona in the given {@link PersonaStore} based on the `details`
1702
 
   * provided.
 
1701
   * Add a new persona in the given {@link PersonaStore} based on the
 
1702
   * ``details`` provided.
1703
1703
   *
1704
1704
   * If the target store is offline, this function will throw
1705
1705
   * {@link IndividualAggregatorError.STORE_OFFLINE}. It's the responsibility of
1713
1713
   *  * message - a user-readable message to pass to the persona being added
1714
1714
   *
1715
1715
   * If a {@link Persona} with the given details already exists in the store, no
1716
 
   * error will be thrown and this function will return `null`.
 
1716
   * error will be thrown and this function will return ``null``.
1717
1717
   *
1718
1718
   * @param parent an optional {@link Individual} to add the new {@link Persona}
1719
1719
   * to. This persona will be appended to its ordered list of personas.
1720
1720
   * @param persona_store the {@link PersonaStore} to add the persona to
1721
1721
   * @param details a key-value map of details to use in creating the new
1722
1722
   * {@link Persona}
1723
 
   * @return the new {@link Persona} or `null` if the corresponding
1724
 
   * {@link Persona} already existed. If non-`null`, the new {@link Persona}
 
1723
   * @return the new {@link Persona} or ``null`` if the corresponding
 
1724
   * {@link Persona} already existed. If non-``null``, the new {@link Persona}
1725
1725
   * will also be added to a new or existing {@link Individual} as necessary.
1726
1726
   * @throws IndividualAggregatorError.STORE_OFFLINE if the persona store was
1727
1727
   * offline
1852
1852
              _("Check the relevant service is running, or change the default store in that service or using the “%s” GSettings key."),
1853
1853
              this._configured_primary_store_type_id,
1854
1854
              this._configured_primary_store_id,
1855
 
              "%s %s".printf (this._FOLKS_GSETTINGS_SCHEMA,
1856
 
                  this._PRIMARY_STORE_CONFIG_KEY));
 
1855
              "%s %s".printf (IndividualAggregator._FOLKS_GSETTINGS_SCHEMA,
 
1856
                  IndividualAggregator._PRIMARY_STORE_CONFIG_KEY));
1857
1857
        }
1858
1858
 
1859
1859
      /* Don't bother linking if it's just one Persona */
1900
1900
  private HashTable<string, Value?> _build_linking_details (
1901
1901
      Set<Persona> personas)
1902
1902
    {
1903
 
      /* `protocols_addrs_set` will be passed to the new Kf.Persona */
 
1903
      /* ``protocols_addrs_set`` will be passed to the new Kf.Persona */
1904
1904
      var protocols_addrs_set = new HashMultiMap<string, ImFieldDetails> (
1905
1905
            null, null,
1906
1906
            (GLib.HashFunc) ImFieldDetails.hash,
2073
2073
   * {@link Individual}.
2074
2074
   *
2075
2075
   * This makes sure that there is at least one {@link Persona} in the
2076
 
   * individual which has `property_name` in its
 
2076
   * individual which has ``property_name`` in its
2077
2077
   * {@link Persona.writeable_properties}. If no such persona exists in the
2078
2078
   * individual, a new one will be created and linked to the individual. (Note
2079
2079
   * that due to the design of the aggregator, this will result in the previous
2086
2086
   * {@link IndividualAggregatorError.PROPERTY_NOT_WRITEABLE} error will be
2087
2087
   * thrown.
2088
2088
   *
2089
 
   * @param individual the individual for which `property_name` should be
 
2089
   * @param individual the individual for which ``property_name`` should be
2090
2090
   * writeable
2091
2091
   * @param property_name the name of the property which needs to be writeable
2092
2092
   * (this should be in lower case using hyphens, e.g. “web-service-addresses”)
2095
2095
   * @throws IndividualAggregatorError.NO_PRIMARY_STORE if no primary store was
2096
2096
   * configured for this individual aggregator
2097
2097
   * @throws IndividualAggregatorError.PROPERTY_NOT_WRITEABLE if the given
2098
 
   * `property_name` referred to a non-writeable property
 
2098
   * ``property_name`` referred to a non-writeable property
2099
2099
   * @throws IndividualAggregatorError if adding a new persona (using
2100
2100
   * {@link IndividualAggregator.add_persona_from_details}) failed, or if
2101
2101
   * linking personas (using {@link IndividualAggregator.link_personas}) failed
2186
2186
              _("Check the relevant service is running, or change the default store in that service or using the “%s” GSettings key."),
2187
2187
              this._configured_primary_store_type_id,
2188
2188
              this._configured_primary_store_id,
2189
 
              "%s %s".printf (this._FOLKS_GSETTINGS_SCHEMA,
2190
 
                  this._PRIMARY_STORE_CONFIG_KEY));
 
2189
              "%s %s".printf (IndividualAggregator._FOLKS_GSETTINGS_SCHEMA,
 
2190
                  IndividualAggregator._PRIMARY_STORE_CONFIG_KEY));
2191
2191
        }
2192
2192
      else if (new_persona == null)
2193
2193
        {
2204
2204
  /**
2205
2205
   * Look up an individual in the aggregator.
2206
2206
   *
2207
 
   * This returns the {@link Individual} with the given `id` if it exists in
2208
 
   * the aggregator, and `null` otherwise.
 
2207
   * This returns the {@link Individual} with the given ``id`` if it exists in
 
2208
   * the aggregator, and ``null`` otherwise.
2209
2209
   *
2210
2210
   * In future, when lazy-loading of individuals' properties is added to folks,
2211
2211
   * this method guarantees to load all properties of the individual, even if
2216
2216
   * that case.
2217
2217
   *
2218
2218
   * @param id ID of the individual to look up
2219
 
   * @return individual with `id`, or `null` if no such individual was found
 
2219
   * @return individual with ``id``, or ``null`` if no such individual was found
2220
2220
   * @throws GLib.Error from {@link IndividualAggregator.prepare}
2221
2221
   *
2222
2222
   * @since 0.7.0