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