*****************************************
OEFastROCS ShapeDatabaseServer XMLRPC API
*****************************************
.. oe:namespace:: ShapeDatabaseServer

This chapter documents the XMLRPC API that is exposed by the
``ShapeDatabaseServer.py`` server since the 1.0 release of
**FastROCS**. Since that release many users have created internal
clients to the server that depend on that XMLRPC API, so **OpenEye**
has strived to keep this API stable for pre-existing client code. This
chapter should serve as a guide for anyone looking to create a new
**FastROCS** server around the toolkit API.

Most users can just use the ``ShapeDatabaseClient.py`` script
directly, without the need to worry about the details of the protocol
between the client and server.

.. note::

   The XMLRPC API will be replaced by a RESTful API in a future
   version of **FastROCS TK**.

.. oe:function:: GetBestOverlays

   .. oe:api:: python

      GetBestOverlays(querymolstr, nhits, iformat = ".oeb", oformat = ".oeb") -> Binary

   Return the ``nhits`` results of the database search performed with
   the query ``querymolstr``. The file format of the data in the
   XML RPC Binary ``querymolstr`` is specified by the ``iformat``
   argument. Valid ``iformat`` arguments are any **OEChem** supported
   molecular file format that :oe:func:`OEChem::OEIs3DFormat` will
   return ``True`` for. This is because **FastROCS TK** requires a 3D
   conformation to search against.

   The returned XML RPC Binary will contain the best ``nhits`` of query
   against the database. The returned XML RPC Binary will contain the molecule
   sorted by the chosen scoring function for the database. ``nhits``
   of ``0`` specifies that all database molecules should be returned
   in sorted order, not a very advisable operation as that could move
   many megabytes to gigabytes of data over the network.

   The file format of the returned XML RPC Binary is specified by the
   ``oformat`` argument. This can be any **OEChem** supported file
   format that :oe:func:`OEChem::OEIsWriteable` will return ``True``
   for. However, scores are only stored as :ref:`SD data
   <section_moltaggeddata_SD>`, so only the following file formats
   will return score information:

   - :oe:const:`OEChem::OEFormat::OEB`
   - :oe:const:`OEChem::OEFormat::SDF`
   - :oe:const:`OEChem::OEFormat::CSV`

   Furthermore, the molecules returned will be aligned to the query
   molecule in 3D. So only formats that can represent 3D information
   will actually contain the resulting alignment.

   .. seealso::

      The :ref:`File Formats <section_molreadwrite_fileformats>`
      section of the **OEChem** documentation for a list of valid file
      formats.

   .. note::

      ``iformat`` and ``oformat`` default to ``.oeb`` in order to be
      compatible with versions of **FastROCS** clients prior to 1.4.0.

   .. warning::

      This XML RPC request will block until the search has
      completed. Since searches can take many seconds to minutes, the
      underlying network connection for the XML RPC request may time
      out. This remote procedure call should only be used when the
      search is known to be short. Using the
      :oe:func:`ShapeDatabaseServer::SubmitQuery` remote procedure
      call to queue up the query is highly preferred for creating a
      better user experience.

.. oe:function:: GetName

   .. oe:api:: python

      GetName() -> str

   Return the name of the database being served from the server. By
   default, this is the filename the server was started with. However,
   this can be changed by the :oe:func:`ShapeDatabaseServer::SetName`
   remote procedure call.

.. oe:function:: GetVersion

   .. oe:api:: python

      GetVersion() -> str

   Return the version of **FastROCS TK** being run on the server.

.. oe:function:: IsLoaded

   .. oe:api:: python

      IsLoaded(blocking = False) -> bool

   Returns ``True`` if the server has finished loading the database
   into memory and ready to accept queries. Returns ``False`` if the
   server is still initializing, causing any queries submitted to wait
   in a queue before they can be processed.

.. oe:function:: OEThrowSetLevel

   .. oe:api:: python

      OEThrowSetLevel(level)

   Turns on debugging information for the server, or turning it back
   off again. The integer ``level`` should be drawn from the
   :oe:constns:`OESystem::OEErrorLevel` namespace. **FastROCS TK**
   uses :oe:constns:`OESystem::OEThrow` to handle all logging
   information. **FastROCS TK** will throw lots of performance
   debugging information to the
   :oe:const:`OESystem::OEErrorLevel::Debug` level that will not be
   seen by default. When contacting OpenEye support about **FastROCS**
   (support@eyesopen.com), including this information would be very
   beneficial to helping solve the problem.

.. oe:function:: QueryHistogram

   .. oe:api:: python

      QueryHistogram(queryidx) -> [int, ..., int]

   Return the current distribution of scores for the search specified
   by the ``queryidx``. The distribution is returned as a list of
   integers. The distribution of scores can be retrieved in
   'real-time' during a search as well, though it is recommended to
   still use ``QueryStatus`` with the ``blocking`` parameter set to
   ``True`` to avoid spurious requests and load on the server.

   The distribution is only guaranteed to be a complete distribution
   of all the scores once the query has fully completed executing. A
   query is fully complete when the integers returned by
   ``QueryStatus`` are equal and both non-zero.

