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