--- a/doc/book/en/devrepo/testing.rst Fri Mar 14 11:18:15 2014 +0100
+++ b/doc/book/en/devrepo/testing.rst Tue Mar 11 15:56:05 2014 +0100
@@ -466,29 +466,26 @@
First, remember to think that some code run on a client side, some
other on the repository side. More precisely:
-* client side: web interface, raw db-api connection (cubicweb-ctl shell for
+* client side: web interface, raw repoapi connection (cubicweb-ctl shell for
instance);
* repository side: RQL query execution, that may trigger hooks and operation.
-The client interact with the repository through a db-api connection.
+The client interacts with the repository through a repoapi connection.
-A db-api connection is tied to a session in the repository. The connection and
+A repoapi connection is tied to a session in the repository. The connection and
request objects are unaccessible from repository code / the session object is
-unaccessible from client code (theorically at least).
+unaccessible from client code (theoretically at least).
-The :mod:`cubicweb.dbapi` module provides a base request class. The web interface
-provides an extended request class.
-
-
-The `request` object provides access to all cubicweb resources, eg:
+The web interface provides a request class. That `request` object provides
+access to all cubicweb resources, eg:
* the registry (which itself provides access to the schema and the
configuration);
-* an underlying db-api connection (when using req.execute, you actually call the
- db-api);
+* an underlying repoapi connection (when using req.execute, you actually call the
+ repoapi);
* other specific resources depending on the client type (url generation according
to base url, form parameters, etc.).
@@ -510,37 +507,32 @@
The `_cw` attribute
```````````````````
The `_cw` attribute available on every application object provides access to all
-cubicweb resources, eg:
+cubicweb resources, i.e.:
-For code running on the client side (eg web interface view), `_cw` is a request
-instance.
+- For code running on the client side (eg web interface view), `_cw` is a request
+ instance.
-For code running on the repository side (hooks and operation), `_cw` is a session
-instance.
+- For code running on the repository side (hooks and operation), `_cw` is a
+ Connection or Session instance.
-Beware some views may be called with a session (eg notifications) or with a
-DB-API request. In the later case, see :meth:`use_web_compatible_requests` on
-:class:`Connection` instances.
+Beware some views may be called with a session (e.g. notifications) or with a
+request.
Request, session and transaction
````````````````````````````````
-In the web interface, an HTTP request is handle by a single request, which will
-be thrown way once the response send.
+In the web interface, an HTTP request is handled by a single request, which will
+be thrown away once the response is sent.
-The web publisher handle the transaction:
+The web publisher handles the transaction:
* commit / rollback is done automatically
* you should not commit / rollback explicitly
-When using a raw db-api, you're on your own regarding transaction.
-
-On the other hand, db-api connection and session live from a user login to its logout.
-
-Because session lives for a long time, and database connections is a limited
-resource, we can't bound a session to its own database connection for all its
+Because a session lives for a long time, and database connections are a limited
+resource, we can't bind a session to its own database connection for all its
lifetime. The repository handles a pool of connections (4 by default), and it's
responsible to attribute them as needed.
@@ -550,13 +542,13 @@
2. the repository attributes a database connection to the session
-3. the repository's querier execute the query
+3. the repository's querier executes the query
4. this query may trigger hooks. Hooks and operation may execute some rql queries
through `_cw.execute`. Those queries go directly to the querier, hence don't
touch the database connection, they use the one attributed in 2.
-5. the repository's get the result of the query in 1. If it was a RQL read query,
+5. the repository gets the result of the query in 1. If it was a RQL read query,
the database connection is released. If it was a write query, the connection
is then tied to the session until the transaction is commited or rollbacked.
@@ -567,11 +559,11 @@
* when using a request, or code executed in hooks, this database connection
handling is totally transparent
-* however, take care when writing test: you are usually faking / testing both the
- server and the client side, so you have to decide when to use self.request() /
- self.session. Ask yourself "where the code I want to test will be running,
- client or repository side ?". The response is usually : use a request :)
- However, if you really need using a session:
+* however, take care when writing tests: you are usually faking / testing both the
+ server and the client side, so you have to decide when to use RepoAccess.client_cnx /
+ RepoAccess.repo_cnx. Ask yourself "where the code I want to test will be running,
+ client or repository side ?". The response is usually : use a client connection :)
+ However, if you really need using a server-side object:
- commit / rollback will free the database connection (unless explicitly told
not to do so).