/thirdparty/breakpad/third_party/protobuf/protobuf/python/google/protobuf/internal/message_listener.py

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