diff options
Diffstat (limited to 'kmymoney2/mymoney/mymoneyfile.h')
| -rw-r--r-- | kmymoney2/mymoney/mymoneyfile.h | 1470 |
1 files changed, 1470 insertions, 0 deletions
diff --git a/kmymoney2/mymoney/mymoneyfile.h b/kmymoney2/mymoney/mymoneyfile.h new file mode 100644 index 0000000..39552c9 --- /dev/null +++ b/kmymoney2/mymoney/mymoneyfile.h @@ -0,0 +1,1470 @@ +/*************************************************************************** + mymoneyfile.h + ------------------- + copyright : (C) 2002, 2007 by Thomas Baumgart + email : ipwizard@users.sourceforge.net + ***************************************************************************/ + +/*************************************************************************** + * * + * This program is free software; you can redistribute it and/or modify * + * it under the terms of the GNU General Public License as published by * + * the Free Software Foundation; either version 2 of the License, or * + * (at your option) any later version. * + * * + ***************************************************************************/ + +#ifndef MYMONEYFILE_H +#define MYMONEYFILE_H + +#ifdef HAVE_CONFIG_H +#include <config.h> +#endif + +// ---------------------------------------------------------------------------- +// QT Includes + +#include <qobject.h> +#include <qstring.h> +#include <qmap.h> +#include <qvaluelist.h> + +// ---------------------------------------------------------------------------- +// Project Includes + +#include <kmymoney/imymoneystorage.h> +#include <kmymoney/mymoneyexception.h> +#include <kmymoney/mymoneyutils.h> +#include <kmymoney/mymoneyinstitution.h> +#include <kmymoney/mymoneyaccount.h> +#include <kmymoney/mymoneytransaction.h> +#include <kmymoney/mymoneypayee.h> +#include <kmymoney/mymoneykeyvaluecontainer.h> +#include <kmymoney/mymoneysecurity.h> +#include <kmymoney/mymoneyprice.h> +#include <kmymoney/mymoneyreport.h> +#include <kmymoney/mymoneybudget.h> +#include <kmymoney/mymoneyscheduled.h> +#include <kmymoney/export.h> + +/** + * @author Thomas Baumgart, Michael Edwardes, Kevin Tambascio + */ + +class IMyMoneyStorage; +class MyMoneyTransactionFilter; + +/** + * This class represents the interface to the MyMoney engine. + * For historical reasons it is still called MyMoneyFile. + * It is implemented using the singleton pattern and thus only + * exists once for each running instance of an application. + * + * The instance of the MyMoneyFile object is accessed as follows: + * + * @code + * MyMoneyFile *file = MyMoneyFile::instance(); + * file->anyMemberFunction(); + * @endcode + * + * The first line of the above code creates a unique MyMoneyFile + * object if it is called for the first time ever. All subsequent + * calls to this functions return a pointer to the object created + * during the first call. + * + * As the MyMoneyFile object represents the business logic, a storage + * manager must be attached to it. This mechanism allows to use different + * access methods to store the objects. The interface to access such an + * storage manager is defined in the class IMyMoneyStorage. The methods + * attachStorage() and detachStorage() are used to attach/detach a + * storage manager object. The following code can be used to create a + * functional MyMoneyFile instance: + * + * @code + * IMyMoneyStorage *storage = .... + * MyMoneyFile *file = MyMoneyFile::instance(); + * file->attachStorage(storage); + * @endcode + * + * The methods addAccount(), modifyAccount() and removeAccount() implement the + * general account maintenance functions. The method reparentAccount() is + * available to move an account from one superordinate account to another. + * account() and accountList() are used to retrieve a single instance or a + * QValueList of MyMoneyAccount objects. + * + * The methods addInstitution(), modifyInstitution() and removeInstitution() + * implement the general institution maintenance functions. institution() and + * institutionList() are used to retrieve a single instance or a + * QValueList of MyMoneyInstitution objects. + * + * The methods addPayee(), modifyPayee() and removePayee() + * implement the general institution maintenance functions. + * payee() and payeeList() are used to retrieve a single instance or a + * QValueList of MyMoneyPayee objects. + * + * The methods addTransaction(), modifyTransaction() and removeTransaction() + * implement the general transaction maintenance functions. + * transaction() and transactionList() are used to retrieve + * a single instance or a QValueList of MyMoneyTransaction objects. + * + * The methods addSecurity(), modifySecurity() and removeSecurity() + * implement the general access to equities held in the engine. + * + * The methods addCurrency(), modifyCurrency() and removeCurrency() + * implement the general access to multiple currencies held in the engine. + * The methods baseCurrency() and setBaseCurrency() allow to retrieve/set + * the currency selected by the user as base currency. If a currency + * reference is emtpy, it will usually be interpreted as baseCurrency(). + * + * The methods liability(), asset(), expense(), income() and equity() are + * used to retrieve the five standard accounts. isStandardAccount() + * checks if a given accountId references one of the or not. + * setAccountName() is used to specify a name for the standard accounts + * from the GUI. + * + * The MyMoneyFile object emits the dataChanged() signal when data + * has been changed. + * + * For abritrary values that have to be stored with the storage object + * but are of importance to the application only, the object is derived + * for MyMoneyKeyValueContainer which provides a container to store + * these values indexed by an alphanumeric key. + * + * @exception MyMoneyException is thrown whenever an error occurs + * while the engine code is running. The MyMoneyException:: object + * describes the problem. + */ +class KMYMONEY_EXPORT MyMoneyFile : public QObject +{ + Q_OBJECT +public: + + class MyMoneyNotifier + { + public: + MyMoneyNotifier(MyMoneyFile* file) { m_file = file; m_file->clearNotification(); }; + ~MyMoneyNotifier() { m_file->notify(); }; + private: + MyMoneyFile* m_file; + }; + + friend class MyMoneyNotifier; + + /** + * This is the function to access the MyMoneyFile object. + * It returns a pointer to the single instance of the object. + */ + static inline MyMoneyFile* instance() { return &file; } + + /** + * This is the destructor for any MyMoneyFile object + */ + ~MyMoneyFile(); + + /** + * @deprecated This is a convenience constructor. Do not use it anymore. + * It will be deprecated in a future version of the engine. + * + * @param storage pointer to object that implements the IMyMoneyStorage + * interface. + */ + MyMoneyFile(IMyMoneyStorage *storage); + + // general get functions + const MyMoneyPayee user(void) const; + + // general set functions + void setUser(const MyMoneyPayee& user); + + /** + * This method is used to attach a storage object to the MyMoneyFile object + * Without an attached storage object, the MyMoneyFile object is + * of no use. + * + * After successful completion, the dataChanged() signal is emitted. + * + * In case of an error condition, an exception is thrown. + * The following error conditions are checked: + * + * - @a storage is not equal to 0 + * - there is no other @a storage object attached (use detachStorage() + * to revert the attachStorage() operation. + * + * @param storage pointer to object that implements the IMyMoneyStorage + * interface. + * + * @sa detachStorage() + */ + void attachStorage(IMyMoneyStorage* const storage); + + /** + * This method is used to detach a previously attached storage + * object from the MyMoneyFile object. If no storage object + * is attached to the engine, this is a NOP. + * + * @param storage pointer to object that implements the IMyMoneyStorage + * interface. + * + * @sa attachStorage() + */ + void detachStorage(IMyMoneyStorage* const storage = 0); + + /** + * This method returns whether a storage is currently attached to + * the engine or not. + * + * @return true if storage object is attached, false otherwise + */ + bool storageAttached(void) const { return m_storage != 0; }; + + /** + * This method returns a pointer to the storage object + * + * @return const pointer to the current attached storage object. + * If no object is attached, returns 0. + */ + IMyMoneyStorage* storage(void) const { return m_storage; }; + + /** + * This method must be called before any single change or a series of changes + * in the underlying storage area is performed. + * Once all changes are complete (i.e. the transaction is completed), + * commitTransaction() must be called to finalize all changes. If an error occurs + * during the processing of the changes call rollbackTransaction() to undo the + * changes done so far. + */ + void startTransaction(void); + + /** + * This method returns whether a transaction has been started (@a true) + * or not (@a false). + */ + bool hasTransaction(void) const; + + /** + * @sa startTransaction() + */ + void commitTransaction(void); + + /** + * @sa startTransaction() + */ + void rollbackTransaction(void); + + /** + * This method is used to return the standard liability account + * @return MyMoneyAccount liability account(group) + */ + const MyMoneyAccount& liability(void) const; + + /** + * This method is used to return the standard asset account + * @return MyMoneyAccount asset account(group) + */ + const MyMoneyAccount& asset(void) const; + + /** + * This method is used to return the standard expense account + * @return MyMoneyAccount expense account(group) + */ + const MyMoneyAccount& expense(void) const; + + /** + * This method is used to return the standard income account + * @return MyMoneyAccount income account(group) + */ + const MyMoneyAccount& income(void) const; + + /** + * This method is used to return the standard equity account + * @return MyMoneyAccount equity account(group) + */ + const MyMoneyAccount& equity(void) const; + + /** + * This method returns the account information for the opening + * balances account for the given @p security. If the respective + * account does not exist, it will be created. The name is constructed + * using MyMoneyFile::OpeningBalancesPrefix and appending " (xxx)" in + * case the @p security is not the baseCurrency(). The account created + * will be a sub-account of the standard equity account provided by equity(). + * + * @param security Security for which the account is searched + * + * @return The opening balance account + * + * @note No notifications will be sent! + */ + const MyMoneyAccount openingBalanceAccount(const MyMoneySecurity& security); + + /** + * This method is essentially the same as the above, except it works on + * const objects. If there is no opening balance account, this method + * WILL NOT create one. Instead it will thrown an exception. + * + * @param security Security for which the account is searched + * + * @return The opening balance account + * + * @note No notifications will be sent! + */ + const MyMoneyAccount openingBalanceAccount(const MyMoneySecurity& security) const; + + /** + * Create an opening balance transaction for the account @p acc + * with a value of @p balance. If the corresponding opening balance account + * for the account's currency does not exist it will be created. If it exists + * and it's opening date is later than the opening date of @p acc, + * the opening date of the opening balances account will be adjusted to the + * one of @p acc. + * + * @param acc reference to account for which the opening balance transaction + * should be created + * @param balance reference to the value of the opening balance transaction + * + * @returns The created MyMoneyTransaction object. In case no transaction has been + * created, the id of the object is empty. + */ + MyMoneyTransaction createOpeningBalanceTransaction(const MyMoneyAccount& acc, const MyMoneyMoney& balance); + + /** + * Retrieve the opening balance transaction for the account @p acc. + * If there is no opening balance transaction, QString() will be returned. + * + * @param acc reference to account for which the opening balance transaction + * should be retrieved + * @return QString id for the transaction, or QString() if no transaction exists + */ + QString openingBalanceTransaction(const MyMoneyAccount& acc) const; + + /** + * This method returns an indicator if the MyMoneyFile object has been + * changed after it has last been saved to permanent storage. + * + * @return true if changed, false if not + */ + bool dirty(void) const; + + /** + * This method is used to force the attached storage object to + * be dirty. This is used by the application to re-set the dirty + * flag after a failed upload to a server when the save operation + * to a local temp file was OK. + */ + void setDirty(void) const; + + /** + * Adds an institution to the file-global institution pool. A + * respective institution-ID will be generated for this object. + * The ID is stored as QString in the object passed as argument. + * + * An exception will be thrown upon error conditions. + * + * @param institution The complete institution information in a + * MyMoneyInstitution object + */ + void addInstitution(MyMoneyInstitution& institution); + + /** + * Modifies an already existing institution in the file global + * institution pool. + * + * An exception will be thrown upon error conditions. + * + * @param institution The complete new institution information + */ + void modifyInstitution(const MyMoneyInstitution& institution); + + /** + * Deletes an existing institution from the file global institution pool + * Also modifies the accounts that reference this institution as + * their institution. + * + * An exception will be thrown upon error conditions. + * + * @param institution institution to be deleted. + */ + void removeInstitution(const MyMoneyInstitution& institution); + + /** + * Adds an account to the file-global account pool. A respective + * account-ID will be generated within this record. The modified + * members of @a account will be updated. + * + * A few parameters of the account to be added are checked against + * the following conditions. If they do not match, an exception is + * thrown. + * + * An account must match the following conditions: + * + * a) the account must have a name with length > 0 + * b) the account must not have an id assigned + * c) the transaction list must be empty + * d) the account must not have any sub-ordinate accounts + * e) the account must have no parent account + * f) the account must not have any reference to a MyMoneyFile object + * + * An exception will be thrown upon error conditions. + * + * @param account The complete account information in a MyMoneyAccount object + * @param parent The complete account information of the parent account + */ + void addAccount(MyMoneyAccount& account, MyMoneyAccount& parent); + + /** + * Modifies an already existing account in the file global account pool. + * + * An exception will be thrown upon error conditions. + * + * @param account reference to the new account information + */ + void modifyAccount(const MyMoneyAccount& account); + + /** + * This method re-parents an existing account + * + * An exception will be thrown upon error conditions. + * + * @param account MyMoneyAccount reference to account to be re-parented + * @param parent MyMoneyAccount reference to new parent account + */ + void reparentAccount(MyMoneyAccount &account, MyMoneyAccount& parent); + + /** + * moves splits from one account to another + * + * @param oldAccount id of the current account + * @param newAccount if of the new account + * + * @return the number of modified splits + */ + unsigned int moveSplits(const QString& oldAccount, const QString& newAccount); + + /** + * This method is used to determince, if the account with the + * given ID is referenced by any split in m_transactionList. + * + * @param id id of the account to be checked for + * @return true if account is referenced, false otherwise + */ + bool hasActiveSplits(const QString& id) const; + + /** + * This method is used to check whether a given + * account id references one of the standard accounts or not. + * + * An exception will be thrown upon error conditions. + * + * @param id account id + * @return true if account-id is one of the standards, false otherwise + */ + bool isStandardAccount(const QString& id) const; + + /** + * Returns @a true, if transaction @p t is a transfer transaction. + * A transfer transaction has two splits, both referencing either + * an asset, a liability or an equity account. + */ + bool isTransfer(const MyMoneyTransaction& t) const; + + /** + * This method is used to set the name for the specified standard account + * within the storage area. An exception will be thrown, if an error + * occurs + * + * @param id QString reference to one of the standard accounts. + * @param name QString reference to the name to be set + * + */ + void setAccountName(const QString& id, const QString& name) const; + + /** + * Deletes an existing account from the file global account pool + * This method only allows to remove accounts that are not + * referenced by any split. Use moveSplits() to move splits + * to another account. An exception is thrown in case of a + * problem. + * + * @param account reference to the account to be deleted. + */ + void removeAccount(const MyMoneyAccount& account); + + /** + * Deletes existing accounts and their subaccounts recursivly + * from the global account pool. + * This method expects that all accounts and their subaccounts + * are no longer assigned to any transactions or splits. + * An exception is thrown in case of a problem deleting an account. + * + * The optional parameter level is used to keep track of the recursion level. + * If the recursion level exceeds 100 (some arbitrary number which seems a good + * maximum), an exception is thrown. + * + * @param account_list Reference to a list of account IDs to be deleted. + * @param level Parameter to keep track of recursion level (do not pass a value here). + */ + void removeAccountList(const QStringList& account_list, unsigned int level = 0); + + /** + * This member function checks all accounts identified by account_list + * and their subaccounts wether they are assigned to transactions/splits or not. + * The function calls itself recursively with the list of sub-accounts of + * the currently processed account. + * + * The optional parameter level is used to keep track of the recursion level. + * If the recursion level exceeds 100 (some arbitrary number which seems a good + * maximum), an exception is thrown. + * + * @param account_list A QStringList with account IDs that need to be checked. + * @param level (optional) Optional parameter to indicate recursion level. + * @return Returns 'false' if at least one account has been found that + * is still referenced by a transaction. + */ + bool hasOnlyUnusedAccounts(const QStringList& account_list, unsigned int level = 0); + + /** + * Adds a transaction to the file-global transaction pool. A respective + * transaction-ID will be generated for this object. The ID is stored + * as QString in the object passed as argument. + * Splits must reference valid accounts and valid payees. The payee + * id can be empty. + * + * An exception will be thrown upon error conditions. + * + * @param transaction reference to the transaction + */ + void addTransaction(MyMoneyTransaction& transaction); + + /** + * This method is used to update a specific transaction in the + * transaction pool of the MyMoneyFile object. + * Splits must reference valid accounts and valid payees. The payee + * id can be empty. + * + * An exception will be thrown upon error conditions. + * + * @param transaction reference to transaction to be changed + */ + void modifyTransaction(const MyMoneyTransaction& transaction); + + /** + * This method is used to extract a transaction from the file global + * transaction pool through an id. In case of an invalid id, an + * exception will be thrown. + * + * @param id id of transaction as QString. + * @return reference to the requested transaction + */ + const MyMoneyTransaction transaction(const QString& id) const; + + /** + * This method is used to extract a transaction from the file global + * transaction pool through an index into an account. + * + * @param account id of the account as QString + * @param idx number of transaction in this account + * @return reference to MyMoneyTransaction object + */ + const MyMoneyTransaction transaction(const QString& account, const int idx) const; + + /** + * This method is used to pull a list of transactions from the file + * global transaction pool. It returns all those transactions + * that match the filter passed as argument. If the filter is empty, + * the whole journal will be returned. + * The list returned is sorted according to the transactions posting date. + * If more than one transaction exists for the same date, the order among + * them is undefined. + * + * @param filter MyMoneyTransactionFilter object with the match criteria + * + * @return set of transactions in form of a QValueList<MyMoneyTransaction> + */ + const QValueList<MyMoneyTransaction> transactionList(MyMoneyTransactionFilter& filter) const; + + void transactionList(QValueList<MyMoneyTransaction>& list, MyMoneyTransactionFilter& filter) const; + + void transactionList(QValueList<QPair<MyMoneyTransaction, MyMoneySplit> >& list, MyMoneyTransactionFilter& filter) const; + + /** + * This method is used to remove a transaction from the transaction + * pool (journal). + * + * @param transaction const reference to transaction to be deleted + */ + void removeTransaction(const MyMoneyTransaction& transaction); + + /** + * This method is used to return the actual balance of an account + * without it's sub-ordinate accounts. If a @p date is presented, + * the balance at the beginning of this date (not including any + * transaction on this date) is returned. Otherwise all recorded + * transactions are included in the balance. + * + * @param id id of the account in question + * @param date return balance for specific date (default = QDate()) + * @return balance of the account as MyMoneyMoney object + */ + const MyMoneyMoney balance(const QString& id, const QDate& date = QDate()) const; + + /** + * This method is used to return the actual balance of an account + * including it's sub-ordinate accounts. If a @p date is presented, + * the balance at the beginning of this date (not including any + * transaction on this date) is returned. Otherwise all recorded + * transactions are included in the balance. + * + * @param id id of the account in question + * @param date return balance for specific date (default = QDate()) + * @return balance of the account as MyMoneyMoney object + */ + const MyMoneyMoney totalBalance(const QString& id, const QDate& date = QDate()) const; + + /** + * This method returns the number of transactions currently known to file + * in the range 0..MAXUINT + * + * @param account QString reference to account id. If account is empty + + all transactions (the journal) will be counted. If account + * is not empty it returns the number of transactions + * that have splits in this account. + * + * @return number of transactions in journal/account + */ + unsigned int transactionCount(const QString& account = QString()) const; + + /** + * This method returns a QMap filled with the number of transactions + * per account. The account id serves as index into the map. If one + * needs to have all transactionCounts() for many accounts, this method + * is faster than calling transactionCount(const QString& account) many + * times. + * + * @return QMap with numbers of transactions per account + */ + const QMap<QString, unsigned long> transactionCountMap(void) const; + + /** + * This method returns the number of institutions currently known to file + * in the range 0..MAXUINT + * + * @return number of institutions known to file + */ + unsigned int institutionCount(void) const; + + /** + * This method returns the number of accounts currently known to file + * in the range 0..MAXUINT + * + * @return number of accounts currently known inside a MyMoneyFile object + */ + unsigned int accountCount(void) const; + + /** + * Returns the institution of a given ID + * + * @param id id of the institution to locate + * @return MyMoneyInstitution object filled with data. If the institution + * could not be found, an exception will be thrown + */ + const MyMoneyInstitution& institution(const QString& id) const; + + /** + * This method returns a list of the institutions + * inside a MyMoneyFile object + * + * @param list reference to the list. It will be cleared by this method first + */ + void institutionList(QValueList<MyMoneyInstitution>& list) const; + + /** + * This method returns a list of the institutions + * inside a MyMoneyFile object. This is a convenience method + * to the one above + * + * @return QValueList containing the institution objects + */ + const QValueList<MyMoneyInstitution> institutionList(void) const; + + /** + * Returns the account addressed by its id. + * + * @param id id of the account to locate. + * @return MyMoneyAccount object carrying the @p id. An exception is thrown + * if the id is unknown + */ + const MyMoneyAccount& account(const QString& id) const; + + /** + * Returns the account addressed by its name. + * + * @param name name of the account to locate. + * @return First MyMoneyAccount object found carrying the @p name. + * An empty MyMoneyAccount object will be returned if the name is not found. + */ + const MyMoneyAccount& accountByName(const QString& name) const; + + /** + * Returns the sub-account addressed by its name. + * + * @param acc account to search in + * @param name name of the account to locate. + * @return First MyMoneyAccount object found carrying the @p name. + * An empty MyMoneyAccount object will be returned if the name is not found. + */ + const MyMoneyAccount& subAccountByName(const MyMoneyAccount& acc, const QString& name) const; + + /** + * This method returns a list of accounts inside a MyMoneyFile object. + * An optional parameter is a list of id's. If this list is emtpy (the default) + * the returned list contains all accounts, otherwise only those referenced + * in the id-list. + * + * @param list reference to QValueList receiving the account objects + * @param idlist QStringList of account ids of those accounts that + * should be returned. If this list is empty, all accounts + * currently known will be returned. + * + * @param recursive if @p true, then recurse in all found accounts. The default is @p false + */ + void accountList(QValueList<MyMoneyAccount>& list, const QStringList& idlist = QStringList(), const bool recursive = false) const; + + /** + * This method is used to convert an account id to a string representation + * of the names which can be used as a category description. If the account + * is part of a hierarchy, the category name will be the concatenation of + * the single account names seperated by MyMoneyAccount::AccountSeperator. + * + * @param accountId QString reference of the account's id + * @param includeStandardAccounts if true, the standard top account will be part + * of the name, otherwise it will not be included (default is @c false) + * + * @return QString of the constructed name. + */ + QString accountToCategory(const QString& accountId, bool includeStandardAccounts = false) const; + + /** + * This method is used to convert a string representing a category to + * an account id. A category can be the concatenation of multiple accounts + * representing a hierarchy of accounts. They have to be seperated by + * MyMoneyAccount::AccountSeperator. + * + * @param category const reference to QString containing the category + * @param type account type if a specific type is required (defaults to UnknownAccountType) + * + * @return QString of the corresponding account. If account was not found + * the return value will be an empty string. + */ + QString categoryToAccount(const QString& category, MyMoneyAccount::accountTypeE type = MyMoneyAccount::UnknownAccountType) const; + + /** + * This method is used to convert a string representing an asset or + * liability account to an account id. An account name can be the + * concatenation of multiple accounts representing a hierarchy of + * accounts. They have to be seperated by MyMoneyAccount::AccountSeperator. + * + * @param name const reference to QString containing the account name + * + * @return QString of the corresponding account. If account was not found + * the return value will be an empty string. + */ + QString nameToAccount(const QString& name) const; + + /** + * This method is used to extract the parent part of an account hierarchy + * name who's parts are seperated by MyMoneyAccount::AccountSeperator. + * + * @param name full account name + * @return parent name (full account name excluding the last part) + */ + QString parentName(const QString& name) const; + + /** + * This method is used to create a new payee + * + * An exception will be thrown upon error conditions + * + * @param payee MyMoneyPayee reference to payee information + */ + void addPayee(MyMoneyPayee& payee); + + /** + * This method is used to retrieve information about a payee + * An exception will be thrown upon error conditions. + * + * @param id QString reference to id of payee + * + * @return MyMoneyPayee object of payee + */ + const MyMoneyPayee& payee(const QString& id) const; + + /** + * This method is used to retrieve the id to a corresponding + * name of a payee/receiver. + * An exception will be thrown upon error conditions. + * + * @param payee QString reference to name of payee + * + * @return MyMoneyPayee object of payee + */ + const MyMoneyPayee& payeeByName(const QString& payee) const; + + /** + * This method is used to modify an existing payee + * + * An exception will be thrown upon error conditions + * + * @param payee MyMoneyPayee reference to payee information + */ + void modifyPayee(const MyMoneyPayee& payee); + + /** + * This method is used to remove an existing payee. + * An error condition occurs, if the payee is still referenced + * by a split. + * + * An exception will be thrown upon error conditions + * + * @param payee MyMoneyPayee reference to payee information + */ + void removePayee(const MyMoneyPayee& payee); + + /** + * This method returns a list of the payees + * inside a MyMoneyStorage object + * + * @return QValueList<MyMoneyPayee> containing the payee information + */ + const QValueList<MyMoneyPayee> payeeList(void) const; + + /** + * This method is used to extract a value from the storage's + * KeyValueContainer. For details see MyMoneyKeyValueContainer::value(). + * + * @param key const reference to QString containing the key + * @return QString containing the value + */ + QString value(const QString& key) const; + + /** + * This method is used to set a value in the storage's + * KeyValueContainer. For details see MyMoneyKeyValueContainer::setValue(). + * + * @param key const reference to QString containing the key + * @param val const reference to QString containing the value + * + * @note Keys starting with the leadin @p kmm- are reserved for internal use + * by the MyMoneyFile object. + */ + void setValue(const QString& key, const QString& val); + + /** + * This method is used to delete a key-value-pair from the + * storage's KeyValueContainer identified by the parameter + * @p key. For details see MyMoneyKeyValueContainer::deletePair(). + * + * @param key const reference to QString containing the key + */ + void deletePair(const QString& key); + + /** + * This method is used to add a scheduled transaction to the engine. + * It must be sure, that the id of the object is not filled. When the + * method returns to the caller, the id will be filled with the + * newly created object id value. + * + * An exception will be thrown upon erronous situations. + * + * @param sched reference to the MyMoneySchedule object + */ + void addSchedule(MyMoneySchedule& sched); + + /** + * This method is used to modify an existing MyMoneySchedule + * object. Therefor, the id attribute of the object must be set. + * + * An exception will be thrown upon erronous situations. + * + * @param sched const reference to the MyMoneySchedule object to be updated + */ + void modifySchedule(const MyMoneySchedule& sched); + + /** + * This method is used to remove an existing MyMoneySchedule object + * from the engine. The id attribute of the object must be set. + * + * An exception will be thrown upon erronous situations. + * + * @param sched const reference to the MyMoneySchedule object to be updated + */ + void removeSchedule(const MyMoneySchedule& sched); + + /** + * This method is used to retrieve a single MyMoneySchedule object. + * The id of the object must be supplied in the parameter @p id. + * + * An exception will be thrown upon erronous situations. + * + * @param id QString containing the id of the MyMoneySchedule object + * @return MyMoneySchedule object + */ + const MyMoneySchedule schedule(const QString& id) const; + + /** + * This method is used to extract a list of scheduled transactions + * according to the filter criteria passed as arguments. + * + * @param accountId only search for scheduled transactions that reference + * account @p accountId. If accountId is the empty string, + * this filter is off. Default is @p QString(). + * @param type only schedules of type @p type are searched for. + * See MyMoneySchedule::typeE for details. + * Default is MyMoneySchedule::TYPE_ANY + * @param occurence only schedules of occurence type @p occurence are searched for. + * See MyMoneySchedule::occurenceE for details. + * Default is MyMoneySchedule::OCCUR_ANY + * @param paymentType only schedules of payment method @p paymentType + * are searched for. + * See MyMoneySchedule::paymentTypeE for details. + * Default is MyMoneySchedule::STYPE_ANY + * @param startDate only schedules with payment dates after @p startDate + * are searched for. Default is all dates (QDate()). + * @param endDate only schedules with payment dates ending prior to @p endDate + * are searched for. Default is all dates (QDate()). + * @param overdue if true, only those schedules that are overdue are + * searched for. Default is false (all schedules will be returned). + * + * @return const QValueList<MyMoneySchedule> list of schedule objects. + */ + const QValueList<MyMoneySchedule> scheduleList(const QString& accountId = QString(), + const MyMoneySchedule::typeE type = MyMoneySchedule::TYPE_ANY, + const MyMoneySchedule::occurenceE occurence = MyMoneySchedule::OCCUR_ANY, + const MyMoneySchedule::paymentTypeE paymentType = MyMoneySchedule::STYPE_ANY, + const QDate& startDate = QDate(), + const QDate& endDate = QDate(), + const bool overdue = false) const; + + const QStringList consistencyCheck(void); + + /** + * MyMoneyFile::OpeningBalancesPrefix is a special string used + * to generate the name for opening balances accounts. See openingBalanceAccount() + * for details. + */ + static const QString OpeningBalancesPrefix; + + /** + * MyMoneyFile::AccountSeperator is used as the seperator + * between account names to form a hierarchy. + */ + static const QString AccountSeperator; + + /** + * createCategory creates a category from a text name. + * + * The whole account hierarchy is created if it doesnt + * already exist. e.g if name = Bills:Credit Card and + * base = expense(), Bills will first be checked to see if + * it exists and created if not. Credit Card will then + * be created with Bills as it's parent. The Credit Card account + * will have it's id returned. + * + * @param base The base account (expense or income) + * @param name The category to create + * + * @return The category account id or empty on error. + * + * @exception An exception will be thrown, if @p base is not equal + * expense() or income(). + **/ + QString createCategory(const MyMoneyAccount& base, const QString& name); + + const QValueList<MyMoneySchedule> scheduleListEx( int scheduleTypes, + int scheduleOcurrences, + int schedulePaymentTypes, + QDate startDate, + const QStringList& accounts=QStringList()) const; + + /** + * This method is used to add a new security object to the engine. + * The ID of the object is the trading symbol, so there is no need for an additional + * ID since the symbol is guaranteed to be unique. + * + * An exception will be thrown upon erronous situations. + * + * @param security reference to the MyMoneySecurity object + */ + void addSecurity(MyMoneySecurity& security); + + /** + * This method is used to modify an existing MyMoneySchedule + * object. + * + * An exception will be thrown upon erronous situations. + * + * @param security reference to the MyMoneySecurity object to be updated + */ + void modifySecurity(const MyMoneySecurity& security); + + /** + * This method is used to remove an existing MyMoneySecurity object + * from the engine. + * + * An exception will be thrown upon erronous situations. + * + * @param security reference to the MyMoneySecurity object to be removed + */ + void removeSecurity(const MyMoneySecurity& security); + + /** + * This method is used to retrieve a single MyMoneySecurity object. + * The id of the object must be supplied in the parameter @p id. + * If no security with the given id is found, then a corresponding + * currency is searched. If @p id is empty, the baseCurrency() is returned. + * + * An exception will be thrown upon erronous situations. + * + * @param id QString containing the id of the MyMoneySecurity object + * @return MyMoneySecurity object + */ + const MyMoneySecurity& security(const QString& id) const; + + /** + * This method is used to retrieve a list of all MyMoneySecurity objects. + */ + const QValueList<MyMoneySecurity> securityList(void) const; + + /** + * This method is used to add a new currency object to the engine. + * The ID of the object is the trading symbol, so there is no need for an additional + * ID since the symbol is guaranteed to be unique. + * + * An exception will be thrown upon erronous situations. + * + * @param currency reference to the MyMoneySecurity object + */ + void addCurrency(const MyMoneySecurity& currency); + + /** + * This method is used to modify an existing MyMoneySecurity + * object. + * + * An exception will be thrown upon erronous situations. + * + * @param currency reference to the MyMoneySecurity object + */ + void modifyCurrency(const MyMoneySecurity& currency); + + /** + * This method is used to remove an existing MyMoneySecurity object + * from the engine. + * + * An exception will be thrown upon erronous situations. + * + * @param currency reference to the MyMoneySecurity object + */ + void removeCurrency(const MyMoneySecurity& currency); + + /** + * This method is used to retrieve a single MyMoneySchedule object. + * The id of the object must be supplied in the parameter @p id. + * If @p id is empty, this method returns baseCurrency(). + * + * An exception will be thrown upon erronous situations. + * + * @param id QString containing the id of the MyMoneySchedule object + * @return MyMoneySchedule object + */ + const MyMoneySecurity& currency(const QString& id) const; + + /** + * This method is used to retrieve the list of all currencies + * known to the engine. + * + * An exception will be thrown upon erronous situations. + * + * @return QValueList of all MyMoneySecurity objects. + */ + const QValueList<MyMoneySecurity> currencyList(void) const; + + /** + * This method retrieves a MyMoneySecurity object representing + * the selected base currency. If the base currency is not + * selected (e.g. due to a previous call to setBaseCurrency()) + * a standard MyMoneySecurity object will be returned. See + * MyMoneySecurity() for details. + * + * An exception will be thrown upon erronous situations. + * + * @return MyMoneySecurity describing base currency + */ + const MyMoneySecurity& baseCurrency(void) const; + + /** + * This method returns the foreign currency of the given two + * currency ids. If second is the base currency id then @a first + * is returned otherwise @a second is returned. + */ + const QString& foreignCurrency(const QString& first, const QString& second) const; + + /** + * This method allows to select the base currency. It does + * not perform any changes to the data in the engine. It merely + * stores a reference to the base currency. The currency + * passed as argument must exist in the engine. + * + * An exception will be thrown upon erronous situations. + * + * @param currency + */ + void setBaseCurrency(const MyMoneySecurity& currency); + + /** + * This method adds/replaces a price to/from the price list + */ + void addPrice(const MyMoneyPrice& price); + + /** + * This method removes a price from the price list + */ + void removePrice(const MyMoneyPrice& price); + + /** + * This method is used to retrieve a price for a specific security + * on a specific date. If there is no price for this date, the last + * known price for this currency is used. If no price information + * is available, 1.0 will be returned as price. + * + * @param fromId the id of the currency in question + * @param toId the id of the currency to convert to (if emtpy, baseCurrency) + * @param date the date for which the price should be returned (default = today) + * @param exactDate if true, entry for date must exist, if false any price information + * with a date less or equal to @p date will be returned + * + * @return price found as MyMoneyPrice object + * @note This throws an exception when the base currency is not set and toId is empty + */ + const MyMoneyPrice price(const QString& fromId, const QString& toId = QString(), const QDate& date = QDate::currentDate(), const bool exactDate = false) const; + + /** + * This method returns a list of all prices. + * + * @return MyMoneyPriceList of all MyMoneyPrice objects. + */ + const MyMoneyPriceList priceList(void) const; + + /** + * This method allows to interrogate the engine, if a known account + * with id @p id has a subaccount with the name @p name. + * + * @param id id of the account to look at + * @param name account name that needs to be searched force + * @retval true account with name @p name found as subaccounts + * @retval false no subaccount present with that name + */ + bool hasAccount(const QString& id, const QString& name) const; + + /** + * This method is used to retrieve the list of all reports + * known to the engine. + * + * An exception will be thrown upon erronous situations. + * + * @return QValueList of all MyMoneyReport objects. + */ + const QValueList<MyMoneyReport> reportList( void ) const; + + /** + * Adds a report to the file-global institution pool. A + * respective report-ID will be generated for this object. + * The ID is stored as QString in the object passed as argument. + * + * An exception will be thrown upon error conditions. + * + * @param report The complete report information in a + * MyMoneyReport object + */ + void addReport( MyMoneyReport& report ); + + /** + * Modifies an already existing report in the file global + * report pool. + * + * An exception will be thrown upon error conditions. + * + * @param report The complete new report information + */ + void modifyReport( const MyMoneyReport& report ); + + /** + * This method returns the number of reports currently known to file + * in the range 0..MAXUINT + * + * @return number of reports known to file + */ + unsigned countReports( void ) const; + + /** + * This method is used to retrieve a single MyMoneyReport object. + * The id of the object must be supplied in the parameter @p id. + * + * An exception will be thrown upon erronous situations. + * + * @param id QString containing the id of the MyMoneyReport object + * @return MyMoneyReport object + */ + const MyMoneyReport report( const QString& id ) const; + + /** + * This method is used to remove an existing MyMoneyReport object + * from the engine. The id attribute of the object must be set. + * + * An exception will be thrown upon erronous situations. + * + * @param report const reference to the MyMoneyReport object to be updated + */ + void removeReport(const MyMoneyReport& report); + + /** + * This method is used to retrieve the list of all budgets + * known to the engine. + * + * An exception will be thrown upon erronous situations. + * + * @return QValueList of all MyMoneyBudget objects. + */ + const QValueList<MyMoneyBudget> budgetList( void ) const; + + /** + * Adds a budget to the file-global institution pool. A + * respective budget-ID will be generated for this object. + * The ID is stored as QString in the object passed as argument. + * + * An exception will be thrown upon error conditions. + * + * @param budget The complete budget information in a + * MyMoneyBudget object + */ + void addBudget( MyMoneyBudget& budget ); + + + /** + * This method is used to retrieve the id to a corresponding + * name of a budget. + * An exception will be thrown upon error conditions. + * + * @param budget QString reference to name of budget + * + * @return MyMoneyBudget refernce to object of budget + */ + const MyMoneyBudget budgetByName(const QString& budget) const; + + + /** + * Modifies an already existing budget in the file global + * budget pool. + * + * An exception will be thrown upon error conditions. + * + * @param budget The complete new budget information + */ + void modifyBudget( const MyMoneyBudget& budget ); + + /** + * This method returns the number of budgets currently known to file + * in the range 0..MAXUINT + * + * @return number of budgets known to file + */ + unsigned countBudgets( void ) const; + + /** + * This method is used to retrieve a single MyMoneyBudget object. + * The id of the object must be supplied in the parameter @p id. + * + * An exception will be thrown upon erronous situations. + * + * @param id QString containing the id of the MyMoneyBudget object + * @return MyMoneyBudget object + */ + const MyMoneyBudget budget( const QString& id ) const; + + /** + * This method is used to remove an existing MyMoneyBudget object + * from the engine. The id attribute of the object must be set. + * + * An exception will be thrown upon erronous situations. + * + * @param budget const reference to the MyMoneyBudget object to be updated + */ + void removeBudget(const MyMoneyBudget& budget); + + + /** + * This method checks, if the given @p object is referenced + * by another engine object. + * + * @param obj const reference to object to be checked + * @param skipCheck MyMoneyFileBitArray with ReferenceCheckBits set for which + * the check should be skipped + * + * @retval false @p object is not referenced + * @retval true @p institution is referenced + */ + bool isReferenced(const MyMoneyObject& obj, const MyMoneyFileBitArray& skipCheck = MyMoneyFileBitArray()) const; + + /** + * Returns true if any of the accounts referenced by the splits + * of transaction @a t is closed. + */ + bool referencesClosedAccount(const MyMoneyTransaction& t) const; + + /** + * Returns true if the accounts referenced by the split @a s is closed. + */ + bool referencesClosedAccount(const MyMoneySplit& s) const; + + /** + * This method checks if the given check no &p no is used in + * a transaction referencing account &p accId. If @p accId is empty, + * @p false is returned. + * + * @param accId id of account to checked + * @param no check number to be verified if used or not + * @retval false @p no is not in use + * @retval true @p no is already assigned + */ + bool checkNoUsed(const QString& accId, const QString& no) const; + + /** + * This method returns the highest assigned check no for + * account @p accId. + * + * @param accId id of account to be scanned + * @return highest check no. used + */ + QString highestCheckNo(const QString& accId) const; + + /** + * Clear all internal caches (used internally for performance measurements) + */ + void clearCache(void); + + void forceDataChanged(void) { emit dataChanged(); } + + void preloadCache(void); + +protected: + /** + * This is the constructor for a new empty file description + */ + MyMoneyFile(); + +signals: + /** + * This signal is emitted whenever any data has been changed in the engine + * via any of the methods of this object + */ + void dataChanged(void); + +private: + static MyMoneyFile file; + + MyMoneyFile& operator=(MyMoneyFile&); // not allowed for singleton + MyMoneyFile(const MyMoneyFile&); // not allowed for singleton + + QString locateSubAccount(const MyMoneyAccount& base, const QString& category) const; + + void ensureDefaultCurrency(MyMoneyAccount& acc) const; + + void warningMissingRate(const QString& fromId, const QString& toId) const; + + /** + * This method creates an opening balances account. The name is constructed + * using MyMoneyFile::OpeningBalancesPrefix and appending " (xxx)" in + * case the @p security is not the baseCurrency(). The account created + * will be a sub-account of the standard equity account provided by equity(). + * + * @param security Security for which the account is searched + */ + const MyMoneyAccount createOpeningBalanceAccount(const MyMoneySecurity& security); + + const MyMoneyAccount openingBalanceAccount_internal(const MyMoneySecurity& security) const; + +private: + /** + * This method is used to add an id to the list of objects + * to be removed from the cache. If id is empty, then nothing is added to the list. + * + * @param id id of object to be notified + * @param reload reload the object (@c true) or not (@c false). The default is @c true + * @see attach, detach + */ + void addNotification(const QString& id, bool reload = true); + + /** + * This method is used to clear the notification list + */ + void clearNotification(void); + + /** + * This method is used to clear all + * objects mentioned in m_notificationList from the cache. + */ + void notify(void); + + /** + * This method checks if a storage object is attached and + * throws and exception if not. + */ + inline void checkStorage(void) const { + if(m_storage == 0) + throw new MYMONEYEXCEPTION("No storage object attached to MyMoneyFile"); + } + + /** + * This method checks that a transaction has been started with + * startTransaction() and throws an exception otherwise. Calls + * checkStorage() to make sure a storage object is present and attached. + */ + void checkTransaction(const char* txt) const; + +private: + /** + * This member points to the storage strategy + */ + IMyMoneyStorage *m_storage; + + /// \internal d-pointer class. + class Private; + /// \internal d-pointer instance. + Private* const d; + + static MyMoneyFile* _instance; +}; + +class KMYMONEY_EXPORT MyMoneyFileTransaction +{ +public: + MyMoneyFileTransaction(); + ~MyMoneyFileTransaction(); + + /** + * Commit the current transaction. + * + * @warning Make sure not to use any variable that might have been altered by + * the transaction. Please keep in mind, that changing transactions + * can also affect account objects. If you still need those variables + * just reload them from the engine. + */ + void commit(void); + void rollback(void); + void restart(void); + +private: + bool m_isNested; + bool m_needRollback; +}; + +#endif + |