Back to index

lightning-sunbird  0.9+nobinonly
orkinCell.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-  */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1999
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either of the GNU General Public License Version 2 or later (the "GPL"),
00026  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef _ORKINCELL_
00039 #define _ORKINCELL_ 1
00040 
00041 #ifndef _MDB_
00042 #include "mdb.h"
00043 #endif
00044 
00045 #ifndef _MORK_
00046 #include "mork.h"
00047 #endif
00048 
00049 #ifndef _MORKNODE_
00050 #include "morkNode.h"
00051 #endif
00052 
00053 #ifndef _MORKHANDLE_
00054 #include "morkHandle.h"
00055 #endif
00056 
00057 #ifndef _MORKCELL_
00058 #include "morkCell.h"
00059 #endif
00060 
00061 //3456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789
00062 
00063 #define morkMagic_kCell 0x43656C6C /* ascii 'Cell' */
00064 
00065 class orkinCell : public morkHandle, public nsIMdbCell { // nsIMdbBlob
00066 
00067 // { ===== begin morkNode interface =====
00068 public: // morkNode virtual methods
00069   // virtual void CloseMorkNode(morkEnv* ev); // morkHandle is fine
00070   virtual ~orkinCell(); // morkHandle destructor does everything
00071   
00072 protected: // construction is protected (use the static Make() method)
00073   orkinCell(morkEnv* ev, // note morkUsage is always morkUsage_kPool
00074     morkHandleFace* ioFace,    // must not be nil, cookie for this handle
00075     morkCellObject* ioObject); // must not be nil, the object for this handle
00076     
00077   // void CloseHandle(morkEnv* ev); // don't need to specialize closing
00078 
00079 private: // copying is not allowed
00080   orkinCell(const morkHandle& other);
00081   orkinCell& operator=(const morkHandle& other);
00082 
00083 // public: // dynamic type identification
00084   // mork_bool IsHandle() const //
00085   // { return IsNode() && mNode_Derived == morkDerived_kHandle; }
00086 // } ===== end morkNode methods =====
00087 
00088 protected: // morkHandle memory management operators
00089   void* operator new(size_t inSize, morkPool& ioPool, morkZone& ioZone, morkEnv* ev) CPP_THROW_NEW
00090   { return ioPool.NewHandle(ev, inSize, &ioZone); }
00091   
00092   void* operator new(size_t inSize, morkPool& ioPool, morkEnv* ev) CPP_THROW_NEW
00093   { return ioPool.NewHandle(ev, inSize, (morkZone*) 0); }
00094   
00095   void* operator new(size_t inSize, morkHandleFace* ioFace) CPP_THROW_NEW
00096   { MORK_USED_1(inSize); return ioFace; }
00097   
00098   
00099 public: // construction:
00100 
00101   static orkinCell* MakeCell(morkEnv* ev, morkCellObject* ioObject);
00102 
00103 public: // utilities:
00104 
00105   // ResyncWithRow() moved to the morkCellObject class:
00106   // mork_bool ResyncWithRow(morkEnv* ev); // return ev->Good()
00107 
00108   morkEnv* CanUseCell(nsIMdbEnv* ev, mork_bool inMutable,
00109     mdb_err* outErr, morkCell** outCell) const;
00110 
00111 public: // type identification
00112   mork_bool IsOrkinCell() const
00113   { return mHandle_Magic == morkMagic_kCell; }
00114 
00115   mork_bool IsOrkinCellHandle() const
00116   { return this->IsHandle() && this->IsOrkinCell(); }
00117 
00118   NS_DECL_ISUPPORTS
00119 
00120 // { ===== begin nsIMdbObject methods =====
00121 
00122   // { ----- begin attribute methods -----
00123   NS_IMETHOD IsFrozenMdbObject(nsIMdbEnv* ev, mdb_bool* outIsReadonly);
00124   // same as nsIMdbPort::GetIsPortReadonly() when this object is inside a port.
00125   // } ----- end attribute methods -----
00126 
00127   // { ----- begin factory methods -----
00128   NS_IMETHOD GetMdbFactory(nsIMdbEnv* ev, nsIMdbFactory** acqFactory); 
00129   // } ----- end factory methods -----
00130 
00131   // { ----- begin ref counting for well-behaved cyclic graphs -----
00132   NS_IMETHOD GetWeakRefCount(nsIMdbEnv* ev, // weak refs
00133     mdb_count* outCount);  
00134   NS_IMETHOD GetStrongRefCount(nsIMdbEnv* ev, // strong refs
00135     mdb_count* outCount);
00136 
00137   NS_IMETHOD AddWeakRef(nsIMdbEnv* ev);
00138   NS_IMETHOD AddStrongRef(nsIMdbEnv* ev);
00139 
00140   NS_IMETHOD CutWeakRef(nsIMdbEnv* ev);
00141   NS_IMETHOD CutStrongRef(nsIMdbEnv* ev);
00142   
00143   NS_IMETHOD CloseMdbObject(nsIMdbEnv* ev); // called at strong refs zero
00144   NS_IMETHOD IsOpenMdbObject(nsIMdbEnv* ev, mdb_bool* outOpen);
00145   // } ----- end ref counting -----
00146   
00147 // } ===== end nsIMdbObject methods =====
00148 
00149 // { ===== begin nsIMdbBlob methods =====
00150 
00151   // { ----- begin attribute methods -----
00152   NS_IMETHOD SetBlob(nsIMdbEnv* ev,
00153     nsIMdbBlob* ioBlob); // reads inBlob slots
00154   // when inBlob is in the same suite, this might be fastest cell-to-cell
00155   
00156   NS_IMETHOD ClearBlob( // make empty (so content has zero length)
00157     nsIMdbEnv* ev);
00158   // clearing a yarn is like SetYarn() with empty yarn instance content
00159   
00160   NS_IMETHOD GetBlobFill(nsIMdbEnv* ev,
00161     mdb_fill* outFill);  // size of blob 
00162   // Same value that would be put into mYarn_Fill, if one called GetYarn()
00163   // with a yarn instance that had mYarn_Buf==nil and mYarn_Size==0.
00164   
00165   NS_IMETHOD SetYarn(nsIMdbEnv* ev, 
00166     const mdbYarn* inYarn);   // reads from yarn slots
00167   // make this text object contain content from the yarn's buffer
00168   
00169   NS_IMETHOD GetYarn(nsIMdbEnv* ev, 
00170     mdbYarn* outYarn);  // writes some yarn slots 
00171   // copy content into the yarn buffer, and update mYarn_Fill and mYarn_Form
00172   
00173   NS_IMETHOD AliasYarn(nsIMdbEnv* ev, 
00174     mdbYarn* outYarn); // writes ALL yarn slots
00175   // AliasYarn() reveals sensitive internal text buffer state to the caller
00176   // by setting mYarn_Buf to point into the guts of this text implementation.
00177   //
00178   // The caller must take great care to avoid writing on this space, and to
00179   // avoid calling any method that would cause the state of this text object
00180   // to change (say by directly or indirectly setting the text to hold more
00181   // content that might grow the size of the buffer and free the old buffer).
00182   // In particular, callers should scrupulously avoid making calls into the
00183   // mdb interface to write any content while using the buffer pointer found
00184   // in the returned yarn instance.  Best safe usage involves copying content
00185   // into some other kind of external content representation beyond mdb.
00186   //
00187   // (The original design of this method a week earlier included the concept
00188   // of very fast and efficient cooperative locking via a pointer to some lock
00189   // member slot.  But let's ignore that complexity in the current design.)
00190   //
00191   // AliasYarn() is specifically intended as the first step in transferring
00192   // content from nsIMdbBlob to a nsString representation, without forcing extra
00193   // allocations and/or memory copies. (A standard nsIMdbBlob_AsString() utility
00194   // will use AliasYarn() as the first step in setting a nsString instance.)
00195   //
00196   // This is an alternative to the GetYarn() method, which has copy semantics
00197   // only; AliasYarn() relaxes a robust safety principle only for performance
00198   // reasons, to accomodate the need for callers to transform text content to
00199   // some other canonical representation that would necessitate an additional
00200   // copy and transformation when such is incompatible with the mdbYarn format.
00201   //
00202   // The implementation of AliasYarn() should have extremely little overhead
00203   // besides the virtual dispatch to the method implementation, and the code
00204   // necessary to populate all the mdbYarn member slots with internal buffer
00205   // address and metainformation that describes the buffer content.  Note that
00206   // mYarn_Grow must always be set to nil to indicate no resizing is allowed.
00207   
00208   // } ----- end attribute methods -----
00209 
00210 // } ===== end nsIMdbBlob methods =====
00211 
00212 // { ===== begin nsIMdbCell methods =====
00213 
00214   // { ----- begin attribute methods -----
00215   NS_IMETHOD SetColumn(nsIMdbEnv* ev, mdb_column inColumn); 
00216   NS_IMETHOD GetColumn(nsIMdbEnv* ev, mdb_column* outColumn);
00217   
00218   NS_IMETHOD GetCellInfo(  // all cell metainfo except actual content
00219     nsIMdbEnv* ev, 
00220     mdb_column* outColumn,           // the column in the containing row
00221     mdb_fill*   outBlobFill,         // the size of text content in bytes
00222     mdbOid*     outChildOid,         // oid of possible row or table child
00223     mdb_bool*   outIsRowChild);  // nonzero if child, and a row child
00224 
00225   // Checking all cell metainfo is a good way to avoid forcing a large cell
00226   // in to memory when you don't actually want to use the content.
00227   
00228   NS_IMETHOD GetRow(nsIMdbEnv* ev, // parent row for this cell
00229     nsIMdbRow** acqRow);
00230   NS_IMETHOD GetPort(nsIMdbEnv* ev, // port containing cell
00231     nsIMdbPort** acqPort);
00232   // } ----- end attribute methods -----
00233 
00234   // { ----- begin children methods -----
00235   NS_IMETHOD HasAnyChild( // does cell have a child instead of text?
00236     nsIMdbEnv* ev,
00237     mdbOid* outOid,  // out id of row or table (or unbound if no child)
00238     mdb_bool* outIsRow); // nonzero if child is a row (rather than a table)
00239 
00240   NS_IMETHOD GetAnyChild( // access table of specific attribute
00241     nsIMdbEnv* ev, // context
00242     nsIMdbRow** acqRow, // child row (or null)
00243     nsIMdbTable** acqTable); // child table (or null)
00244 
00245 
00246   NS_IMETHOD SetChildRow( // access table of specific attribute
00247     nsIMdbEnv* ev, // context
00248     nsIMdbRow* ioRow); // inRow must be bound inside this same db port
00249 
00250   NS_IMETHOD GetChildRow( // access row of specific attribute
00251     nsIMdbEnv* ev, // context
00252     nsIMdbRow** acqRow); // acquire child row (or nil if no child)
00253 
00254 
00255   NS_IMETHOD SetChildTable( // access table of specific attribute
00256     nsIMdbEnv* ev, // context
00257     nsIMdbTable* inTable); // table must be bound inside this same db port
00258 
00259   NS_IMETHOD GetChildTable( // access table of specific attribute
00260     nsIMdbEnv* ev, // context
00261     nsIMdbTable** acqTable); // acquire child table (or nil if no child)
00262   // } ----- end children methods -----
00263 
00264 // } ===== end nsIMdbCell methods =====
00265 };
00266 
00267 //3456789_123456789_123456789_123456789_123456789_123456789_123456789_123456789
00268 
00269 #endif /* _ORKINCELL_ */