git.iko.soy/project-m36
on master help sign in
Merge pull request #140 from 3noch/master
fd05d50AgentM
docs/projectm36_client_library.markdown+3−1
compare with master
unifiedsplit
@@ -2,6 +2,8 @@
2
2
3The Project:M36 client library is the preferred method for interacting with Project:M36 databases. It supports all features of the DBMS while other interfaces may not.
3The Project:M36 client library is the preferred method for interacting with Project:M36 databases. It supports all features of the DBMS while other interfaces may not.
4
4
5+**Note:** A less featureful but more convenient client API also is available: see [documentation](simple_api.markdown).
6+
5The client supports both in-process and remote Project:M36 access.
7The client supports both in-process and remote Project:M36 access.
6
8
7## Setup
9## Setup
@@ -10,7 +12,7 @@ The client supports both in-process and remote Project:M36 access.
10```haskell
12```haskell
11import ProjectM36.Client
13import ProjectM36.Client
12```
14```
13−2. Create a Connection with a ConnectionInfo in the Either monad
15+2. Create a Connection with a `ConnectionInfo` in the Either monad
14```haskell
16```haskell
15conn <- connectProjectM36 (InProcessConnectionInfo NoPersistence)
17conn <- connectProjectM36 (InProcessConnectionInfo NoPersistence)
16```
18```
docs/simple_api.markdown+23−22
@@ -2,40 +2,41 @@
2
2
3## Introduction
3## Introduction
4
4
5−For common use cases, the ```ProjectM36.Client.Simple``` API can assist in transaction management. The API is designed to be less overwhelming than the full-featured ```ProjectM36.Client```.
5+For common use cases, the `ProjectM36.Client.Simple` API can assist in transaction management. The API is designed to be less overwhelming than the full-featured `ProjectM36.Client` (see [documentation](projectm36_client_library.markdown)).
6
6
7As such, not all features are available through the simple API, but, because the simple API is a thin layer over the complete API, the user may dip into the complete API at any time.
7As such, not all features are available through the simple API, but, because the simple API is a thin layer over the complete API, the user may dip into the complete API at any time.
8
8
9## Usage
9## Usage
10
10
11−1. Create a ```DbConn``` to connect to the database:
11+ 1. Create a `DbConn` to connect to the database:
12
12
13− ```haskell
13+ ```haskell
14− import ProjectM36.Client.Simple
14+ import ProjectM36.Client.Simple
15− ...
15+ ...
16− eDbconn <- simpleConnectProjectM36 (CrashSafePersistence (tempdir </> "db")) emptyNotificationCallback []
16+ let connInfo = InProcessConnectionInfo (CrashSafePersistence "my.db") emptyNotificationCallback []
17+ eDbconn <- simpleConnectProjectM36 connInfo
17− ```
18+ ```
18
19
19− The result is either a ```DbError``` or the connection linked to the "master" branch of the database.
20+ The result is `Either` a `DbError` or a connection linked to the `"master"` branch of the database.
20
21
21−1. Construct the ```Db``` monad using ```withTransaction```:
22+ 1. Run the `Db` monad using `withTransaction`:
22
23
23− ```haskell
24+ ```haskell
24− withTransaction dbconn $ do
25+ withTransaction dbconn $ do
25− execute $ Assign "x" (ExistingRelation relationTrue)
26+ execute $ Assign "x" (ExistingRelation relationTrue)
26− query $ RelationVariable "x" ()
27+ query $ RelationVariable "x" ()
27− ```
28+ ```
28
29
29− If there is an error in the above update or query, then an exception is thrown behind the scenes which cancels the transactions, rolls back any changes, and the error is returned by ```withTransaction```.
30+ If there is an error in the above update or query, then an exception is thrown behind the scenes which cancels the transactions, rolls back any changes, and the error is returned by `withTransaction`.
30
31
31− ```query``` is used with ```RelationalExpr``` queries which read the current database state.
32+ `query` is used with `RelationalExpr` queries which read the current database state.
32
33
33− ```execute``` is used with ```DatabaseContextExpr``` values which write the current database state.
34+ `execute` is used with `DatabaseContextExpr` values which write the current database state.
34
35
35− To execute a query without cancelling the transaction on an error, use the ```queryOrErr``` and ```executeOrErr``` variants.
36+ To execute a query without cancelling the transaction on an error, use the `queryOrErr` and `executeOrErr` variants.
36
37
37−1. Close the connection:
38+ 1. Close the connection:
38
39
39− ```haskell
40+ ```haskell
40− close dbconn
41+ close dbconn
41− ```
42+ ```
src/lib/ProjectM36/Client.hs+1
@@ -83,6 +83,7 @@ module ProjectM36.Client
83 IncDepName,
83 IncDepName,
84 InclusionDependency(..),
84 InclusionDependency(..),
85 AttributeName,
85 AttributeName,
86+ RelationalError(..),
86 RequestTimeoutException(..),
87 RequestTimeoutException(..),
87 RemoteProcessDiedException(..),
88 RemoteProcessDiedException(..),
88 AtomType(..),
89 AtomType(..),
src/lib/ProjectM36/Client/Simple.hs+51−35
@@ -1,76 +1,95 @@
1{-# LANGUAGE GeneralizedNewtypeDeriving #-}
1{-# LANGUAGE GeneralizedNewtypeDeriving #-}
2module ProjectM36.Client.Simple (
2module ProjectM36.Client.Simple (
3 simpleConnectProjectM36,
3 simpleConnectProjectM36,
4+ simpleConnectProjectM36At,
4 withTransaction,
5 withTransaction,
6+ withTransactionUsing,
5 execute,
7 execute,
8+ executeOrErr,
6 query,
9 query,
10+ queryOrErr,
11+ cancelTransaction,
12+ orCancelTransaction,
7 rollback,
13 rollback,
8 close,
14 close,
9 Atom(..),
15 Atom(..),
10 AtomType(..),
16 AtomType(..),
17+ Db,
18+ DbConn,
11 DbError(..),
19 DbError(..),
20+ RelationalError(..),
12 Attribute(..),
21 Attribute(..),
22+ C.Atomable(toAtom, fromAtom),
13 C.ConnectionInfo(..),
23 C.ConnectionInfo(..),
14 C.PersistenceStrategy(..),
24 C.PersistenceStrategy(..),
15 C.NotificationCallback,
25 C.NotificationCallback,
16 C.emptyNotificationCallback,
26 C.emptyNotificationCallback,
17 C.DatabaseContextExpr(..),
27 C.DatabaseContextExpr(..),
18− C.RelationalExprBase(..)
28+ C.RelationalExprBase(..)
19 ) where
29 ) where
20-- | A simplified client interface for Project:M36 database access.
30-- | A simplified client interface for Project:M36 database access.
21−import ProjectM36.Error
31+
32+import Control.Exception.Base
33+import Control.Monad ((<=<))
34+import Control.Monad.Reader
22import ProjectM36.Base
35import ProjectM36.Base
23import qualified ProjectM36.Client as C
36import qualified ProjectM36.Client as C
24−import Control.Monad.Reader
37+import ProjectM36.Error
25−import Control.Exception.Base
26
38
27type DbConn = (C.SessionId, C.Connection)
39type DbConn = (C.SessionId, C.Connection)
28
40
29−newtype Db a = Db {runDB :: ReaderT DbConn IO a}
41+newtype Db a = Db {runDb :: ReaderT DbConn IO a}
30 deriving (Functor, Applicative, Monad, MonadIO)
42 deriving (Functor, Applicative, Monad, MonadIO)
31−
43+
44+-- This exception type should never be observable by the API users.
45+-- It merely carries errors which end up as RelError at the end of a transaction.
32newtype TransactionCancelled = TransactionCancelled DbError deriving Show
46newtype TransactionCancelled = TransactionCancelled DbError deriving Show
33instance Exception TransactionCancelled
47instance Exception TransactionCancelled
34
48
35−-- | A simple alternative to 'connectProjectM36' which includes simple session management
49+-- | A simple alternative to 'connectProjectM36' which includes simple session management.
36−simpleConnectProjectM36 :: C.ConnectionInfo -> IO (Either DbError DbConn)
50+simpleConnectProjectM36At :: HeadName -> C.ConnectionInfo -> IO (Either DbError DbConn)
37−simpleConnectProjectM36 connInfo = do
51+simpleConnectProjectM36At headName connInfo = do
38 eConn <- C.connectProjectM36 connInfo
52 eConn <- C.connectProjectM36 connInfo
39 case eConn of
53 case eConn of
40 Left err -> pure (Left (ConnError err))
54 Left err -> pure (Left (ConnError err))
41 Right conn -> do
55 Right conn -> do
42− eSess <- C.createSessionAtHead conn "master"
56+ eSess <- C.createSessionAtHead conn headName
43 case eSess of
57 case eSess of
44 Left err -> do
58 Left err -> do
45 C.close conn
59 C.close conn
46 pure (Left (RelError err))
60 pure (Left (RelError err))
47 Right sess -> pure (Right (sess, conn))
61 Right sess -> pure (Right (sess, conn))
48−
62+
63+-- | Same as 'simpleConnectProjectM36At' but always connects to the @master@ branch.
64+simpleConnectProjectM36 :: C.ConnectionInfo -> IO (Either DbError DbConn)
65+simpleConnectProjectM36 = simpleConnectProjectM36At "master"
66+
67+-- | Closes the database connection.
49−close :: DbConn -> IO ()
68+close :: DbConn -> IO ()
50close (_ , conn) = C.close conn
69close (_ , conn) = C.close conn
51
70
52-- | Runs a Db monad which may include some database updates. If an exception or error occurs, the transaction is rolled back. Otherwise, the transaction is committed to the head of the current branch.
71-- | Runs a Db monad which may include some database updates. If an exception or error occurs, the transaction is rolled back. Otherwise, the transaction is committed to the head of the current branch.
53withTransaction :: DbConn -> Db a -> IO (Either DbError a)
72withTransaction :: DbConn -> Db a -> IO (Either DbError a)
54−withTransaction sessconn = withTransactionUsing sessconn UnionMergeStrategy
73+withTransaction sessconn = withTransactionUsing sessconn UnionMergeStrategy
55
74
56-- | Same a 'withTransaction' except that the merge strategy can be specified.
75-- | Same a 'withTransaction' except that the merge strategy can be specified.
57withTransactionUsing :: DbConn -> MergeStrategy -> Db a -> IO (Either DbError a)
76withTransactionUsing :: DbConn -> MergeStrategy -> Db a -> IO (Either DbError a)
58withTransactionUsing (sess, conn) strat dbm = do
77withTransactionUsing (sess, conn) strat dbm = do
59 eHeadName <- C.headName sess conn
78 eHeadName <- C.headName sess conn
60− case eHeadName of
79+ case eHeadName of
61 Left err -> pure (Left (RelError err))
80 Left err -> pure (Left (RelError err))
62 Right headName -> do
81 Right headName -> do
63 let successFunc = C.autoMergeToHead sess conn strat headName
82 let successFunc = C.autoMergeToHead sess conn strat headName
64− block = runReaderT (runDB dbm) (sess, conn)
83+ block = runReaderT (runDb dbm) (sess, conn)
65 handler :: TransactionCancelled -> IO (Either DbError a)
84 handler :: TransactionCancelled -> IO (Either DbError a)
66 handler (TransactionCancelled err) = pure (Left err)
85 handler (TransactionCancelled err) = pure (Left err)
67 handle handler $ do
86 handle handler $ do
68 ret <- C.withTransaction sess conn (block >>= pure . Right) successFunc
87 ret <- C.withTransaction sess conn (block >>= pure . Right) successFunc
69− case ret of
88+ case ret of
70− Left err -> pure (Left (RelError err))
89+ Left err -> pure (Left (RelError err))
71 Right val -> pure (Right val)
90 Right val -> pure (Right val)
72
91
73−-- | A union of connection and other errors that can be returned from 'withDBConnection'.
92+-- | A union of connection and other errors that can be returned from 'withTransaction'.
74data DbError = ConnError C.ConnectionError |
93data DbError = ConnError C.ConnectionError |
75 RelError RelationalError |
94 RelError RelationalError |
76 TransactionRolledBack
95 TransactionRolledBack
@@ -78,26 +97,18 @@ data DbError = ConnError C.ConnectionError |
78
97
79-- | Execute a 'DatabaseContextExpr' in the 'DB' monad. Database context expressions manipulate the state of the database. In case of an error, the transaction is terminated and the connection's session is rolled back.
98-- | Execute a 'DatabaseContextExpr' in the 'DB' monad. Database context expressions manipulate the state of the database. In case of an error, the transaction is terminated and the connection's session is rolled back.
80execute :: C.DatabaseContextExpr -> Db ()
99execute :: C.DatabaseContextExpr -> Db ()
81−execute expr = do
82− ret <- executeOrErr expr
100+execute = orCancelTransaction <=< executeOrErr
83− case ret of
101+
84− Left err -> liftIO $ cancelTransaction (RelError err)
85− Right _ -> pure ()
86−
87-- | Run a 'RelationalExpr' query in the 'DB' monad. Relational expressions perform read-only queries against the current database state.
102-- | Run a 'RelationalExpr' query in the 'DB' monad. Relational expressions perform read-only queries against the current database state.
88query :: C.RelationalExpr -> Db Relation
103query :: C.RelationalExpr -> Db Relation
89−query expr = do
104+query = orCancelTransaction <=< queryOrErr
90− ret <- queryOrErr expr
105+
91− case ret of
92− Left err -> liftIO $ cancelTransaction (RelError err)
93− Right rel -> pure rel
94−
95-- | Run a 'DatabaseContextExpr' update expression. If there is an error, just return it without cancelling the current transaction.
106-- | Run a 'DatabaseContextExpr' update expression. If there is an error, just return it without cancelling the current transaction.
96executeOrErr :: C.DatabaseContextExpr -> Db (Either RelationalError ())
107executeOrErr :: C.DatabaseContextExpr -> Db (Either RelationalError ())
97executeOrErr expr = Db $ do
108executeOrErr expr = Db $ do
98− (sess, conn) <- ask
109+ (sess, conn) <- ask
99 lift $ C.executeDatabaseContextExpr sess conn expr
110 lift $ C.executeDatabaseContextExpr sess conn expr
100−
111+
101-- | Run a 'RelationalExpr' query expression. If there is an error, just return it without cancelling the transaction.
112-- | Run a 'RelationalExpr' query expression. If there is an error, just return it without cancelling the transaction.
102queryOrErr :: C.RelationalExpr -> Db (Either RelationalError Relation)
113queryOrErr :: C.RelationalExpr -> Db (Either RelationalError Relation)
103queryOrErr expr = Db $ do
114queryOrErr expr = Db $ do
@@ -106,7 +117,12 @@ queryOrErr expr = Db $ do
106
117
107-- | Unconditionally roll back the current transaction and throw an exception to terminate the execution of the Db monad.
118-- | Unconditionally roll back the current transaction and throw an exception to terminate the execution of the Db monad.
108rollback :: Db ()
119rollback :: Db ()
109−rollback = Db $ lift $ cancelTransaction TransactionRolledBack
120+rollback = cancelTransaction TransactionRolledBack
121+
122+-- | Cancel a transaction and carry some error information with it.
123+cancelTransaction :: DbError -> Db a
124+cancelTransaction err = liftIO $ throwIO (TransactionCancelled err)
110
125
111−cancelTransaction :: DbError -> IO a
126+-- | Converts the 'Either' result from a 'Db' action into an immediate cancel in the case of error.
112−cancelTransaction err = throwIO (TransactionCancelled err)
127+orCancelTransaction :: Either RelationalError a -> Db a
128+orCancelTransaction = either (cancelTransaction . RelError) pure