CatalogsDB::DBManager

Search for usage in LXR

CatalogsDB::DBManager Class Reference

#include <catalogsdb.h>

Public Member Functions

 DBManager (const DBManager &other)
 
 DBManager (const QString &filename)
 
std::pair< bool, QStringadd_object (const int catalog_id, const CatalogObject &obj)
 
std::pair< bool, QStringadd_object (const int catalog_id, const SkyObject::TYPE t, const CachingDms &r, const CachingDms &d, const QString &n, const float m=NaN::f, const QString &lname=QString(), const QString &catalog_identifier=QString(), const float a=0.0, const float b=0.0, const double pa=0.0, const float flux=0)
 
std::pair< bool, QStringadd_objects (const int catalog_id, const CatalogObjectVector &objects)
 
bool catalog_exists (const int id)
 
bool compile_master_catalog ()
 
std::pair< bool, QStringcopy_objects (const int id_1, const int id_2)
 
const QStringdb_file_name () const
 
std::pair< bool, QStringdump_catalog (int catalog_id, QString file_path)
 
CatalogObjectList find_objects_by_name (const int catalog_id, const QString &name, const int limit=-1)
 
CatalogObjectList find_objects_by_name (const QString &name, const int limit=-1, const bool exactMatchOnly=false)
 
CatalogObjectList find_objects_by_wildcard (const QString &wildcard, const int limit=-1)
 
int find_suitable_catalog_id ()
 
std::tuple< bool, const QString, CatalogObjectList > general_master_query (const QString &where, const QString &order_by="", const int limit=-1)
 
const std::pair< bool, Catalogget_catalog (const int id)
 
ColorMap get_catalog_colors ()
 
CatalogColorMap get_catalog_colors (const int id)
 
const std::pair< bool, CatalogStatisticsget_catalog_statistics (const int catalog_id)
 
const std::vector< Catalogget_catalogs (bool include_disabled=false)
 
const std::pair< bool, CatalogStatisticsget_master_statistics ()
 
std::pair< bool, CatalogObjectget_object (const CatalogObject::oid &oid)
 
std::pair< bool, CatalogObjectget_object (const CatalogObject::oid &oid, const int catalog_id)
 
CatalogObjectList get_objects (float maglim=default_maglim, int limit=-1)
 
CatalogObjectList get_objects (SkyObject::TYPE type, float maglim=default_maglim, int limit=-1)
 
CatalogObjectList get_objects_all ()
 
CatalogObjectList get_objects_in_catalog (SkyObject::TYPE type, const int catalog_id, float maglim=default_maglim, int limit=-1)
 
CatalogObjectVector get_objects_in_trixel (const int trixel)
 
CatalogObjectVector get_objects_in_trixel_no_nulls (const int trixel)
 
CatalogObjectVector get_objects_in_trixel_null_mag (const int trixel)
 
int htmesh_level () const
 
std::pair< bool, QStringimport_catalog (const QString &file_path, const bool overwrite=false)
 
std::pair< bool, QStringinsert_catalog_colors (const int id, const CatalogColorMap &colors)
 
DBManageroperator= (DBManager other)
 
std::pair< bool, QStringregister_catalog (const Catalog &cat)
 
std::pair< bool, QStringregister_catalog (const int id, const QString &name, const bool mut, const bool enabled, const double precedence, const QString &author=cat_defaults.author, const QString &source=cat_defaults.source, const QString &description=cat_defaults.description, const int version=cat_defaults.version, const QString &color=cat_defaults.color, const QString &license=cat_defaults.license, const QString &maintainer=cat_defaults.maintainer, const QDateTime &timestamp=cat_defaults.timestamp)
 
std::pair< bool, QStringremove_catalog (const int id)
 
std::pair< bool, QStringremove_object (const int catalog_id, const CatalogObject::oid &id)
 
std::pair< bool, QStringset_catalog_enabled (const int id, const bool enabled)
 
std::pair< bool, QStringupdate_catalog_meta (const Catalog &cat)
 
bool update_catalog_views ()
 

Detailed Description

Manages the catalog database and provides an interface to provide an interface to query and modify the database.

For more information on how the catalog database system works see the KStars Handbook.

The class manages a database connection which is assumed to be working (invariant). If the database can't be accessed a DatabaseError is thrown upon construction. The manager is designed to hold as little state as possible because the database should be the single source of truth. Prepared statements are made class members, only if they are performance critical.

Most methods in this class are thread safe.

The intention is that you access a/the catalogs database directly locally in the code where objects from the database are required and not through layers of references and pointers.

The main DSO database can be accessed as follows:

