ltpda-connection-manager: README annotate

annotate README @ 4:c706c10a76bd

Add help comments.

author	Daniele Nicolodi <daniele@science.unitn.it>
date	Mon, 24 May 2010 00:14:37 +0200
parents	b71833fb33ef
children

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:

Mercurial > hg > ltpda-connection-manager

annotate README @ 4:c706c10a76bd