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_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
}

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 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 668 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 677 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 1032 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 393 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 335 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 903 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 225 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 728 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 515 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 488 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 1067 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 943 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 1084 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 376 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 1153 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 1179 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 1022 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 611 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 1012 of file catalogsdb.cpp.

◆ get_object()

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 536 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 560 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 569 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 579 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 251 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 258 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 265 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 351 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 790 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 1185 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. 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 307 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 869 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 713 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 592 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 922 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 240 of file catalogsdb.cpp.


The documentation for this class was generated from the following files:
Manages the catalog database and provides an interface to provide an interface to query and modify th...
Definition: catalogsdb.h:181
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Aug 18 2022 03:56:49 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.