1fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# Protocol Buffers - Google's data interchange format 2fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# Copyright 2008 Google Inc. All rights reserved. 3fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# http://code.google.com/p/protobuf/ 4fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# 5fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# Redistribution and use in source and binary forms, with or without 6fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# modification, are permitted provided that the following conditions are 7fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# met: 8fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# 9fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# * Redistributions of source code must retain the above copyright 10fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# notice, this list of conditions and the following disclaimer. 11fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# * Redistributions in binary form must reproduce the above 12fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# copyright notice, this list of conditions and the following disclaimer 13fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# in the documentation and/or other materials provided with the 14fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# distribution. 15fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# * Neither the name of Google Inc. nor the names of its 16fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# contributors may be used to endorse or promote products derived from 17fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# this software without specific prior written permission. 18fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# 19fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 31fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville"""Defines a listener interface for observing certain 32fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Savillestate transitions on Message objects. 33fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 34fbaaef999ba563838ebd00874ed8a1c01fbf286dWink SavilleAlso defines a null implementation of this interface. 35fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville""" 36fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 37fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville__author__ = 'robinson@google.com (Will Robinson)' 38fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 39fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 40fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Savilleclass MessageListener(object): 41fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 42d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville """Listens for modifications made to a message. Meant to be registered via 43d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville Message._SetListener(). 44d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville 45d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville Attributes: 46d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville dirty: If True, then calling Modified() would be a no-op. This can be 47d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville used to avoid these calls entirely in the common case. 48fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville """ 49fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 50d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville def Modified(self): 51d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville """Called every time the message is modified in such a way that the parent 52d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville message may need to be updated. This currently means either: 53d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville (a) The message was modified for the first time, so the parent message 54d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville should henceforth mark the message as present. 55d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville (b) The message's cached byte size became dirty -- i.e. the message was 56d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville modified for the first time after a previous call to ByteSize(). 57d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville Therefore the parent should also mark its byte size as dirty. 58d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville Note that (a) implies (b), since new objects start out with a client cached 59d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville size (zero). However, we document (a) explicitly because it is important. 60d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville 61d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville Modified() will *only* be called in response to one of these two events -- 62d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville not every time the sub-message is modified. 63fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 64d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville Note that if the listener's |dirty| attribute is true, then calling 65d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville Modified at the moment would be a no-op, so it can be skipped. Performance- 66d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville sensitive callers should check this attribute directly before calling since 67d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville it will be true most of the time. 68fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville """ 69d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville 70fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville raise NotImplementedError 71fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 72fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 73fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Savilleclass NullMessageListener(object): 74fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 75fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville """No-op MessageListener implementation.""" 76fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville 77d0332953cda33fb4f8e24ebff9c49159b69c43d6Wink Saville def Modified(self): 78fbaaef999ba563838ebd00874ed8a1c01fbf286dWink Saville pass 79