settings.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015, 2024, Oracle and/or its affiliates.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License, version 2.0, as
 * published by the Free Software Foundation.
 *
 * This program is designed to work with certain software (including
 * but not limited to OpenSSL) that is licensed under separate terms, as
 * designated in a particular file or component or in included license
 * documentation. The authors of MySQL hereby grant you an additional
 * permission to link the program and your derivative works with the
 * separately licensed software that they have either included with
 * the program or referenced in the documentation.
 *
 * Without limiting anything contained in the foregoing, this file,
 * which is part of Connector/C++, is also subject to the
 * Universal FOSS Exception, version 1.0, a copy of which can be found at
 * https://oss.oracle.com/licenses/universal-foss-exception.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License, version 2.0, for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 */
 
#ifndef MYSQLX_DEVAPI_SETTINGS_H
#define MYSQLX_DEVAPI_SETTINGS_H
 
#include "common.h"
#include "detail/settings.h"
 
 
namespace mysqlx {
MYSQLX_ABI_BEGIN(2,0)
 
 
/*
  TODO: Cross-references to session options inside Doxygen docs do not work.
*/
 
 
class SessionOption
{
#define SESS_OPT_ENUM_any(X,N) X = N,
#define SESS_OPT_ENUM_bool(X,N) X = N,
#define SESS_OPT_ENUM_num(X,N) X = N,
#define SESS_OPT_ENUM_str(X,N) X = N,
#define SESS_OPT_ENUM_bool(X,N) X = N,
 
public:
 
 
  enum Enum {
    SESSION_OPTION_LIST(SESS_OPT_ENUM)
    LAST
  };
 
  SessionOption(Enum opt)
    : m_opt(opt)
  {}
 
  SessionOption()
  {}
 
  bool operator==(const SessionOption &other) const
  {
    return m_opt == other.m_opt;
  }
 
  bool operator==(Enum opt) const
  {
    return m_opt == opt;
  }
 
  bool operator!=(Enum opt) const
  {
    return m_opt != opt;
  }
 