CatalogsDB::DBManager manager{ CatalogsDB::dso_db_path() };
for(auto& o : manager.get_objects(10)) {
// do something
}
Manages the catalog database and provides an interface to provide an interface to query and modify th...
Definition catalogsdb.h:183

To query the database, first check if the required query is already hardcoded into the DBManager. If this is not the case you can either add it (if it is performance critical and executed frequently) or use DBManager::general_master_query to construct a custom SQL query.

Definition at line 182 of file catalogsdb.h.

Constructor & Destructor Documentation

◆ DBManager() [1/2]

DBManager::DBManager ( const QString & filename)

Constructs a database manager from the filename which is resolved to a path in the kstars data directory.

The constructor resolves the path to the database, opens it (throws if that does not work), checks the database version (throws if that does not match), initializes the database, registers the user catalog and updates the all_catalog_view.

Definition at line 80 of file catalogsdb.cpp.

◆ DBManager() [2/2]

DBManager::DBManager ( const DBManager & other)

Definition at line 184 of file catalogsdb.cpp.

◆ ~DBManager()

CatalogsDB::DBManager::~DBManager ( )
inline

Definition at line 218 of file catalogsdb.h.

Member Function Documentation

◆ add_object() [1/2]

std::pair< bool, QString > DBManager::add_object ( const int catalog_id,
const CatalogObject & obj )

Add the `object` to a table with `catalog_id`.

For the rest of the arguments see CatalogObject::CatalogObject.

Returns
wether the operation was successful and if not, an error message

Definition at line 689 of file catalogsdb.cpp.

◆ add_object() [2/2]

std::pair< bool, QString > DBManager::add_object ( const int catalog_id,
const SkyObject::TYPE t,
const CachingDms & r,
const CachingDms & d,
const QString & n,
const float m = NaN::f,
const QString & lname = QString(),
const QString & catalog_identifier = QString(),
const float a = 0.0,
const float b = 0.0,
const double pa = 0.0,
const float flux = 0 )

Add a CatalogObject to a table with `catalog_id`.

For the rest of the arguments see CatalogObject::CatalogObject.

Returns
wether the operation was successful and if not, an error message

Definition at line 698 of file catalogsdb.cpp.

◆ add_objects()

std::pair< bool, QString > CatalogsDB::DBManager::add_objects ( const int catalog_id,
const CatalogObjectVector & objects )

Add the `objects` to a table with `catalog_id`.

For the rest of the arguments see CatalogObject::CatalogObject.

Returns
wether the operation was successful and if not, an error message

Definition at line 1056 of file catalogsdb.cpp.

◆ catalog_exists()

bool DBManager::catalog_exists ( const int id)
Returns
true if the catalog with id exists
Todo
use std::optional when transitioning to c++17

Definition at line 398 of file catalogsdb.cpp.

◆ compile_master_catalog()

bool DBManager::compile_master_catalog ( )

Compiles the master catalog by merging the individual catalogs based on oid and precedence and creates an index by (trixel, magnitude) on the master table.

Caution you may want to call update_catalog_views beforhand.

Returns
true in case of success, false in case of an error

Definition at line 337 of file catalogsdb.cpp.

◆ copy_objects()

std::pair< bool, QString > DBManager::copy_objects ( const int id_1,
const int id_2 )

Clone objects from the catalog with `id_1` to another with id_2.

Useful to create a custom catalog from an immutable one.

Definition at line 926 of file catalogsdb.cpp.

◆ db_file_name()

const QString & CatalogsDB::DBManager::db_file_name ( ) const
inline
Returns
the filename of the database

Definition at line 227 of file catalogsdb.h.

◆ dump_catalog()

std::pair< bool, QString > DBManager::dump_catalog ( int catalog_id,
QString file_path )

Dumps the catalog with `id` into the file under the path file_path.

This file can then be imported with import_catalog. If the file already exists, it will be overwritten.

The user_version and application_id pragmas are set to special values, but otherwise the dump format is equal to the internal database format.

Returns
wether the operation was successful and if not, an error message

Definition at line 749 of file catalogsdb.cpp.

◆ find_objects_by_name() [1/2]

CatalogObjectList DBManager::find_objects_by_name ( const int catalog_id,
const QString & name,
const int limit = -1 )

Find an objects by name in the catalog with `catalog_id`.

Returns
a list of matching objects

Definition at line 526 of file catalogsdb.cpp.

◆ find_objects_by_name() [2/2]

CatalogObjectList DBManager::find_objects_by_name ( const QString & name,
const int limit = -1,
const bool exactMatchOnly = false )

Find an objects by name.

