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