StreamBase C++ API  7.6.2dev
Field.hpp
1 //
2 // Copyright (c) 2004-2016 Cloud Software Group, Inc. All rights reserved.
3 //
4 
5 #ifndef STREAMBASE_FIELD_H_
6 #define STREAMBASE_FIELD_H_
7 
8 #include "StreamBase.hpp"
9 
10 #include <string>
11 #include <vector>
12 
13 #include "CompleteDataType.hpp"
14 #include "Schema.hpp"
15 
16 SB_INTERNAL_FWD(SchemaUtil);
17 
18 SB_NAMESPACE_BEGIN;
19 
20  /// Information (name, type, and optionally size) about a field in a Schema.
21  /// <p>
22  /// A field can be looked up within a schema in three ways:
23  /// <ol>
24  /// <li>By index: By the zero-based ordinal position of the field within the
25  /// schema</li>
26  /// <li>By simple name: By the name of the field itself (e.g., "myint")</li>
27  /// <li>By path name: By a dot-separated list of names that define a path
28  /// through a set of nested schemas that arise through the use of fields of
29  /// type Tuple (e.g., "mynestedtuple.myint").</li>
30  /// </ol>
31  /// <p>
32  /// A Field object can be used to obtain the value of a field in a tuple.
33  /// However, there are rules that must be obeyed in doing so. For example,
34  /// one must obtain the Field object from a Schema object that describes the
35  /// schema of the tuple (i.e., as opposed to directly from a Field
36  /// constructor).
37  /// <p>
38  /// See the "client" StreamBase sample (<em>streambase-install-dir</em>/sample/client)
39  /// for examples of proper use of Field objects.
40 class Field {
41  public:
42  /// Constructs a null (invalid) field.
43  Field();
44 
45  // Destroy a field, freeing _schema
46  ~Field();
47 
48  /// Constructs a field; deprecated.
49  /// @deprecated Use Field(std::string&, const CompleteDataType&) instead.
50  Field(const std::string &name, DataType type, size_t size = (size_t)-1);
51 
52  /// Constructs a field; deprecated.
53  /// @deprecated Use Field(std::string&, CompleteDataType::forTuple(const Schema& schema)) instead.
54  Field(const std::string &name, DataType type, const Schema& schema);
55 
56  /// Constructs a field.
57  Field(const std::string &name, const CompleteDataType& cdt);
58 
59  /// Copy constructor
60  Field(const Field& f);
61 
62  /// Assignment operator
63  Field& operator=(const Field& f);
64 
65 #ifndef DOXYGEN_INTERNAL_ONLY
66  /// Returns an XML representation of a field.
67  std::string as_xml() const;
68 #endif
69 
70  /// Returns a string representation of a field.
71  std::string as_string() const;
72 
73  /// Returns the field's schema (valid only if the field's type is TUPLE)
74  const Schema getSchema() const { return _cdt.getSchema(); }
75 
76  /// Returns the name of a field.
77  const std::string &getName() const { return _name; }
78 
79  /// Returns the type of a field (e.g., DataType::INT).
80  const DataType &getType() const { return _cdt.getType(); }
81 
82  /// Returns the complete type of a field (e.g., DataType::LIST of DataType::INTs).
83  const CompleteDataType &getCompleteType() const { return _cdt; }
84 
85  /// Returns the complete type of a field's elements
86  /// (e.g., on a DataType::LIST of DataType::INTs, returns a CompleteDataType of DataType::INT).
88 
89  const CompleteDataType& getReturnType() const {
90  return _cdt.getReturnType();
91  }
92 
93  const Schema& getArgumentSchema() const {
94  return _cdt.getArgumentSchema();
95  }
96 
97  /// Returns the size of a field if it has a fixed size or -1
98  size_t getFixedSize() const {
99  return getType().getSize();
100  }
101 
102  /// Returns the index of the field
103  int getIndex() const { return _index; }
104 
105  /// Return true if the fields are the same type (including
106  /// size information)
107  bool sameType(const Field &other) const {
108  return _cdt == other._cdt;
109  }
110 
111  const std::vector<Field> &getFieldPath() const { return _field_path; }
112 
113 #ifndef DOXYGEN_INTERNAL_ONLY
114  /// The size of the header at the beginning of variably-sized data types
115  static const int VARLEN_HEADER_SIZE = 4;
116 
117  /// The size of the header at the beginning of every string.
118  static const int STRING_HEADER_SIZE = VARLEN_HEADER_SIZE;
119 
120  /// The size of the header at the beginning of every nested tuple.
121  static const int NESTED_TUPLE_HEADER_SIZE = VARLEN_HEADER_SIZE;
122 
123  /// The size of the header at the beginning of every list.
124  static const int LIST_HEADER_SIZE = VARLEN_HEADER_SIZE + 4;
125 #endif
126 
127  private:
128  Field(const std::vector<Field>& field_path);
129 
130  std::string _name;
131  CompleteDataType _cdt;
132  size_t _size;
133  int _index;
134  std::vector<Field> _field_path; // non-empty only for Fields that are paths
135 
136  std::string as_xml_helper(const CompleteDataType& cdt, std::string tag, std::string name) const;
137 
138  friend class Schema;
139  friend class sb_internal::SchemaUtil;
140  friend class JavaQBox;
141 };
142 
143 SB_NAMESPACE_END;
144 
145 #endif /*STREAMBASE_FIELD_H_*/