diff options
Diffstat (limited to 'include/google/protobuf/descriptor_database.h')
| -rw-r--r-- | include/google/protobuf/descriptor_database.h | 398 |
1 files changed, 0 insertions, 398 deletions
diff --git a/include/google/protobuf/descriptor_database.h b/include/google/protobuf/descriptor_database.h deleted file mode 100644 index f4f06bbfa6..0000000000 --- a/include/google/protobuf/descriptor_database.h +++ /dev/null @@ -1,398 +0,0 @@ -// Protocol Buffers - Google's data interchange format -// Copyright 2008 Google Inc. All rights reserved. -// https://developers.google.com/protocol-buffers/ -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are -// met: -// -// * Redistributions of source code must retain the above copyright -// notice, this list of conditions and the following disclaimer. -// * Redistributions in binary form must reproduce the above -// copyright notice, this list of conditions and the following disclaimer -// in the documentation and/or other materials provided with the -// distribution. -// * Neither the name of Google Inc. nor the names of its -// contributors may be used to endorse or promote products derived from -// this software without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -// Author: kenton@google.com (Kenton Varda) -// Based on original Protocol Buffers design by -// Sanjay Ghemawat, Jeff Dean, and others. -// -// Interface for manipulating databases of descriptors. - -#ifndef GOOGLE_PROTOBUF_DESCRIPTOR_DATABASE_H__ -#define GOOGLE_PROTOBUF_DESCRIPTOR_DATABASE_H__ - - -#include <map> -#include <string> -#include <utility> -#include <vector> - -#include <google/protobuf/stubs/common.h> -#include <google/protobuf/descriptor.h> - -// Must be included last. -#include <google/protobuf/port_def.inc> - -#ifdef SWIG -#error "You cannot SWIG proto headers" -#endif - -namespace google { -namespace protobuf { - -// Defined in this file. -class DescriptorDatabase; -class SimpleDescriptorDatabase; -class EncodedDescriptorDatabase; -class DescriptorPoolDatabase; -class MergedDescriptorDatabase; - -// Abstract interface for a database of descriptors. -// -// This is useful if you want to create a DescriptorPool which loads -// descriptors on-demand from some sort of large database. If the database -// is large, it may be inefficient to enumerate every .proto file inside it -// calling DescriptorPool::BuildFile() for each one. Instead, a DescriptorPool -// can be created which wraps a DescriptorDatabase and only builds particular -// descriptors when they are needed. -class PROTOBUF_EXPORT DescriptorDatabase { - public: - inline DescriptorDatabase() {} - virtual ~DescriptorDatabase(); - - // Find a file by file name. Fills in in *output and returns true if found. - // Otherwise, returns false, leaving the contents of *output undefined. - virtual bool FindFileByName(const std::string& filename, - FileDescriptorProto* output) = 0; - - // Find the file that declares the given fully-qualified symbol name. - // If found, fills in *output and returns true, otherwise returns false - // and leaves *output undefined. - virtual bool FindFileContainingSymbol(const std::string& symbol_name, - FileDescriptorProto* output) = 0; - - // Find the file which defines an extension extending the given message type - // with the given field number. If found, fills in *output and returns true, - // otherwise returns false and leaves *output undefined. containing_type - // must be a fully-qualified type name. - virtual bool FindFileContainingExtension(const std::string& containing_type, - int field_number, - FileDescriptorProto* output) = 0; - - // Finds the tag numbers used by all known extensions of - // extendee_type, and appends them to output in an undefined - // order. This method is best-effort: it's not guaranteed that the - // database will find all extensions, and it's not guaranteed that - // FindFileContainingExtension will return true on all of the found - // numbers. Returns true if the search was successful, otherwise - // returns false and leaves output unchanged. - // - // This method has a default implementation that always returns - // false. - virtual bool FindAllExtensionNumbers(const std::string& /* extendee_type */, - std::vector<int>* /* output */) { - return false; - } - - - // Finds the file names and appends them to the output in an - // undefined order. This method is best-effort: it's not guaranteed that the - // database will find all files. Returns true if the database supports - // searching all file names, otherwise returns false and leaves output - // unchanged. - // - // This method has a default implementation that always returns - // false. - virtual bool FindAllFileNames(std::vector<std::string>* /*output*/) { - return false; - } - - // Finds the package names and appends them to the output in an - // undefined order. This method is best-effort: it's not guaranteed that the - // database will find all packages. Returns true if the database supports - // searching all package names, otherwise returns false and leaves output - // unchanged. - bool FindAllPackageNames(std::vector<std::string>* output); - - // Finds the message names and appends them to the output in an - // undefined order. This method is best-effort: it's not guaranteed that the - // database will find all messages. Returns true if the database supports - // searching all message names, otherwise returns false and leaves output - // unchanged. - bool FindAllMessageNames(std::vector<std::string>* output); - - private: - GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(DescriptorDatabase); -}; - -// A DescriptorDatabase into which you can insert files manually. -// -// FindFileContainingSymbol() is fully-implemented. When you add a file, its -// symbols will be indexed for this purpose. Note that the implementation -// may return false positives, but only if it isn't possible for the symbol -// to be defined in any other file. In particular, if a file defines a symbol -// "Foo", then searching for "Foo.[anything]" will match that file. This way, -// the database does not need to aggressively index all children of a symbol. -// -// FindFileContainingExtension() is mostly-implemented. It works if and only -// if the original FieldDescriptorProto defining the extension has a -// fully-qualified type name in its "extendee" field (i.e. starts with a '.'). -// If the extendee is a relative name, SimpleDescriptorDatabase will not -// attempt to resolve the type, so it will not know what type the extension is -// extending. Therefore, calling FindFileContainingExtension() with the -// extension's containing type will never actually find that extension. Note -// that this is an unlikely problem, as all FileDescriptorProtos created by the -// protocol compiler (as well as ones created by calling -// FileDescriptor::CopyTo()) will always use fully-qualified names for all -// types. You only need to worry if you are constructing FileDescriptorProtos -// yourself, or are calling compiler::Parser directly. -class PROTOBUF_EXPORT SimpleDescriptorDatabase : public DescriptorDatabase { - public: - SimpleDescriptorDatabase(); - ~SimpleDescriptorDatabase() override; - - // Adds the FileDescriptorProto to the database, making a copy. The object - // can be deleted after Add() returns. Returns false if the file conflicted - // with a file already in the database, in which case an error will have - // been written to GOOGLE_LOG(ERROR). - bool Add(const FileDescriptorProto& file); - - // Adds the FileDescriptorProto to the database and takes ownership of it. - bool AddAndOwn(const FileDescriptorProto* file); - - // implements DescriptorDatabase ----------------------------------- - bool FindFileByName(const std::string& filename, - FileDescriptorProto* output) override; - bool FindFileContainingSymbol(const std::string& symbol_name, - FileDescriptorProto* output) override; - bool FindFileContainingExtension(const std::string& containing_type, - int field_number, - FileDescriptorProto* output) override; - bool FindAllExtensionNumbers(const std::string& extendee_type, - std::vector<int>* output) override; - - bool FindAllFileNames(std::vector<std::string>* output) override; - - private: - // An index mapping file names, symbol names, and extension numbers to - // some sort of values. - template <typename Value> - class DescriptorIndex { - public: - // Helpers to recursively add particular descriptors and all their contents - // to the index. - bool AddFile(const FileDescriptorProto& file, Value value); - bool AddSymbol(const std::string& name, Value value); - bool AddNestedExtensions(const std::string& filename, - const DescriptorProto& message_type, Value value); - bool AddExtension(const std::string& filename, - const FieldDescriptorProto& field, Value value); - - Value FindFile(const std::string& filename); - Value FindSymbol(const std::string& name); - Value FindExtension(const std::string& containing_type, int field_number); - bool FindAllExtensionNumbers(const std::string& containing_type, - std::vector<int>* output); - void FindAllFileNames(std::vector<std::string>* output); - - private: - std::map<std::string, Value> by_name_; - std::map<std::string, Value> by_symbol_; - std::map<std::pair<std::string, int>, Value> by_extension_; - - // Invariant: The by_symbol_ map does not contain any symbols which are - // prefixes of other symbols in the map. For example, "foo.bar" is a - // prefix of "foo.bar.baz" (but is not a prefix of "foo.barbaz"). - // - // This invariant is important because it means that given a symbol name, - // we can find a key in the map which is a prefix of the symbol in O(lg n) - // time, and we know that there is at most one such key. - // - // The prefix lookup algorithm works like so: - // 1) Find the last key in the map which is less than or equal to the - // search key. - // 2) If the found key is a prefix of the search key, then return it. - // Otherwise, there is no match. - // - // I am sure this algorithm has been described elsewhere, but since I - // wasn't able to find it quickly I will instead prove that it works - // myself. The key to the algorithm is that if a match exists, step (1) - // will find it. Proof: - // 1) Define the "search key" to be the key we are looking for, the "found - // key" to be the key found in step (1), and the "match key" to be the - // key which actually matches the search key (i.e. the key we're trying - // to find). - // 2) The found key must be less than or equal to the search key by - // definition. - // 3) The match key must also be less than or equal to the search key - // (because it is a prefix). - // 4) The match key cannot be greater than the found key, because if it - // were, then step (1) of the algorithm would have returned the match - // key instead (since it finds the *greatest* key which is less than or - // equal to the search key). - // 5) Therefore, the found key must be between the match key and the search - // key, inclusive. - // 6) Since the search key must be a sub-symbol of the match key, if it is - // not equal to the match key, then search_key[match_key.size()] must - // be '.'. - // 7) Since '.' sorts before any other character that is valid in a symbol - // name, then if the found key is not equal to the match key, then - // found_key[match_key.size()] must also be '.', because any other value - // would make it sort after the search key. - // 8) Therefore, if the found key is not equal to the match key, then the - // found key must be a sub-symbol of the match key. However, this would - // contradict our map invariant which says that no symbol in the map is - // a sub-symbol of any other. - // 9) Therefore, the found key must match the match key. - // - // The above proof assumes the match key exists. In the case that the - // match key does not exist, then step (1) will return some other symbol. - // That symbol cannot be a super-symbol of the search key since if it were, - // then it would be a match, and we're assuming the match key doesn't exist. - // Therefore, step 2 will correctly return no match. - }; - - DescriptorIndex<const FileDescriptorProto*> index_; - std::vector<std::unique_ptr<const FileDescriptorProto>> files_to_delete_; - - // If file is non-nullptr, copy it into *output and return true, otherwise - // return false. - bool MaybeCopy(const FileDescriptorProto* file, FileDescriptorProto* output); - - GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(SimpleDescriptorDatabase); -}; - -// Very similar to SimpleDescriptorDatabase, but stores all the descriptors -// as raw bytes and generally tries to use as little memory as possible. -// -// The same caveats regarding FindFileContainingExtension() apply as with -// SimpleDescriptorDatabase. -class PROTOBUF_EXPORT EncodedDescriptorDatabase : public DescriptorDatabase { - public: - EncodedDescriptorDatabase(); - ~EncodedDescriptorDatabase() override; - - // Adds the FileDescriptorProto to the database. The descriptor is provided - // in encoded form. The database does not make a copy of the bytes, nor - // does it take ownership; it's up to the caller to make sure the bytes - // remain valid for the life of the database. Returns false and logs an error - // if the bytes are not a valid FileDescriptorProto or if the file conflicted - // with a file already in the database. - bool Add(const void* encoded_file_descriptor, int size); - - // Like Add(), but makes a copy of the data, so that the caller does not - // need to keep it around. - bool AddCopy(const void* encoded_file_descriptor, int size); - - // Like FindFileContainingSymbol but returns only the name of the file. - bool FindNameOfFileContainingSymbol(const std::string& symbol_name, - std::string* output); - - // implements DescriptorDatabase ----------------------------------- - bool FindFileByName(const std::string& filename, - FileDescriptorProto* output) override; - bool FindFileContainingSymbol(const std::string& symbol_name, - FileDescriptorProto* output) override; - bool FindFileContainingExtension(const std::string& containing_type, - int field_number, - FileDescriptorProto* output) override; - bool FindAllExtensionNumbers(const std::string& extendee_type, - std::vector<int>* output) override; - bool FindAllFileNames(std::vector<std::string>* output) override; - - private: - class DescriptorIndex; - // Keep DescriptorIndex by pointer to hide the implementation to keep a - // cleaner header. - std::unique_ptr<DescriptorIndex> index_; - std::vector<void*> files_to_delete_; - - // If encoded_file.first is non-nullptr, parse the data into *output and - // return true, otherwise return false. - bool MaybeParse(std::pair<const void*, int> encoded_file, - FileDescriptorProto* output); - - GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(EncodedDescriptorDatabase); -}; - -// A DescriptorDatabase that fetches files from a given pool. -class PROTOBUF_EXPORT DescriptorPoolDatabase : public DescriptorDatabase { - public: - explicit DescriptorPoolDatabase(const DescriptorPool& pool); - ~DescriptorPoolDatabase() override; - - // implements DescriptorDatabase ----------------------------------- - bool FindFileByName(const std::string& filename, - FileDescriptorProto* output) override; - bool FindFileContainingSymbol(const std::string& symbol_name, - FileDescriptorProto* output) override; - bool FindFileContainingExtension(const std::string& containing_type, - int field_number, - FileDescriptorProto* output) override; - bool FindAllExtensionNumbers(const std::string& extendee_type, - std::vector<int>* output) override; - - private: - const DescriptorPool& pool_; - GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(DescriptorPoolDatabase); -}; - -// A DescriptorDatabase that wraps two or more others. It first searches the -// first database and, if that fails, tries the second, and so on. -class PROTOBUF_EXPORT MergedDescriptorDatabase : public DescriptorDatabase { - public: - // Merge just two databases. The sources remain property of the caller. - MergedDescriptorDatabase(DescriptorDatabase* source1, - DescriptorDatabase* source2); - // Merge more than two databases. The sources remain property of the caller. - // The vector may be deleted after the constructor returns but the - // DescriptorDatabases need to stick around. - explicit MergedDescriptorDatabase( - const std::vector<DescriptorDatabase*>& sources); - ~MergedDescriptorDatabase() override; - - // implements DescriptorDatabase ----------------------------------- - bool FindFileByName(const std::string& filename, - FileDescriptorProto* output) override; - bool FindFileContainingSymbol(const std::string& symbol_name, - FileDescriptorProto* output) override; - bool FindFileContainingExtension(const std::string& containing_type, - int field_number, - FileDescriptorProto* output) override; - // Merges the results of calling all databases. Returns true iff any - // of the databases returned true. - bool FindAllExtensionNumbers(const std::string& extendee_type, - std::vector<int>* output) override; - - - // This function is best-effort. Returns true if at least one underlying - // DescriptorDatabase returns true. - bool FindAllFileNames(std::vector<std::string>* output) override; - - private: - std::vector<DescriptorDatabase*> sources_; - GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(MergedDescriptorDatabase); -}; - -} // namespace protobuf -} // namespace google - -#include <google/protobuf/port_undef.inc> - -#endif // GOOGLE_PROTOBUF_DESCRIPTOR_DATABASE_H__ |