[C++ Toolkit ANNOUNCE] BIG! New NCBI network client API.

[Denis Vakatov]

FYI,

We have got ourselves a new NCBI network client API, which is based on the
new NCBI dispatcher and load-balancer -- all re-written, refined and
dramatically extended in functionality!

The primary purporse of this API is to provide a seamless
connection to the NCBI network services.

NOTE:  this API also implements numerous "generic" functionalities,
       which are not "NCBI specific", such as portable socket and HTTP
       connection (which also can be converted to the C++ i/o streams),
       simple heap manager, data buffering, sendmail, etc.

Without getting into too much details:  the new client API has
superior multi-layered design, extended functionality, is way more flexible
and configurable, and it eliminates numerous restrictions, oddities
and not-transparency of the old NCBI network API. [;-)))]

Its core functionality is implemented in "C", and there are some
auxiliary "C++" interfaces as well.
The "C" part is shared between the C and C++ NCBI Toolkits -- there
is a separate "connect" library in the C++ Toolkit, which also is a
part of "ncbi" library of the C Toolkit (this code is 100% identical
in the Toolkits).
The "C" part is also 100% included into the "xconnect" library, which
adds "C++" API.

You can find its brief description in:
    http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/libs/conn.html


["C" programmers]

A very simple example (for the "bounce" service that does nothing
but bounces back all incoming data):
    http://www.ncbi.nlm.nih.gov/IEB/ToolBox/C_DOC/lxr/source/connect/test/test_ncbi_service_connector.c

A helper API to create "AsnIoPtr" based on "CONN" or
directly on name of the service:
    http://www.ncbi.nlm.nih.gov/IEB/ToolBox/C_DOC/lxr/source/connect/asn_connection.h

The new API is already in the NCBI C Toolkit Release from July 9:
    ftp://ftp.ncbi.nlm.nih.gov/toolbox/ncbi_tools/CURRENT/
It's pretty stable already, and we have already started to use it
internally.


[ "C/C++" programmers ]

There is a helper API to create C++ I/O stream based on "CONN" or
directly on the service name:
    http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/include/connect/ncbi_conn_stream.hpp

You then can attach the standard C++ I/O stream to the NCBI
serialization stream, and i/o data in ASN.1 or XML format:
    http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/programming_manual/asn.html
A good example of such application is ID1_FETCH:
    http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/src/app/id1_fetch/id1_fetch.cpp


DISCLAIMER / ENTICEMENT:

		  All the above is, of course, just for a brief announcement.
More docs are due (and some already exist) on this.
However, an inquisitive mind can IMHO "figure out" and start using
this API already, provided with:

 - even that small amount of docs:
       http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/libs/conn.html

 - and especially:
  1) the API headers (which contain a lot of end-user interfaces and
     extended comments), such as:
       http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/include/connect/ncbi_connection.h
       http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/include/connect/ncbi_service_connector.h
       http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/include/connect/ncbi_conn_stream.hpp
       and others...
  2) tests:
       http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/src/connect/test/test_ncbi_service_connector.c
       http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/src/connect/test/test_ncbi_conn_stream.cpp
       and others...
  3) demo:
       http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/src/app/id1_fetch/id1_fetch.cpp


Good luck,
Denis, Anton



P.S. We are planning to make the next pre-release of the NCBI C++
     Toolkit (for all platforms) in a day or two.


Credits:

  Anton Lavrentiev (lavr at ncbi.nlm.nih.gov)
     The new NCBI network dispatcher, including load-balancer.
     Most of the client API.

  Denis Vakatov (vakatov at ncbi.nlm.nih.gov)
     Overall project supervision. Parts of the client API.
     NCBI "firewal daemon".
     

Debits:

   None so far... :-)))