17e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# Protocol Buffers - Google's data interchange format 27e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# Copyright 2008 Google Inc. All rights reserved. 37e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# http://code.google.com/p/protobuf/ 47e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# 57e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# Redistribution and use in source and binary forms, with or without 67e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# modification, are permitted provided that the following conditions are 77e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# met: 87e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# 97e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# * Redistributions of source code must retain the above copyright 107e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# notice, this list of conditions and the following disclaimer. 117e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# * Redistributions in binary form must reproduce the above 127e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# copyright notice, this list of conditions and the following disclaimer 137e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# in the documentation and/or other materials provided with the 147e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# distribution. 157e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# * Neither the name of Google Inc. nor the names of its 167e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# contributors may be used to endorse or promote products derived from 177e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# this software without specific prior written permission. 187e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# 197e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 207e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 217e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 227e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 237e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 247e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 257e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 267e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 277e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 287e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 297e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 307e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 317e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang"""Defines a listener interface for observing certain 327e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wangstate transitions on Message objects. 337e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 347e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing WangAlso defines a null implementation of this interface. 357e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang""" 367e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 377e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang__author__ = 'robinson@google.com (Will Robinson)' 387e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 397e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 407e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wangclass MessageListener(object): 417e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 427e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang """Listens for modifications made to a message. Meant to be registered via 437e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang Message._SetListener(). 447e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 457e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang Attributes: 467e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang dirty: If True, then calling Modified() would be a no-op. This can be 477e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang used to avoid these calls entirely in the common case. 487e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang """ 497e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 507e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang def Modified(self): 517e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang """Called every time the message is modified in such a way that the parent 527e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang message may need to be updated. This currently means either: 537e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang (a) The message was modified for the first time, so the parent message 547e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang should henceforth mark the message as present. 557e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang (b) The message's cached byte size became dirty -- i.e. the message was 567e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang modified for the first time after a previous call to ByteSize(). 577e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang Therefore the parent should also mark its byte size as dirty. 587e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang Note that (a) implies (b), since new objects start out with a client cached 597e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang size (zero). However, we document (a) explicitly because it is important. 607e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 617e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang Modified() will *only* be called in response to one of these two events -- 627e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang not every time the sub-message is modified. 637e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 647e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang Note that if the listener's |dirty| attribute is true, then calling 657e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang Modified at the moment would be a no-op, so it can be skipped. Performance- 667e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang sensitive callers should check this attribute directly before calling since 677e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang it will be true most of the time. 687e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang """ 697e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 707e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang raise NotImplementedError 717e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 727e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 737e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wangclass NullMessageListener(object): 747e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 757e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang """No-op MessageListener implementation.""" 767e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang 777e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang def Modified(self): 787e7f2e9122af6c7e7e7d4ba205fdf46d50b95eefYing Wang pass 79