1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Class Poco::Data::Session</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="language" content="en"/>
<meta name="date" content="2009-11-24"/>
<meta name="generator" content="PocoDoc"/>
<link rel="stylesheet" href="css/styles.css" type="text/css"/>
</head>
<body bgcolor="#ffffff" leftmargin="0" topmargin="0">
<div class="header">
<h1 class="namespace"><a href="Poco.Data.html" class="namespace">Poco::Data</a></h1>
<h1 class="symbol">class Session</h1>
</div>
<div class="body">
<p>
<b>Library:</b> Data<br />
<b>Package:</b> DataCore<br />
<b>Header:</b> Poco/Data/Session.h</p>
<h2>Description</h2>
<div class="description">
<p>A <a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a> holds a connection to a Database and creates <a href="Poco.Data.Statement.html" title="class Poco::Data::Statement">Statement</a> objects. </p>
<p>Sessions are always created via the <a href="Poco.Data.SessionFactory.html" title="class Poco::Data::SessionFactory">SessionFactory</a>: </p>
<p></p>
<pre>Session ses(SessionFactory::instance().create(connectorKey, connectionString));
</pre>
<p>where the first param presents the type of session one wants to create (e.g., for <a href="Poco.Data.SQLite.html" title="namespace Poco::Data::SQLite">SQLite</a> one would choose "<a href="Poco.Data.SQLite.html" title="namespace Poco::Data::SQLite">SQLite</a>", for <a href="Poco.Data.ODBC.html" title="namespace Poco::Data::ODBC">ODBC</a> the key is "<a href="Poco.Data.ODBC.html" title="namespace Poco::Data::ODBC">ODBC</a>") and the second param is the connection string that the session implementation requires to connect to the database. The format of the connection string is specific to the actual connector. </p>
<p>A simpler form to create the session is to pass the connector key and connection string directly to the <a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a> constructor. </p>
<p>A concrete example to open an <a href="Poco.Data.SQLite.html" title="namespace Poco::Data::SQLite">SQLite</a> database stored in the file "dummy.db" would be </p>
<p></p>
<pre>Session ses("SQLite", "dummy.db");
</pre>
<p>Via a <a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a> one can create two different types of statements. First, statements that should only be executed once and immediately, and second, statements that should be executed multiple times, using a separate execute() call. The simple one is immediate execution: </p>
<p></p>
<pre>ses << "CREATE TABLE Dummy (data INTEGER(10))", now;
</pre>
<p>The now at the end of the statement is required, otherwise the statement would not be executed. </p>
<p>If one wants to reuse a <a href="Poco.Data.Statement.html" title="class Poco::Data::Statement">Statement</a> (and avoid the overhead of repeatedly parsing an SQL statement) one uses an explicit <a href="Poco.Data.Statement.html" title="class Poco::Data::Statement">Statement</a> object and its execute() method: </p>
<p></p>
<pre>int i = 0;
Statement stmt = (ses << "INSERT INTO Dummy VALUES(:data)", use(i));
for (i = 0; i < 100; ++i)
{
stmt.execute();
}
</pre>
<p>The above example assigns the variable i to the ":data" placeholder in the SQL query. The query is parsed and compiled exactly once, but executed 100 times. At the end the values 0 to 99 will be present in the Table "DUMMY". </p>
<p>A faster implementaton of the above code will simply create a vector of int and use the vector as parameter to the use clause (you could also use set or multiset instead): </p>
<p></p>
<pre>std::vector<int> data;
for (int i = 0; i < 100; ++i)
{
data.push_back(i);
}
ses << "INSERT INTO Dummy VALUES(:data)", use(data);
</pre>
<p>NEVER try to bind to an empty collection. This will give a <a href="Poco.Data.BindingException.html" title="class Poco::Data::BindingException">BindingException</a> at run-time! </p>
<p>Retrieving data from a database works similar, you could use simple data types, vectors, sets or multiset as your targets: </p>
<p></p>
<pre>std::set<int> retData;
ses << "SELECT * FROM Dummy", into(retData));
</pre>
<p>Due to the blocking nature of the above call it is possible to partition the data retrieval into chunks by setting a limit to the maximum number of rows retrieved from the database: </p>
<p></p>
<pre>std::set<int> retData;
Statement stmt = (ses << "SELECT * FROM Dummy", into(retData), limit(50));
while (!stmt.done())
{
stmt.execute();
}
</pre>
<p>The "into" keyword is used to inform the statement where output results should be placed. The limit value ensures that during each run at most 50 rows are retrieved. Assuming Dummy contains 100 rows, retData will contain 50 elements after the first run and 100 after the second run, i.e. the collection is not cleared between consecutive runs. After the second execute stmt.done() will return true. </p>
<p>A prepared <a href="Poco.Data.Statement.html" title="class Poco::Data::Statement">Statement</a> will behave exactly the same but a further call to execute() will simply reset the <a href="Poco.Data.Statement.html" title="class Poco::Data::Statement">Statement</a>, execute it again and append more data to the result set. </p>
<p>Note that it is possible to append several "bind" or "into" clauses to the statement. Theoretically, one could also have several limit clauses but only the last one that was added will be effective. Also several preconditions must be met concerning binds and intos. Take the following example: </p>
<p></p>
<pre>ses << "CREATE TABLE Person (LastName VARCHAR(30), FirstName VARCHAR, Age INTEGER(3))";
std::vector<std::string> nameVec; // [...] add some elements
std::vector<int> ageVec; // [...] add some elements
ses << "INSERT INTO Person (LastName, Age) VALUES(:ln, :age)", use(nameVec), use(ageVec);
</pre>
<p>The size of all use parameters MUST be the same, otherwise an exception is thrown. Furthermore, the amount of use clauses must match the number of wildcards in the query (to be more precisely: each binding has a numberOfColumnsHandled() value which is per default 1. The sum of all these values must match the wildcard count in the query. But this is only important if you have written your own <a href="Poco.Data.TypeHandler.html" title="class Poco::Data::TypeHandler">TypeHandler</a> specializations). If you plan to map complex object types to tables see the <a href="Poco.Data.TypeHandler.html" title="class Poco::Data::TypeHandler">TypeHandler</a> documentation. For now, we simply assume we have written one <a href="Poco.Data.TypeHandler.html" title="class Poco::Data::TypeHandler">TypeHandler</a> for Person objects. Instead of having n different vectors, we have one collection: </p>
<p></p>
<pre>std::vector<Person> people; // [...] add some elements
ses << "INSERT INTO Person (LastName, FirstName, Age) VALUES(:ln, :fn, :age)", use(people);
</pre>
<p>which will insert all Person objects from the people vector to the database (and again, you can use set, multiset too, even map and multimap if Person provides an operator() which returns the key for the map). The same works for a SELECT statement with "into" clauses: </p>
<p></p>
<pre>std::vector<Person> people;
ses << "SELECT * FROM PERSON", into(people);
</pre>
</div>
<h2>Member Summary</h2>
<p><b>Member Functions: </b><a href="Poco.Data.Session.html#2912" title="Poco::Data::Session::begin()">begin</a>, <a href="Poco.Data.Session.html#2915" title="Poco::Data::Session::close()">close</a>, <a href="Poco.Data.Session.html#2913" title="Poco::Data::Session::commit()">commit</a>, <a href="Poco.Data.Session.html#2911" title="Poco::Data::Session::createStatementImpl()">createStatementImpl</a>, <a href="Poco.Data.Session.html#2921" title="Poco::Data::Session::getFeature()">getFeature</a>, <a href="Poco.Data.Session.html#2926" title="Poco::Data::Session::getProperty()">getProperty</a>, <a href="Poco.Data.Session.html#2928" title="Poco::Data::Session::impl()">impl</a>, <a href="Poco.Data.Session.html#2916" title="Poco::Data::Session::isConnected()">isConnected</a>, <a href="Poco.Data.Session.html#2917" title="Poco::Data::Session::isTransaction()">isTransaction</a>, <a href="Poco.Data.Session.html#2909" title="Poco::Data::Session::operator <<()">operator <<</a>, <a href="Poco.Data.Session.html#2904" title="Poco::Data::Session::operator =()">operator =</a>, <a href="Poco.Data.Session.html#2914" title="Poco::Data::Session::rollback()">rollback</a>, <a href="Poco.Data.Session.html#2918" title="Poco::Data::Session::setFeature()">setFeature</a>, <a href="Poco.Data.Session.html#2923" title="Poco::Data::Session::setProperty()">setProperty</a>, <a href="Poco.Data.Session.html#2907" title="Poco::Data::Session::swap()">swap</a></p>
<h2>Constructors</h2>
<h3><a name="2897">Session</a></h3>
<p class="decl"><a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a>(<br /> <a href="Poco.AutoPtr.html" title="class Poco::AutoPtr">Poco::AutoPtr</a> < <a href="Poco.Data.SessionImpl.html" title="class Poco::Data::SessionImpl">SessionImpl</a> > ptrImpl<br />);</p>
<div class="description">
<p>Creates the <a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a>. </p>
</div>
<h3><a name="2902">Session</a></h3>
<p class="decl"><a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a>(<br /> const <a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a> & param33<br />);</p>
<div class="description">
<p>Creates a session by copying another one. </p>
</div>
<h3><a name="2899">Session</a></h3>
<p class="decl"><a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a>(<br /> const std::string & connector,<br /> const std::string & connectionString<br />);</p>
<div class="description">
<p>Creates a new session, using the given connector (which must have been registered), and connectionString. </p>
</div>
<h2>Destructor</h2>
<h3><a name="2906">~Session</a></h3>
<p class="decl">~<a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a>();</p>
<div class="description">
<p>Destroys the <a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a>. </p>
</div>
<h2>Member Functions</h2>
<h3><a name="2912">begin</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void begin();</p>
<div class="description">
<p>Starts a transaction. </p>
</div>
<h3><a name="2915">close</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void close();</p>
<div class="description">
<p>Closes the session. </p>
</div>
<h3><a name="2913">commit</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void commit();</p>
<div class="description">
<p>Commits and ends a transaction. </p>
</div>
<h3><a name="2911">createStatementImpl</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.Data.StatementImpl.html" title="class Poco::Data::StatementImpl">StatementImpl</a> * createStatementImpl();</p>
<div class="description">
<p>Creates a <a href="Poco.Data.StatementImpl.html" title="class Poco::Data::StatementImpl">StatementImpl</a>. </p>
</div>
<h3><a name="2921">getFeature</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">bool getFeature(<br /> const std::string & name<br />) const;</p>
<div class="description">
<p>Look up the state of a feature. </p>
<p>Features are a generic extension mechanism for session implementations. and are defined by the underlying <a href="Poco.Data.SessionImpl.html" title="class Poco::Data::SessionImpl">SessionImpl</a> instance. </p>
<p>Throws a <a href="Poco.Data.NotSupportedException.html" title="class Poco::Data::NotSupportedException">NotSupportedException</a> if the requested feature is not supported by the underlying implementation. </p>
</div>
<h3><a name="2926">getProperty</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.Any.html" title="class Poco::Any">Poco::Any</a> getProperty(<br /> const std::string & name<br />) const;</p>
<div class="description">
<p>Look up the value of a property. </p>
<p>Properties are a generic extension mechanism for session implementations. and are defined by the underlying <a href="Poco.Data.SessionImpl.html" title="class Poco::Data::SessionImpl">SessionImpl</a> instance. </p>
<p>Throws a <a href="Poco.Data.NotSupportedException.html" title="class Poco::Data::NotSupportedException">NotSupportedException</a> if the requested property is not supported by the underlying implementation. </p>
</div>
<h3><a name="2928">impl</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl"><a href="Poco.Data.SessionImpl.html" title="class Poco::Data::SessionImpl">SessionImpl</a> * impl();</p>
<div class="description">
<p>Returns a pointer to the underlying <a href="Poco.Data.SessionImpl.html" title="class Poco::Data::SessionImpl">SessionImpl</a>. </p>
</div>
<h3><a name="2916">isConnected</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">bool isConnected();</p>
<div class="description">
<p>Returns true if and only if session is connected, false otherwise. </p>
</div>
<h3><a name="2917">isTransaction</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">bool isTransaction();</p>
<div class="description">
<p>Returns true if and only if a transaction is in progress, false otherwise. </p>
</div>
<h3><a name="2909">operator <<</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">template < typename T > <a href="Poco.Data.Statement.html" title="class Poco::Data::Statement">Statement</a> operator << (<br /> const T & t<br />);</p>
<div class="description">
<p>Creates a <a href="Poco.Data.Statement.html" title="class Poco::Data::Statement">Statement</a> with the given data as SQLContent </p>
</div>
<h3><a name="2904">operator =</a></h3>
<p class="decl"><a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a> & operator = (<br /> const <a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a> & param34<br />);</p>
<div class="description">
<p>Assignement operator. </p>
</div>
<h3><a name="2914">rollback</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void rollback();</p>
<div class="description">
<p>Rolls back and ends a transaction. </p>
</div>
<h3><a name="2918">setFeature</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void setFeature(<br /> const std::string & name,<br /> bool state<br />);</p>
<div class="description">
<p>Set the state of a feature. </p>
<p>Features are a generic extension mechanism for session implementations. and are defined by the underlying <a href="Poco.Data.SessionImpl.html" title="class Poco::Data::SessionImpl">SessionImpl</a> instance. </p>
<p>Throws a <a href="Poco.Data.NotSupportedException.html" title="class Poco::Data::NotSupportedException">NotSupportedException</a> if the requested feature is not supported by the underlying implementation. </p>
</div>
<h3><a name="2923">setProperty</a> <img src="images/inline.gif" alt="inline" title="inline" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void setProperty(<br /> const std::string & name,<br /> const <a href="Poco.Any.html" title="class Poco::Any">Poco::Any</a> & value<br />);</p>
<div class="description">
<p>Set the value of a property. </p>
<p>Properties are a generic extension mechanism for session implementations. and are defined by the underlying <a href="Poco.Data.SessionImpl.html" title="class Poco::Data::SessionImpl">SessionImpl</a> instance. </p>
<p>Throws a <a href="Poco.Data.NotSupportedException.html" title="class Poco::Data::NotSupportedException">NotSupportedException</a> if the requested property is not supported by the underlying implementation. </p>
</div>
<h3><a name="2907">swap</a></h3>
<p class="decl">void swap(<br /> <a href="Poco.Data.Session.html" title="class Poco::Data::Session">Session</a> & other<br />);</p>
<div class="description">
<p>Swaps the session with another one. </p>
</div>
<p class="footer">POCO C++ Libraries 1.3.6-all<br />
Copyright © 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p>
</div>
</body>
</html>
|
