doc/3.19.rst
changeset 9404 3e3e9b37e177
parent 9127 aff75b69db92
child 9405 7fc5e13d049f
equal deleted inserted replaced
9403:d81207fb9499 9404:3e3e9b37e177
       
     1 What's new in CubicWeb 4.0?
       
     2 ============================
       
     3 
       
     4 Behavior Changes
       
     5 ----------------
       
     6 
       
     7 * The anonymous property of Session and Connection are now computed from the
       
     8   related user login. If it match the ``anonymous-user`` in the config the
       
     9   connection is anonymous. Beware that the ``anonymous-user`` config is web
       
    10   specific. Therefore, no session may be anonymous in repository only setup.
       
    11 
       
    12 New Repository Access API
       
    13 -------------------------
       
    14 
       
    15 Connection replace Session
       
    16 ~~~~~~~~~~~~~~~~~~~~~~~~~~
       
    17 
       
    18 A new explicite Connection object replace Session as the main repository entry
       
    19 point. Connection hold all the necessary methods to be used Server side
       
    20 (``execute``, ``commit``, ``rollback``, ``call_service``, ``entity_from_eid``,
       
    21 etc…). You obtains a new Connection object using ``session.new_cnx()``.
       
    22 Connection object need have an explicite begin and end. Use them as a context
       
    23 manager::
       
    24 
       
    25     with session.new_cnx() as cnx:
       
    26         self.execute('INSERT Elephant E, E name "Cabar"')
       
    27         self.commit()
       
    28         self.execute('INSERT Elephant E, E name "Celeste"')
       
    29         self.commit()
       
    30     # Once you get out of the "with" clause, the connection is closed.
       
    31 
       
    32 Using the same Connection object in multiple threads will give you access to the
       
    33 same Transaction. However, Connection object are not thread safe.
       
    34 
       
    35 ``repository.internal_session`` is deprecated in favor of
       
    36 ``repository.internal_cnx``. Note that internal connection are now safe.
       
    37 Integrity hooks are enabled.
       
    38 
       
    39 Backward compact is preserved on Session. They can still be used to access the
       
    40 database for the next few version.
       
    41 
       
    42 dbapi vs repoapi
       
    43 ~~~~~~~~~~~~~~~~
       
    44 
       
    45 A new API have been introduced to replace the dbapi. It is called "repoapi".
       
    46 
       
    47 there is three relevant function for now:
       
    48 
       
    49 ``repoapi.get_repository(config)`` takes a config object and return credential
       
    50 
       
    51 ``repoapi.connect(repo, **credential)`` return a ClientConnection associated to
       
    52 the user identified by the credential. The ClientConnection is associated to its
       
    53 own Session that is closed when the ClientConnection is closed. A
       
    54 ClientConnection is a Connection-like object to be used client side.
       
    55 
       
    56 ``repoapi.anonymous_cnx(repo)`` return a ClientConnection associated to the
       
    57 anonymous user if describe in the Config.
       
    58 
       
    59 repoapi.ClientConnection replace dbapi.Connection and company
       
    60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
       
    61 
       
    62 On the client/web side, the Request is now using a ``repoapi.ClientConnection``
       
    63 instead of a ``dbapi.connection``. The ``ClientConnection`` have multiple backward
       
    64 compat method to looks like a ``dbapi.Cursor`` and ``dbapi.Connection``. It will
       
    65 remain that way for a few version.
       
    66 
       
    67 Session used on the Web side are now the same than the one used Server side.
       
    68 Some backward compat method have been installed on the server side Session to
       
    69 ease the transition.
       
    70 
       
    71 The authentification stack have been altered to use the ``repoapi`` instead of
       
    72 the ``dbapi``. Cubes adding new element in this stack are likely to break.
       
    73 
       
    74 New API in test
       
    75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
       
    76 
       
    77 All current methods and attributes used to access the repo on ``CubicwebTC`` are
       
    78 deprecated. You can now use a ``RepoAccess`` object. A ``RepoAccess`` object is
       
    79 linked to a new ``Session`` for a specified user. It is able to create
       
    80 ``Connection``, ``ClientConnection`` and web side request linked to this
       
    81 session::
       
    82 
       
    83     access =self.new_access("babar") # create a new RepoAccess for user babar
       
    84     with access.repo_cnx() as cnx:
       
    85         # some work with server side cnx
       
    86         cnx.execute(…)
       
    87         cnx.commit()
       
    88         cnx.execute(…)
       
    89         cnx.commit()
       
    90 
       
    91     with access.client_cnx() as cnx:
       
    92         # some work with client side cnx
       
    93         cnx.execute(…)
       
    94         cnx.commit()
       
    95 
       
    96     with access.web_request(elephant="babar") as req:
       
    97         # some work with client side cnx
       
    98         elephant_name = req.form["elephant"]
       
    99         req.execute(…)
       
   100         req.cnx.commit()
       
   101 
       
   102 By default ``testcase.admin_access`` contains a ``RepoAccess`` object for the
       
   103 default admin session.
       
   104 
       
   105 
       
   106 API changes
       
   107 -----------
       
   108 
       
   109 * ``RepositorySessionManager.postlogin`` is now called with two arguments,
       
   110   request and session. And this now happens before the session is linked to the
       
   111   request.
       
   112 
       
   113 * ``SessionManager`` and ``AuthenticationManager`` now take a repo object at
       
   114   initialization time instead of a vreg.
       
   115 
       
   116 * The ``async`` argument of ``_cw.call_service`` have been dropped. All call are
       
   117   now  synchronous. The zmq notification bus looks like a good replacement for
       
   118   most async usecase.
       
   119 
       
   120 * ``repo.stats()`` is now deprecated. The same information are available through
       
   121   a service (``_cw.call_service('repo_stats')``)
       
   122 
       
   123 * ``repo.gc_stats()`` is now deprecated. The same information are available through
       
   124   a service (``_cw.call_service('repo_gc_stats')``)
       
   125 
       
   126 * ``request.set_session`` no longer takes an optional ``user`` argument.
       
   127 
       
   128 * CubicwebTC does not have repo and cnx as class attributes anymore. They are
       
   129   standard instance attributes. ``set_cnx`` and ``_init_repo`` class methods
       
   130   become instance methods.
       
   131 
       
   132 * ``set_cnxset`` and ``free_cnxset`` are deprecated. cnxset are now
       
   133   automatically managed.
       
   134 
       
   135 
       
   136 Deprecated Code Drops
       
   137 ----------------------
       
   138 
       
   139 * The ldapuser source has been dropped. ldapfeed is the only official source
       
   140   remaining for ldap.
       
   141 
       
   142 * session.hijack_user mechanism has been dropped.