Schema.hpp

// Copyright (c) 2004-2023 TIBCO Software Inc.  All rights reserved.

#ifndef STREAMBASE_SCHEMA_H
#define STREAMBASE_SCHEMA_H

#if !(defined(WIN32) || defined(__APPLE__))
#include <limits.h>
#endif

#include "StreamBase.hpp"

#include <cassert>

#include "Exceptions.hpp"
#include "SBHashMap.hpp"

SB_INTERNAL_FWD(SchemaUtil);
SB_INTERNAL_FWD(Errors);

SB_NAMESPACE_BEGIN;

class Field;
class Tuple;
class Timestamp;
class JavaQBox;
class SchemaRep;

/// Error parsing a tuple as a delimited string
STREAMBASE_EXCEPTION_TYPE(TupleStringParseException, sb_internal::Errors::NON_FATAL_ERROR);

/// No field found with the given name or index
STREAMBASE_EXCEPTION_TYPE(NoSuchFieldException, sb_internal::Errors::NON_FATAL_ERROR);

/// Field path name contained an not-leaf segment whose type was not TUPLE
STREAMBASE_EXCEPTION_TYPE(NonTupleFieldInPath, sb_internal::Errors::NON_FATAL_ERROR);

#ifndef DOXYGEN_SKIP
///
/// A hash func that knows how to work on a string
struct StringHashFunc
{
    size_t operator()(const std::string &str) const
    {
        const std::string::value_type *buffer = str.data();
        size_t hashcode = 0;
        for (unsigned int i = 0; i < str.size(); i++)
        {
            // TODO: Find a better hash function or something.
            hashcode = (37 * hashcode) + *(buffer++);
        }
        return hashcode;
    }
};
#endif

/// A type of tuple, containing zero or more fields (each encapsulated
/// as a Schema::Field object).
///
/// Schemas are immutable: once constructed they may not be
/// changed.
class Schema
{
private:
    /// The length of hashes returned by the hash() method.
    static const int HASH_LENGTH = 16; 

    /// The header of each tuple has a tuple id (an unsigned int)
    /// which requires a fixed amount of space. In addition,
    /// a variable size word aligned bit field containing a mask
    /// for null fields is added to the header after the schema 
    /// is created.
    static const int HEADER_SIZE = 4;

public:
        typedef sb::Field Field;

    static const Schema EMPTY_SCHEMA;

    /// Flags for creating a schema.  
    enum Flags {
        /// @deprecated ignored
        NO_HEADER = 1
    };

    /// Creates an uninitialized Schema. This should NOT be used
    /// to create a Schema with no fields; to construct such a Schema
    /// use one of the other overloads and pass an empty list of fields.
    Schema();
    ~Schema();
    
    /// Copy constructor
    Schema(const Schema& schema);
    
    /// Assignment operator
    Schema& operator=(const Schema&);

    /// Constructs a Schema from a sequence of Field objects.
    template <typename Iterator>
    Schema(std::string name, Iterator begin, Iterator end, Flags flags = Flags());

    /// Constructs a Schema from a sequence of Field objects.
    template <typename Iterator>
    Schema(Iterator begin, Iterator end, Flags flags = Flags());

    /// Constructs a Schema from a vector of Field objects.
    /// If the vector is empty the Schema will contain no fields.
    Schema(std::string name, const std::vector<Field>& fields, Flags flags = Flags());

    /// Constructs a Schema from a vector of Field objects.
    /// If the vector is empty the Schema will contain no fields.
    Schema(const std::vector<Field>& fields, Flags flags = Flags());

  private:
    // hash_map<> or map<>? Does the hash calc overhead overwhelm the 
    // the calc time for map to do a operator<? In some benchmarks (on linux) 
    // hash_map<> was faster than map<> in all cases. KDM 3/16/06
    typedef QUALIFIED_SB_HASH_MAP<std::string, int, StringHashFunc> FieldIndexMap;
    typedef QUALIFIED_SB_HASH_MAP<std::string, Field, StringHashFunc> FieldPathMap;

