source: NonGTP/Xerces/xerces-c_2_8_0/include/xercesc/internal/XSerializeEngine.hpp @ 2674

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