This will search the name, long_name and catalog_identifier fields in all enabled catalogs for `name` and then return a new instance of CatalogObject sourced from the master catalog.

Parameters
limitUpper limit to the quanitity of results. -1 means "no limit"
exactMatchOnlyIf true, the supplied name must match exactly
Returns
a list of matching objects

Definition at line 499 of file catalogsdb.cpp.

◆ find_objects_by_wildcard()

CatalogObjectList CatalogsDB::DBManager::find_objects_by_wildcard ( const QString & wildcard,
const int limit = -1 )

Find an objects by searching the name four wildcard.

See the LIKE sqlite statement.

Returns
a list of matching objects

Definition at line 1091 of file catalogsdb.cpp.

◆ find_suitable_catalog_id()

int DBManager::find_suitable_catalog_id ( )

Finds the smallest free id for a catalog.

Definition at line 966 of file catalogsdb.cpp.

◆ general_master_query()

std::tuple< bool, const QString, CatalogObjectList > CatalogsDB::DBManager::general_master_query ( const QString & where,
const QString & order_by = "",
const int limit = -1 )

Find an objects by searching the master catlog with a query like SELECT ... FROM master WHERE \p where ORDER BY \p order_by ....

To be used if performance does not matter (much). order_by can be ommitted.

Returns
wether the query was successful, an error message if any and a list of matching objects

Definition at line 1108 of file catalogsdb.cpp.

◆ get_catalog()

const std::pair< bool, Catalog > DBManager::get_catalog ( const int id)
Returns
wether the catalog with the id has been found and the catalog.
Todo
use std::optional when transitioning to c++17

Definition at line 381 of file catalogsdb.cpp.

◆ get_catalog_colors() [1/2]

ColorMap CatalogsDB::DBManager::get_catalog_colors ( )
Returns
the catalog colors as a hash table of the form catalog id: scheme: color.

The colors are loaded from the Catalog::color field and the SqlStatements::color_table in that order.

Definition at line 1177 of file catalogsdb.cpp.

◆ get_catalog_colors() [2/2]

CatalogsDB::CatalogColorMap CatalogsDB::DBManager::get_catalog_colors ( const int id)
Returns
the catalog colors as a hash table of for the catalog with id in the form scheme: color.

The colors are loaded from the Catalog::color field and the SqlStatements::color_table in that order.

Definition at line 1203 of file catalogsdb.cpp.

◆ get_catalog_statistics()

const std::pair< bool, CatalogStatistics > DBManager::get_catalog_statistics ( const int catalog_id)
Returns
statistics about the catalog with `catalog_id`.

Definition at line 1046 of file catalogsdb.cpp.

◆ get_catalogs()

const std::vector< Catalog > DBManager::get_catalogs ( bool include_disabled = false)
Returns
a vector with all catalogs from the database. If include_disabled is true, disabled catalogs will be included.

Definition at line 631 of file catalogsdb.cpp.

◆ get_master_statistics()

const std::pair< bool, CatalogStatistics > DBManager::get_master_statistics ( )
Returns
statistics about the master catalog.

Definition at line 1036 of file catalogsdb.cpp.

◆ get_object() [1/2]

std::pair< bool, CatalogObject > DBManager::get_object ( const CatalogObject::oid & oid)

Get an object by `oid`.

Optinally a `catalog_id` can be speicfied.

Returns
if the object was found and the object itself

Definition at line 547 of file catalogsdb.cpp.

◆ get_object() [2/2]

std::pair< bool, CatalogObject > DBManager::get_object ( const CatalogObject::oid & oid,
const int catalog_id )

Definition at line 560 of file catalogsdb.cpp.

◆ get_objects() [1/2]

CatalogObjectList DBManager::get_objects ( float maglim = default_maglim,
int limit = -1 )

Get limit objects with magnitude smaller than maglim (smaller = brighter) from the database.

Definition at line 572 of file catalogsdb.cpp.

◆ get_objects() [2/2]

CatalogObjectList DBManager::get_objects ( SkyObject::TYPE type,
float maglim = default_maglim,
int limit = -1 )

Get limit objects of type with magnitude smaller than maglim (smaller = brighter) from the database.

Optionally one can filter by `catalog_id`.

Definition at line 589 of file catalogsdb.cpp.

◆ get_objects_all()

CatalogObjectList DBManager::get_objects_all ( )

Get all objects from the database.

Definition at line 581 of file catalogsdb.cpp.

◆ get_objects_in_catalog()

CatalogObjectList DBManager::get_objects_in_catalog ( SkyObject::TYPE type,
const int catalog_id,
float maglim = default_maglim,
int limit = -1 )