  public:
    /// Returns a non-null value if the object was not created with
    /// the no-argument constructor, i.e., this is a meaningful
    /// Schema.
    ///
    /// Useful in the following manner:
    ///
    /// <pre>
    /// Schema td = callSomeMethod();
    /// if (td) {
    ///     cout << "someMethod returned a valid Schema: " << td << endl;
    /// } else {
    ///     cout << "no such Schema" << endl;
    /// }
    /// </pre>
    operator const void *() const { return _isInitialized ? _rep.get() : (const void*) NULL; }

    /// Return true if the schema has space for a header, false otherwise. 
    /// @deprecated
    bool hasHeader() const {
        return true;
    }

    /// Return the size of the header.
    size_t getHeaderSize() const {
        return HEADER_SIZE;
    }

#ifndef DOXYGEN_SKIP
    /// Return the size of the Null mask.
    size_t getNullMaskSize() const;

    /// Return the offset of the Null mask.
    size_t getNullMaskOffset() const {
        if ( hasHeader() )
            return HEADER_SIZE;
        else
            return 0;
    }
#endif

    /// Return the Fields object description of a field in the schema.
    ///
    /// @param field_num the zero-relative index of the field. 
    /// @throws NoSuchFieldException if field_num is too large
    const Field& getField(size_t field_num) const;

    /// Return the Fields object description of a field in the schema.
    ///
    /// @param pathName the path name of the field to fetch.
    /// @throws NoSuchFieldException if field is not found.
    const Field& getField(const std::string &pathName) const;

        /// Returns true if a field of a given path name is present,
        /// otherwise it returns false.
        ///
        /// @param pathName the path name of the field to fetch.
        const bool hasField(const std::string &pathName) const;

    /// Returns a reference to a vector of all fields in the schema.
    const std::vector<Field>& getFields() const;

    /// Returns the index of the field with a particular name (note: <b>not</b> 
    /// path name), or -1 if there is no such field.
    int indexOfField(const std::string &name) const;

    /// Returns the name of the schema or empty string at runtime.
    const std::string &getName() const;

    /// Returns the number of fields in the schema.
    size_t getNumFields() const;

    /// Returns a string representation of the schema.
    std::string as_string() const;

#ifndef DOXYGEN_SKIP
    /// Returns an XML representation of this schema.
    ///
    /// @param name a name to use if the schema is anonymous (ignored
    ///    if the schema has a name)
    /// @param aAddUUID add the UUID to the XML output
    std::string as_xml(std::string name = std::string(), bool aAddUUID = true) const;
#endif

    /// Returns true if this schema has the same field types in the
    /// same order as another Schema.
    bool sameFieldTypes(const Schema& other) const;

    /// Returns true if this schema has the same field Names and Types
    /// in the same order as another Schema
    bool sameFields(const Schema& other) const;

    /// Parse and return a schema from an XML string.  The root tag must be
    /// &lt;schema&gt;.
    static Schema fromXml(const std::string &input, Flags flags = Flags());

    bool operator == (const Schema& other) const;
    bool operator != (const Schema& other) const {
        return !(*this == other);
    }

private:

    // Add a field to the description.
    void addField(const Field& f);

    // Computes and sets _header_size
    // Add a sequence of fields to the description.
    template <typename Iterator>
    void addFields(Iterator begin, Iterator end) {
        while (begin != end)
            addField(*(begin++));
    }

    void resolveFieldPathName(const std::string& pathName, std::vector<Field>& fields) const;

private:
    std::shared_ptr<SchemaRep> _rep;
    bool _isInitialized;
    friend class sb_internal::SchemaUtil;
    friend class SchemaRep;
};

SB_NAMESPACE_END;

inline std::ostream& operator << (std::ostream& os, const sb::Schema& schema) {
    os << schema.as_string();
    return os;
}

#endif