source: icXML/icXML-devel/src/xercesc/internal/XSerializeEngine.hpp @ 2722

Last change on this file since 2722 was 2722, checked in by cameron, 6 years ago

Original Xerces files with import mods for icxercesc

File size: 22.8 KB
Line 
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/*
19 * $Id: XSerializeEngine.hpp 679296 2008-07-24 08:13:42Z borisk $
20 */
21
22#if !defined(XERCESC_INCLUDE_GUARD_XSERIALIZE_ENGINE_HPP)
23#define XERCESC_INCLUDE_GUARD_XSERIALIZE_ENGINE_HPP
24
25#include <icxercesc/util/RefHashTableOf.hpp>
26#include <xercesc/util/ValueVectorOf.hpp>
27#include <xercesc/util/XMLExceptMsgs.hpp>
28
29#include <xercesc/internal/XSerializationException.hpp>
30
31XERCES_CPP_NAMESPACE_BEGIN
32
33class XSerializable;
34class XProtoType;
35class MemoryManager;
36class XSerializedObjectId;
37class BinOutputStream;
38class BinInputStream;
39class XMLGrammarPool;
40class XMLGrammarPoolImpl;
41class XMLStringPool;
42
43class XMLUTIL_EXPORT XSerializeEngine
44{
45public:
46
47    enum { mode_Store
48         , mode_Load
49    };
50
51
52    static const bool toReadBufferLen;
53
54    typedef unsigned int   XSerializedObjectId_t;
55
56    /***
57      *
58      *  Destructor
59      *
60      ***/
61    ~XSerializeEngine();
62
63    /***
64      *
65      *  Constructor for de-serialization(loading)
66      *
67      *  Application needs to make sure that the instance of
68      *  BinInputStream, persists beyond the life of this
69      *  SerializeEngine.
70      *
71      *  Param
72      *     inStream         input stream
73      *     gramPool         Grammar Pool
74      *     bufSize          the size of the internal buffer
75      *
76      ***/
77    XSerializeEngine(BinInputStream*         inStream
78                   , XMLGrammarPool* const   gramPool
79                   , XMLSize_t               bufSize = 8192 );
80
81
82    /***
83      *
84      *  Constructor for serialization(storing)
85      *
86      *  Application needs to make sure that the instance of
87      *  BinOutputStream, persists beyond the life of this
88      *  SerializeEngine.
89      *
90      *  Param
91      *     outStream        output stream
92      *     gramPool         Grammar Pool
93      *     bufSize          the size of the internal buffer
94      *
95      ***/
96    XSerializeEngine(BinOutputStream*        outStream
97                   , XMLGrammarPool* const   gramPool
98                   , XMLSize_t               bufSize = 8192 );
99
100    /***
101      *
102      *  When serialization, flush out the internal buffer
103      *
104      *  Return:
105      *
106      ***/
107    void flush();
108
109    /***
110      *
111      *  Checking if the serialize engine is doing serialization(storing)
112      *
113      *  Return: true, if it is
114      *          false, otherwise
115      *
116      ***/
117    inline bool isStoring() const;
118
119    /***
120      *
121      *  Checking if the serialize engine is doing de-serialization(loading)
122      *
123      *  Return: true, if it is
124      *          false, otherwise
125      *
126      ***/
127    inline bool isLoading() const;
128
129    /***
130      *
131      *  Get the GrammarPool
132      *
133      *  Return: XMLGrammarPool
134      *
135      ***/
136    XMLGrammarPool* getGrammarPool() const;
137
138    /***
139      *
140      *  Get the StringPool
141      *
142      *  Return: XMLStringPool
143      *
144      ***/
145    XMLStringPool* getStringPool() const;
146
147    /***
148      *
149      *  Get the embeded Memory Manager
150      *
151      *  Return: MemoryManager
152      *
153      ***/
154    MemoryManager* getMemoryManager() const;
155
156    /***
157      *
158      *  Get the storer level (the level of the serialize engine
159      *  which created the binary stream that this serialize engine
160      *  is loading).
161      *
162      *  The level returned is meaningful only when
163      *  the engine isLoading.
164      *
165      *  Return: level
166      *
167      ***/
168    inline unsigned int getStorerLevel() const;
169
170    /***
171      *
172      *  Write object to the internal buffer.
173      *
174      *  Param
175      *     objectToWrite:    the object to be serialized
176      *
177      *  Return:
178      *
179      ***/
180           void           write(XSerializable* const objectToWrite);
181
182    /***
183      *
184      *  Write prototype info to the internal buffer.
185      *
186      *  Param
187      *     protoType:    instance of prototype
188      *
189      *  Return:
190      *
191      ***/
192           void           write(XProtoType* const protoType);
193
194    /***
195      *
196      *  Write a stream of XMLByte to the internal buffer.
197      *
198      *  Param
199      *     toWrite:   the stream of XMLByte to write
200      *     writeLen:  the length of the stream
201      *
202      *  Return:
203      *
204      ***/
205           void           write(const XMLByte* const toWrite
206                               ,      XMLSize_t      writeLen);
207
208    /***
209      *
210      *  Write a stream of XMLCh to the internal buffer.
211      *
212      *  Param
213      *     toWrite:   the stream of XMLCh to write
214      *     writeLen:  the length of the stream
215      *
216      *  Return:
217      *
218      ***/
219           void           write(const XMLCh* const toWrite
220                               ,      XMLSize_t    writeLen);
221
222    /***
223      *
224      *  Write a stream of XMLCh to the internal buffer.
225      *
226      *  Write the bufferLen first if requested, then the length
227      *  of the stream followed by the stream.
228      *
229      *  Param
230      *     toWrite:        the stream of XMLCh to write
231      *     bufferLen:      the maximum size of the buffer
232      *     toWriteBufLen:  specify if the bufferLen need to be written or not
233      *
234      *  Return:
235      *
236      ***/
237           void           writeString(const XMLCh* const toWrite
238                                    , const XMLSize_t    bufferLen = 0
239                                    , bool               toWriteBufLen = false);
240
241    /***
242      *
243      *  Write a stream of XMLByte to the internal buffer.
244      *
245      *  Write the bufferLen first if requested, then the length
246      *  of the stream followed by the stream.
247      *
248      *  Param
249      *     toWrite:        the stream of XMLByte to write
250      *     bufferLen:      the maximum size of the buffer
251      *     toWriteBufLen:  specify if the bufferLen need to be written or not
252      *
253      *  Return:
254      *
255      ***/
256           void           writeString(const XMLByte* const toWrite
257                                    , const XMLSize_t      bufferLen = 0
258                                    , bool                 toWriteBufLen = false);
259
260    static const bool toWriteBufferLen;
261
262    /***
263      *
264      *  Read/Create object from the internal buffer.
265      *
266      *  Param
267      *     protoType:    an instance of prototype of the object anticipated
268      *
269      *  Return:          to object read/created
270      *
271      ***/
272               XSerializable* read(XProtoType* const protoType);
273
274    /***
275      *
276      *  Read prototype object from the internal buffer.
277      *  Verify if the same prototype object found in buffer.
278      *
279      *  Param
280      *     protoType:    an instance of prototype of the object anticipated
281      *     objTag:       the object Tag to an existing object
282      *
283      *  Return:          true  : if matching found
284      *                   false : otherwise
285      *
286      ***/
287           bool           read(XProtoType* const    protoType
288                                     , XSerializedObjectId_t*       objTag);
289
290    /***
291      *
292      *  Read XMLByte stream from the internal buffer.
293      *
294      *  Param
295      *     toRead:   the buffer to hold the XMLByte stream
296      *     readLen:  the length of the XMLByte to read in
297      *
298      *  Return:
299      *
300      ***/
301           void           read(XMLByte* const toRead
302                             , XMLSize_t      readLen);
303
304    /***
305      *
306      *  Read XMLCh stream from the internal buffer.
307      *
308      *  Param
309      *     toRead:   the buffer to hold the XMLCh stream
310      *     readLen:  the length of the XMLCh to read in
311      *
312      *  Return:
313      *
314      ***/
315           void           read(XMLCh* const toRead
316                             , XMLSize_t    readLen);
317
318    /***
319      *
320      *  Read a stream of XMLCh from the internal buffer.
321      *
322      *  Read the bufferLen first if requested, then the length
323      *  of the stream followed by the stream.
324      *
325      *  Param
326      *     toRead:       the pointer to the buffer to hold the XMLCh stream
327      *     bufferLen:    the size of the buffer created
328      *     dataLen:       the length of the stream
329      *     toReadBufLen: specify if the bufferLen need to be read or not
330      *
331      *  Return:
332      *
333      ***/
334           void           readString(XMLCh*&        toRead
335                                   , XMLSize_t&     bufferLen
336                                   , XMLSize_t&     dataLen
337                                   , bool           toReadBufLen = false);
338
339     /***
340       *
341       *  Read a stream of XMLCh from the internal buffer.
342       *
343       *  Read the bufferLen first if requested, then the length
344       *  of the stream followed by the stream.
345       *
346       *  Param
347       *     toRead:       the pointer to the buffer to hold the XMLCh stream
348       *     bufferLen:    the size of the buffer created
349       *
350       *  Return:
351       *
352       ***/
353            inline void     readString(XMLCh*&        toRead
354                                    , XMLSize_t&      bufferLen);
355
356     /***
357       *
358       *  Read a stream of XMLCh from the internal buffer.
359       *
360       *  Param
361       *     toRead:       the pointer to the buffer to hold the XMLCh stream
362       *
363       *  Return:
364       *
365       ***/
366            inline void      readString(XMLCh*&        toRead);
367
368    /***
369      *
370      *  Read a stream of XMLByte from the internal buffer.
371      *
372      *  Read the bufferLen first if requested, then the length
373      *  of the stream followed by the stream.
374      *
375      *  Param
376      *     toRead:       the pointer to the buffer to hold the XMLByte stream
377      *     bufferLen:    the size of the buffer created
378      *     dataLen:       the length of the stream
379      *     toReadBufLen: specify if the bufferLen need to be read or not
380      *
381      *  Return:
382      *
383      ***/
384           void           readString(XMLByte*&      toRead
385                                   , XMLSize_t&     bufferLen
386                                   , XMLSize_t&     dataLen
387                                   , bool           toReadBufLen = false);
388
389
390     /***
391       *
392       *  Read a stream of XMLByte from the internal buffer.
393       *
394       *  Read the bufferLen first if requested, then the length
395       *  of the stream followed by the stream.
396       *
397       *  Param
398       *     toRead:       the pointer to the buffer to hold the XMLByte stream
399       *     bufferLen:    the size of the buffer created
400       *
401       *  Return:
402       *
403       ***/
404            inline void       readString(XMLByte*&      toRead
405                                       , XMLSize_t&     bufferLen);
406
407     /***
408       *
409       *  Read a stream of XMLByte from the internal buffer.
410       *
411       *  Read the bufferLen first if requested, then the length
412       *  of the stream followed by the stream.
413       *
414       *  Param
415       *     toRead:       the pointer to the buffer to hold the XMLByte stream
416       *     bufferLen:    the size of the buffer created
417       *     dataLen:       the length of the stream
418       *     toReadBufLen: specify if the bufferLen need to be read or not
419       *
420       *  Return:
421       *
422       ***/
423            inline void       readString(XMLByte*&      toRead);
424
425    /***
426      *
427      *  Check if the template object has been stored or not
428      *
429      *  Param
430      *    objectPtr:     the template object pointer
431      *
432      *  Return:          true  : the object has NOT been stored yet
433      *                   false : otherwise
434      *
435      ***/
436           bool           needToStoreObject(void* const templateObjectToWrite);
437
438    /***
439      *
440      *  Check if the template object has been loaded or not
441      *
442      *  Param
443      *    objectPtr:     the address of the template object pointer
444      *
445      *  Return:          true  : the object has NOT been loaded yet
446      *                   false : otherwise
447      *
448      ***/
449           bool           needToLoadObject(void**       templateObjectToRead);
450
451    /***
452      *
453      *  In the case of needToLoadObject() return true, the client
454      *  application needs to instantiate an expected template object, and
455      *  register the address to the engine.
456      *
457      *  Param
458      *    objectPtr:     the template object pointer newly instantiated
459      *
460      *  Return:
461      *
462      ***/
463           void           registerObject(void* const templateObjectToRegister);
464
465    /***
466      *
467      *  Insertion operator for serializable classes
468      *
469      ***/
470
471        friend XSerializeEngine& operator<<(XSerializeEngine&
472                                      , XSerializable* const );
473
474    /***
475      *
476      *  Insertion operators for
477      *     . basic Xerces data types
478      *     . built-in types
479      *
480      ***/
481           XSerializeEngine& operator<<(XMLByte);
482           XSerializeEngine& operator<<(XMLCh);
483
484           XSerializeEngine& operator<<(char);
485           XSerializeEngine& operator<<(short);
486           XSerializeEngine& operator<<(int);
487           XSerializeEngine& operator<<(unsigned int);
488           XSerializeEngine& operator<<(long);
489           XSerializeEngine& operator<<(unsigned long);
490           XSerializeEngine& operator<<(float);
491           XSerializeEngine& operator<<(double);
492           XSerializeEngine& operator<<(bool);
493
494    // These cannot be done as operators since on some platforms they
495    // may collide with int/long types.
496    //
497    void writeSize (XMLSize_t);
498    void writeInt64 (XMLInt64);
499    void writeUInt64 (XMLUInt64);
500
501
502    /***
503      *
504      *  Extraction operators for
505      *     . basic Xerces data types
506      *     . built-in types
507      *
508      ***/
509           XSerializeEngine& operator>>(XMLByte&);
510           XSerializeEngine& operator>>(XMLCh&);
511
512           XSerializeEngine& operator>>(char&);
513           XSerializeEngine& operator>>(short&);
514           XSerializeEngine& operator>>(int&);
515           XSerializeEngine& operator>>(unsigned int&);
516           XSerializeEngine& operator>>(long&);
517           XSerializeEngine& operator>>(unsigned long&);
518           XSerializeEngine& operator>>(float&);
519           XSerializeEngine& operator>>(double&);
520           XSerializeEngine& operator>>(bool&);
521
522    void readSize (XMLSize_t&);
523    void readInt64 (XMLInt64&);
524    void readUInt64 (XMLUInt64&);
525
526    /***
527      *
528      *  Getters
529      *
530      ***/
531    inline
532    XMLSize_t       getBufSize()    const;
533
534    inline
535    XMLSize_t       getBufCur()     const;
536
537    inline
538    XMLSize_t       getBufCurAccumulated()     const;
539
540    inline
541    unsigned long   getBufCount()    const;
542
543    void                  trace(char*)     const;
544
545private:
546    // -----------------------------------------------------------------------
547    //  Unimplemented constructors and operators
548    // -----------------------------------------------------------------------
549        XSerializeEngine();
550    XSerializeEngine(const XSerializeEngine&);
551        XSerializeEngine& operator=(const XSerializeEngine&);
552
553    /***
554      *
555      *   Store Pool Opertions
556      *
557      ***/
558           XSerializedObjectId_t  lookupStorePool(void* const objectPtr) const;
559           void                   addStorePool(void* const objectPtr);
560
561    /***
562      *
563      *   Load Pool Opertions
564      *
565      ***/
566           XSerializable* lookupLoadPool(XSerializedObjectId_t objectTag) const;
567           void           addLoadPool(void* const objectPtr);
568
569    /***
570      *
571      *    Intenal Buffer Operations
572      *
573      ***/
574    inline void           checkAndFillBuffer(XMLSize_t bytesNeedToRead);
575
576    inline void           checkAndFlushBuffer(XMLSize_t bytesNeedToWrite);
577
578           void           fillBuffer();
579
580           void           flushBuffer();
581
582           void           pumpCount();
583
584    inline void           resetBuffer();
585
586    /***
587      *
588      *    Helper
589      *
590      ***/
591    inline void            ensureStoring()                          const;
592
593    inline void            ensureLoading()                          const;
594
595    inline void            ensureStoreBuffer()                      const;
596
597    inline void            ensureLoadBuffer()                       const;
598
599    inline void            ensurePointer(void* const)               const;
600
601    inline void            Assert(bool  toEval
602                                , const XMLExcepts::Codes toThrow)  const;
603
604
605    inline XMLSize_t       calBytesNeeded(XMLSize_t)  const;
606
607    inline XMLSize_t       alignAdjust(XMLSize_t)     const;
608
609    inline void            alignBufCur(XMLSize_t);
610
611    // Make XTemplateSerializer friend of XSerializeEngine so that
612    // we can call lookupStorePool and lookupLoadPool in the case of
613    // annotations.
614    friend class XTemplateSerializer;
615
616    // -------------------------------------------------------------------------------
617    //  data
618    //
619    //  fStoreLoad:
620    //               Indicator: storing(serialization) or loading(de-serialization)
621    //
622    //  fStorerLevel:
623    //              The level of the serialize engine which created the binary
624    //              stream that this serialize engine is loading
625    //
626    //              It is set by GrammarPool when loading
627    //
628    //  fGrammarPool:
629    //               Thw owning GrammarPool which instantiate this SerializeEngine
630    //               instance
631    //
632    //  fInputStream:
633    //               Binary stream to read from (de-serialization), provided
634    //               by client application, not owned.
635    //
636    //  fOutputStream:
637    //               Binary stream to write to (serialization), provided
638    //               by client application, not owned.
639    //
640    //  fBufSize:
641    //               The size of the internal buffer
642    //
643    //  fBufStart/fBufEnd:
644    //
645    //               The internal buffer.
646    //  fBufEnd:
647    //               one beyond the last valid cell
648    //               fBufEnd === (fBufStart + fBufSize)
649    //
650    //  fBufCur:
651    //               The cursor of the buffer
652    //
653    //  fBufLoadMax:
654    //               Indicating the end of the valid content in the buffer
655    //
656    //  fStorePool:
657    //                Object collection for storing
658    //
659    //  fLoadPool:
660    //                Object collection for loading
661    //
662    //  fMapCount:
663    // -------------------------------------------------------------------------------
664    const short                            fStoreLoad;
665    unsigned int                           fStorerLevel;
666
667    XMLGrammarPool*  const                 fGrammarPool;
668    BinInputStream*  const                 fInputStream;
669    BinOutputStream* const                 fOutputStream;
670
671    unsigned long                          fBufCount;
672
673    //buffer
674    const XMLSize_t                        fBufSize;
675        XMLByte* const                         fBufStart;
676        XMLByte* const                         fBufEnd;
677    XMLByte*                               fBufCur;
678    XMLByte*                               fBufLoadMax;
679
680
681
682    /***
683     *   Map for storing object
684     *
685     *   key:   XSerializable*
686     *          XProtoType*
687     *
688     *   value: XMLInteger*, owned
689     *
690     ***/
691    RefHashTableOf<XSerializedObjectId, PtrHasher>*   fStorePool;
692
693    /***
694     *   Vector for loading object, objects are NOT owned
695     *
696     *   data:   XSerializable*
697     *           XProtoType*
698     *
699     ***/
700    ValueVectorOf<void*>*                  fLoadPool;
701
702    /***
703     *   object counter
704     ***/
705        XSerializedObjectId_t                  fObjectCount;
706
707    //to allow grammar pool to set storer level when loading
708    friend class XMLGrammarPoolImpl;
709};
710
711inline bool XSerializeEngine::isStoring() const
712{
713    return (fStoreLoad == mode_Store);
714}
715
716inline bool XSerializeEngine::isLoading() const
717{
718    return (fStoreLoad == mode_Load);
719}
720
721inline XSerializeEngine& operator<<(XSerializeEngine&       serEng
722                                  , XSerializable* const    serObj)
723{
724        serEng.write(serObj);
725    return serEng;
726}
727
728inline void XSerializeEngine::ensureStoring() const
729{
730        Assert(isStoring(), XMLExcepts::XSer_Storing_Violation);
731}
732
733inline void XSerializeEngine::ensureLoading() const
734{
735        Assert(isLoading(), XMLExcepts::XSer_Loading_Violation);
736}
737
738
739
740inline void XSerializeEngine::Assert(bool toEval
741                                   , const XMLExcepts::Codes toThrow) const
742{
743    if (!toEval)
744    {
745        ThrowXMLwithMemMgr(XSerializationException, toThrow, getMemoryManager());
746    }
747
748}
749
750inline void XSerializeEngine::readString(XMLCh*&        toRead
751                                       , XMLSize_t&     bufferLen)
752{
753    XMLSize_t dummyDataLen;
754    readString(toRead, bufferLen, dummyDataLen);
755}
756
757inline void XSerializeEngine::readString(XMLCh*&        toRead)
758{
759    XMLSize_t dummyBufferLen;
760    XMLSize_t dummyDataLen;
761    readString(toRead, dummyBufferLen, dummyDataLen);
762}
763
764inline void XSerializeEngine::readString(XMLByte*&      toRead
765                                       , XMLSize_t&     bufferLen)
766{
767    XMLSize_t dummyDataLen;
768    readString(toRead, bufferLen, dummyDataLen);
769}
770
771inline void XSerializeEngine::readString(XMLByte*&      toRead)
772{
773    XMLSize_t dummyBufferLen;
774    XMLSize_t dummyDataLen;
775    readString(toRead, dummyBufferLen, dummyDataLen);
776}
777
778inline
779XMLSize_t XSerializeEngine::getBufSize() const
780{
781    return fBufSize;
782}
783
784inline
785XMLSize_t XSerializeEngine::getBufCur() const
786{
787    return (fBufCur-fBufStart);
788}
789
790inline
791XMLSize_t XSerializeEngine::getBufCurAccumulated() const
792{
793    return (fBufCount - (isStoring() ? 0: 1)) * fBufSize + (fBufCur-fBufStart);
794}
795
796inline
797unsigned long XSerializeEngine::getBufCount() const
798{
799    return fBufCount;
800}
801
802inline
803unsigned int XSerializeEngine::getStorerLevel() const
804{
805    return fStorerLevel;
806}
807
808/***
809 *  Ought to be nested class
810 ***/
811class XSerializedObjectId : public XMemory
812{
813public:
814
815    ~XSerializedObjectId(){};
816
817private:
818
819    inline XSerializedObjectId(XSerializeEngine::XSerializedObjectId_t val):
820        fData(val) { };
821
822    inline XSerializeEngine::XSerializedObjectId_t getValue() const {return fData; };
823
824    friend class XSerializeEngine;
825
826private:
827    // -----------------------------------------------------------------------
828    //  Unimplemented constructors and operators
829    // -----------------------------------------------------------------------
830        XSerializedObjectId();
831    XSerializedObjectId(const XSerializedObjectId&);
832        XSerializedObjectId& operator=(const XSerializedObjectId&);
833
834    XSerializeEngine::XSerializedObjectId_t    fData;
835
836};
837
838
839XERCES_CPP_NAMESPACE_END
840
841#endif
Note: See TracBrowser for help on using the repository browser.