unique_position.proto 3.7 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182
  1. // Copyright (c) 2012 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. //
  5. // Protobuf representation of the UniquePosition class.
  6. // If you change or add any fields in this file, update proto_visitors.h and
  7. // potentially proto_enum_conversions.{h, cc}.
  8. syntax = "proto2";
  9. option java_multiple_files = true;
  10. option java_package = "org.chromium.components.sync.protocol";
  11. option optimize_for = LITE_RUNTIME;
  12. package sync_pb;
  13. // A UniquePosition is a string of bytes.
  14. //
  15. // Unique positions are unique per-item, since they are guaranteed to end with a
  16. // fixed-length suffix that is unique per-item. The position string may not end
  17. // with a '\0' byte.
  18. //
  19. // Prior to the suffix is a series of arbitrary bytes of arbitrary length.
  20. // Items under the same parent are positioned relative to each other by a
  21. // lexicographic comparison of their UniquePosition values.
  22. message UniquePosition {
  23. // History:
  24. //
  25. // Unique positions were first introduced in M28. This change was rolled out
  26. // in such a way that it would try to maintain backwards compatibilty with
  27. // clients that understood only the old int64-based positions.
  28. //
  29. // At first, clients supported only the 'value' field. This version never
  30. // made it to stable. We later added support for the 'compressed_value'
  31. // field, and clients would populate either one or the other.
  32. //
  33. // In M30, we added the custom_compressed_v1 representation. This
  34. // representation was better than the previous implementations in almost every
  35. // way. However, we could not use it right away, since older clients would
  36. // not understand it. We decided to write both the old-style ('value' or
  37. // 'custom_compressed') representation and the 'custom_compressed_v1'
  38. // repersentations to every protobuf during the transition period. Protobufs
  39. // written during this transition period would be readable by clients who
  40. // understand at least one of the two formats.
  41. //
  42. // In M33, we dropped support for writing the backwards-compatibility fields.
  43. // Protobufs written by this version or later are not be intelligible by
  44. // clients with version M29 or older. Those clients will end up making use of
  45. // the old int64 position fallback mechanism.
  46. // The uncompressed string of bytes representing the position.
  47. //
  48. // Deprecated. See history note above.
  49. optional bytes value = 1 [deprecated = true];
  50. // The client may choose to write a compressed position to this field instead
  51. // of populating the 'value' above. If it chooses to use compression, the
  52. // 'value' field above must be empty. The position value will be compressed
  53. // with gzip and stored in the compressed_value field. The position's
  54. // uncompressed length must be specified and written to the
  55. // uncompressed_length field.
  56. //
  57. // Deprecated. See history note above.
  58. optional bytes compressed_value = 2 [deprecated = true];
  59. optional uint64 uncompressed_length = 3 [deprecated = true];
  60. // This encoding uses compression scheme designed especially for unique
  61. // positions. It has the property that X < Y precisely when Compressed(X) <
  62. // Compressed(Y), which is very useful when the most common operation is to
  63. // compare these positions against each other. Their values may remain
  64. // compressed in memory.
  65. //
  66. // The compression scheme is implemented and documented in
  67. // sync/core_impl/base/unique_position.cc.
  68. //
  69. // As of M30, this is the preferred encoding. Newer clients may continue to
  70. // populate the 'value' and 'compressed_value' fields to ensure backwards
  71. // compatibility, but they will always try to read from this field first.
  72. optional bytes custom_compressed_v1 = 4;
  73. }