KDbTableOrQuerySchema.h

/* This file is part of the KDE project
   Copyright (C) 2004-2015 Jarosław Staniek <[email protected]>
 
   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.
 
   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.
 
   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
*/
 
#ifndef KDBTABLEORQUERYSCHEMA_H
#define KDBTABLEORQUERYSCHEMA_H
 
#include <QByteArray>
 
#include "KDbQueryColumnInfo.h"
 
class KDbConnection;
class KDbFieldList;
class KDbTableSchema;
class KDbQuerySchema;
 
/*! Variant class providing a pointer to table or query. */
class KDB_EXPORT KDbTableOrQuerySchema
{
public:
    //! Type of object: table or query
    //! @since 3.1
    enum class Type {
        Table,
        Query
    };
 
    /*! Creates a new KDbTableOrQuerySchema variant object, retrieving table or query schema
     using @a conn connection and @a name. If both table and query exists for @a name,
     table has priority over query.
     Check whether a query or table has been found by testing (query() || table()) expression. */
    KDbTableOrQuerySchema(KDbConnection *conn, const QByteArray& name);
 
    /*! Creates a new KDbTableOrQuerySchema variant object, retrieving table or query schema
     using @a conn connection and @a name. If @a type is Table, @a name is assumed
     to be a table name, otherwise @a name is assumed to be a query name.
     Check whether a query or table has been found by testing (query() || table()) expression.
     @since 3.1 */
    KDbTableOrQuerySchema(KDbConnection *conn, const QByteArray &name, Type type);
 
    /*! Creates a new KDbTableOrQuerySchema variant object. @a tableOrQuery should be of
     class KDbTableSchema or KDbQuerySchema.
     Check whether a query or table has been found by testing (query() || table()) expression. */
    explicit KDbTableOrQuerySchema(KDbFieldList *tableOrQuery);
 
    /*! Creates a new KDbTableOrQuerySchema variant object, retrieving table or query schema
     using @a conn connection and @a id.
     Check whether a query or table has been found by testing (query() || table()) expression. */
    KDbTableOrQuerySchema(KDbConnection *conn, int id);
 
    /*! Creates a new KDbTableOrQuerySchema variant object, keeping a pointer to @a table
     object. */
    explicit KDbTableOrQuerySchema(KDbTableSchema* table);
 
    /*! Creates a new KDbTableOrQuerySchema variant object, keeping a pointer to @a query
     object. */
    explicit KDbTableOrQuerySchema(KDbQuerySchema* query);
 
    ~KDbTableOrQuerySchema();
 
    //! @return a pointer to the query if it's provided
    KDbQuerySchema* query() const;
 
    //! @return a pointer to the table if it's provided
    KDbTableSchema* table() const;
 
    //! @return name of a query or table
    QByteArray name() const;
 
    //! @return caption (if present) or name of the table/query
    QString captionOrName() const;
 
    /**
     * @brief Returns number of columns within record set returned from specified table or query
     *
     * In case of query expanded fields list is counted.
     * For tables @a conn is not required.
     * Returns -1 if the object has neither table or query assigned.
     * Returns -1 if the object has query assigned but @a conn is @c nullptr.
     */
    int fieldCount(KDbConnection *conn) const;
 
    /*! Mode for columns(). */
    enum class ColumnsMode {
        NonUnique, //!< Non-unique columns are returned
        Unique     //!< Unique columns are returned
    };
 
    //! @return all columns for the table or the query
    const KDbQueryColumnInfo::Vector columns(KDbConnection *conn, ColumnsMode mode = ColumnsMode::NonUnique);
 
    /*! @return a field of the table or the query schema for name @a name
     or 0 if there is no such field. */
    KDbField* field(const QString& name);
 
    /*! Like KDbField* field(const QString& name);
     but returns all information associated with field/column @a name. */
    KDbQueryColumnInfo* columnInfo(KDbConnection *conn, const QString& name);
 
private:
    class Private;
    Private * const d;
 
    Q_DISABLE_COPY(KDbTableOrQuerySchema)
};
 
//! A pair (connection, table-or-schema) for QDebug operator<<
//! @since 3.1
typedef std::tuple<KDbConnection*, const KDbTableOrQuerySchema&> KDbConnectionAndSchema;
 
//! Sends information about table or query schema and connection @a connectionAndSchema to debug output @a dbg.
//! @since 3.1
KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbConnectionAndSchema &connectionAndSchema);
 
#endif