  operator int()
  {
    return m_opt;
  }
 
protected:
  int m_opt = LAST;
};
 
 
class ClientOption
  : protected SessionOption
{
 
#define CLIENT_OPT_ENUM_any(X,N) X = -N,
#define CLIENT_OPT_ENUM_bool(X,N) X = -N,
#define CLIENT_OPT_ENUM_num(X,N) X = -N,
#define CLIENT_OPT_ENUM_str(X,N) X = -N,
 
 
public:
 
  using SessionEnum = SessionOption::Enum;
 
  
  enum Enum {
    CLIENT_OPTION_LIST(CLIENT_OPT_ENUM)
  };
 
  ClientOption()
  {}
 
  ClientOption(SessionOption opt)
    : SessionOption(opt)
  {}
 
  ClientOption(Enum opt)
  {
    m_opt = opt;
  }
 
  ClientOption(SessionEnum opt)
    : SessionOption(opt)
  {}
 
  bool operator==(Enum opt) const
  {
    return m_opt == opt;
  }
 
  bool operator==(SessionEnum opt) const
  {
    return SessionOption::operator==(opt);
  }
 
  bool operator!=(Enum opt) const
  {
    return m_opt != opt;
  }
 
  bool operator!=(SessionEnum opt) const
  {
    return SessionOption::operator!=(opt);
  }
 
  inline operator int()
  {
    return SessionOption::operator int();
  }
 
};
 
 
// Note: Doxygen gets confused here and renders docs incorrectly.
 
inline
std::string OptionName(ClientOption opt)
{
#define CLT_OPT_NAME_any(X,N) case ClientOption::X: return #X;
#define CLT_OPT_NAME_bool(X,N) CLT_OPT_NAME_any(X,N)
#define CLT_OPT_NAME_num(X,N) CLT_OPT_NAME_any(X,N)
#define CLT_OPT_NAME_str(X,N) CLT_OPT_NAME_any(X,N)
 
#define SESS_OPT_NAME_any(X,N) case SessionOption::X: return #X;
#define SESS_OPT_NAME_bool(X,N) SESS_OPT_NAME_any(X,N)
#define SESS_OPT_NAME_num(X,N) SESS_OPT_NAME_any(X,N)
#define SESS_OPT_NAME_str(X,N) SESS_OPT_NAME_any(X,N)
#define SESS_OPT_NAME_bool(X,N) SESS_OPT_NAME_any(X,N)
 
 
  switch (opt)
  {
    CLIENT_OPTION_LIST(CLT_OPT_NAME)
    SESSION_OPTION_LIST(SESS_OPT_NAME)
 
  default:
    throw_error("Unexpected Option"); return "";
  };
}
 
 
 
inline std::string ClientOptionName(ClientOption opt)
{
  return OptionName(opt);
}
 
inline std::string SessionOptionName(SessionOption opt)
{
  return OptionName(opt);
}
 
 
enum_class SSLMode
{
#define SSL_ENUM(X,N) X = N,
 
  SSL_MODE_LIST(SSL_ENUM)
};
 
 
 
inline
std::string SSLModeName(SSLMode m)
{
#define MODE_NAME(X,N) case SSLMode::X: return #X;
 
  switch (m)
  {
    SSL_MODE_LIST(MODE_NAME)
  default:
    {
      std::ostringstream buf;
      buf << "<UKNOWN (" << unsigned(m) << ")>" << std::ends;
      return buf.str();
    }
  };
}
 
 
 
enum_class AuthMethod
{
#define AUTH_ENUM(X,N) X=N,
 
  AUTH_METHOD_LIST(AUTH_ENUM)
};
 
 
 
inline
std::string AuthMethodName(AuthMethod m)
{
#define AUTH_NAME(X,N) case AuthMethod::X: return #X;
 
  switch (m)
  {
    AUTH_METHOD_LIST(AUTH_NAME)
  default:
    {
      std::ostringstream buf;
      buf << "<UKNOWN (" << unsigned(m) << ")>" << std::ends;
      return buf.str();
    }
  };
}
 
 
enum_class CompressionMode
{
#define COMPRESSION_ENUM(X,N) X = N,
 
  COMPRESSION_MODE_LIST(COMPRESSION_ENUM)
};
 
 
inline
std::string CompressionModeName(CompressionMode m)
{
#define COMPRESSION_NAME(X,N) case CompressionMode::X: return #X;
 
  switch (m)
  {
    COMPRESSION_MODE_LIST(COMPRESSION_NAME)
  default:
    {
      std::ostringstream buf;
      buf << "<UKNOWN (" << unsigned(m) << ")>" << std::ends;
      return buf.str();
    }
  };
}
 
 
 
namespace internal {
 
 
/*
  Encapsulate public enumerations in the Settings_traits class to be used
  by Settings_detail<> template.
*/
 
struct Settings_traits
{
  using Options         = mysqlx::SessionOption;
  using COptions        = mysqlx::ClientOption;
  using SSLMode         = mysqlx::SSLMode;
  using AuthMethod      = mysqlx::AuthMethod;
  using CompressionMode = mysqlx::CompressionMode;
 
  static std::string get_mode_name(SSLMode mode)
  {
    return SSLModeName(mode);
  }
 
  static std::string get_option_name(COptions opt)
  {
    return ClientOptionName(opt);
  }
 
  static std::string get_auth_name(AuthMethod m)
  {
    return AuthMethodName(m);
  }
};
 
 
template<>
PUBLIC_API
void
internal::Settings_detail<internal::Settings_traits>::
do_set(session_opt_list_t &&opts);
 
 
template<typename Option, typename base_iterator>
class iterator
{
  base_iterator m_it;
  std::pair<Option, mysqlx::Value> m_pair;
 
public:
 using iterator_category = std::input_iterator_tag;
 using value_type = std::pair<Option, mysqlx::Value>;
 
 iterator(const base_iterator &init) : m_it(init) {}
 
 iterator(const iterator &init) : m_it(init.m_it) {}
 
 std::pair<Option, mysqlx::Value> &operator*() {
    auto &el = *m_it;
    m_pair.first = static_cast<typename Option::Enum>(el.first);
    m_pair.second = el.second;
    return m_pair;
  }
 
  std::pair<ClientOption, mysqlx::Value>* operator->()
  {
    return &operator*();
  }
 
