server/storage/entities-header.xsl

0001 <!--
0002     SPDX-FileCopyrightText: 2006-2007 Volker Krause <vkrause@kde.org>
0003
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 -->
0006
0007 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
0008                 version="1.0">
0009
0010 <!-- table class header template -->
0011 <xsl:template name="table-header">
0012 <xsl:variable name="className"><xsl:value-of select="@name"/></xsl:variable>
0013 <xsl:variable name="entityName"><xsl:value-of select="@name"/></xsl:variable>
0014
0015 /**
0016   Representation of a record in the <xsl:value-of select="$entityName"/> table.
0017   <xsl:if test="comment != ''">
0018   &lt;br&gt;
0019   <xsl:value-of select="comment"/>
0020   </xsl:if>
0021   This class is implicitly shared.
0022 */
0023 class <xsl:value-of select="$className"/> : private Entity
0024 {
0025     friend class DataStore;
0026
0027 public:
0028     /// List of <xsl:value-of select="$entityName"/> records.
0029     typedef QList&lt;<xsl:value-of select="$className"/>&gt; List;
0030
0031     // make some stuff accessible from Entity:
0032     using Entity::Id;
0033     using Entity::id;
0034     using Entity::setId;
0035     using Entity::isValid;
0036     using Entity::joinByName;
0037     using Entity::addToRelation;
0038     using Entity::removeFromRelation;
0039
0040     <xsl:for-each select="enum">
0041     enum <xsl:value-of select="@name"/> {
0042       <xsl:for-each select="value">
0043       <xsl:value-of select="@name"/><xsl:if test="@value"> = <xsl:value-of select="@value"/></xsl:if>,
0044       </xsl:for-each>
0045     };
0046     </xsl:for-each>
0047
0048     // constructor
0049     <xsl:value-of select="$className"/>();
0050     explicit <xsl:value-of select="$className"/>(
0051     <xsl:for-each select="column[@name != 'id']">
0052       <xsl:call-template name="argument"/><xsl:if test="position() != last()">, </xsl:if>
0053     </xsl:for-each> );
0054     <xsl:if test="column[@name = 'id']">
0055     explicit <xsl:value-of select="$className"/>(
0056     <xsl:for-each select="column">
0057       <xsl:call-template name="argument"/><xsl:if test="position() != last()">, </xsl:if>
0058     </xsl:for-each> );
0059     </xsl:if>
0060     <xsl:value-of select="$className"/>(const <xsl:value-of select="$className"/> &amp;other);
0061
0062     // destructor
0063     ~<xsl:value-of select="$className"/>();
0064
0065     /// assignment operator
0066     <xsl:value-of select="$className"/> &amp;operator=(const <xsl:value-of select="$className"/> &amp;other);
0067
0068     /// comparison operator, compares ids, not content
0069     bool operator==(const <xsl:value-of select="$className"/> &amp;other) const;
0070
0071     // accessor methods
0072     <xsl:for-each select="column[@name != 'id']">
0073     /**
0074       Returns the value of the <xsl:value-of select="@name"/> column of this record.
0075       <xsl:value-of select="comment"/>
0076     */
0077     <xsl:call-template name="data-type"/><xsl:text> </xsl:text><xsl:value-of select="@name"/>() const;
0078     /**
0079       Sets the value of the <xsl:value-of select="@name"/> column of this record.
0080       <xsl:value-of select="comment"/>
0081     */
0082     void <xsl:call-template name="setter-signature"/>;
0083     </xsl:for-each>
0084
0085     /** Returns the name of the SQL table. */
0086     static QString tableName();
0087
0088     /**
0089       Returns a list of all SQL column names. The names are in the correct
0090       order for usage with extractResult().
0091     */
0092     static QStringList columnNames();
0093
0094     /**
0095       Returns a list of all SQL column names prefixed with their tables names.
0096       The names are in the correct order for usage with extractResult().
0097     */
0098     static QStringList fullColumnNames();
0099
0100     <xsl:for-each select="column">
0101     static QString <xsl:value-of select="@name"/>Column();
0102     static QString <xsl:value-of select="@name"/>FullColumnName();
0103     </xsl:for-each>
0104
0105     /**
0106       Extracts the query result.
0107       @param query A executed query containing a list of <xsl:value-of select="$entityName"/> records.
0108       Note that the fields need to be in the correct order (same as in the constructor)!
0109     */
0110     static QList&lt;<xsl:value-of select="$className"/>&gt; extractResult(QSqlQuery &amp;query);
0111     static QList&lt;<xsl:value-of select="$className"/>&gt; extractResult(DataStore *dataStore, QSqlQuery &amp;query);
0112
0113     /** Count records with value @p value in column @p column. */
0114     static int count(const QString &amp;column, const QVariant &amp;value);
0115     static int count(DataStore *store, const QString &amp;column, const QVariant &amp;value);
0116
0117     // check existence
0118     <xsl:if test="column[@name = 'id']">
0119     /** Checks if a record with id @p id exists. */
0120     static bool exists(qint64 id);
0121     static bool exists(DataStore *store, qint64 id);
0122     </xsl:if>
0123     <xsl:if test="column[@name = 'name']">
0124     /** Checks if a record with name @name exists. */
0125     static bool exists(const <xsl:value-of select="column[@name = 'name']/@type"/> &amp;name);
0126     static bool exists(DataStore *store, const <xsl:value-of select="column[@name = 'name']/@type"/> &amp;name);
0127     </xsl:if>
0128
0129     // data retrieval
0130     <xsl:if test="column[@name = 'id']">
0131     /** Returns the record with id @p id. */
0132     <xsl:text>static </xsl:text><xsl:value-of select="$className"/> retrieveById(qint64 id);
0133     <xsl:text>static </xsl:text><xsl:value-of select="$className"/> retrieveById(DataStore *store, qint64 id);
0134     </xsl:if>
0135
0136     <xsl:if test="column[@name = 'name'] and $className != 'PartType'">
0137     /** Returns the record with name @p name. */
0138     <xsl:text>static </xsl:text><xsl:value-of select="$className"/> retrieveByName(const <xsl:value-of select="column[@name = 'name']/@type"/> &amp;name);
0139     <xsl:text>static </xsl:text><xsl:value-of select="$className"/> retrieveByName(DataStore *store, const <xsl:value-of select="column[@name = 'name']/@type"/> &amp;name);
0140
0141     /** Returns the record with name @p name. If such record does not exist,
0142         it will be created. This method is thread-safe, so if multiple callers
0143         call it on non-existent name, only one will create the new record, others
0144         will wait and read it from the cache. */
0145     <xsl:text>static </xsl:text><xsl:value-of select="$className"/> retrieveByNameOrCreate(const <xsl:value-of select="column[@name = 'name']/@type"/> &amp;name);
0146     <xsl:text>static </xsl:text><xsl:value-of select="$className"/> retrieveByNameOrCreate(DataStore *store, const <xsl:value-of select="column[@name = 'name']/@type"/> &amp;name);
0147     </xsl:if>
0148
0149     <xsl:if test="column[@name = 'name'] and $className = 'PartType'">
0150     <!-- Special case for PartTypes, which are identified by "NS:NAME" -->
0151     <xsl:text>static PartType retrieveByFQName(const QString &amp;ns, const QString &amp;name);</xsl:text>
0152     <xsl:text>static PartType retrieveByFQName(DataStore *store, const QString &amp;ns, const QString &amp;name);</xsl:text>
0153     <xsl:text>static PartType retrieveByFQNameOrCreate(const QString &amp;ns, const QString &amp;name);</xsl:text>
0154     <xsl:text>static PartType retrieveByFQNameOrCreate(DataStore *store, const QString &amp;ns, const QString &amp;name);</xsl:text>
0155     </xsl:if>
0156
0157     /** Retrieve all records from this table. */
0158     static <xsl:value-of select="$className"/>::List retrieveAll();
0159     static <xsl:value-of select="$className"/>::List retrieveAll(DataStore *store);
0160     /** Retrieve all records with value @p value in column @p key. */
0161     static <xsl:value-of select="$className"/>::List retrieveFiltered(const QString &amp;key, const QVariant &amp;value);
0162     static <xsl:value-of select="$className"/>::List retrieveFiltered(DataStore *store, const QString &amp;key, const QVariant &amp;value);
0163
0164     <!-- data retrieval for referenced tables (n:1) -->
0165     <xsl:for-each select="column[@refTable != '']">
0166       <xsl:variable name="method-name"><xsl:call-template name="method-name-n1"><xsl:with-param name="table" select="@refTable"/></xsl:call-template></xsl:variable>
0167     /**
0168       Retrieve the <xsl:value-of select="@refTable"/> record referred to by the
0169       <xsl:value-of select="@name"/> column of this record.
0170     */
0171     <xsl:value-of select="@refTable"/><xsl:text> </xsl:text><xsl:value-of select="$method-name"/>() const;
0172     <xsl:value-of select="@refTable"/><xsl:text> </xsl:text><xsl:value-of select="$method-name"/>(DataStore *store) const;
0173
0174     /**
0175       Set the  <xsl:value-of select="@refTable"/> record referred to by the
0176       <xsl:value-of select="@name"/> column of this record.
0177     */
0178     void set<xsl:call-template name="uppercase-first"><xsl:with-param name="argument"><xsl:value-of select="$method-name"/></xsl:with-param></xsl:call-template>
0179       (const <xsl:value-of select="@refTable"/> &amp;value);
0180     </xsl:for-each>
0181
0182     <!-- data retrieval for inverse referenced tables (1:n) -->
0183     <xsl:for-each select="reference">
0184     /**
0185       Retrieve a list of all <xsl:value-of select="@table"/> records referring to this record
0186       in their column <xsl:value-of select="@key"/>.
0187     */
0188     QList&lt;<xsl:value-of select="@table"/>&gt; <xsl:value-of select="@name"/>() const;
0189     QList&lt;<xsl:value-of select="@table"/>&gt; <xsl:value-of select="@name"/>(DataStore *store) const;
0190     </xsl:for-each>
0191
0192     // data retrieval for n:m relations
0193     <xsl:for-each select="../relation[@table1 = $entityName]">
0194       <xsl:variable name="method-name"><xsl:call-template name="method-name-n1"><xsl:with-param name="table"><xsl:value-of select="@table2"/></xsl:with-param></xsl:call-template></xsl:variable>
0195       QList&lt;<xsl:value-of select="@table2"/>&gt; <xsl:value-of select="$method-name"/>s() const;
0196       QList&lt;<xsl:value-of select="@table2"/>&gt; <xsl:value-of select="$method-name"/>s(DataStore *store) const;
0197     </xsl:for-each>
0198
0199     /**
0200       Inserts this record into the DataStore.
0201       @param insertId pointer to an int, filled with the identifier of this record on success.
0202     */
0203     bool insert(qint64 *insertId = nullptr);
0204     bool insert(DataStore *store, qint64 *insertId = nullptr);
0205
0206     /**
0207       Returns @c true if this record has any pending changes.
0208     */
0209     bool hasPendingChanges() const;
0210
0211     /**
0212       Stores all changes made to this record into the database.
0213       Note that this method assumes the existence of an 'id' column to identify
0214       the record to update. If that column does not exist, all records will be
0215       changed.
0216       @returns true on success, false otherwise.
0217     */
0218     bool update();
0219     bool update(DataStore *store);
0220
0221     <xsl:if test="column[@name = 'id']">
0222     /** Deletes this record. */
0223     bool remove();
0224     bool remove(DataStore *store);
0225
0226     /** Deletes the record with the given id. */
0227     static bool remove(qint64 id);
0228     static bool remove(DataStore *store, qint64 id);
0229     </xsl:if>
0230
0231     /**
0232       Invalidates the cache entry for this record.
0233       This method has no effect if caching is not enabled for this table.
0234     */
0235     void invalidateCache() const;
0236
0237     /**
0238       Invalidates all cache entries for this table.
0239       This method has no effect if caching is not enabled for this table.
0240     */
0241     static void invalidateCompleteCache();
0242
0243     /**
0244       Enable/disable caching for this table.
0245       This method is not thread-safe, call before activating multi-threading.
0246     */
0247     static void enableCache(bool enable);
0248
0249     // manipulate n:m relations
0250     <xsl:for-each select="../relation[@table1 = $entityName]">
0251     <xsl:variable name="rightSideClass"><xsl:value-of select="@table2"/></xsl:variable>
0252     /**
0253       Checks whether this record is in a n:m relation with the <xsl:value-of select="@table2"/> @p value.
0254     */
0255     bool relatesTo<xsl:value-of select="@table2"/>(const <xsl:value-of select="$rightSideClass"/> &amp;value) const;
0256     bool relatesTo<xsl:value-of select="@table2"/>(DataStore *store, const <xsl:value-of select="$rightSideClass"/> &amp;value) const;
0257     static bool relatesTo<xsl:value-of select="@table2"/>(qint64 leftId, qint64 rightId);
0258     static bool relatesTo<xsl:value-of select="@table2"/>(DataStore *store, qint64 leftId, qint64 rightId);
0259
0260     /**
0261       Adds a n:m relation between this record and the <xsl:value-of select="@table2"/> @p value.
0262     */
0263     bool add<xsl:value-of select="@table2"/>(const <xsl:value-of select="$rightSideClass"/> &amp;value) const;
0264     bool add<xsl:value-of select="@table2"/>(DataStore *store, const <xsl:value-of select="$rightSideClass"/> &amp;value) const;
0265     static bool add<xsl:value-of select="@table2"/>(qint64 leftId, qint64 rightId);
0266     static bool add<xsl:value-of select="@table2"/>(DataStore *store, qint64 leftId, qint64 rightId);
0267
0268     /**
0269       Removes a n:m relation between this record and the <xsl:value-of select="@table2"/> @p value.
0270     */
0271     bool remove<xsl:value-of select="@table2"/>(const <xsl:value-of select="$rightSideClass"/> &amp;value) const;
0272     bool remove<xsl:value-of select="@table2"/>(DataStore *store, const <xsl:value-of select="$rightSideClass"/> &amp;value) const;
0273     static bool remove<xsl:value-of select="@table2"/>(qint64 leftId, qint64 rightId);
0274     static bool remove<xsl:value-of select="@table2"/>(DataStore *store, qint64 leftId, qint64 rightId);
0275
0276     /**
0277       Removes all relations between this record and any <xsl:value-of select="@table2"/>.
0278     */
0279     bool clear<xsl:value-of select="@table2"/>s() const;
0280     bool clear<xsl:value-of select="@table2"/>s(DataStore *store) const;
0281     static bool clear<xsl:value-of select="@table2"/>s(qint64 id);
0282     static bool clear<xsl:value-of select="@table2"/>s(DataStore *store, qint64 id);
0283     </xsl:for-each>
0284
0285     // delete records
0286     static bool remove(const QString &amp;column, const QVariant &amp;value);
0287     static bool remove(DataStore *store, const QString &amp;column, const QVariant &amp;value);
0288
0289 private:
0290     class Private;
0291     QSharedDataPointer&lt;Private&gt; d;
0292 };
0293 </xsl:template>
0294
0295 <!-- debug stream operators -->
0296 <xsl:template name="table-debug-header">
0297 <xsl:variable name="className"><xsl:value-of select="@name"/></xsl:variable>
0298
0299 #ifndef QT_NO_DEBUG_STREAM
0300 // debug stream operator
0301 QDebug &amp;operator&lt;&lt;(QDebug &amp;d, const Akonadi::Server::<xsl:value-of select="$className"/> &amp;entity);
0302 #endif
0303 </xsl:template>
0304
0305
0306 <!-- relation class header template -->
0307 <xsl:template name="relation-header">
0308 <xsl:variable name="className"><xsl:value-of select="@table1"/><xsl:value-of select="@table2"/>Relation</xsl:variable>
0309
0310 <xsl:if test="comment != ''">
0311 /**
0312   <xsl:value-of select="comment"/>
0313 */
0314 </xsl:if>
0315 class <xsl:value-of select="$className"/>
0316 {
0317   public:
0318     // SQL table information
0319     static QString tableName();
0320     static QString leftColumn();
0321     static QString leftFullColumnName();
0322     static QString rightColumn();
0323     static QString rightFullColumnName();
0324 };
0325 </xsl:template>
0326
0327 </xsl:stylesheet>