libwt-dev 3.1.10-1ubuntu2 / usr / include / Wt / WServer

// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2008 Emweb bvba, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef WSERVER_H_
#define WSERVER_H_

#include <Wt/WApplication>
#include <Wt/WAbstractServer>

#ifndef WT_TARGET_JAVA

namespace Wt {

struct WServerImpl;

/*! \class WServer Wt/WServer Wt/WServer
 *  \brief A class encapsulating an application server.
 *
 * This server class represents an instance of an application server.
 *
 * It offers support for multiple application entry points and control
 * over starting and stopping the server. This may be used as an
 * alternative to using WRun() when you wish to support multiple
 * application entry points, or for integrating a %Wt (stand-alone
 * httpd) server application into an existing application, with control
 * over starting and stopping the server as appropriate.
 *
 * As an example usage, consider the implementation of WRun(), which
 * starts the server until a Ctrl-C is pressed or a termination signal
 * has been received, or a restart is indicated using SIGHUP or a changed
 * binary (argv[0]):
 *
 * \code
int WRun(int argc, char *argv[], ApplicationCreator createApplication)
{
  try {
    // use argv[0] as the application name to match a suitable entry
    // in the Wt configuration file, and use the default configuration
    // file (which defaults to /etc/wt/wt_config.xml unless the environment
    // variable WT_CONFIG_XML is set)
    WServer server(argv[0]);

    // WTHTTP_CONFIGURATION is e.g. "/etc/wt/wthttpd"
    server.setServerConfiguration(argc, argv, WTHTTP_CONFIGURATION);

    // add a single entry point, at the default location (as determined
    // by the server configuration's deploy-path)
    server.addEntryPoint(Wt::Application, createApplication);
    if (server.start()) {
      int sig = WServer::waitForShutdown(argv[0]);

      std::cerr << "Shutdown (signal = " << sig << ")" << std::endl;
      server.stop();

      if (sig == SIGHUP)
	WServer::restart(argc, argv, environ);
    }
  } catch (WServer::Exception& e) {
    std::cerr << e.what() << "\n";
    return 1;
  } catch (std::exception& e) {
    std::cerr << "exception: " << e.what() << "\n";
    return 1;
  }
}
 * \endcode
 */
class WTCONNECTOR_API WServer : public WAbstractServer
{
public:
  /*! \class Exception
   *  \brief Server %Exception class.
   */
  class WT_API Exception : public std::exception
  {
  public:
    Exception(const std::string what);
    ~Exception() throw();

    /*! \brief Returns the error message.
     */
    const char *what() const throw() { return what_.c_str(); }

  private:
    std::string what_;
  };

  /*! \brief Creates a new server instance.
   *
   * The \p wtApplicationPath is used to match specific
   * application-settings in the %Wt configuration file. If no
   * specific match could be found, the general settings are used
   * (corresponding to the '*' selector).
   *
   * The %Wt application configuration is read from the
   * \p wtConfigurationFile. If empty, this defaults to the value
   * configured at build time.
   *
   * For more information on configuring %Wt applications, see \ref
   * configuration_sec "Configuration".
   *
   * \throws Exception : indicates a configuration problem.
   *
   * \sa setServerConfiguration()
   */
  WServer(const std::string& wtApplicationPath = std::string(),
	  const std::string& wtConfigurationFile = std::string());

  /*! \brief Destructor.
   *
   * If the server was still running, it is stopped first by calling
   * stop(). It is probably safer to call stop() first yourself, since
   * this allows exceptions to be caught.
   *
   * \sa isRunning(), stop()
   */
  virtual ~WServer();

  /*! \brief Configures the HTTP(S) server or FastCGI process.
   *
   * Configures the HTTP(S) server using command-line arguments, a
   * configuration file, or both. The valid options are described in
   * \ref config_wthttpd "Built-in httpd configuration".
   *
   * The applications themselves are configured using the configuration
   * file passed to the constructor.
   *
   * The server configuration must be set before any other
   * functionality can be used.
   *
   * In case of FastCGI deployment, the \p serverConfigurationFile
   * argument is ignored, and depending on the command-line arguments,
   * this process may become a FastCGI protocol relay process which
   * never returning from this call but directs the FastCGI stream to
   * the correct session, rather than a Wt application server.
   *
   * \throws Exception : indicates a configuration problem.
   */  
  void setServerConfiguration(int argc, char *argv[],
			      const std::string& serverConfigurationFile
			      = std::string());

  /*! \brief Binds an entry-point to a callback function to create
   *         a new application.
   *
   * The \p path is the local URL at which the application is
   * deployed: when a user visits this URL, the callback will be
   * called to create a new application. If empty, the URL is inferred
   * from the server configuration's deploy-path (see also \ref
   * config_wthttpd "Built-in httpd configuration").
   *
   * The path must start with a '/'.
   *
   * The optional \p favicon is a URL path (which should not
   * contain the host part!) to a favicon, which is the icon displayed
   * in the browser for your application. Alternatively, you may
   * specify a favicon using the "favicon" property in the
   * configuration file (see als \ref config_general "Application
   * settings (wt_config.xml)").
   */
  void addEntryPoint(EntryPointType type, ApplicationCreator callback,
		     const std::string& path = std::string(),
                     const std::string& favicon = std::string());