  iterator& operator++()
  {
    ++m_it;
    return *this;
  }
 
  iterator& operator--()
  {
    --m_it;
    return *this;
  }
 
  bool operator !=(const iterator &other)
  {
    return m_it != other.m_it;
  }
 
};
 
 
} // internal namespace
 
 
class Client;
class Session;
 
class SessionSettings
  : private internal::Settings_detail<internal::Settings_traits>
{
  using Value = mysqlx::Value;
 
public:
 
  SessionSettings(const string &uri)
  {
    try {
      Settings_detail::set_from_uri(uri);
    }
    CATCH_AND_WRAP
  }
 
 
  SessionSettings(
    const std::string &host, unsigned port,
    const string  &user,
    const char *pwd = NULL,
    const string &db = string()
  )
  {
    set(
      SessionOption::HOST, host,
      SessionOption::PORT, port,
      SessionOption::USER, user
    );
 
    if (pwd)
      set(SessionOption::PWD, std::string(pwd));
 
    if (!db.empty())
      set(SessionOption::DB, db);
  }
 
  SessionSettings(
    const std::string &host, unsigned port,
    const string  &user,
    const std::string &pwd,
    const string &db = string()
  )
    : SessionSettings(host, port, user, pwd.c_str(), db)
  {}
 
  SessionSettings(
    const std::string &host,
    const string  &user,
    const char    *pwd = NULL,
    const string  &db = string()
  )
    : SessionSettings(host, DEFAULT_MYSQLX_PORT, user, pwd, db)
  {}
 
  SessionSettings(
    const std::string &host,
    const string  &user,
    const std::string &pwd,
    const string  &db = string()
  )
    : SessionSettings(host, DEFAULT_MYSQLX_PORT, user, pwd, db)
  {}
 
  SessionSettings(
    unsigned port,
    const string  &user,
    const char    *pwd = NULL,
    const string  &db = string()
  )
    : SessionSettings("localhost", port, user, pwd, db)
  {}
 
  SessionSettings(
    unsigned port,
    const string  &user,
    const std::string &pwd,
    const string  &db = string()
  )
    : SessionSettings("localhost", port, user, pwd.c_str(), db)
  {}
 
  /*
    Templates below are here to take care of the optional password
    parameter of type const char* (which can be either 3-rd or 4-th in
    the parameter list). Without these templates passing
    NULL as password is ambiguous because NULL is defined as 0,
    which has type int, and then it could be treated as port value.
  */
 
  template <
    typename    HOST,
    typename    PORT,
    typename    USER,
    typename... T,
    typename std::enable_if<
      std::is_constructible<SessionSettings, HOST, PORT, USER, const char*, T...>::value
    >::type* = nullptr
  >
  SessionSettings(HOST h, PORT p, USER u, long, T... args)
    : SessionSettings(h, p, u, nullptr, args...)
  {}
 
 
  template <
    typename    PORT,
    typename    USER,
    typename... T,
    typename std::enable_if<
      std::is_constructible<SessionSettings, PORT, USER, const char*, T...>::value
    >::type* = nullptr
  >
  SessionSettings(PORT p, USER u, long, T... args)
    : SessionSettings(p, u, nullptr, args...)
  {}
 
 
  template <typename... R>
  SessionSettings(SessionOption::Enum opt, R&&...rest)
  {
    try {
      // set<true> means that only SessionOption can be used
      Settings_detail::set<true>(opt, std::forward<R>(rest)...);
    }
    CATCH_AND_WRAP
  }
 
  /*
    Return an iterator pointing to the first element of the SessionSettings.
  */
  using iterator = internal::iterator<SessionOption, Settings_detail::iterator>;
 
  iterator begin()
  {
    try {
      return Settings_detail::begin();
    }
    CATCH_AND_WRAP
  }
 
  /*
    Return an iterator pointing to the last element of the SessionSettings.
  */
 
  iterator end()
  {
    try {
      return Settings_detail::end();
    }
    CATCH_AND_WRAP
  }
 
 
  Value find(SessionOption opt)
  {
    try {
      return Settings_detail::get(opt);
    }
    CATCH_AND_WRAP
  }
 
  template<typename... R>
  void set(SessionOption opt, R&&... rest)
  {
    try {
      // set<true> means that only SessionOption can be used
      Settings_detail::set<true>(opt, std::forward<R>(rest)...);
    }
    CATCH_AND_WRAP
  }
 
  void clear()
  {
    try {
      Settings_detail::clear();
    }
    CATCH_AND_WRAP
  }
 
  void erase(SessionOption opt)
  {
    try {
      Settings_detail::erase(static_cast<int>(opt));
    }
    CATCH_AND_WRAP
  }
 
 
  bool has_option(SessionOption opt)
  {
    try {
      return Settings_detail::has_option(opt);
    }
    CATCH_AND_WRAP
  }
 
private:
 
  friend Client;
  friend Session;
};
 
 
class ClientSettings
  : private internal::Settings_detail<internal::Settings_traits>
{
 
public:
 
  using Base = internal::Settings_detail<internal::Settings_traits>;
  using Value = mysqlx::Value;
 
  /*
    Return an iterator pointing to the first element of the SessionSettings.
  */
 
  using iterator = internal::iterator<ClientOption, Settings_detail::iterator>;
 
  iterator begin()
  {
    try {
      return Settings_detail::begin();
    }
    CATCH_AND_WRAP
  }
 
  /*
    Return an iterator pointing to the last element of the SessionSettings.
  */
 
  iterator end()
  {
    try {
      return Settings_detail::end();
    }
    CATCH_AND_WRAP
  }
 
  ClientSettings(const string &uri)
  {
    try {
      Settings_detail::set_from_uri(uri);
    }
    CATCH_AND_WRAP
  }
 
  ClientSettings(const string &uri, ClientSettings &opts)
  {
    try {
      Settings_detail::set_from_uri(uri);
      Settings_detail::set_client_opts(opts);
    }
    CATCH_AND_WRAP
  }
 
  ClientSettings(const string &uri, const DbDoc &options)
  {
    try {
      Settings_detail::set_from_uri(uri);
      std::stringstream str_opts;
      str_opts << options;
      Settings_detail::set_client_opts(str_opts.str());
    }
    CATCH_AND_WRAP
  }
 
  ClientSettings(const string &uri, const char *options)
  {
    try {
      Settings_detail::set_from_uri(uri);
      Settings_detail::set_client_opts(options);
    }
    CATCH_AND_WRAP
  }
 
  template<typename...R>
  ClientSettings(const string &uri, mysqlx::ClientOption opt, R... rest)
  try
    : ClientSettings(uri)
  {
    // set<false> means that both SessionOption and ClientOption can be used
    Settings_detail::set<false>(opt, std::forward<R>(rest)...);
  }
  CATCH_AND_WRAP
 
 
  template <typename... R>
  ClientSettings(mysqlx::ClientOption opt, R&&...rest)
  {
    try {
      // set<false> means that both SessionOption and ClientOption can be used
      Settings_detail::set<false>(opt, std::forward<R>(rest)...);
    }
    CATCH_AND_WRAP
  }
 
  Value find(mysqlx::ClientOption opt)
  {
    try {
      return Settings_detail::get(opt);
    }
    CATCH_AND_WRAP
  }
 
  template<typename OPT, typename... R>
  void set(OPT opt, R&&... rest)
  {
    try {
      // set<false> means that both SessionOption and ClientOption can be used
      Settings_detail::set<false>(opt, std::forward<R>(rest)...);
    }
    CATCH_AND_WRAP
  }
 
 
  void clear()
  {
    try {
      Settings_detail::clear();
    }
    CATCH_AND_WRAP
  }
 
  void erase(mysqlx::ClientOption opt)
  {
    try {
      Settings_detail::erase(static_cast<int>(opt));
    }
    CATCH_AND_WRAP
  }
 
 
  bool has_option(ClientOption::Enum opt)
  {
    try {
      return Settings_detail::has_option(opt);
    }
    CATCH_AND_WRAP
  }
 
  bool has_option(SessionOption::Enum opt)
  {
    try {
      return Settings_detail::has_option(opt);
    }
    CATCH_AND_WRAP
  }
 
private:
  friend Client;
  friend Session;
};
 
 
MYSQLX_ABI_END(2,0)
}  // mysqlx
 
#endif