CatalogsDB::DBManager
#include <catalogsdb.h>
Public Member Functions | |
DBManager (const DBManager &other) | |
DBManager (const QString &filename) | |
std::pair< bool, QString > | add_object (const int catalog_id, const CatalogObject &obj) |
std::pair< bool, QString > | 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) |
std::pair< bool, QString > | add_objects (const int catalog_id, const CatalogObjectVector &objects) |
bool | catalog_exists (const int id) |
bool | compile_master_catalog () |
std::pair< bool, QString > | copy_objects (const int id_1, const int id_2) |
const QString & | db_file_name () const |
std::pair< bool, QString > | dump_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, Catalog > | get_catalog (const int id) |
ColorMap | get_catalog_colors () |
CatalogColorMap | get_catalog_colors (const int id) |
const std::pair< bool, CatalogStatistics > | get_catalog_statistics (const int catalog_id) |
const std::vector< Catalog > | get_catalogs (bool include_disabled=false) |
const std::pair< bool, CatalogStatistics > | get_master_statistics () |
std::pair< bool, CatalogObject > | get_object (const CatalogObject::oid &oid) |
std::pair< bool, CatalogObject > | get_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, QString > | import_catalog (const QString &file_path, const bool overwrite=false) |
std::pair< bool, QString > | insert_catalog_colors (const int id, const CatalogColorMap &colors) |
DBManager & | operator= (DBManager other) |
std::pair< bool, QString > | register_catalog (const Catalog &cat) |
std::pair< bool, QString > | 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 ×tamp=cat_defaults.timestamp) |
std::pair< bool, QString > | remove_catalog (const int id) |
std::pair< bool, QString > | remove_object (const int catalog_id, const CatalogObject::oid &id) |
std::pair< bool, QString > | set_catalog_enabled (const int id, const bool enabled) |
std::pair< bool, QString > | update_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:
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()
|
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()
|
inline |
- Returns
- the filename of the database
Definition at line 227 of file catalogsdb.h.
◆ dump_catalog()
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
-
limit Upper limit to the quanitity of results. -1
means "no limit"exactMatchOnly If 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 formscheme: 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
istrue
, 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()
|
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()
|
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()
|
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()
|
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=()
Definition at line 197 of file catalogsdb.h.
◆ register_catalog() [1/2]
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
. Theall_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()
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:
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.