annotate README @ 2:b71833fb33ef

More details on the utils.mysql package.
author Daniele Nicolodi <daniele@science.unitn.it>
date Sun, 23 May 2010 22:09:23 +0200
parents c4b57991935a
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
1 * Requirements
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
2
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
3 1. Provide an interface for the user to insert connection
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
4 credentials: server hostname, database name, user name and
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
5 password.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
6
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
7 2. Avoid that the user has to enter those information too often,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
8 like when retrieving many objects from the repository. This is
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
9 done caching the credentials for a configurable amount of time
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
10
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
11 3. Provide understandable error messages.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
12
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
13 4. Track open connections, and avoid excessive proliferation of open
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
14 connections to the database, due to miss behaving user functions.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
15
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
16 This is all about managing connections, so I would propose to call
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
17 this component LTPDAConnectionManager.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
18
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
19
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
20 * Interface definition
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
21
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
22 ** LTPDAConnectionManager()
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
23
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
24 Isntantiates a singleton class managing credentials and connections.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
25
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
26 Credentials are cached. Credentials, except password are cached
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
27 forever, passwords are cached for a configurable amount of time.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
28
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
29 Connections are tracked putting each handed out connection into a
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
30 list. When a new connection is requested, or when requested via a
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
31 dedicated method, the connection list is walked and closed
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
32 connections are removed from it. When the connection number exceeds
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
33 a configurable maximum, no more connection are instantiated.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
34
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
35 The singleton clas is implemented as an handle matlab class that
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
36 stores an handle to itself in appdata storage. When the class is
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
37 instantiates it returns an handle to the copy referenced in
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
38 appdata.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
39
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
40 *** appdataKey
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
41
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
42 Static mehod that returns the key used to store the handle to
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
43 instance data in appdata.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
44
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
45 *** credentialsExpiry
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
46
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
47 Property. Taken from user preferences. Time after which the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
48 credentials are not valid anymore.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
49
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
50 *** maxConnectionsNumber
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
51
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
52 Property. Taken from user preferences. The maximum number of
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
53 connections that can be open at the same time toward the same
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
54 host.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
55
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
56 *** cachePassword
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
57
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
58 Property. Taken from user preferences. Defines if password should
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
59 be cached along with other database access credentials. It may
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
60 take the values:
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
61
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
62 0. passwords are not cached,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
63 1. passwords are always cached,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
64 2. ask if the users desires to cache the given password.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
65
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
66 *** connect(hostname, database, username, password)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
67
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
68 Try to connect to the database with the given credentials. If the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
69 connection attempt fails with an 'access denied' error, prompt the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
70 user for username using the given username as default, and
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
71 password. Present the option to cache password. Cache username and
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
72 password accordingly to user choice. Do not cache passwords by
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
73 default.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
74
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
75 Return an object implementing the java.sql.Connection interface,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
76 representing a connection to the given database, with the given
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
77 credentials.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
78
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
79 Connection errors, other than access denied are reported as
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
80 fatal exceptions. User hitting the cancel button on input forms is
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
81 reported as an 'user canceled' exception.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
82
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
83 *** connect(hostname, database, username)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
84
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
85 Search the credentials cache for user password. If it is not
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
86 found, or the connection attempt fails with an access denied
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
87 error, prompt the user for username, using the given username as
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
88 default, and password. Present the option to cache password. Try
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
89 to connect to the database with the given credentials. When the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
90 connections succeeds, cache username and password accordingly to
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
91 user choice.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
92
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
93 Return an object implementing the java.sql.Connection interface,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
94 representing a connection to the given database, with the given
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
95 credentials.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
96
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
97 Errors, other than acces denied, are reported as fatal
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
98 exceptions. User hitting the cancel button on input forms is
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
99 reported as an 'user canceled' exception. Access denied errors are
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
100 catched and credentials are asked again.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
101
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
102 *** connect(hostname, database)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
103
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
104 Search the credentials cache looking for usernames and passwords
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
105 for accessing the given database. If credentials are not found,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
106 there is more than one set of credentials matching, or the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
107 connection attempt fails with an 'acces denied' error, prompt the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
108 user for username and password. Present the option to cache
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
109 password. When the connections succeeds, cache username and
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
110 password accordingly to user choice.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
111
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
112 Return an object implementing the java.sql.Connection interface,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
113 representing a connection to the given database, with the given
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
114 credentials.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
115
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
116 Errors, other than acces denied, are reported as fatal
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
117 exceptions. User hitting the cancel button on input forms is
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
118 reported as an 'user canceled' exception. Access denied errors are
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
119 catched and credentials are asked again.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
120
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
121 *** connect()
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
122
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
123 Make the user choose between a list of hostname-database-username
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
124 tuples obtained from the credentials cache, and the possibility of
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
125 entering a hostname and a database. Then proceed as in the case of
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
126 the call to connect(hostname, database).
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
127
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
128 The list of hostname-database pairs can be initialized with data
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
129 from the LTPDA toolbox preferences or witj the add() method.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
130
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
131 *** connect(plist)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
132
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
133 Same as the previous calls but taking parameters from PLIST.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
134
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
135 If PLIST has a 'connection' parameter, and if this is a valid java
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
136 object, implementing the java.sql.Connection, return it instead of
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
137 creating a new connection. If the object does not fulfill the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
138 requirements throw a meaningful error.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
139
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
140 *** count()
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
141
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
142 Return the number of open connections in the connection pool. It
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
143 has the side effect of removing from the pool any close connection.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
144
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
145 *** close(ids)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
146
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
147 Close connections with the given IDs in the connections pool. If no
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
148 ID is given close all connection.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
149
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
150 *** clear()
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
151
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
152 Clear credentials cache.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
153
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
154 *** add(credentials)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
155
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
156 Add the given credentials to the cache.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
157
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
158
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
159 ** Utilities
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
160
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
161 *** utils.jmysql
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
162
2
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
163 Package containing a collection of functions and classes for
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
164 interfacing to a database from a pure matlab environment. Except
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
165 connect() all the functions take a java object implementing
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
166 java.sql.Connection as first parameter.
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
167
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
168 NOTE: Currently we use a MySQL database, however all the described
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
169 functions make no assumptions on the kind of database. It would be
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
170 fairly trivial to extend those to work on different databases,
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
171 exploiting the abstraction offered by the JDBC layer. In this case
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
172 a proper name for the package would be utils.db.
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
173
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
174
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
175 *** utils.jmysql.credentials
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
176
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
177 A simple class for organizing, in a convenient way, the
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
178 credentials required to establish a connection to a database
b71833fb33ef More details on the utils.mysql package.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 1
diff changeset
179 server.
0
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
180
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
181 *** utils.jmysql.connect(hostname, database, username, password)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
182
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
183 Return an object implementing the java.sql.Connection interface,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
184 representing a connection to the given database, with the given
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
185 credentials.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
186
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
187 Throw an error if the connection fails.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
188
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
189 This function can be used when the programmer wants full controll
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
190 on the connection, stepping aside of the connection manager.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
191
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
192 Should not be used in toolbox functions or by the toolbox users.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
193
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
194 *** utils.jmysql.execute(conn, query, varargin)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
195
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
196 Execute the query QUERY, with the parameters specified in VARARGIN
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
197 through the connection CONN. Returns the results in a 2d cell
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
198 array. See the actual implementation.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
199
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
200 QUERY is a string, CONN is a java object implementing
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
201 java.sql.Connection, VARARGIN can contain any base matlab type. we
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
202 can think about introducing the marshalling for time() objects
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
203 into SQL strings.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
204
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
205 See current implementation in CVS.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
206
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
207 *** plist.REPOSITORY_CREDENTIALS_PLIST
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
208
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
209 Static method that returns a default plist that specifies the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
210 credentials required to connect to a repository. Should be
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
211 combined in the default plist of the ltpda methods that require
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
212 a connection to the database. Those parameters are:
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
213
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
214 hostname - Server hostname
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
215 database - Database name
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
216 username - User login name
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
217 password - Password
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
218
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
219 In addition to those any ltpda method requiring a database
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
220 connection should accept a 'connection' parameter in his plist. An
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
221 open connection can be provided though this parameter. The caller
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
222 is responsible of closing the connection once it is done with it.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
223
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
224
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
225 * Examples
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
226
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
227 function out = useless(a, b, plist)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
228
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
229 % obtain a database connection
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
230 cm = LTPDAConnectionManager();
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
231 conn = cm.connect(pl)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
232
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
233 % ask the database to sum A and B
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
234 out = utils.jmysql.execute(conn, 'SELECT ?+?', a, b);
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
235
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
236 % out is a cell array containing A + B
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
237 disp out{1};
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
238
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
239 % check who is in charge of the connection
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
240 if conn ~= find(pl, 'connection')
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
241 % close connection
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
242 conn.close()
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
243 end
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
244
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
245 end
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
246
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
247 This function can be used as follows:
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
248
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
249 - useless(1, 2)
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
250
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
251 Will ask the user for hostname, database, username, password.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
252
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
253 - useless(1, 2, plist('hostname', 'localhost', 'database', 'test'))
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
254
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
255 Will ask the user for username and password.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
256
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
257 - useless(1, 2, plist('hostname', 'localhost', 'database', 'test', 'username', 'daniele'))
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
258
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
259 Will ask the user for password.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
260
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
261 - useless(1, 2, plist('hostname', 'localhost', 'database', 'test', 'username', 'daniele', 'password', 'passwd'))
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
262
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
263 Will not ask the user.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
264
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
265 - conn = utils.jmysql.conn('localhost', 'test', 'daniele', 'passwd')
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
266 useless(1, 2, plist('connection', conn));
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
267 useless(3, 4, plist('connection', conn));
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
268 conn.close();
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
269
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
270 Anything is asked to the user. The connection is provided by the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
271 user and should not be closed inside the function. This is
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
272 usefull for continuously running automated processes.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
273
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
274
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
275 This code is a stupid example of connections not being closed properly:
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
276
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
277 pl = plist('hostname', 'localhost', 'database', 'test', 'username', 'daniele', 'password', 'passwd');
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
278 cm = LTPDAConnectionManager();
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
279 cm.maxConnectionsNumber = 20;
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
280 for kk = 1:100
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
281 conn{kk} = cm.connect(pl);
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
282 end
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
283
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
284 It should fail at iteration 21 with an error similat to
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
285
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
286 ### too many connections open to 'localhost'
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
287
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
288
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
289 * Use cases
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
290
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
291 ** Interactive usage
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
292
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
293 A connection can be obtained from the connection manager in the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
294 following ways, requiring user interaction:
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
295
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
296 1. Open a connection without providing any credential.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
297
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
298 A. If there are cached credentials show a list of (hostname,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
299 database, username) touple, give the possibiity to chose between
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
300 any of those and creating a new one.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
301
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
302 B. If there are no cached credentials for the (hostname,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
303 database, username) touple, or the user choses 'new' in the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
304 previeus step, a dialog box asks the user for hostname and
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
305 database. The hostname field is an editable drop down lists
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
306 populated with data from the user preferences and cached
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
307 credentials. ADVANCED: the database filed is an editable drop
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
308 down list, when the user presses the drop down button, a list of
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
309 databases is fetch from the server.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
310
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
311 C. If there are cached credentials for the (hostname, database,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
312 username) touple go to E.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
313
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
314 D. A dialog box asks the user for username and password and
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
315 gives the option to remember credentials. Username field is an
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
316 editable drop down populated with usernames from the credentials
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
317 cache, the username last entered username this (hostname,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
318 database) pair is the default. The provided username is cached
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
319 into the credential cache.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
320
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
321 E. Connection to the database it attempt. If the connection
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
322 fails go back to C. If the connection succeds and the user
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
323 selected the 'store credentials' options save the password in
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
324 the credentials cache.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
325
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
326 F. Return the connection to the caller.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
327
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
328 2. Open a connection providing hostname and database.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
329
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
330 A. If there are cached credentials go to 1.E.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
331
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
332 B. If there are no cached credentials go to 1.D.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
333
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
334 3. Open a connection providing hostname, database, username.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
335
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
336 A. If there are cached credentials for the (hostname, database,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
337 username) touple go to 1.E.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
338
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
339 A. If there are no cached credentials for the (hostname, database,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
340 username) touple go to 1.D.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
341
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
342 4. Open a connection providing hostname, database, username, password.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
343
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
344 A. Go to 1.E.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
345
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
346 ** Non interactive usage
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
347
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
348 A connection can be obtained without requiring user interaction in
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
349 the following ways:
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
350
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
351 1. Known good credendials can be provided to the connection manager
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
352 connect() method. If called with four arguments it will not
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
353 require user interaction if it connects successfully to the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
354 database.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
355
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
356 2. Known good credentials can be added to the cache with the connection
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
357 manager add() method. Any call to the connection manager
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
358 connect() method specifying at least hostname and database
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
359 matching the ones inserted in the cache, will then use the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
360 cached credentials. User interaction is required if the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
361 connection fails.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
362
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
363 3. A connection can be obtained with the utils.jmysql.connect()
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
364 function and given to the ltpda methods requiring a database
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
365 connection with the 'connection' plist parameter. In this way
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
366 the caller has full control on the connection.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
367
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
368 ** Functions chaining
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
369
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
370 In the case where a procedure needs to call several ltpda methods
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
371 requiring database access, it is recommended that the connection is
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
372 created in the outermost function, and passed to called functions
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
373 using the 'connection' plist parameter.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
374
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
375 This avoids to query the user for connection credentials more than
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
376 once during the executing of the same procedure, even when password
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
377 caching is disabled. It also avoids the performance penalty of
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
378 connecting multiple times to the server.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
379
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
380 ** Multiple users scenario
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
381
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
382 Consider the case where two users are sharing the same matlab
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
383 instance. The two users must be able to interleave the creation of
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
384 database connections, each one with his own credentials. This can
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
385 be accomplished in different ways:
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
386
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
387 1. If the interleaving of the operations of two users is frequent,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
388 the connection manager can be configured, via the user
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
389 preferences, to never cache passwords. The users will be always
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
390 queried for their credentials.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
391
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
392 If procedures are well written, each one should not require to
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
393 enter user credentials more than once.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
394
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
395 2. If the interleaving of the two users is not so frequent, the
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
396 connection manager can be configured, via the user preferences,
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
397 to cache passwords for a short time.
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
398
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
399 3. The connection manager can be tricked into creating multiple
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
400 user profiles for the same database connection. For example:
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
401
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
402 cm = LTPDAConnectionManager();
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
403 cm.add(credentials('host', 'db', 'user1');
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
404 cm.add(credentials('host', 'db', 'user2');
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
405
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
406 Password caching can be enabled. The connection manager will
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
407 make the user decide which credentials to use. However the use
d5fef23867bb First workig implementation.
Daniele Nicolodi <daniele@science.unitn.it>
parents:
diff changeset
408 of the user own credentials is not enforced.
1
c4b57991935a Tell emacs to use org mode for this file.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 0
diff changeset
409
c4b57991935a Tell emacs to use org mode for this file.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 0
diff changeset
410
c4b57991935a Tell emacs to use org mode for this file.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 0
diff changeset
411 # Local Variables:
c4b57991935a Tell emacs to use org mode for this file.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 0
diff changeset
412 # mode: org
c4b57991935a Tell emacs to use org mode for this file.
Daniele Nicolodi <daniele@science.unitn.it>
parents: 0
diff changeset
413 # End: