casacore
SSMStringHandler.h
Go to the documentation of this file.
1 //# SSMStringHandler.h: Store strings in the Standard Storage Manager
2 //# Copyright (C) 2000
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef TABLES_SSMSTRINGHANDLER_H
29 #define TABLES_SSMSTRINGHANDLER_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/OS/Conversion.h>
35 #include <casacore/casa/BasicSL/String.h>
36 #include <casacore/casa/Arrays/Array.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations.
41 class SSMBase;
42 
43 
44 // <summary>
45 // Store strings in the Standard Storage Manager.
46 // </summary>
47 
48 // <use visibility=local>
49 
50 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tSSMStringHandler.cc">
51 // </reviewed>
52 
53 // <prerequisite>
54 //# Classes you should understand before using this one.
55 // <li> <linkto class=SSMBase>SSMBase</linkto>
56 // </prerequisite>
57 
58 // <etymology>
59 // SSMStringHandler handles strings for the Standard Storage Manager.
60 // </etymology>
61 
62 // <synopsis>
63 // Variable length strings cannot be stored in the data bucket.
64 // Only short (<8 characters) strings can be stored directly.
65 // Class SSMStringhandler is used by the SSM to store strings in
66 // so-called string buckets.
67 // A string bucket has the following layout:
68 // <ul>
69 // <li> The first Int is reserved to be used for the free bucket list.
70 // <li> <src>itsUsedLength</src> tells how many bytes have been used.
71 // Thus it tells the next free byte in the string part.
72 // In principle it always increases. Only if data are removed
73 // from the last part of the string part, it is decreased, thus
74 // the deleted part can be reused again.
75 // <li> <src>itsNDeleted</src> tells how many bytes of the string part
76 // are deleted (i.e. not used). Initially it is the length of the
77 // string part of the bucket (i.e. bucketsize minus 4 Ints).
78 // When a string is stored, its length is subtracted from itsNDeleted.
79 // When a string is removed, its length is added again.
80 // When the string part is deleted, the bucket is added to the
81 // free bucket list.
82 // <li> <src>itsNextBucket</src> tells the next bucket if the last
83 // entry in the bucket is continued in another bucket.
84 // Normally this field is -1 (meaning not continued), but long
85 // strings or string arrays might be continued in another bucket
86 // (and continued from there again).
87 // <li> The string part is a sequence of bytes containing the string
88 // data. When a value is to be stored, it will replace the current
89 // value if the new value is not longer. Otherwise the current
90 // value (if any) is deleted and the new value is appended to
91 // the end of the string part in the last bucket used.
92 // <p>
93 // For a scalar string only its characters are stored. Its length
94 // (and bucketnr and offset in string bucket) are stored in the data
95 // bucket.
96 // <br>
97 // A fixed length array is stored as an array of bytes. That byte
98 // array contains length-value pairs for each element of the array.
99 // The total length (and bucketnr and offset) are stored in the data
100 // bucket.
101 // <br>
102 // A variable length array is stored as the shape, a flag, optionally
103 // followed by the string array as length-value pairs (as above).
104 // The shape consists of the nr of dimensions followed by the
105 // length of each dimension. The flag indicates if a string array
106 // is actually stored. It is not if only the shape of the array
107 // is set, but no data put yet.
108 // </ul>
109 // SSMStringHandler keeps a copy of the current bucket in use to reduce
110 // the number of accesses to the bucket cache.
111 // <p>
112 // It also keeps the bucket number of the last bucket where data were
113 // added to. It tells which bucket to use when new data has to be stored.
114 // </synopsis>
115 
116 //# <todo asof="$DATE:$">
117 //# A List of bugs, limitations, extensions or planned refinements.
118 //# </todo>
119 
121 {
122 public:
123  // Default constructor initializes last string bucket to -1.
125 
127 
128  // Set or get last string bucketnr.
129  // Setting is needed when an existing table is opened.
130  // <group>
132  Int lastStringBucket() const;
133  // </group>
134 
135  // Put a single string or an array of strings into a bucket.
136  // If its length does not exceed the given length, it reuses
137  // the currently used space (given by bucketnr and offset).
138  // Otherwise it adds the data to the last string bucket.
139  // It fills the offset and bucketnr where the data are stored and the
140  // length occupied in the buckets.
141  // An array of strings is flattened first (a la SSMColumn::writeString).
142  // <br>
143  // If <src>handleShape</src> is True (for variable shaped arrays), the
144  // shape will be put first.
145  // <group>
146  void put (Int& bucketNr, Int& offset, Int& length,
147  const String& string);
148  void put (Int& bucketNr, Int& offset, Int& length,
149  const Array<String>& string, Bool handleShape);
150  // </group>
151 
152  // Put a single string or an array of strings into a bucket.
153  // If its length does not exceed the given length, it reuses
154  // the currently used space (given by bucketnr and offset).
155  // Otherwise it adds the data to the last string bucket.
156  // It fills the offset and bucketnr where stored and the
157  // length occupied in the buckets.
158  void putShape (Int& bucketNr, Int& offset, Int& length,
159  const IPosition& aShape);
160 
161  // Get the shape in the given bucket and offset.
162  // It sets the offset to the data right after the shape.
163  // The IPosition object is resized as needed.
164  void getShape (IPosition& aShape, Int bucket, Int& offset, Int length);
165 
166  // Remove data with the given length from a bucket.
167  // If the data are continued in next bucket(s), they will be
168  // removed there as well.
169  void remove (Int bucketNr, Int offset, Int length);
170 
171  // Get a string or an array of strings.
172  // The array must have the correct shape.
173  // <src>handleShape</src> will be True for variable shaped arrays
174  // indicating that the data are preceeded by the shape.
175  // <group>
176  void get (String& string, Int bucket, Int offset, Int length);
177  void get (Array<String>& string, Int bucket, Int offset,
178  Int length, Bool handleShape);
179  // </group>
180 
181  // Flush the currently used string bucket.
182  void flush();
183 
184  // Initialize the StringHandler
185  void init();
186 
187  // Resynchronize (after a table lock was acquired).
188  // It clears the itsCurrentBucket variable to assure that buckets
189  // are reread.
190  void resync();
191 
192 private:
193  // Forbid copy constructor and assignment.
194  // <group>
197  // </group>
198 
199  // Get the given bucket and make it current.
200  // It first writes the current bucket if it has changed.
201  // <br>
202  // If <src>isNew</src> is True the bucket is new,
203  // so the Ints at its beginning do not have to be interpreted.
204  void getBucket (uInt bucketNr, Bool isNew=False);
205 
206  // Get a new bucket and make it current.
207  // If <src>doConcat</src> is True, the new bucket is a continuation,
208  // so <src>itsNextBucket</src> in the currently used bucket is filled
209  // with the new bucket number.
210  void getNewBucket (Bool doConcat);
211 
212  // Put the data with the given length at the end of the current bucket.
213  // If they do not fit, they are continued in a new bucket.
214  void putData (Int length, const Char* data);
215 
216  // Get the data with the given length from the curent bucket at the
217  // given offset. If sets the offset to the byte after the data read.
218  // Continuation buckets are followed (and made current).
219  void getData (Int length, Char* data, Int& offset);
220 
221  // Replace the current data with the new data.
222  // It is used by <src>put</src> after having assured that the
223  // new length does not exceed the current one.
224  // It follows continuation buckets as needed.
225  // <group>
226  void replace (Int bucketNr, Int offset, Int length,
227  const String& string);
228  void replace (Int bucketNr, Int offset, Int length, Int totalLength,
229  const IPosition& aShape);
230  void replace (Int bucketNr, Int offset, Int length, Int totalLength,
231  const Array<String>& string, Bool handleShape);
232  void replaceData (Int& offset,Int length, const Char* data);
233  // </group>
234 
235 
236  SSMBase* itsSSMPtr; // Pointer to SSMBase stucture
237  Int itsCurrentBucket; // bucketnr of current string bucket (-1 is none)
238  Int itsLength; // length of bucket in use (only the string part)
239  Int itsNDeleted; // #bytes deleted from the string part of the bucket
240  Int itsUsedLength; // #bytes used from the string part of the bucket
241  Int itsNextBucket; // next bucket for long strings
242  char* itsData; // bucket string data
243  char* itsIntBuf; // buffer for initialisation params
244  Bool isChanged; // has current bucket been changed?
245  uInt itsIntSize; // size of integers in this system
246  Int itsLastBucket; // last string bucket used
247  uInt itsStart; // Start position of actual data in bucket
248 };
249 
250 
251 inline void SSMStringHandler::setLastStringBucket (Int lastStringBucket)
252 {
254 }
255 
257 {
258  return itsLastBucket;
259 }
260 
261 
262 
263 } //# NAMESPACE CASACORE - END
264 
265 #endif
SSMStringHandler(SSMBase *aBase)
Default constructor initializes last string bucket to -1.
SSMStringHandler(const SSMStringHandler &)
Forbid copy constructor and assignment.
void get(String &string, Int bucket, Int offset, Int length)
Get a string or an array of strings.
void init()
Initialize the StringHandler.
void replaceData(Int &offset, Int length, const Char *data)
void setLastStringBucket(Int lastStringBucket)
Set or get last string bucketnr.
void remove(Int bucketNr, Int offset, Int length)
Remove data with the given length from a bucket.
void get(Array< String > &string, Int bucket, Int offset, Int length, Bool handleShape)
void getData(Int length, Char *data, Int &offset)
Get the data with the given length from the curent bucket at the given offset.
void replace(Int bucketNr, Int offset, Int length, Int totalLength, const Array< String > &string, Bool handleShape)
void resync()
Resynchronize (after a table lock was acquired).
void flush()
Flush the currently used string bucket.
void replace(Int bucketNr, Int offset, Int length, const String &string)
Replace the current data with the new data.
void replace(Int bucketNr, Int offset, Int length, Int totalLength, const IPosition &aShape)
void putData(Int length, const Char *data)
Put the data with the given length at the end of the current bucket.
void getNewBucket(Bool doConcat)
Get a new bucket and make it current.
void getBucket(uInt bucketNr, Bool isNew=False)
Get the given bucket and make it current.
SSMStringHandler & operator=(const SSMStringHandler &)
void put(Int &bucketNr, Int &offset, Int &length, const String &string)
Put a single string or an array of strings into a bucket.
void getShape(IPosition &aShape, Int bucket, Int &offset, Int length)
Get the shape in the given bucket and offset.
void putShape(Int &bucketNr, Int &offset, Int &length, const IPosition &aShape)
Put a single string or an array of strings into a bucket.
void put(Int &bucketNr, Int &offset, Int &length, const Array< String > &string, Bool handleShape)
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode length(const LatticeExprNode &expr, const LatticeExprNode &axis)
2-argument function to get the length of an axis.
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
char Char
Definition: aipstype.h:46