dynamic_message.h revision fbaaef999ba563838ebd00874ed8a1c01fbf286d
149edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// Protocol Buffers - Google's data interchange format 249edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// Copyright 2008 Google Inc. All rights reserved. 349edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// http://code.google.com/p/protobuf/ 449edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// 549edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// Redistribution and use in source and binary forms, with or without 649edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// modification, are permitted provided that the following conditions are 749edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// met: 849edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// 949edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// * Redistributions of source code must retain the above copyright 1049edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// notice, this list of conditions and the following disclaimer. 1149edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// * Redistributions in binary form must reproduce the above 1249edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// copyright notice, this list of conditions and the following disclaimer 1349edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// in the documentation and/or other materials provided with the 1449edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// distribution. 1549edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// * Neither the name of Google Inc. nor the names of its 1649edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// contributors may be used to endorse or promote products derived from 1749edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// this software without specific prior written permission. 1849edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// 1949edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 2049edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 2149edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 2249edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 2349edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 2449edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 2549edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 2649edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 2749edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 2849edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 2949edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 3049edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org 3149edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// Author: kenton@google.com (Kenton Varda) 3249edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// Based on original Protocol Buffers design by 3349edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// Sanjay Ghemawat, Jeff Dean, and others. 3449edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// 3549edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// Defines an implementation of Message which can emulate types which are not 3649edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// known at compile-time. 3749edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org 3849edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org#ifndef GOOGLE_PROTOBUF_DYNAMIC_MESSAGE_H__ 3949edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org#define GOOGLE_PROTOBUF_DYNAMIC_MESSAGE_H__ 4049edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org 4149edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org#include <google/protobuf/message.h> 4249edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org#include <google/protobuf/stubs/common.h> 4349edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org 4449edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.orgnamespace google { 4549edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.orgnamespace protobuf { 4649edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org 4749edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.org// Defined in other files. 4849edbdf52640c88918f8e6638ab4965819eb1dfekmillikin@chromium.orgclass Descriptor; // descriptor.h 49class DescriptorPool; // descriptor.h 50 51// Constructs implementations of Message which can emulate types which are not 52// known at compile-time. 53// 54// Sometimes you want to be able to manipulate protocol types that you don't 55// know about at compile time. It would be nice to be able to construct 56// a Message object which implements the message type given by any arbitrary 57// Descriptor. DynamicMessage provides this. 58// 59// As it turns out, a DynamicMessage needs to construct extra 60// information about its type in order to operate. Most of this information 61// can be shared between all DynamicMessages of the same type. But, caching 62// this information in some sort of global map would be a bad idea, since 63// the cached information for a particular descriptor could outlive the 64// descriptor itself. To avoid this problem, DynamicMessageFactory 65// encapsulates this "cache". All DynamicMessages of the same type created 66// from the same factory will share the same support data. Any Descriptors 67// used with a particular factory must outlive the factory. 68class LIBPROTOBUF_EXPORT DynamicMessageFactory : public MessageFactory { 69 public: 70 // Construct a DynamicMessageFactory that will search for extensions in 71 // the DescriptorPool in which the exendee is defined. 72 DynamicMessageFactory(); 73 74 // Construct a DynamicMessageFactory that will search for extensions in 75 // the given DescriptorPool. 76 DynamicMessageFactory(const DescriptorPool* pool); 77 ~DynamicMessageFactory(); 78 79 // implements MessageFactory --------------------------------------- 80 81 // Given a Descriptor, constructs the default (prototype) Message of that 82 // type. You can then call that message's New() method to construct a 83 // mutable message of that type. 84 // 85 // Calling this method twice with the same Descriptor returns the same 86 // object. The returned object remains property of the factory and will 87 // be destroyed when the factory is destroyed. Also, any objects created 88 // by calling the prototype's New() method share some data with the 89 // prototype, so these must be destoyed before the DynamicMessageFactory 90 // is destroyed. 91 // 92 // The given descriptor must outlive the returned message, and hence must 93 // outlive the DynamicMessageFactory. 94 // 95 // Note that while GetPrototype() is idempotent, it is not const. This 96 // implies that it is not thread-safe to call GetPrototype() on the same 97 // DynamicMessageFactory in two different threads simultaneously. However, 98 // the returned objects are just as thread-safe as any other Message. 99 const Message* GetPrototype(const Descriptor* type); 100 101 private: 102 const DescriptorPool* pool_; 103 104 // This struct just contains a hash_map. We can't #include <google/protobuf/stubs/hash.h> from 105 // this header due to hacks needed for hash_map portability in the open source 106 // release. Namely, stubs/hash.h, which defines hash_map portably, is not a 107 // public header (for good reason), but dynamic_message.h is, and public 108 // headers may only #include other public headers. 109 struct PrototypeMap; 110 scoped_ptr<PrototypeMap> prototypes_; 111 112 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(DynamicMessageFactory); 113}; 114 115} // namespace protobuf 116 117} // namespace google 118#endif // GOOGLE_PROTOBUF_DYNAMIC_MESSAGE_H__ 119 120