.. oe:function:: QueryStatus

   .. oe:api:: python

      QueryStatus(queryidx, blocking = False) -> (int, int)

   Return the current progress of the search specified by the
   ``queryidx``. The progress is returned as a pair of integers. The
   first integer in the pair is how many conformers have already been
   searched. The second integer in the pair is how many conformers
   there are total in the database to be searched. When the two
   integers are equal, the search has finished, and a call to
   :oe:func:`ShapeDatabaseServer::QueryResults` will return
   immediately with the resulting hits.

   ``queryidx`` must be an integer that was previously returned by the
   :oe:func:`ShapeDatabaseServer::SubmitQuery` remote procedure
   call. This remote procedure call can be called any number of times
   with the same ``queryidx`` between the matching
   :oe:func:`ShapeDatabaseServer::SubmitQuery` remote procedure call
   and the finishing :oe:func:`ShapeDatabaseServer::QueryResults`
   remote procedure call.

   The ``blocking`` parameter specifies whether this remote procedure
   call should return immediately. If ``blocking`` is ``False``, the
   remote procedure call will return immediately with the current
   status. However, this returned value could be identical to a
   previous call and provide no new information to the end user. If
   ``blocking`` is ``True``, this remote procedure call will not
   return until there is new information to return. This will result
   in less "busy waiting" network traffic constantly pinging the
   server for an update.

   .. note::

      It is possible for both values returned to be ``0`` even
      though the search is not complete. There is a very short period
      of time that the XML RPC service does not know the total number
      of conformers yet after the query has been submitted. Users can
      disregard this state and requery the server for a new status.

.. oe:function:: QueryResults

   .. oe:api:: python

      QueryResults(queryidx) -> Binary

   Return a XML RPC Binary of search results for the specified
   ``queryidx``. The contents of the XML RPC Binary, including file
   format and size, are controlled by the corresponding call to
   :oe:func:`ShapeDatabaseServer::SubmitQuery`.

   This remote procedure call will block if the search is not
   completed yet. Use the :oe:func:`ShapeDatabaseServer::QueryStatus`
   remote procedure call to determine if the results are ready to
   return.

   .. warning::

      This function can only be called once for a particular
      ``queryidx``. Once a query's results are retrieved with this
      remote procedure call, all record of the search are removed from
      the server's memory. The reverse is true as well though, if this
      function is not called, the query's results will stay resident
      in memory until the server is restarted.

.. oe:function:: SetName

   .. oe:api:: python

      SetName(name)

   Specify the name of the database this server is serving. Subsequent
   calls to the :oe:func:`ShapeDatabaseServer::GetName` remote
   procedure call will return this name.

.. oe:function:: SubmitQuery

   .. oe:api:: python

      SubmitQuery(querymolstr, nhits, iformat = ".oeb", oformat = ".oeb",
                  shapeOnly = False) -> int

   Submit a query 3D molecule to the server and begin processing
   immediately. If there is already a search in progress, the query
   will be submitted to a queue. An integer index is returned to allow
   tracking the progress of the search through the
   :oe:func:`ShapeDatabaseServer::QueryStatus` function, and then to retrieve the results
   through the :oe:func:`ShapeDatabaseServer::QueryResults` function. This function will
   return immediately, unlike the
   :oe:func:`ShapeDatabaseServer::GetBestOverlays` remote procedure
   call.

   The ``shapeOnly`` argument specifies that :ref:`color scoring
   <shapetk_color_features>` should not be performed and taken into
   account when scoring and sorting molecules. This defaults to
   ``False`` to be compatible with versions of **FastROCS** prior to
   1.5.0.

   The file format of the query in the XML RPC Binary ``querymolstr`` is
   specified by the ``iformat`` argument. Valid ``iformat`` arguments
   are any **OEChem** supported molecular file format that
   :oe:func:`OEChem::OEIs3DFormat` will return ``True`` for. This is
   because **FastROCS TK** requires a 3D conformation to search
   against. In addition to supporting 3D conformations from standard
   **OEChem** file formats, shape queries from ``.sq`` files are also
   supported as queries. ``.sq`` files are most easily constructed
   from within the vROCS GUI. They are usable from the **Shape TK**
   through the :ref:`OEShapeQueryPublic <OEShape_OEShapeQueryPublic>` APIs.

   The ``nhits`` argument specifies how many hits should be returned
   by the corresponding :oe:func:`ShapeDatabaseServer::QueryResults` remote procedure
   call. These hits will be returned in the order of the best score
   first. A value of ``0`` given to ``nhits`` specifies that all
   database molecules should be returned, not a very advisable
   operation as that can potentially push many megabytes to gigabytes
   of data over the network.

   The file format of the XML RPC Binary to return from
   :oe:func:`ShapeDatabaseServer::QueryResults` is specified by the ``oformat``
   argument. This can be any **OEChem** supported file format that
   :oe:func:`OEChem::OEIsWriteable` will return ``True`` for. However,
   scores are only stored as :ref:`SD data
   <section_moltaggeddata_SD>`, so only the following file formats
   will return score information:

   - :oe:const:`OEChem::OEFormat::OEB`
   - :oe:const:`OEChem::OEFormat::SDF`
   - :oe:const:`OEChem::OEFormat::CSV`

   Furthermore, the molecules returned will be aligned to the query
   molecule in 3D. So only formats that can represent 3D information
   will actually contain the resulting alignment.

   .. seealso::

      The :ref:`File Formats <section_molreadwrite_fileformats>`
      section of the **OEChem** documentation for a list of valid file
      formats.

   .. note::

      ``iformat`` and ``oformat`` default to ``.oeb`` in order to be
      compatible with versions of **FastROCS** clients prior to 1.4.0.

