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 181 of file catalogsdb.h.
Constructor & Destructor Documentation
◆ DBManager()
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.
Member Function Documentation
◆ add_object() [1/2]
std::pair< bool, QString > DBManager::add_object | ( | const int | catalog_id, |
const CatalogObject & | obj | ||
) |
Add the
to a table with object
. 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 677 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 686 of file catalogsdb.cpp.
◆ add_objects()
std::pair< bool, QString > CatalogsDB::DBManager::add_objects | ( | const int | catalog_id, |
const CatalogObjectVector & | objects | ||
) |
Add the
to a table with objects
. 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 1041 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 394 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 336 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
to another with id_1
id_2
.
Useful to create a custom catalog from an immutable one.
Definition at line 912 of file catalogsdb.cpp.
◆ db_file_name()
|
inline |
- Returns
- the filename of the database
Definition at line 226 of file catalogsdb.h.
◆ dump_catalog()
Dumps the catalog with
into the file under the path id
. 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 737 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 516 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
and then return a new instance of name
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 489 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 1076 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 952 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 1093 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 377 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 1162 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 1188 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 1031 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 620 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 1021 of file catalogsdb.cpp.
◆ get_object()
std::pair< bool, CatalogObject > DBManager::get_object | ( | const CatalogObject::oid & | oid | ) |
Get an object by
. oid
Optinally a
can be speicfied.catalog_id
- Returns
- if the object was found and the object itself
Definition at line 537 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 561 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 578 of file catalogsdb.cpp.
◆ get_objects_all()
CatalogObjectList DBManager::get_objects_all | ( | ) |
Get all objects from the database.
Definition at line 570 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
of catalog_id
type
with magnitude smaller than maglim
(smaller = brighter) from the database.
Optionally one can filter by
. catalog_id
Definition at line 588 of file catalogsdb.cpp.
◆ get_objects_in_trixel()
|
inline |
- Returns
- return a vector of objects in the trixel with
id
.
Definition at line 252 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 259 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 266 of file catalogsdb.h.
◆ htmesh_level()
|
inline |
- Returns
- return the htmesh level used by the catalog db
Definition at line 357 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
is set to true. Immutable catalogs are overwritten by default.overwrite
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 799 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 1194 of file catalogsdb.cpp.
◆ register_catalog()
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 308 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 878 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
from the catalog with the oid
. catalog_id
Refreshes the master catalog.
- Returns
- wether the operation was successful and if not, an error message
Definition at line 722 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 601 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 931 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 241 of file catalogsdb.cpp.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Jun 5 2023 03:56:24 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.