  /*! \brief Binds a resource to a fixed path.
   *
   * Resources may either be private to a single session or
   * public. Use this method to add a public resource with a fixed
   * path.
   */
  void addResource(WResource *resource, const std::string& path);

  /*! \brief Starts the server in the background.
   *
   * Returns whether the server could be successfully started.
   *
   * \throws Exception : indicates a problem starting the server.
   *
   * \sa isRunning(), stop()
   */
  bool start();

  /*! \brief Stops the server.
   *
   * All active application sessions are terminated cleanly, and the
   * HTTP(S) server is shut down.
   *
   * \throw Exception : indicates a problem while stopping the server.
   *
   * \sa isRunning(), start()
   */
  void stop();

  /*! \brief Resumes the server.
   *
   * This closes and reopens the listen socket(s) for accepting new
   * TCP and/or SSL connections. This may be needed when the OS (like
   * IPhoneOS) has closed the sockets while suspending the
   * application.
   */
  void resume();

  /*! \brief Waits for a shutdown signal.
   *
   * This static method blocks the current thread, waiting for a
   * shutdown signal. The implementation and details are platform
   * dependent, but this is usually Ctrl-C (SIGINT), SIGKILL, or
   * SIGHUP.
   *
   * This method is convenient if you want to customize how the server
   * is started (by instantiating a WServer object yourself, instead
   * of using Wt::Wrun()), but still want to use %Wt as a standalone
   * server that cleanly terminates on interruption.
   *
   * The optional \p restartWatchFile parameter can be used to let the
   * server watch for changes to a particular file (usually the binary
   * itself, argv[0]) which it will also interpret as SIGHUP. This may
   * be convenient to start the new binary after cleanly shutting down,
   * using restart(). <i>(Experimental, UNIX only)</i>
   */
  static int waitForShutdown(const char *restartWatchFile = 0);

  /*! \brief A utility method to restart.
   *
   * This will result the application with the new image (argv[0]), effectively
   * loading a newly deployed version. <i>(Experimental, UNIX only)</i>
   */
  static void restart(int argc, char **argv, char **envp);

  /*! \brief Returns whether the server is running.
   *
   * \sa start(), stop()
   */
  bool isRunning() const;

  /*! \brief Returns the server http port number.
   *
   * Returns -1 if the port is not known (i.e. because the connector is
   * not aware of how the http server is configured).
   */
  int httpPort() const;

  /*! \brief Returns the approot special property
   *
   * \sa WApplication::appRoot()
   */
  std::string appRoot() const;

  /*! \brief Reads a configuration property.
   *
   * As properties are unique to an executable location, they are defined
   * from the moment that setServerConfiguration() is invoked. Use this
   * method to access configuration properties outside of an active
   * session, e.g. from within the main() function.
   *
   * \sa WApplication::readConfigurationProperty()
   */
  bool readConfigurationProperty(const std::string& name,
				 std::string& value) const;

  void expireSessions();

  WServerImpl *impl() { return impl_; }

  virtual void handleRequest(WebRequest *request);

  /*! \brief Posts a function to a session.
   *
   * This is a thread-safe method to post a particular event
   * (implemented as a function object) to be run within the context
   * of a session, identified by its WApplication::sessionId(). The
   * method will safely handle the case where the session is being
   * terminated, and the session lock will be taken to execute the
   * function in the context of the session (with
   * WApplication::instance() pointing to the correct application),
   * just as with a request initiated by the browser. You will
   * typically also want to push the changes to the client using
   * server-initiated updates (WApplication::triggerUpdate()).
   *
   * The method returns immediately, and the function will be run
   * within the thread-pool that handles incoming web requests. In
   * this way, it avoids dead-lock scenarios.
   *
   * If a \p fallbackFunction is specified then in case the session
   * is dead, it is called instead.
   * 
   * This provides a good alternative to grabbing the update lock of
   * an application to directly push changes to a session out of its
   * event loop.
   */
  virtual void post(const std::string& sessionId,
		    const boost::function<void ()>& function,
                    const boost::function<void ()>& fallbackFunction
		      = boost::function<void ()>());

  /*! \brief Returns the server instance.
   *
   * Returns the single server instance. This may be useful when using
   * WRun(), which does not provide direct access to the instantiated
   * server, but still you want to use functions like
   * post().
   *
   * \note When instantiating multiple servers, this will simply return the
   *       last instance. You probably want to avoid this function then.
   */
  static WServer *instance() { return instance_; }

  /*! \brief Initializes a thread.
   *
   * This method is called within each newly created server thread,
   * and may be specialized to customize scheduling properties.
   *
   * The default implementation does nothing.
   *
   * \note This currently only works for the built-in httpd connector.
   */
  virtual void initializeThread();

  virtual bool usesSlashExceptionForInternalPaths() const;

private:
  WServerImpl *impl_;

  void post(const boost::function<void ()>& function);
};

}

#endif // WT_TARGET_JAVA

#endif // WSERVER_H_