Get limit objects from the catalog with `catalog_id` of type with magnitude smaller than maglim (smaller = brighter) from the database.

Optionally one can filter by catalog_id.

Definition at line 599 of file catalogsdb.cpp.

◆ get_objects_in_trixel()

CatalogObjectVector CatalogsDB::DBManager::get_objects_in_trixel ( const int trixel)
inline
Returns
return a vector of objects in the trixel with id.

Definition at line 253 of file catalogsdb.h.

◆ get_objects_in_trixel_no_nulls()

CatalogObjectVector CatalogsDB::DBManager::get_objects_in_trixel_no_nulls ( const int trixel)
inline
Returns
return a vector of objects of known mag in the trixel with id.

Definition at line 260 of file catalogsdb.h.

◆ get_objects_in_trixel_null_mag()

CatalogObjectVector CatalogsDB::DBManager::get_objects_in_trixel_null_mag ( const int trixel)
inline
Returns
return a vector of objects of unknown mag in the trixel with id.

Definition at line 267 of file catalogsdb.h.

◆ htmesh_level()

int CatalogsDB::DBManager::htmesh_level ( ) const
inline
Returns
return the htmesh level used by the catalog db

Definition at line 358 of file catalogsdb.h.

◆ import_catalog()

std::pair< bool, QString > DBManager::import_catalog ( const QString & file_path,
const bool overwrite = false )

Loads a dumped catalog from path `file_path`.

Will overwrite an existing catalog if `overwrite` is set to true. Immutable catalogs are overwritten by default.

Checks if the pragma application_id matches CatalogsDB::application_id and the pragma user_version to match the database format version.

Returns
wether the operation was successful and if not, an error message

Definition at line 812 of file catalogsdb.cpp.

◆ insert_catalog_colors()

std::pair< bool, QString > CatalogsDB::DBManager::insert_catalog_colors ( const int id,
const CatalogColorMap & colors )

Saves the configures colors of the catalog with id id in colors into the database.

Returns
wether the insertion was possible and an error message if not.

Definition at line 1209 of file catalogsdb.cpp.

◆ operator=()

DBManager & CatalogsDB::DBManager::operator= ( DBManager other)
inline

Definition at line 197 of file catalogsdb.h.

◆ register_catalog() [1/2]

std::pair< bool, QString > DBManager::register_catalog ( const Catalog & cat)

Definition at line 319 of file catalogsdb.cpp.

◆ register_catalog() [2/2]

std::pair< bool, QString > DBManager::register_catalog ( const int id,
const QString & name,
const bool mut,
const bool enabled,
const double precedence,
const QString & author = cat_defaults.author,
const QString & source = cat_defaults.source,
const QString & description = cat_defaults.description,
const int version = cat_defaults.version,
const QString & color = cat_defaults.color,
const QString & license = cat_defaults.license,
const QString & maintainer = cat_defaults.maintainer,
const QDateTime & timestamp = cat_defaults.timestamp )

Registers a new catalog in the database.

For the parameters

See also
Catalog. The catalog gets inserted into m_catalogs. The all_catalog_view is updated.
Returns
true in case of success, false in case of an error (along with the error)

Definition at line 309 of file catalogsdb.cpp.

◆ remove_catalog()

std::pair< bool, QString > DBManager::remove_catalog ( const int id)

remove a catalog

Returns
true in case of succes, false and an error message in case of an error

This will recreate the master table.

Definition at line 892 of file catalogsdb.cpp.

◆ remove_object()

std::pair< bool, QString > DBManager::remove_object ( const int catalog_id,
const CatalogObject::oid & id )

Remove the catalog object with the `oid` from the catalog with the `catalog_id`.

Refreshes the master catalog.

Returns
wether the operation was successful and if not, an error message

Definition at line 734 of file catalogsdb.cpp.

◆ set_catalog_enabled()

std::pair< bool, QString > DBManager::set_catalog_enabled ( const int id,
const bool enabled )

Enable or disable a catalog.

Returns
true in case of succes, false and an error message in case of an error

This will recreate the master table.

Definition at line 612 of file catalogsdb.cpp.

◆ update_catalog_meta()

std::pair< bool, QString > DBManager::update_catalog_meta ( const Catalog & cat)

Update the metatadata `catalog`.

The updated fields are: title, author, source, description.

Returns
true in case of success, false in case of an error (along with the error).

Definition at line 945 of file catalogsdb.cpp.

◆ update_catalog_views()

bool DBManager::update_catalog_views ( )

Updates the all_catalog_view so that it includes all known catalogs.

Returns
true in case of success, false in case of an error

Definition at line 238 of file catalogsdb.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:15:14 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.