15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# Protocol Buffers - Google's data interchange format 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# Copyright 2008 Google Inc. All rights reserved. 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# http://code.google.com/p/protobuf/ 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# Redistribution and use in source and binary forms, with or without 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# modification, are permitted provided that the following conditions are 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# met: 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# * Redistributions of source code must retain the above copyright 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# notice, this list of conditions and the following disclaimer. 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# * Redistributions in binary form must reproduce the above 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# copyright notice, this list of conditions and the following disclaimer 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# in the documentation and/or other materials provided with the 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# distribution. 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# * Neither the name of Google Inc. nor the names of its 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# contributors may be used to endorse or promote products derived from 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# this software without specific prior written permission. 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)"""Defines a listener interface for observing certain 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)state transitions on Message objects. 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)Also defines a null implementation of this interface. 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)""" 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)__author__ = 'robinson@google.com (Will Robinson)' 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class MessageListener(object): 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """Listens for modifications made to a message. Meant to be registered via 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Message._SetListener(). 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Attributes: 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) dirty: If True, then calling Modified() would be a no-op. This can be 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) used to avoid these calls entirely in the common case. 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """ 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) def Modified(self): 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """Called every time the message is modified in such a way that the parent 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) message may need to be updated. This currently means either: 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) (a) The message was modified for the first time, so the parent message 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) should henceforth mark the message as present. 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) (b) The message's cached byte size became dirty -- i.e. the message was 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) modified for the first time after a previous call to ByteSize(). 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Therefore the parent should also mark its byte size as dirty. 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Note that (a) implies (b), since new objects start out with a client cached 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) size (zero). However, we document (a) explicitly because it is important. 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Modified() will *only* be called in response to one of these two events -- 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) not every time the sub-message is modified. 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Note that if the listener's |dirty| attribute is true, then calling 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Modified at the moment would be a no-op, so it can be skipped. Performance- 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) sensitive callers should check this attribute directly before calling since 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) it will be true most of the time. 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """ 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) raise NotImplementedError 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NullMessageListener(object): 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) """No-op MessageListener implementation.""" 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) def Modified(self): 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) pass 79